The OpenSea API field that lies: reading a collection's real listings

The collection/NFT endpoint returns an empty orders array for some API keys, which looks exactly like “nothing is listed”

I first treated the orders field on OpenSea’s collection/NFT response as listing state. That was a mistake.

For some API keys, the response contains this:

{
  "nft": {
    "identifier": "..."
  },
  "orders": []
}

The misleading field is orders. Its reported count is the length of an empty array, even when OpenSea’s UI shows an active listing for the same token.

That makes the failure difficult to detect. The request succeeds, the JSON parses, and the field has the expected type. There is no authentication error or warning saying that orders were omitted.

My decision rule is now: never interpret an empty orders array from the collection/NFT endpoint as proof that a token is unlisted. It only proves that this response returned no orders.

This matters to my restocking daemon. A false “unlisted” result can make it rebuild a Seaport listing that already exists. The direct cost is extra API and reconciliation work. The more serious cost is incorrect local state, because later automation starts from a false premise.

The endpoint that does return the real order set, and the two-line parser that maps it to token ids and prices

I fetch the collection-wide active set from:

GET /api/v2/listings/collection/{collection_slug}/all

I follow its pagination cursor until no further page is available. I also reject responses that do not contain the expected listing collection. A successful HTTP response is not enough; the payload shape must pass validation before it can replace my previous snapshot.

For each returned Seaport listing, the token identifier is in the offered item and the current amount is in the price object. This is the parser I use:

const live = listings.map(({ protocol_data: { parameters: { offer: [item] } }, price: { current } }) =>
  ({ tokenId: item.identifierOrCriteria, priceWei: current.value }));

I keep priceWei as a string. Converting it to a JavaScript number would create avoidable precision risk. Display formatting happens later.

I also scope the request and stored snapshot to the Base collection contract. Token identifiers are only meaningful inside that chain-and-contract boundary.

The rule is simple: the listings endpoint is authoritative for current OpenSea visibility; my database is a record of intent and prior actions.

Reconciling your own database against that live set: the query that finds rows you believe are listed but are not, and the reverse

After fetching all pages, I load the normalized results into a temporary live_listings table. Then I compare sets in both directions:

SELECT token_id, price_wei
FROM nft_inventory
WHERE listing_status = 'listed'
EXCEPT
SELECT token_id, price_wei
FROM live_listings;

SELECT token_id, price_wei
FROM live_listings
EXCEPT
SELECT token_id, listing_price_wei
FROM nft_inventory
WHERE listing_status = 'listed';

The first result contains database rows I believe are listed but OpenSea does not currently return. These require inspection before restocking because an expired, cancelled, delayed, or malformed listing should not all trigger the same action.

The reverse result contains live OpenSea listings missing from my local listed set, including price mismatches. I import or flag those before the daemon makes another order.

I do not mutate inventory when the listings request fails, pagination is incomplete, or parsing rejects an entry. In those cases, the previous successful snapshot remains in place. “Unknown” must not collapse into “unlisted.”

I use this reconciliation against the collection at https://thunderous-sunflower-a910b4.netlify.app.

Practical takeaway: replace any orders-array availability check with a paginated listings snapshot and run both set differences before automating listing changes.