Perp CityDocs

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:

  1. POST /auth/wallet/challenge with {"address": "0x..."}. The response has a nonce, a message, and expires_at: the challenge is valid for 5 minutes and can be used once.
  2. Sign the message with the wallet (EIP-191 personal_sign).
  3. POST /auth/wallet/keys with {"nonce": "...", "signature": "0x..."}. Optional fields: name (up to 100 characters) and expires_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."
  }
}
Statuserror.codeMeaning
401missing_api_keyNo X-API-Key header
401invalid_api_keyThe key does not exist or was revoked
401expired_api_keyThe key passed its expires_in_days; mint a new one rather than retrying
429rate_limitedOver 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:

HeaderMeaning
X-RateLimit-LimitRequests allowed per minute (120)
X-RateLimit-RemainingRequests left in the current window
X-RateLimit-ResetSeconds 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.

On this page