Authentication & Rate Limits
How to authenticate against the PerpCity Bot API - the X-API-Key header, getting a key in the browser or from a wallet, error codes, and rate limits.
Every data request to the Bot API carries an API key in the X-API-Key header:
curl -H "X-API-Key: pc_bot_your_key_here" "https://testnet-bot-api.perp.city/markets?limit=5"Keys are prefixed pc_bot_. The full key is shown only once, when it is created; after that, only a preview is listed. GET /health (and, on testnet, /time and /height), /docs and /openapi.json need no key. WebSocket clients send the key in their first message instead of a header (see below).
Getting a key
Each account can hold at most 5 active keys. Creating a sixth returns 429; revoke one first.
In the browser
Sign in with email or a wallet at perp.city/developer and create a key. The page lists and revokes your keys too.
From a wallet
A bot or agent that controls a wallet can mint its own key, with no browser:
POST /auth/wallet/challengewith{"address": "0x..."}. The response has anonce, amessage, andexpires_at: the challenge is valid for 5 minutes and can be used once.- Sign the
messagewith the wallet (EIP-191personal_sign). POST /auth/wallet/keyswith{"nonce": "...", "signature": "0x..."}. Optional fields:name(up to 100 characters) andexpires_in_days(1 to 365). The response contains the new key.
The wallet must hold at least 0.0002 ETH on the API's network when it mints. Minting is limited to 10 requests per minute per IP address.
With a wallet-minted key, GET /auth/wallet/keys lists your keys and DELETE /auth/wallet/keys/{key_id} revokes one, so a bot can rotate its own keys.
On testnet, GET /me describes the calling key and the trading account it is bound to. GET /me/positions is GET /positions for that account; it returns 409 no_trading_address if the key is not bound to one. Mainnet does not serve these routes yet.
Error responses
Authentication and rate-limit errors return a stable code in error.code. Branch on the code: the message text can change, the codes will not.
{
"detail": "Missing API key. Pass your key in the X-API-Key header. See https://docs.perp.city/bot-api/authentication.",
"error": {
"code": "missing_api_key",
"message": "Missing API key. Pass your key in the X-API-Key header. See https://docs.perp.city/bot-api/authentication."
}
}| Status | error.code | Meaning |
|---|---|---|
401 | missing_api_key | No X-API-Key header |
401 | invalid_api_key | The key does not exist or was revoked |
401 | expired_api_key | The key passed its expires_in_days; mint a new one rather than retrying |
429 | rate_limited | Over the rate limit; wait for Retry-After |
Rate limits
Each key gets 120 requests per minute, counted over a sliding window, so there is no fixed reset at the top of the minute. Responses carry:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed per minute (120) |
X-RateLimit-Remaining | Requests left in the current window |
X-RateLimit-Reset | Seconds until the window frees a request (a duration, not a timestamp) |
Over the limit, the API returns 429 with Retry-After in seconds. The limit is enforced per server process, so treat the headers as approximate and always handle 429. A fetch wrapper that waits for Retry-After, with capped exponential backoff as a fallback:
async function botApiFetch(url: string, apiKey: string, maxRetries = 5): Promise<Response> {
let backoffMs = 1_000;
for (let attempt = 0; ; attempt++) {
const res = await fetch(url, { headers: { "X-API-Key": apiKey } });
if (res.status !== 429 || attempt >= maxRetries) return res;
const retryAfter = Number(res.headers.get("Retry-After"));
const waitMs = retryAfter > 0 ? retryAfter * 1_000 : backoffMs;
await new Promise((resolve) => setTimeout(resolve, Math.min(waitMs, 60_000)));
backoffMs = Math.min(backoffMs * 2, 60_000);
}
}WebSocket
WebSocket clients do not send the X-API-Key header. Within 10 seconds of connecting to /ws, send the key as the first message:
{ "api_key": "pc_bot_your_key_here" }A valid key gets {"status": "authenticated"}. A missing, invalid or expired key closes the socket with code 4001. The subscription protocol is on the Bot API page.