API Reference

Webhook Events

We currently support sending the following webhook events:

Event Types

👍

Looking for sale events? All transfer event types also include sale data

EntityEventEvent TypeDescriptionEvent Schema
walletinbound_transferwallet.inbound_transferWallet inbound transfer to wallet addressesTransfer Model
walletoutbound_transferwallet.outbound_transferWallet outbound transfer from wallet addressesTransfer Model
nfttransfernft.transferNFT transfer for nft_idsTransfer Model
contracttransfercontract.transferNFT transfers including mints/burns on a contractTransfer Model
contractnft_metadata_updatecontract.nft_metadata_updateNFT IDs with metadata updates on a specified contract.a subset of the NFT Model*
chainnft_metadata_updatechain.nft_metadata_updateNFT IDs with metadata updates on a specified chaina subset of the NFT Model *
chainfloor_price_updatechain.floor_price_updateChain floor price updates on marketplacesa subset of the Collection model containing floor price Floor price models
chaintransferchain.transferNFT transfers including mints/burns on a chainTransfer Model
chainlisting_addedchain.listing_addedNFT Listing addedListing Event Model
chainlisting_modifiedchain.listing_modifiedNFT Listing modifiedListing Event Model
chainlisting_removedchain.listing_removedNFT Listing removedListing Event Model
collectionfloor_price_updatecollection.floor_price_updateCollection floor price updates on marketplacesa subset of the Collection model containing floor price Floor price models
collectiontransfercollection.transferNFTs transfers including mints/burns in a collectionTransfer Model

🚧

Certain webhook events with high volumes require whitelisting to be used - please contact [email protected] if you'd like to use any of the following:

chain.transfer, chain.floor_price_update, chain.listing_added, chain.listing_modified, chain.listing_removed


Event Payload

Each webhook will be a POST request at a URL specified during webhook creation.

Example: You will receive the following wallet.inbound_transfer event message if your webhook is subscribed for wallet.inbound_transfer with:

  • wallet_address: 0xfa6E0aDDF68267b8b6fF2dA55Ce01a53Fad6D8e2
  • chain: ethereum

The payload for transfer messages are formatted according to the Transfer Model which includes sale_details

📘

When a reorganization occurs, we will set is_removed=True for any transfer that is removed and publish a transfer webhook message.

wallet.inbound_transfer

{
    "type": "wallet.inbound_transfer",
    "data": {
        "nft_id": "ethereum.0xc0cb81c1f89ab0873653f67eea42652f13cd8416.4963",
        "chain": "ethereum",
        "contract_address": "0xc0Cb81c1F89Ab0873653f67EEa42652F13CD8416",
        "token_id": "4963",
        "from_address": "0x951038bB372D16180c0AFB0f46aB283059154004",
        "to_address": "0xfa6E0aDDF68267b8b6fF2dA55Ce01a53Fad6D8e2",
        "quantity": 1,
        "timestamp": "2021-11-01T16:42:15Z",
        "block_number": 13532274,
        "block_hash": "0x935a670596d3b6ad924a5ea4ef11487754b596a5a1fa1586cfb9f71685e779eb",
        "transaction": "0x06cf3ec933480aa9323fb0a3e26f88bd35af334adb692609fa56d8e7fb96b786",
        "log_index": 295,
        "batch_transfer_index": 0,
        "sale_details": {
            "marketplace_name": "OpenSea",
            "is_bundle_sale": false,
            "payment_token": {
                "payment_token_id": "ethereum.native",
                "name": "Ether",
                "symbol": "ETH",
                "address": null,
                "decimals": 18
            },
            "unit_price": 29900000000000000,
            "total_price": 29900000000000000
        }
    }
}

contract.transfer

The payload for contract.transfer messages are formatting as a subset of the Transfer Model

{
  "data": {
    "batch_transfer_index": 0,
    "block_hash": "0x28f60b269f1e2ca3ef51c04f40f0d0fc9733c3e4e5e5fe1198a79e5d7ca5b76d",
    "block_number": 16484391,
    "chain": "ethereum",
    "collection_id": "9ba9674e66333b1f224d7747e2c21e2b",
    "contract_address": "0x4fEA85cd2De7c4FCa058769C350b9e0589945022",
    "from_address": null,
    "log_index": 240,
    "nft_id": "ethereum.0x4fea85cd2de7c4fca058769c350b9e0589945022.475",
    "quantity": 1,
    "sale_details": null,
    "timestamp": "2023-01-25 14:20:35+00:00",
    "to_address": "0x9a89aA7b67ebAbA68141fb92eD5253cC3F197F1C",
    "token_id": "475",
    "transaction": "0x61b7ceea7fe5c246c530b5b54832c407e86c0d9d5e105632975890580159f201"
  },
  "type": "contract.transfer"
}

