Set up required endpoints
This is a feature intended for managed partners. If you are not a managed partner and would like to become one, please reach out to us on our #dev-discussion channel on Discord.
If you are a managed partner, your partner success manager needs to set up a commercial partnership with MoonPay for you. Please reach out to them to facilitate this.
In order to implement this NFT primary sale card checkout feature, you need to complete the following:
- Establish a commercial partnership with MoonPay (your partner success manager will facilitate this for you)
- Set up and register with Immutable X with the required endpoints
How to set up and register endpoints
1. Create endpoints
You are required to provide the following endpoints:
- Trigger the mint: An endpoint to mint the asset once payment has been confirmed with MoonPay
- Get asset info: An endpoint to get information about the minted asset and render the checkout
Triggering the mint endpoint
Headers required:
Name | Description |
---|---|
IMX-Signature - How to validate this | Signature to confirm that the request was made by Immutable X |
IMX-Timestamp - How to generate this | Timestamp header to validate IMX-Signature |
Request body:
Property | Type | Description |
---|---|---|
offer_id | String | The ID of the offer provided for the NFT to be minted |
contract_address | String | Smart contract address of the NFT |
user | String | User that the NFT will be minted for (will become the NFT's owner) |
wallet_address | String | Wallet address that will receive the payment, in crypto (from MoonPay), for the minted NFT |
external_transaction_id | String (UUID) | Unique Immutable X transaction ID that can be used to get information about the transaction |
Response:
Property | Type | Descrtiption |
---|---|---|
contract_address | String | Smart contract address of the NFT |
token_id | String | Token ID (as specified by the NFT smart contract) of the minted asset |
tx_id | Integer | Minting transaction ID - see mintTokens response |
Example:
Request: POST /mint
headers: {
"IMX-Signature": "5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd",
"IMX-Timestamp": "1492774577"
}
data: {
"offer_id": "string",
"contract_address": "string",
"user": "string",
"wallet_address": "string",
"external_transaction_id": "string(UUID)",
}
Status: 200
Response: {
"contract_address": "string",
"token_id": "string",
"tx_id": 0
}
If minting fails, please provide a response with the error code and message.
Response: {
"code": "number", // the error code
"message": "string", // the error message
"details": "string" // the error details
}
Get asset info endpoint
This endpoint will be used to get information about the asset to be minted using trigger mint endpoint.
Response:
Property | Type | Description |
---|---|---|
offer_id | String | The ID of the offer provided for the NFT to be minted |
contract_address | String | Smart contract address of the NFT |
name | String | Token name to be rendered at checkout |
collection | String | Collection name to be rendered at checkout |
image_url | String | URL where the image to be displayed for the minted asset is hosted |
price_currency_code | String | Currency of the amount to be paid. Choose from: "ETH" or "USDC" |
price | String | Amount of the currency required to mint the token |
seller_address | String | Wallet address that will receive the payment, in crypto (from MoonPay), for the minted NFT |
Example:
Example Request: GET /:contract_address/:offer_id
Status: 200
Response: {
"offer_id": "123",
"contract_address": "0xacb3...",
"name": "SiShinylver Card Pack",
"collection": "Gods Unchained",
"image_url": "https://images.godsunchained.com/cardpack-images--marketing/256/mortal--neutral--shiny--legendary.png",
"price": "125.29",
"price_currency_code": "USD",
"seller_address": "0xacb3...",
}
If an offer is unavailable, a response should return 404 - Not Found
.
Status: 404
Response: {
"code": "404", // the error code
"message": "Missing offer", // the error message
"details": "The offer id {offer_id} is not a valid offer for purchase" // the error details
}
2. Register with Immutable X using created endpoints
When you've set up the endpoints required in the previous step, please register with Immutable X using the registerNftPrimarySalesContract API endpoint.
After registration, Immutable X will send you a webhook key that will be used to validate the signature when initiating mint requests.
3. How to validate the IMX-Signature
Generate a signed_payload
by concatenating the following:
IMX-Timestamp
header- The character
.
- JSON payload of the message to be signed
Example:
const payload = JSON.stringify({
offer_id: '1',
contract_address: '0x23a...',
user: '0x8b1...',
wallet_address: '0x11a...',
external_transaction_id: '00000000-0000-0000-aaaa-0000a000aa00',
});
const signed_payload = imx_timestamp_header_value + '.' + payload;
You will then need to compute an HMAC with the SHA-256 hash function using the webhook key that we provided when you registered the endpoints with Immutable X for the signed_payload
and use it to compare the signature in the header:
import crypto from 'crypto-js';
const generatedSignature = crypto
.HmacSHA256(signed_payload, webhookKey)
.toString();