Aggregator integration

Everything below uses the public read-only API at https://exclusivo.one/v1. There is no key and no signup. Two facts shape the whole design of an Exclusivo integration:

• Our EVM order book has no on-chain footprint. EVM listings are off-chain signed Seaport orders stored in our database, and cancels are database-only too. Neither produces a transaction. A crawler that only reads chain data will see our sales and never see a single listing.
• Each endpoint has its own cache TTL. Polling faster than the TTL returns the same cached body while still consuming your rate-limit budget, so the TTLs below are the natural poll intervals.

The two rate buckets are counted separately per IP: 120 requests per minute on the list bucket and 300 per minute on the item bucket. All responses are CORS-open (Access-Control-Allow-Origin: *) and every route answers OPTIONS.

Start from the collections list. It is cursor-paginated, sorted by volume by default, and ranks Exclusivo-launched collections first. Pass chain to restrict it to one chain and sort to switch between volume, floor and recent.

# first page, all chains
curl "https://exclusivo.one/v1/collections?limit=100"

# one chain, newest first
curl "https://exclusivo.one/v1/collections?chain=base&sort=recent&limit=100"

Store the id of every collection you see — it is the identifier every other endpoint accepts. The same endpoints also accept a raw contract address (EVM), a collection mint (Solana), or the platform slug, so you can address a collection with whatever you already have on file.

Sales and listings need different strategies because only one of them is an append-only log.

orderId is the cross-system join key. It is the Seaport order hash on EVM and the listing id on Solana, and the same value appears on a listing and on the sale that fills it. If you index Seaport logs yourself, the orderHash in OrderFulfilled matches our orderId exactly, which is what lets you attach our order book to your own chain-derived sales without heuristics.

• Address casing is not cosmetic. EVM addresses are returned lowercase and can be compared case-insensitively. Solana base58 addresses are case-sensitive; lowercasing one produces a different, invalid address, so never normalize them.
• Compare prices as integers. price.raw is a decimal string of base units (wei or lamports) and is exact; parse it with BigInt. price.decimal is for display and loses precision on large wei values.
• Filter on marketplace before you aggregate. Rows with a foreign marketplace slug are listings and sales we surface from another venue. If you already ingest that venue directly, counting our copy as well will double-count volume.

When an upstream source degrades we serve the last-good data and label it rather than failing or, worse, returning a silently empty result. Three flags exist:

Similarly, a 502 upstream_error means a data source is temporarily down. Retry it; never persist it as "no listings". And treat price.usd as advisory: it is null whenever the price feed is unavailable and always null for chains without a feed.

Limits are per IP, per minute, in two independent buckets: 120 on list endpoints (/collections, /listings, /sales) and 300 on single-item endpoints (/collections/{id}, /floor, /tokens/…). A 429 returns the standard error envelope with code rate_limited and carries Retry-After alongside X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (an ISO-8601 timestamp, not epoch seconds).

Budget from the list bucket, because that is the tighter one. At limit=100 a full listings walk costs one to three requests, so 120 requests per minute is roughly 40 collections fully re-read per minute. If you track more collections than that, tier them: poll the top by volume every 30 seconds and the tail every few minutes, and use the cheap /floor call — which draws on the 300/min item bucket — to decide whether a tail collection is worth paging at all.

const BASE = "https://exclusivo.one/v1";
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

// One shared fetcher: honours Retry-After, backs off on transient upstream
// errors, and throws on anything a retry cannot fix.
async function apiGet(path, { retries = 4 } = {}) {
  for (let attempt = 0; ; attempt++) {
    const res = await fetch(BASE + path, { headers: { accept: "application/json" } });

    if (res.status === 429) {
      if (attempt >= retries) throw new Error("rate limited");
      const retryAfter = Number(res.headers.get("retry-after")) || 2;
      await sleep(retryAfter * 1000);
      continue;
    }

    // 502 upstream_error is transient — never persist it as "no data".
    if (res.status === 502) {
      if (attempt >= retries) throw new Error("upstream unavailable");
      await sleep(2 ** attempt * 1000);
      continue;
    }

    if (!res.ok) throw new Error((await res.json()).error.message);
    return res.json();
  }
}

Putting it together: a paging helper, a sales walk that stops at the watermark, and a listings walk that only closes out rows when the read was complete.

// Yields whole pages so callers can inspect pagination and meta.
async function* pages(path) {
  let cursor = null;
  do {
    const query = new URLSearchParams({ limit: "100" });
    if (cursor) query.set("cursor", cursor);   // omit it entirely on page 1
    const body = await apiGet(`${path}?${query}`);
    yield body;
    cursor = body.pagination.hasMore ? body.pagination.nextCursor : null;
  } while (cursor);
}

function listingKey(item) {
  if (item.orderId) return `${item.chain}:${item.orderId}`;
  const asset = item.mint ?? `${item.contractAddress}:${item.tokenId}`;
  return `${item.chain}:${asset}:${item.seller}:${item.price.raw}`;
}

async function syncListings(collectionId, store) {
  const seen = new Set();
  let degraded = false;

  for await (const page of pages(`/collections/${collectionId}/listings`)) {
    if (page.meta?.stale) degraded = true;
    for (const item of page.data) {
      const key = listingKey(item);
      seen.add(key);
      store.upsertListing(key, item);
    }
  }

  // Absent rows mean sold / cancelled / expired — but only when the read was
  // complete. A degraded page is missing rows, not reporting delistings.
  if (!degraded) store.closeListingsMissingFrom(collectionId, seen);
}

async function syncSales(collectionId, store) {
  const watermark = store.newestSaleTimestamp(collectionId); // ISO string or null

  for await (const page of pages(`/collections/${collectionId}/sales`)) {
    for (const sale of page.data) {
      if (watermark && sale.timestamp <= watermark) return;  // caught up
      store.upsertSale(`${sale.chain}:${sale.orderId ?? sale.tx}`, sale);
    }
  }
}

async function tick(collectionIds, store) {
  // Serial per collection keeps the list bucket (120/min) predictable. There is
  // no remaining-quota header on success, so raise concurrency only against a
  // budget you track yourself.
  for (const id of collectionIds) {
    await syncSales(id, store);
    await syncListings(id, store);
  }
}

• The listings window is bounded. Roughly the 250 cheapest active listings per collection. Do not treat a completed walk as proof that no deeper listings exist.
• There is no cancel event of any kind. Disappearance from the listings snapshot is the only cancel signal, and it does not distinguish sold from cancelled from expired. Join against /sales by orderId to tell them apart.
• Sales cursors reference a specific row. A cursor that can no longer be resolved returns 400 bad_request. Handle it by restarting that collection's walk from the newest page rather than retrying the cursor.
• ApeChain activity is API-only. It routes through a different fulfilment path and carries none of our on-chain attribution markers, so nothing about it is reconstructible from chain data.
• Prices are the seller ask. Marketplace fee and royalty are charged to the buyer on top, so a listing's price is exactly what the seller receives — see Floor for the ask-versus-buyer distinction.

Once you are ingesting, the natural next step is proving it: Verify listings on-chain shows how to confirm any sale we report directly from chain data.