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.

Sections

• What information does the trades webhook event provide?

---

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:

1. Backend Integration: Use your local application's backend to keep track of metadata attributes and token_id to metadata_id mappings. These can be found by subscribing to NFT and Metadata events.

2. 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:

note

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"
    }
}

note

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.