Conventions

https://exclusivo.one/v1

Every endpoint is GET. Each one also answers OPTIONS for CORS preflight and nothing else — a POST, PUT or DELETE to a /v1 path is not handled by the API and will not do what you expect.

Two endpoints exist purely to help you discover the rest: GET /v1 returns the endpoint list, and GET /v1/openapi.json returns the OpenAPI 3.1 document. The spec document is served bare, without the data envelope described below, because it is the artifact your codegen tool consumes.

There is none. The API is public and read-only: no key, no bearer token, no signup, no origin allowlist. Do not send an Authorization header — it is ignored, and building your client around one will make migration harder if we ever add scoped keys.

Because there is no key, everything is scoped to your IP address instead. That is the unit the rate limiter counts.

Limits are per IP, per fixed 60-second window, and split into two independent counters. A burst of listing pages cannot exhaust your budget for single-token lookups, and vice versa.

When you exceed a bucket the response is a 429 carrying the standard error envelope with code rate_limited, plus these headers:

If a production integration needs more headroom, email dev@psukhe.media rather than sharding across IPs.

Successful responses are always an object with a data key. Single-item endpoints put an object there; list endpoints put an array there and add a pagination object.

{
  "data": { … }
}

{
  "data": [ … ],
  "pagination": {
    "nextCursor": "eyJrIjoibGlzdGluZ3Mtb2Zmc2V0IiwidiI6IjI1In0",
    "hasMore": true
  }
}

A third key, meta, appears only when a data source degraded — see Staleness flags. Treat it as optional: it is absent on a healthy response, and today only the listings endpoint ever emits it, even though the OpenAPI schema permits it on any list endpoint.

Errors are a single consistent shape. There is no partial-success mode: a request either returns data or returns error.

{
  "error": {
    "code": "bad_request",
    "message": "Invalid cursor."
  }
}

Those four codes are the complete set. message is human-readable and may change wording at any time — branch on code, never on message.

Upstream failure text is deliberately not passed through. If you need to know why a source degraded, the meta.staleSources array names it; the message will not.

Every list endpoint takes limit (default 25, minimum 1, maximum 100) and cursor. Cursors are opaque base64url strings. Internally they encode which pagination strategy minted them and a position value, but that encoding is an implementation detail and will change.

# page 1
curl "https://exclusivo.one/v1/collections?limit=50"

# page 2 — pass back exactly what you received
curl "https://exclusivo.one/v1/collections?limit=50&cursor=eyJrIjoiY29sbGVjdGlvbnMiLCJ2IjoiMjUifQ"

Responses are cached at the CDN edge, not in your browser. Each endpoint sends Cache-Control: public, s-maxage=N, stale-while-revalidate=2N, so a stale copy can be served for a further N seconds while a fresh one is fetched in the background.

Polling faster than s-maxage spends rate limit for a response that cannot have changed. Floor at 10 seconds is the fastest-moving figure we publish; nothing here is a substitute for a websocket, and we do not offer one.

The API is callable directly from a browser. Every response — success and error alike — carries:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Content-Type, Accept
Access-Control-Max-Age: 86400

Credentials are not supported and not needed. Because Allow-Headers is limited to Content-Type and Accept, adding a custom header to your fetch will fail preflight — send a plain GET.

Every monetary value in the API — floors, listing prices, sale prices, last sale — is the same four-field object.

{
  "raw": "1250000000",   // integer base units (lamports / wei), decimal string
  "decimal": 1.25,       // human-readable native amount
  "currency": "SOL",     // native symbol of the item's chain
  "usd": 243.75          // best-effort; null when no feed is available
}

Two chain families, two rules, and they are not interchangeable.

The {id} path segment on every collection endpoint accepts three forms, all resolving to the same collection:

• the canonical platform slug, e.g. solgods_;
• a raw contract address (EVM) or collection mint (Solana);
• a <chain>_<contract> document id, e.g. ethereum_0x8a90cab2b38dba80c64b7734e58ee1db38b8992e.

Responses return the document id in id (on collections) and collectionId (on listings, sales and tokens). Feeding that value straight back in as {id} always works, which is what makes it the right join key to store.

Exclusivo charges the buyer on top of the seller ask. A listing price is exactly what the seller receives, in every response, on every endpoint.

The practical consequence: the price on a listing and the askFloor on a collection are seller-side numbers, and a buyer will pay more than either. The one place we publish the buyer-side figure is buyerFloor on the floor endpoint.

We would rather serve last-known-good data with a flag than fail a request, so several endpoints degrade instead of erroring. The flag is not uniform, and each variant means something different.

The collections list endpoint has no degraded mode at all: if the index is unreachable it returns upstream_error rather than a partial page.