Webhook Events: Trades
The trades webhook event signals when a trade occurs on Immutable's Global Orderbook. The details of the trade are present, including additional fees.
What information does the trades webhook event provide?
The trade_created
event is triggered when an order executes on Immutable's centralized orderbook. This order may have been placed through the same marketplace that the buyer purchased the asset from or a different marketplace. In this event, the fee type: MAKER_ECOSYSTEM
is collected by the listing marketplace (i.e., the seller's marketplace), while the fee type: TAKER_ECOSYSTEM
is collected by the marketplace that the buyer used.
The trade_created
event provides all important details of the trade, including the trade id
, order_id
, token_id
, price, currency, and associated fees. The buyer (taker_address
) and sellers (maker_address
) marketplace is also identified.
This event does not provide asset metadata. To determine the metadata of the exchanged asset, you have two workflows available:
Backend Integration: Use your local application's backend to keep track of metadata attributes and
token_id
tometadata_id
mappings. These can be found by subscribing to NFT and Metadata events.API Polling: Utilize the Blockchain Data API NFT endpoint using
token_id
to review the asset's metadata attributes.
Example responses
Below are some examples of trade_created
events for common use-cases:
Trades events are labeled as "Created" because they are immutable and finalised when published (i.e. trade_created
)
New trade - Buyer and seller executing through 2 different marketplaces
{
"event_name": "imtbl_zkevm_trade_created",
"event_id": "018b3ac9-f0d1-a626-1d3e-aebad25e55f3",
"chain": "imtbl-zkevm-testnet",
"data": {
"id": "018b3ac9-f0ce-a4e2-14d3-2360733e7f71",
"order_id": "018b3ac9-a2c3-c153-8c18-01902b663abb",
"chain": {
"id": "eip155:13473",
"name": "imtbl-zkevm-testnet"
},
"buy": [
{
"type": "NATIVE",
"amount": "1000000"
}
],
"sell": [
{
"type": "ERC721",
"contract_address": "0xfdee4926d1a7b01cc1b8d086faf0b2194c99acc8",
"token_id": "1"
}
],
"buyer_fees": [
{
"type": "MAKER_ECOSYSTEM",
"amount": "1",
"recipient": "0xc606830d8341bc9f5f5dd7615e9313d2655b505d"
},
{
"type": "PROTOCOL",
"amount": "20000",
"recipient": "0x9a48b1b27743d807331d06ecf0bfb15c06fdb58d"
},
{
"type": "ROYALTY",
"amount": "10000",
"recipient": "0x9a48b1b27743d807331d06ecf0bfb15c06fdb58d"
},
{
"type": "TAKER_ECOSYSTEM",
"amount": "1",
"recipient": "0x71c7656ec7ab88b098defb751b7401b5f6d8976f"
}
],
"buyer_address": "0x452e19c31112972fcb28f0b064f008d7206dc5e0",
"seller_address": "0xc606830d8341bc9f5f5dd7615e9313d2655b505d",
"maker_address": "0xc606830d8341bc9f5f5dd7615e9313d2655b505d",
"taker_address": "0x452e19c31112972fcb28f0b064f008d7206dc5e0",
"blockchain_metadata": {
"transaction_hash": "0x78feeab1f1d5d7cb3004d8c077a770a59f558435a497add4f9002cef66c822d0",
"block_number": "2883316",
"transaction_index": "0",
"log_index": "0"
},
"indexed_at": "2022-03-23T07:24:41.00Z"
}
}
New trade - Buyer and seller executing through the same marketplace
{
"event_name": "imtbl_zkevm_trade_created",
"event_id": "018b3ac9-f0d1-a626-1d3e-aebad25e55f3",
"chain": "imtbl-zkevm-testnet",
"data": {
"id": "018b3ac9-f0ce-a4e2-14d3-2360733e7f71",
"order_id": "018b3ac9-a2c3-c153-8c18-01902b663abb",
"chain": {
"id": "eip155:13473",
"name": "imtbl-zkevm-testnet"
},
"buy": [
{
"type": "NATIVE",
"amount": "1000000"
}
],
"sell": [
{
"type": "ERC721",
"contract_address": "0xfdee4926d1a7b01cc1b8d086faf0b2194c99acc8",
"token_id": "1"
}
],
"buyer_fees": [
{
"type": "MAKER_ECOSYSTEM",
"amount": "1",
"recipient": "0xc606830d8341bc9f5f5dd7615e9313d2655b505d"
},
{
"type": "PROTOCOL",
"amount": "20000",
"recipient": "0x9a48b1b27743d807331d06ecf0bfb15c06fdb58d"
},
{
"type": "ROYALTY",
"amount": "10000",
"recipient": "0x9a48b1b27743d807331d06ecf0bfb15c06fdb58d"
},
{
"type": "TAKER_ECOSYSTEM",
"amount": "1",
"recipient": "0xc606830d8341bc9f5f5dd7615e9313d2655b505d"
}
],
"buyer_address": "0x452e19c31112972fcb28f0b064f008d7206dc5e0",
"seller_address": "0xc606830d8341bc9f5f5dd7615e9313d2655b505d",
"maker_address": "0xc606830d8341bc9f5f5dd7615e9313d2655b505d",
"taker_address": "0x452e19c31112972fcb28f0b064f008d7206dc5e0",
"blockchain_metadata": {
"transaction_hash": "0x78feeab1f1d5d7cb3004d8c077a770a59f558435a497add4f9002cef66c822d0",
"block_number": "2883316",
"transaction_index": "0",
"log_index": "0"
},
"indexed_at": "2022-03-23T07:24:41.00Z"
}
}
With orders containing ERC1155 tokens, there may be multiple imtbl_zkevm_trade_created
events mapping to a single listing due to ERC1155 orders being partially fillable.