API reference
Floor
“Floor price” means two different numbers depending on who is asking. We return both, explicitly labelled, so you never have to guess which one you got.
Endpoint
/v1/collections/{id}/floorNo query parameters. {id} accepts a canonical slug, a contract address or collection mint, or a <chain>_<contract> document id — see identifier resolution.
curl "https://exclusivo.one/v1/collections/solgods_/floor"{
"data": {
"collectionId": "solana_85ghq5exuysxeu4aexgs7d44udegrf3bvf6gx8ysgame",
"askFloor": { "raw": "12500000000", "decimal": 12.5, "currency": "SOL", "usd": 2437.50 },
"buyerFloor": { "raw": "13500000000", "decimal": 13.5, "currency": "SOL", "usd": 2632.50 },
"aggregated": true,
"updatedAt": "2026-07-26T14:02:11.418Z",
"stale": false
}
}Cached for 10 seconds at the edge with a further 10 seconds of stale-while-revalidate. This is the fastest-moving figure the API publishes; polling harder than that spends rate limit on an unchanged response.
askFloor vs buyerFloor
This distinction is the entire reason this endpoint exists separately from stats.floor on the collection object. Getting it wrong does not produce an error; it produces a number that is quietly wrong by the size of the fee stack, in whichever direction hurts you.
| askFloor | buyerFloor | |
|---|---|---|
| Definition | The lowest price any seller is asking. | The lowest total a buyer would actually pay to complete a purchase right now. |
| Includes fees? | No. This is what the seller receives. | Yes — marketplace fee and creator royalty are added on top, or the external marketplace’s own buyer total is used. |
| Use it for | Comparing against another marketplace’s published floor; charting floor history; valuing a portfolio at what a holder could list into. | Any surface where a user is about to spend money: “buy now” buttons, sweep estimates, cart totals. |
| Relationship | Always the lower of the two, or equal when the cheapest fill carries no fees. | Never lower than askFloor. It can be materially higher on a high-royalty collection. |
The classic mistake
buyerFloor as “Exclusivo floor” next to another marketplace’s ask floor makes us look more expensive than we are by the full fee stack — several percent, and more on collections with a large royalty. Compare like for like: ask against ask. Show buyerFloor only where the number is a price someone is about to pay.The other classic mistake
askFloor and discovering the transaction needs more. On Solana the buyer needs the ask plus the platform fee plus the royalty in the wallet before signing. If you size a sweep from askFloor, the last few buys in the batch will fail on insufficient funds.The fee model
Exclusivo listings quote the seller ask. Fees are additive on top, so buyerFloor for an Exclusivo-native listing is:
buyerTotal = ask
+ ask × platformFeeBps / 10000
+ ask × royaltyBps / 10000
# platformFeeBps = 300 (3%) on Solana
# platformFeeBps = 200 (2%) on every EVM chain
# royaltyBps = the collection's royaltyBps (0 when unset)When the cheapest fill sits on an external marketplace rather than on our own order book, the arithmetic differs by source:
| Source of the cheapest fill | What buyerFloor contains |
|---|---|
| Exclusivo (Solana or EVM) | Seller ask plus our platform fee plus the creator royalty, exactly as above. |
| Magic Eden (Solana) | Magic Eden’s own buyer-facing price, taken as reported. Our aggregator fee is not folded into this figure. |
| OpenSea (EVM) | The OpenSea ask plus our aggregator fee (2% of the ask, added on top), because that is what a buyer routing the purchase through Exclusivo pays. |
buyerFloor is a minimum across heterogeneous sources
buyerFloor is not fixed, and the response does not tell you which source won. If you need to know, call the listings endpoint and read marketplace on the cheapest item.Where each floor comes from
askFloor
Resolved through a three-step cascade, taking the first source that yields a usable number:
- the live indexer analytics floor — the cheapest active listing in the mirror;
- the indexer collection row's stored floor price;
- the floor snapshot on our own collection document.
All three are seller-side. If every step fails or yields a non-positive value, askFloor is null.
buyerFloor
Resolved live against the marketplace overlays on every request, with an 8-second budget. If that resolve fails or times out, and the collection is on Solana or Ethereum, we fall back to a persisted last-good value with a 30-minute lifetime and set stale: true.
On Base, Ink, Polygon, ApeChain and Abstract there is no persisted store, so a failed resolve returns buyerFloor: null with stale: false. The absence of the flag does not mean the number is good — it means there was nothing to fall back to.
Aggregation and chains
aggregated is always true in the current implementation. It is a constant documenting a property of the endpoint, not a per-request signal: these floors combine our own order book with external marketplaces (Magic Eden on Solana, OpenSea on EVM). Do not branch on it.
Aggregation is across marketplaces, not across chains. A collection belongs to exactly one chain, the response is scoped to that collection, and the currency of both prices is that chain's native currency. There is no cross-chain floor, and no query parameter to request one — if you track the same brand on several chains, call this endpoint once per collection and compare the results yourself.
Comparing floors across chains
currency: "ETH", and both are different from Ethereum mainnet ETH in liquidity terms even though the symbol matches. Key your comparisons on the collection's chain, never on the currency symbol.Field reference
| Field | Type | Notes |
|---|---|---|
collectionId | string | The canonical document id of the resolved collection. Echoed so you can confirm which collection your identifier resolved to. |
askFloor | Price | null | Cheapest seller ask. Null when no source produced a positive floor — typically a collection with no active listings anywhere. |
buyerFloor | Price | null | Cheapest buyer all-in total. Null when the live resolve failed and no last-good value exists. |
aggregated | boolean | Always true. Marks that these floors span Exclusivo plus external marketplaces. |
updatedAt | string (ISO 8601) | The moment this response was generated — not the moment the underlying floor was observed. See below. |
stale | boolean | True only when buyerFloor came from the persisted last-good store. Never reflects askFloor. |
Errors: not_found when the identifier does not resolve, or when it resolves to a collection whose chain is unknown; rate_limited at 300 req/min.
Gotchas
updatedAt is not a data timestamp
updatedAt is stamped when the response is built, so it is always “now” — even on a stale: true response carrying a floor that could be up to 30 minutes old, and even when the CDN serves the payload again seconds later. It cannot be used to detect staleness, to order two responses, or to decide whether the floor moved. Use stale for the freshness question and compare askFloor.raw / buyerFloor.raw between polls to detect movement.
stale does not apply to askFloor
The flag is only ever set by the buyer-floor fallback path. askFloor has its own silent cascade down to a stored snapshot, and that fallback is never flagged. A response with stale: false can still carry an askFloor from the stored snapshot because the indexer was unreachable.
null is unknown, not zero
Both floors are nullable, and a null means “we could not determine this”, never “the floor is zero” and never “nothing is listed”. Coercing null to 0 in a portfolio valuation writes a real holding down to nothing; coercing it to Infinity in a sweep quote makes the collection unbuyable. Propagate the unknown.
buyerFloor can exceed askFloor by more than the fees
The two figures are resolved from different source sets, so the cheapest ask and the cheapest fill are not always the same listing. An ask that exists in the indexer mirror but is not fillable through any live overlay will lower askFloor without lowering buyerFloor. Do not compute an implied fee rate by dividing one by the other.