Skip to content
rare
⌘K
Marketplace API

Getting started

Caching

The Cache-Control values the rare.market API sends for each endpoint family, and how to cache responses in your client.

Every successful JSON response has a Cache-Control header that says how long you can reuse it. Caching what you can keeps your app fast and keeps you under the rate limit.

Cache-Control by endpoint

EndpointsCache-Control
Most reads: collections, collection details, items, traits, holders, orders, offers, events, accounts, search, home, deals and most analyticspublic, max-age=5, stale-while-revalidate=30
GET /statuspublic, max-age=10, stale-while-revalidate=30
Slow-moving reads: GET /policies/{type}, GET /collections/{slug}/about, GET /collections/{slug}/holder-quality, GET /collections/{slug}/bubblespublic, max-age=300, stale-while-revalidate=600
Quotes (POST /quotes/*), sessions and /me, POST /types/report, gas sponsor routes, notification routes, an owner's hidden items (GET /accounts/{address}/items?hidden=true)no-store
Streams (GET /stream, GET /notify/stream)no-store
ErrorsNo Cache-Control header (no-store on 401, 429 and 503 busy)

Routes in the API reference also send s-maxage, so the edge in front of the API keeps their answers for a short while (5 seconds for listings, offers and activity, up to a day for Walrus shares; the reference lists each as x-edge-cache-seconds). Requests answered from the edge cache are fast and do not count toward your rate limit. A request that carries an Authorization header is never cached.

What the values mean:

  • max-age=5: the response is fresh for 5 seconds. Reuse it without asking again.
  • stale-while-revalidate=30: for 30 seconds after that, you can show the stale copy while you fetch a new one in the background.
  • no-store: do not cache. The answer is personal or changes with every call.

Validators

JSON responses do not send ETag or Last-Modified, and the API does not answer 304 Not Modified. Revalidating means fetching the full response again.

How fresh the data is

Cache-Control is not the only delay. Some aggregates, such as collection rankings and stats, are computed on the server every few seconds, so two requests a moment apart can return the same values. Analytics responses carry asOf: the time of the newest event their results include. Compare asOf to decide whether a result changed instead of comparing whole bodies.

For prices, listings and activity that must be current, subscribe to the event stream instead of polling (see Activity feeds). Before a purchase, ask for a quote with POST /quotes/buy: quotes are no-store and mark each line available or not.

Caching in your client

  • Respect max-age. Do not fetch the same URL again inside its fresh window. Browsers and most HTTP caching libraries do this for you.
  • Key by the full URL. Query parameters (window, sort, limit, cursor, filters) change the response.
  • Use stale data while you refresh. Inside the stale-while-revalidate window, show the cached copy and refresh in the background.
  • Never cache no-store responses or errors.
  • Share a cache across users on your server. All public responses are the same for every caller, so one cached copy can serve all your users.

A small in-memory cache that follows max-age:

# Show the caching header for a request.
curl -s -D - -o /dev/null "https://rare.market/api/v1/collections/popkins" | grep -i cache-control
--
TPS:--