Hub

API reference

The hub is an API first. This site is one client of it: every page is built from the calls below, and each example here runs against the live book.

Basics

The base URL is https://pandoexchange.com. Reads need no key. Requests and responses are JSON.

  • A collection is named by its chain id and contract address, as in 1/0x5af0d9827e0c53e4799bb226655a1de152a425a5.
  • Amounts are wei, as decimal strings, in fields ending in Wei. They are never floating-point numbers.
  • NFTX liquidity prices are indicative spot prices before redemption fees, price impact and gas. A pool's inventory count does not mean all its NFTs can be bought for the displayed unit price. A purchase needs a fresh quote for the selected tokens and quantity.
  • priceWei is the maker's price. feeWei is the hub fee: zero for OpenSea on mainnet and for CryptoPunks. The new Space Poggers purchase quotes also charge zero Hub fee. takerWei includes any applicable Hub fee; NFTX spot entries remain indicative.
  • Lists come as { "object": "list", "data": [], "hasMore": false, "nextCursor": null }. Pass nextCursor back as cursor for the next page.
  • Every response carries a Request-Id header. Server-Timing says how long the hub spent on it.
  • Reads are cached close to the caller for a few seconds: collections for 5, depth for 1. For a live book, use the WebSocket.

Errors

A failed request answers with a status code and one shape:

{
  "error": {
    "type": "invalid_request",
    "message": "expected a 20-byte hex address",
    "param": "collection"
  }
}
invalid_request400. A parameter is missing or malformed. param names it.
unauthorized401. The route needs a token and did not get the right one.
not_found404. No such collection, listing or image.
unprocessable422. The request is well formed but cannot be carried out, such as a signature that does not match.
upstream_error502. A source the hub depends on failed.
not_configured503. This deployment is missing a setting the route needs.
rate_limited429. Too many requests needing a fresh chain read (pool estimates, purchase quotes) from one address this minute. Retry-After says when to try again.
internal_error500. A fault on our side. Quote the Request-Id.

Collections

Every collection includes capabilities describing cart availability, fee-preview pool IDs, pool-impact support and wallet-purchase status. NFTX inventory alone does not establish a supported purchase route. Currently only reviewed Ethereum Space Poggers has read-only fee previews; wallet purchases are paused across all collection pages and OpenSea API-sourced fills carry no Hub fee.

GET/v1/collections

Every collection on the hub, highest 7-day volume first, each with its floor from the merged book.

limit1 to 100. Default 50.
cursornextCursor from the previous page.
qMatch on name, slug or contract address.
curl https://pandoexchange.com/v1/collections?limit=5
GET/v1/collections/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5

One collection by chain id and contract address. This is the form to store.

curl https://pandoexchange.com/v1/collections/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5
GET/v1/collections/milady

The same collection by its slug, for when a person is typing.

curl https://pandoexchange.com/v1/collections/milady

The book

One merged order book per collection, from four sources: opensea, nftx, punks (the market inside the CryptoPunks contract, read from the chain) and native (listings made here). Listings are ranked by takerWei, which is what the buyer pays with the fee included, so a cheaper-looking listing on another source does not jump the queue. A token listed several times appears once, at its lowest price.

GET/v1/collections/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5/depth

The best listings and offers across every source. best.collectionBid is the highest collection-wide ETH/WETH offer after venue fees and any Hub fee, before gas; token-specific bids (such as CryptoPunks contract bids) remain in bids and best.bid. Space Poggers includes independent NFTX V2/V4 sell estimates and CryptoPunks an NFTX V4 one, marked priceKind=estimate and venueVersion; NFTX estimates and punk bids carry the Hub fee (FEE_BPS, 0.5%) in feeWei. sellSources distinguishes an empty offer feed from an unavailable one. ETH and WETH are compared 1:1 and retain their denomination. No sale is simulated or sent by this read.

limitEntries per side, 1 to 200. Default 25.
curl https://pandoexchange.com/v1/collections/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5/depth?limit=5
WS/v1/collections/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5/ws

A WebSocket. It sends the current depth on connect, then the new depth each time the book changes. Send the text ping and it answers pong.

wscat -c wss://pandoexchange.com/v1/collections/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5/ws
GET/v1/collections/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5/tokens

Minted NFTs in numeric token-ID order. Each page includes known ownership, indexed listings and traits, and finalized indexing progress. Unlisted items have permanent token pages.

cursorThe decimal nextCursor from the previous page.
ownerFilter by holder address. Add offers=1 to find tokens with Hub offers.
traitType, traitValueUse both to filter by an indexed trait.
curl https://pandoexchange.com/v1/collections/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5/tokens?limit=50
GET/v1/collections/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5/tokens/4267