collection.transfer

The payload for collection.transfer messages are formatting as a subset of the Transfer Model

{
  "data": {
    "batch_transfer_index": 0,
    "block_hash": "0x28f60b269f1e2ca3ef51c04f40f0d0fc9733c3e4e5e5fe1198a79e5d7ca5b76d",
    "block_number": 16484391,
    "chain": "ethereum",
    "collection_id": "9ba9674e66333b1f224d7747e2c21e2b",
    "contract_address": "0x4fEA85cd2De7c4FCa058769C350b9e0589945022",
    "from_address": null,
    "log_index": 240,
    "nft_id": "ethereum.0x4fea85cd2de7c4fca058769c350b9e0589945022.475",
    "quantity": 1,
    "sale_details": null,
    "timestamp": "2023-01-25 14:20:35+00:00",
    "to_address": "0x9a89aA7b67ebAbA68141fb92eD5253cC3F197F1C",
    "token_id": "475",
    "transaction": "0x61b7ceea7fe5c246c530b5b54832c407e86c0d9d5e105632975890580159f201"
  },
  "type": "collection.transfer"
}

nft_metadata_update

The payload for nft_metadata_update messages are formatting as a subset of the NFT Model*

{
    "type": "chain.nft_metadata_update",
    "nfts": [
        {
            "nft_id": "ethereum.0x8943c7bac1914c9a7aba750bf2b6b09fd21037e0.5903",
            "name": "#5903",
            "description": "Lazy Lions",
            "image_url": "https://cdn.simplehash.com/assets/ab011a63a526ba533a868fe361b69004a70fcceb2b0c1c1bb3f6d92dbab95039.jpg",
            "video_url": null,
            "audio_url": null,
            "model_url": null,
            "previews": {
                "image_small_url": "https://lh3.googleusercontent.com/9MwgePRAM6ZteqhFiJr5nBJw16ptq7zCgZTlw8RwNJJO67XfyF945KL7RP4GmdDuWXcRsYo1yoDjYYQoveOpGYFKm3DG5b7nyw=s250",
                "image_medium_url": "https://lh3.googleusercontent.com/9MwgePRAM6ZteqhFiJr5nBJw16ptq7zCgZTlw8RwNJJO67XfyF945KL7RP4GmdDuWXcRsYo1yoDjYYQoveOpGYFKm3DG5b7nyw",
                "image_large_url": "https://lh3.googleusercontent.com/9MwgePRAM6ZteqhFiJr5nBJw16ptq7zCgZTlw8RwNJJO67XfyF945KL7RP4GmdDuWXcRsYo1yoDjYYQoveOpGYFKm3DG5b7nyw=s1000",
                "image_opengraph_url": "https://lh3.googleusercontent.com/9MwgePRAM6ZteqhFiJr5nBJw16ptq7zCgZTlw8RwNJJO67XfyF945KL7RP4GmdDuWXcRsYo1yoDjYYQoveOpGYFKm3DG5b7nyw=k-w1200-s2400-rj",
                "blurhash": "USE.IOjb0ik9XKWBV}t6x[ofM|V@i|aeW;of"
            },
            "extra_metadata": {
                "attributes": [
                    {
                        "trait_type": "Background",
                        "value": "Iron"
                    },
                    {
                        "trait_type": "Body",
                        "value": "Black"
                    },
                    {
                        "trait_type": "Bodygear",
                        "value": "Purple Fur Coat"
                    },
                    {
                        "trait_type": "Earring",
                        "value": "Nothing"
                    },
                    {
                        "trait_type": "Eyes",
                        "value": "Stoner"
                    },
                    {
                        "trait_type": "Headgear",
                        "value": "Bucket Hat"
                    },
                    {
                        "trait_type": "Mane",
                        "value": "Brown"
                    },
                    {
                        "trait_type": "Mouth",
                        "value": "Yelling"
                    }
                ],
                "image_original_url": "ipfs://QmVHxVJeJ8HseTjnhke29irvaQvehjgLqVTJ3R1UUtZKR6",
                "animation_original_url": null
            }
        }
    ]
}

📘

nft_metadata_update events are only sent for existing NFTs that changed. New NFTs do not trigger an nft_metadata_update message.

* Included fields from the NFT model:

  • nft_id
  • name
  • description
  • image_url
  • video_url
  • audio_url
  • model_url
  • previews
  • extra_metadata

floor_price_update

The payload for floor_price_update messages are formatting as a subset of the Collection model

