Understanding null NFT field in OpenSea API cancellation events

NFT
1

I’m working with OpenSea’s event API and noticed something confusing about cancellation events. Some cancel events show complete NFT details while others have the nft field set to null.

Here’s what a typical cancel event looks like:

{
  "event_type": "cancel",
  "order_hash": "0x1f2e3d4c5b6a7890abcdef1234567890fedcba0987654321",
  "order_type": "listing",
  "maker": "0x3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d",
  "chain": "ethereum",
  "event_timestamp": 1726200000,
  "nft": {
    "identifier": "3421",
    "collection": "cool-cats-collection",
    "contract": "0x9a8b7c6d5e4f3g2h1i0j9k8l7m6n5o4p3q2r1s0t",
    "token_standard": "erc721",
    "name": "Cool Cat #3421",
    "description": "A collection of randomly generated cats",
    "image_url": "https://example.com/image.png",
    "display_image_url": "https://example.com/display.png",
    "metadata_url": "https://example.com/metadata/3421",
    "opensea_url": "https://opensea.io/assets/ethereum/contract/3421",
    "updated_at": "2024-08-20T10:15:30.123456",
    "is_disabled": false,
    "is_nsfw": false
  }
}

But then I see events like this: {"event_type": "cancel", "order_hash": "0x9f8e7d6c5b4a3210fedcba0987654321abcdef12", "order_type": "listing", "maker": "0x5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a", "chain": "ethereum", "event_timestamp": 1726200100, "nft": null}

What causes the nft field to be null in these cancellation events? What type of listings do these null NFT cancellations represent?

2

Yeah, this is super annoying when parsing events! Usually happens with trait-based offers where someone bids on “any NFT with blue eyes” or whatever. There’s no specific token so OpenSea just nulls it out. I’ve also seen this with expired listings where the NFT got transferred after listing but before cancellation - the API can’t match the token anymore so you get a null field.

3

You’ll see null NFT fields when dealing with collection-wide offers or bundle listings instead of individual NFTs. When someone cancels a collection offer (they’re bidding on any item from a collection, not a specific token), OpenSea can’t fill the nft field since there’s no specific NFT tied to that order. This also happens when the original NFT metadata goes missing or the contract has issues preventing OpenSea from grabbing current token details. I run into this all the time with older collections or during temporary API hiccups on OpenSea’s side. Bundle cancellations cause null values too since you’re dealing with multiple NFTs, not just one token. The API doesn’t handle multi-NFT stuff well in that field, so it just defaults to null.

4

hmm this is really interesting! I’ve been seeing the same pattern but never dug into it. So collection offers definitely cause this - but what about floor bids? Like when someone bids at floor price without picking a specific token?

Also curious - when you get these null nft events, can you trace back what the original offer targeted? Maybe through order_hash or another API field? Wondering if there’s a separate endpoint that gives more context about what these mystery cancellations actually were.

Another thing I’m noticing - do you see more null cancellations during high gas periods? Could be people canceling broad offers when gas gets expensive since they’re more likely to lose money on random fills? Just a theory but the timing seems to match in my data.