One token by its exact decimal ID. A missing token returns 404 when absence is established. An unresolved lookup returns 503.

curl https://pandoexchange.com/v1/collections/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5/tokens/4267
POST/v1/collections/1/0xeee6674eee16d03e6e3e69b4eba866d98b881a23/tokens/42/offers/preview

Preview a Syzygy offer for a single token. Supply a public bidder address, priceWei in WETH and a Unix expiration within 30 days. The response gives the creator royalty, Hub fee, seller proceeds and approval status. Wallet signing is paused.

curl https://pandoexchange.com/v1/collections/1/0xeee6674eee16d03e6e3e69b4eba866d98b881a23/tokens/42/offers/preview \
  -H 'content-type: application/json' \
  -d 'undefined'
GET/v1/collections/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5/items

Every listing and every NFT held by an NFTX pool, as one list, cheapest first. Pool NFTs are priced from the stored chosen-NFT curve where there is one (priceKind=estimate: V2 fees included; V4 from NFTX's quote for one, swap fees and price impact included), else at the pool's spot price (priceKind=indicative, fees extra); listings are priceKind=listing. Each item carries its venue and traits (null while unread). facets gives the count each venue and trait value would show with the other filters applied. Neither a quote nor a reservation.

venueComma-separated: opensea, nftx-v2, nftx-v4, punks, native.
traitType:Value, repeatable. Values of one type are alternatives; different types must all match. Items whose traits are unread never match.
qWords to match: a whole number matches a token ID exactly; any word matches trait text. Up to 100 characters.
likeA token ID. Orders the list by how closely each NFT's traits match that token's: most trait values shared first, then rarer shared values, then cheapest. Values that only say a trait is missing ("None") are not counted. Each item gains match: matched of of trait values, and score (0 to 1, weighted by rarity). NFTs sharing no trait, or not yet read, are left out.
limitItems per page, 1 to 1000. Default 100.
cursorThe nextCursor from the previous page.
curl https://pandoexchange.com/v1/collections/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5/items?limit=5
GET/v1/collections/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5/traits

Traits of every NFT that is listed or held by a pool, as [type, value] pairs by token ID. Read from each token's own metadata (OpenSea's copy where the metadata is on IPFS, which Workers cannot reach), for reviewed collections only, a few dozen tokens a minute. read, pending and failed say how far that has got.

curl https://pandoexchange.com/v1/collections/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5/traits
GET/v1/collections/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5/liquidity

NFTX V2 vaults and the V4 pool for this collection, including inventory counts and indicative ETH spot prices. Answered from the book's own reads (V2 every minute, V4 every five), so it is fast; asOf says when. A version that could not be read keeps its last inventory and reports the failure in errors. These are inventory reads, not executable purchase quotes.

includetokens: add every pool's token IDs, keyed by pool id.
curl https://pandoexchange.com/v1/collections/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5/liquidity
GET/v1/collections/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5/liquidity/v4/tokens

Individual NFTs held by a pool. Use the pool id from the liquidity response (for example v4 or v2-174). Follow nextCursor until hasMore is false. Pages come from the book's last read; before its first read, V2 pages read one Ethereum block and V4 uses the upstream cursor.

limitTokens per page, 1 to 100. Default 100.
cursorThe opaque nextCursor from the previous page.
curl https://pandoexchange.com/v1/collections/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5/liquidity/v4/tokens?limit=100
GET/v1/collections/1/0x4a8b01e437c65fa8612e8b699266c0e0a98ff65c/liquidity/v4/impact

Read-only basket estimates for reviewed Ethereum ERC-721 collections with NFTX V2 or V4 pools. Returns collection identity, aggregate basket cost, the next NFT's marginal cost and its change in basis points. V2 includes swap and target-redemption fees. V4 estimates the collection tokens needed for floor redemption, including swap fees. NFT eligibility and actual purchase execution still need separate checks. Hub fees and gas are extra. Selection does not reserve or buy NFTs. No wallet needed; never cached.

quantityNFTs selected from this pool, 0 to 100, bounded by available inventory. Default 0. Use v2-174 or v4 as the pool id.
curl https://pandoexchange.com/v1/collections/1/0x4a8b01e437c65fa8612e8b699266c0e0a98ff65c/liquidity/v4/impact?quantity=2
GET/v1/collections/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5/activity

