Rate limits

Each private key has its own limit, applied as a token bucket:

Setting	Default
Sustained rate	60 requests per minute
Burst	20 requests

The bucket holds up to 20 requests and refills at one per second, so short bursts are fine as long as the average stays under 60 a minute. If you need more, ask us; limits are set per key. A service-wide cap also protects the API as a whole.

When you hit the limit

The API returns 429 with a Retry-After header (seconds) and {"code": "rate_limited", ...}. Wait at least that long before the next request from that key.

curl

# -i shows the Retry-After header on a 429
curl -i https://api.nimbusmint.bot/partner/v1/health \
  -H "Authorization: Bearer $NIMBUS_PRIVATE_KEY"

Node

async function nimbusGet(url, attempt = 0) {
  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.NIMBUS_PRIVATE_KEY}` },
  });
  if (res.status === 429 && attempt < 3) {
    const wait = Number(res.headers.get('Retry-After') ?? '1');
    await new Promise((r) => setTimeout(r, wait * 1000));
    return nimbusGet(url, attempt + 1);
  }
  return res;
}

Python

import time

def nimbus_get(url, params=None, attempt=0):
    res = requests.get(url, headers=HEADERS, params=params, timeout=10)
    if res.status_code == 429 and attempt < 3:
        time.sleep(int(res.headers.get("Retry-After", "1")))
        return nimbus_get(url, params, attempt + 1)
    return res

The limit is per key, not per user

Every request made with a key counts against that key’s bucket, however many of your users caused it. A bot that calls the API once per user command will hit the limit as soon as it gets busy, which is exactly when you least want it to. Design for the number of collections you track, not the number of people using your product.

Stay under the limit

• Cache responses yourself. /hits returns cache_ttl_s (currently 30): reuse the answer for that many seconds instead of calling again; the API caches for that long anyway. Every response is sent with Cache-Control: no-store, so HTTP caches and proxies will not do this for you.
• Key the cache by the question, not the user. Use contract, chain_id, since and until (and top) as the key. A thousand users asking about the same collection are one cache entry.
• Coalesce concurrent requests. When ten commands arrive before the first answer comes back, send one request and give all ten the same result (a “single-flight” lock per cache key).
• Share one cache across your bot’s processes or shards, for example in Redis, so each process does not fetch the same answer separately.
• Do not poll /hits. Call it when a user asks (for example on /gas), not on a timer per collection.
• Sync /mints incrementally. Run it as a background job, not per user request: page with limit=500, store next_cursor, and resume from it on the next run instead of re-reading the whole window. Every few minutes is plenty.
• Call /health rarely. Once at startup and once a day is enough to watch your key’s expiry.
• Show something useful on a 429. Serve the last cached answer (and say how old it is) or your own data, rather than failing the command.

Tip

With a 30-second cache, one busy collection costs at most two calls a minute no matter how many people run /gas.

Retrying safely

• Retry only 429 and 503. Never retry 400, 401 or 403: they will fail the same way and still use your limit.
• Wait at least Retry-After seconds, add a little random jitter, and cap the number of attempts (three is plenty). Retrying immediately, or from every shard at once, keeps you limited for longer.
• Log every 429 with the endpoint and parameters. Repeated 429s on the same question usually mean a missing cache.

Planning for growth

• Ask before you need it. Limits are set per key, and we can raise yours. Tell us before a launch, a big drop or a marketing push, with the requests per minute you expect after caching.
• Use separate keys for separate jobs (for example one for your bot and one for a /mints sync), so a busy job cannot starve the other. A service-wide cap still applies to all keys together.

Do not work around the limit

Spreading traffic over extra keys, rotating keys or rotating IP addresses to avoid 429s breaks the Terms and can get your keys revoked. If the limit is too low for honest, cached use, ask us to raise it.