{
    "type": "collection.floor_price_update",
    "data": [
        {
            "collection_id": "f650a50db4caf3bbf7adc1ff3be6613d",
            "floor_price": {
                "marketplace_id": "opensea",
                "payment_token": {
                    "address": null,
                    "decimals": 18,
                    "name": "Ether",
                    "payment_token_id": "ethereum.native",
                    "symbol": "ETH"
                },
                "value": 52000000000000000
            }
        }
    ]
}

Listing Events

The payload for listing_added, listing_modified and listing_removed messages are formatted according to the Listing Event models. Clients can utilize the event_type field to differentiate between added, modified, and removed events.

listing_added

{
  "data": [
    {
      "auction_type": null,
      "bundle_item_number": null,
      "event_reason": null,
      "event_timestamp": "2023-04-10T18:27:44Z",
      "event_type": "listing_added",
      "expiration_timestamp": "2023-04-11T18:25:35Z",
      "id": "4f5daf086c76a54c582bdb38c9be33a3",
      "listing_id": "33dce63f96de5cdbbce1a597be040bc5",
      "listing_timestamp": "2023-04-10T18:25:35Z",
      "marketplace_id": "opensea",
      "nft_id": "ethereum.0x495f947276749ce646f68ac8c248420045cb7b5e.90424313133455989675090412725094648373690516806513837690923291384495481028609",
      "payment_token": {
        "address": null,
        "decimals": 18,
        "name": "Ether",
        "payment_token_id": "ethereum.native",
        "symbol": "ETH"
      },
      "permalink": "https://opensea.io/assets/ethereum/0x495f947276749ce646f68ac8c248420045cb7b5e/90424313133455989675090412725094648373690516806513837690923291384495481028609",
      "price": 15000000000000000,
      "quantity": 1,
      "quantity_remaining": 1,
      "seller_address": "0xC7Ea58f876876317EB2179E24e4fe41D0a49E10d"
    }
  ],
  "type": "chain.listing_added"
}

listing_modified

📘

event_reason provides additional information for event_type

{
  "data": [
    {
      "auction_type": null,
      "bundle_item_number": null,
      "event_reason": "quantity_changed",
      "event_timestamp": "2023-04-10T18:27:47Z",
      "event_type": "listing_modified",
      "expiration_timestamp": "2023-05-10T18:21:20Z",
      "id": "03b1d79ccbcd60db91acbf6e97d4dc01",
      "listing_id": "6dcfb4e573af61a81ea3480911afe2ad",
      "listing_timestamp": "2023-04-10T18:21:20Z",
      "marketplace_id": "opensea",
      "nft_id": "ethereum.0x9b235f9fba22df59076b88e8df1f4fcfa2a5c842.808",
      "payment_token": {
        "address": null,
        "decimals": 18,
        "name": "Ether",
        "payment_token_id": "ethereum.native",
        "symbol": "ETH"
      },
      "permalink": "https://opensea.io/assets/ethereum/0x9b235f9fba22df59076b88e8df1f4fcfa2a5c842/808",
      "price": 5000000000000000,
      "quantity": 1,
      "quantity_remaining": 0,
      "seller_address": "0xB0aDFDCCEA1e8808084764A37340cC78A2761e0B"
    }
  ],
  "type": "chain.listing_modified"
}

listing_removed

{
  "data": [
    {
      "auction_type": null,
      "bundle_item_number": null,
      "event_reason": null,
      "event_timestamp": "2023-04-10T18:27:48Z",
      "event_type": "listing_removed",
      "expiration_timestamp": "2023-05-10T18:13:29Z",
      "id": "7468ecb1852bb55ef9be67f0a8a74838",
      "listing_id": "7bf9dbe07f46e22e28141821beedfc5a",
      "listing_timestamp": "2023-04-10T18:13:29Z",
      "marketplace_id": "opensea",
      "nft_id": "ethereum.0x9b235f9fba22df59076b88e8df1f4fcfa2a5c842.855",
      "payment_token": {
        "address": null,
        "decimals": 18,
        "name": "Ether",
        "payment_token_id": "ethereum.native",
        "symbol": "ETH"
      },
      "permalink": "https://opensea.io/assets/ethereum/0x9b235f9fba22df59076b88e8df1f4fcfa2a5c842/855",
      "price": 4400000000000000,
      "quantity": 1,
      "quantity_remaining": 0,
      "seller_address": "0xBF08D77bea18f88687024E5fdCaC1EB486337f15"
    }
  ],
  "type": "chain.listing_removed"
}

To indicate that a webhook message has been processed, return a HTTP 2XX status code (200-299) to the webhook message within a reasonable time-frame (15 seconds). If a non-200 is returned, or outside the required time-frame, re-tries will be attempted on an exponential backoff schedule over the course of approximately one day.