Skip to main content

Bring Your Own - Stock management

The Primary Sales Widget requires a few different webhooks to be available in your backend. This section describes the request payloads we'll send and what are the expected responses.


💡Primary Sales Widget Enablement
The Primary Sales Widget is currently in its closed Beta release phase and we anticipate making it available publicly soon.

To gain access to the Primary Sales Widget, please complete the following form and our team will be in contact.

Webhook authentication

Every webhook has its own api_key parameter associated to it. We'll pass this key within the Authorization header on every request.

Example confirmation request headers

curl --location 'CONFIRMATION_URL' \
--request POST
--header 'Content-Type: application/json' \
--header 'Authorization: CONFIRMATION_API_KEY' \
--data '{ ... }'

Quote endpoint

Method: POST

Before going through with a sale, the Primary Sales Widget needs to know how much an order may cost to the end user. This should include every currency supported in your store.

Example request

{
"recipient_address": "0xdd9AAE1C317eE6EFEb0F3DB0A068e9Ed952a6CEB",
"products": [
{
"product_id": "P0002",
"quantity": 1
}
]
}

Example response

{
"products": [
{
"product_id": "P0002",
"quantity": 1,
"pricing": [
{
"currency": "USDC",
"currency_type": "crypto",
"amount": 20
},
{
"currency": "ETH",
"currency_type": "crypto",
"amount": 0.00679
},
{
"currency": "USD",
"currency_type": "fiat",
"amount": 19.98
}
]
}
],
"totals": [
{
"currency": "USDC",
"currency_type": "crypto",
"amount": 20
},
{
"currency": "ETH",
"currency_type": "crypto",
"amount": 0.00679
},
{
"currency": "USD",
"currency_type": "fiat",
"amount": 19.98
}
]
}
  • The products key should include an individual product cost breakdown, with the price for the request quantities.
  • The totals key should include the sum of all product amounts in each currency.

Sale authorisation endpoint

Method: POST

Every sale needs to be authorised by your Game Backend. Once an order is initialised, we’ll make a request to the authorisation webhook expecting confirmation for each sale item. The stock should be reserved in the Game backend until expiry is reached.

Example request

{
"recipient_address": "0xdd9AAE1C317eE6EFEb0F3DB0A068e9Ed952a6CEB",
"currency": "USDC",
"products": [
{
"product_id": "P0002",
"quantity": 1
}
]
}

Example response

{
"reference": "O00001",
"currency": "USDC",
"products": [
{
"product_id": "P0001",
"collection_address": "0xdd9AAE1C317eE6EFEb0F3DB0A068e9Ed952a6CEA",
"contract_type": "ERC721"
"detail": [
{
"token_id": "1698732498",
"amount": 10
}
]
}
]
}

Field response description

PropertyDescription
referenceUnique identifier for this order (max length 32 characters).
currencyConfirms the ERC20 symbol used for payment on this transaction.
productsFlat list of each item that should be minted. If the same product_id was requested at quantities greater than one, we expect one line item for each individual token.
product_idItem identifier, same as the one sent on the request.
collection_addressAddress of the ERC721 collection this item belongs to.
contract_typeERC721 or ERC1155 depending of the collection contract type
token_idToken ID generated by your service for this specific mint. The token should have all the metadata associated with the item populated.
amountConfirmation of the ERC20 token’s amount to be transferred for this item.

Transaction confirmation endpoint

Method: POST

When a sale transaction is finalised, we will send a confirmation to your Game backend.

The following diagram illustrates a successful sale that leads to a confirmation.

Example request

{
"reference": "qko2Fo9Dhx1zz21cQXX2CL",
"tx_hash": "0x123456",
"token_id_hash": "b7d016666d769",
"recipient_address": "0x123456",
"order": {
"contract_address": "0x999888",
"total_amount": 1,
"deadline": 1713864739,
"created_at": 1713863839302,
"currency": "USDC",
"products": [
{
"product_id": "test-item",
"detail": [
{
"token_id": "20719342457395",
"amount": 9.90
}
],
"quantity": 1,
"collection_address": "0x777888",
"collection_type": "ERC721"
}
]
}
}

Expired orders endpoint

Method: POST

If a transaction is not executed before its defined expiry time, your service will be notified to release the inventory back to stock.

The following diagram illustrates an abandoned sale that leads to an expired order.

Example request

{
"reference": "qko2Fo9Dhx1zz21cQXX2CL"
}

Status code - Success and errors

PropertyDescription
200Processed successfully
400Error with the request
404Products don't exist or stock is not sufficient
429Rate limited
500System error

Once you have these API's implemented within your own Game backend - Stock management system, you can continue with the Backend Configuration final steps.

IMX Whitepaper IMX Tokenomics Block Explorer Careers Contact Us