Authentication

Access model

The API is in private beta. Anonymous requests work for evaluation at a low rate limit; an API key unlocks production limits and gets your usage tracked under your name.

Tier	How	Rate limit
Anonymous	nothing — just call the API	30 requests / minute / IP
API key	X-API-Key header	600 requests / minute / key

1. Get a key

Keys are issued manually during the beta — there is no self-serve signup yet. Request one from the TiltDesk team (Telegram or email) with:

• who you are / project name (this becomes your key’s owner label),
• what you’re building and roughly how many requests you expect.

You’ll receive a key like td_live_yourname_…. Store it like a password — it is shown once and only a hash is kept server-side.

2. Use it

Send the key on every request as the X-API-Key header:

curl -H "X-API-Key: td_live_yourname_…" \
  "https://api.tiltdesk.xyz/v1/markets?category=crypto&limit=5"

There is no OAuth dance, no token refresh — one static header.

3. Handle limits and errors

Every response carries an X-Request-Id header — include it when reporting an issue and we can trace your exact request.

• Over the rate limit → 429 with a Retry-After header (seconds). Back off and retry.
• Invalid or revoked key → 401 with code invalid_api_key.
• All errors share one shape:

{ "error": { "code": "rate_limited", "message": "rate limit exceeded", "request_id": "19f1f…" } }

Rotation & revocation

Keys can be revoked (or re-enabled) server-side at any time and stop working within a minute. If your key leaks, tell us — we revoke and reissue immediately.