Authentication

Every read endpoint is public. You can call the API without an account, a key or a wallet. An API key identifies your app and gives it its own rate limit instead of sharing one with everything else on your IP address.

Anonymous access

Send requests with no credentials. Anonymous requests are rate limited per IP address. See Rate limits for the numbers.

curl "https://rare.market/api/v1/status"

{
  "suiUsd": 0.9123,
  "tps": 122,
  "checkpoint": 338534372,
  "degraded": false
}

Anonymous access suits scripts, prototypes and low-volume tools. If many users or servers share one IP address (an office network, a serverless platform, a shared host), they share one limit. Use a key in that case.

API keys

Get a free key at rare.market/developers: connect a Sui wallet and sign a message, no email. A wallet can hold up to 5 keys, and can regenerate or revoke each one there. The key is shown once; only a hash of it is stored. Send it with every request in the x-api-key header (header names are case-insensitive).

curl "https://rare.market/api/v1/collections?limit=5" \
  -H "X-API-Key: $RARE_API_KEY"

A key changes how you are rate limited: 300 requests a minute and 200,000 a day instead of 60 and 20,000 per IP address (see Rate limits). It does not change the data you get back: responses are the same with or without a key.

An unknown or revoked key answers 401 invalid_api_key; requests without a key are anonymous, never refused for the missing key. A browser EventSource cannot send headers, so /notify/stream also accepts the key as ?apiKey=.

Calling from a browser

Every route in the API reference allows any origin for GET (Access-Control-Allow-Origin: *), so a web page can call it directly, and the preflight allows the x-api-key header. Routes that are not in the reference (sessions, /me, quotes, the gas sponsor's POST routes) send no CORS headers and stay usable only from rare.market and from servers. Do not put a key in a public web page: browser calls work without one.

Wallet sessions

The session and /me routes are used by rare.market's own pages and are not part of the public reference, so they can change without notice. They are described here because the developers page uses them to manage API keys.

A few routes act for a wallet: the watchlist and hidden items under /me. They need a session token, which a wallet gets by signing a message. The wallet always comes from the session, never from the path or the body.

1. Request a challenge

   POST /session/challenge with { "address": "0x..." } (a full 64 hex character Sui address). The response is { message, nonce, expiresAt }. The challenge is valid for 5 minutes.

2. Sign the message

   Have the wallet sign message as a personal message. Wallet, zkLogin and passkey signatures all verify the same way. Signing does not create a transaction or cost gas.

3. Exchange the signature for a token

   POST /session with { address, message, signature }. The response is { token, expiresAt, me }. The token lasts 30 days.

4. Send the token

   Send Authorization: Bearer <token> on /me requests. DELETE /session with the same header signs out.

A missing, expired or unknown token on these routes returns 401 unauthorized.