Sales, mints, transfers and burns, newest first, read from the chain by the collection's book: no marketplace API is involved. A sale settled through Seaport, NFTX V2 or V4, Payment Processor or the CryptoPunks contract carries its price, venue and side (buy: a listing or pool NFT was bought; sell: an offer was accepted or an NFT sold into a pool). priceWei is what the buyer paid, venue fees and royalties included; a sale into a pool is what the seller received. quantity above 1 means one payment bought that many NFTs and priceWei is an equal share of it. A sale settled anywhere else is a transfer with no price. The book follows the chain three blocks behind its head and starts thirty days back; index says how far it has read, how many transactions still await their receipts, and why the last read failed if it did. Reviewed Ethereum ERC-721 collections and CryptoPunks only.

typeComma-separated: sale, mint, transfer, burn. Default: all four.
tokenIdOnly this token's events.
sinceUnix seconds. Nothing older.
limitEvents per page, 1 to 1000. Default 50.
cursorThe nextCursor from the previous page (an event id, blockNumber:logIndex).
curl https://pandoexchange.com/v1/collections/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5/activity?type=sale&limit=5
GET/v1/collections/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5/floor-history

The floor (what the cheapest NFT cost a buyer, after venue fees) and the best collection-wide offer (net to a seller), as the book recorded them: one point each time either changed, and at least one an hour. before is the record in force at the start of the range. A listing is signed off chain, so nothing earlier than recordingSince can be read back. ETH and WETH are counted 1:1.

range1d, 7d, 30d or 90d. Default 7d.
curl https://pandoexchange.com/v1/collections/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5/floor-history?range=7d
GET/v1/collections/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5/stats

How many orders the book holds and how quickly events reach it, as percentiles in milliseconds.

curl https://pandoexchange.com/v1/collections/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5/stats

Listings

A listing made here is a standard Seaport 1.6 order with the fee as one of its payment lines, so the seller signs the fee along with the price. Listing is two calls: get the data to sign, then send the signature.

POST/v1/collections/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5/listings/build

Returns the typed data for the seller's wallet to sign, and the order hash.

curl https://pandoexchange.com/v1/collections/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5/listings/build \
  -H 'content-type: application/json' \
  -d '{"offerer":"0x1111111111111111111111111111111111111111","tokenId":"4267","priceWei":"1000000000000000000"}'
POST/v1/collections/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5/listings

Puts the signed order on the book. The signature and the fee line are checked first.

curl https://pandoexchange.com/v1/collections/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5/listings \
  -H 'content-type: application/json' \
  -d '{"order":"the message from the build call","signature":"0x…"}'

Fills

The purchase quote route checks a Space Poggers purchase against the buyer's actual wallet state before returning it. The older fill routes only encode transactions. The hub never holds funds or keys, and the server never sends a transaction.

POST/v1/collections/1/0x4a8b01e437c65fa8612e8b699266c0e0a98ff65c/purchases/quote

A fresh, simulated purchase of selected Space Poggers. NFTX: choose v2-174 or v4 and up to ten tokenIds. OpenSea: source opensea, one tokenId and orderHash. Returns a maximum spend, short expiry and unsigned transaction. No Hub fee. Quotes are never cached; the actual buyer needs enough ETH for the maximum and gas.

curl https://pandoexchange.com/v1/collections/1/0x4a8b01e437c65fa8612e8b699266c0e0a98ff65c/purchases/quote \
  -H 'content-type: application/json' \
  -d '{"source":"nftx","poolId":"v2-174","tokenIds":["4"],"buyer":"0x2222222222222222222222222222222222222222","slippageBps":100}'
POST/v1/collections/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5/fills/native

The transaction that buys one of the hub's own listings.

curl https://pandoexchange.com/v1/collections/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5/fills/native \
  -H 'content-type: application/json' \
  -d '{"orderHash":"0xabababababababababababababababababababababababababababababababab","fulfiller":"0x2222222222222222222222222222222222222222"}'
POST/v1/collections/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5/fills/opensea

Encodes an OpenSea fill without a Hub fee on mainnet while written commercial permission is absent. This low-level route does not simulate; the page uses purchases/quote instead.

curl https://pandoexchange.com/v1/collections/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5/fills/opensea \
  -H 'content-type: application/json' \
  -d '{"orderHash":"0xabababababababababababababababababababababababababababababababab","fulfiller":"0x2222222222222222222222222222222222222222"}'

Images

Token images are read from the chain once, stored, and served from here. They are served only for collections the hub has reviewed.

GET/img/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5/4267

A token's image. Add ?size=full for the original; the default is a smaller copy when one was made.

curl https://pandoexchange.com/img/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5/4267
GET/img/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5

The collection's own picture.

curl https://pandoexchange.com/img/1/0x5af0d9827e0c53e4799bb226655a1de152a425a5