Bot API
The PerpCity Bot API - indexed, read-only REST and WebSocket market data for trading bots, liquidators, and AI agents.
The Bot API is a read-only API over indexed PerpCity data: markets, prices, trades, positions, and liquidation candidates. Bots use it so they do not need their own chain indexer. It does not place trades; trades are on-chain transactions sent with an SDK.
| Mainnet (Arbitrum One) | Testnet (Arbitrum Sepolia) | |
|---|---|---|
| Base URL | https://bot-api.perp.city | https://testnet-bot-api.perp.city |
| Interactive docs | /docs | /docs |
| OpenAPI spec | /openapi.json | /openapi.json |
The OpenAPI spec is the complete reference for request parameters and response fields. This page covers what the spec does not: how fresh the data is, which endpoints to use for what, and how to use the liquidation feeds.
Testnet runs a newer build
Mainnet does not yet serve /height, /time, /me or /me/positions, and its responses do not carry the X-Indexed-* headers. Everything else on this page works on both networks. Each network's OpenAPI spec lists the routes it serves.
Data freshness
The API never makes on-chain calls per request. Every answer is as of the latest indexed block:
- Every response carries
X-Indexed-BlockandX-Indexed-Atheaders. GET /heightreturns the same block and its time. It is a lower bound: a block with no PerpCity event writes no indexed row.GET /healthreportslag_seconds, the age of the indexed head.GET /timereturns the server clock, so you can measure your own clock skew first.
These are testnet-only for now (see above). On mainnet, GET /health returns only {"status": "ok"}. Confirm anything you are about to act on against the chain.
Authentication
Send an API key in the X-API-Key header on every data request. Keys are prefixed pc_bot_ and are self-service: create one at perp.city/developer, or have a bot mint its own by signing a challenge with its wallet. The limit is 120 requests per minute per key. Authentication & Rate Limits covers both ways to get a key, the error codes, and how to handle 429.
Quick start
BASE=https://testnet-bot-api.perp.city
KEY=pc_bot_your_key_here
# Active markets, largest open interest first
curl -s -H "X-API-Key: $KEY" "$BASE/markets?active=true&sort=open_interest&order=desc&limit=10"
# Live mark, index and funding for one market
curl -s -H "X-API-Key: $KEY" "$BASE/markets/0xPERP_ADDRESS/live"
# Liquidation candidates for one market
curl -s -H "X-API-Key: $KEY" "$BASE/positions/liquidatable?perp_address=0xPERP_ADDRESS"List endpoints return { "items": [...], "total": ..., "limit": ..., "offset": ..., "has_more": ... }.
Endpoints
Markets
Markets are keyed by the address of their Perp contract.
| Endpoint | Returns |
|---|---|
GET /markets | All markets. Filter with q (name, symbol or ticker), beacon, active, has_liquidity, min_open_interest, max_open_interest; sort by open_interest, funding, liquidity or created |
GET /markets/{perp_address} | One market |
GET /markets/{perp_address}/live | Live mark, index and funding state |
GET /markets/{perp_address}/stats | 24-hour stats |
GET /markets/{perp_address}/snapshots | Historical snapshots, filtered by start_time / end_time |
GET /markets/{perp_address}/trades | Recent trades, filtered by start_time / end_time |
GET /markets/{ticker}/history | The full index history for a market's ticker, including source data from before the beacon was on-chain |
All of these take limit and offset:
| Endpoint | Default limit | Maximum |
|---|---|---|
/markets | 100 | 500 |
/snapshots | 100 | 1000 |
/trades | 50 | 500 |
/history | 500 | 1000 |
Positions
| Endpoint | Returns |
|---|---|
GET /positions | Positions, filtered by holder, perp_address, is_open, is_maker, is_long |
GET /positions/{position_id} | One position |
GET /me/positions | The calling key's own positions (testnet only for now) |
GET /positions and /me/positions take limit (default 100, maximum 500) and offset.
Liquidations
| Endpoint | Returns |
|---|---|
GET /positions/liquidatable | Liquidation candidates with health, distance to liquidation, and estimated reward |
GET /positions/risk | Every open position, makers and unlisted markets included, with keyset pagination |
GET /liquidation-markets | The contract version and liquidation mode of each market |
/positions/liquidatable is a permissive candidate list computed from indexed data. A row means "worth checking", not "liquidatable". Each row carries the arguments a liquidation needs (id, perp_address, is_maker, amount). Simulate the call before you send it, then send it only if the simulation succeeds. Sort by most_underwater (default) or largest_reward. Set listed_only=true to skip markets the app no longer lists.
/positions/liquidatable takes limit (default 100, maximum 500) and offset. /positions/risk is for bots that keep their own risk model. It has no offset: page with after_perp and after_id from the last row, with limit up to 500 (the default). The feed is live, not a snapshot, so repeat full sweeps to pick up new positions. A position missing from the feed is not proof that it closed on-chain.
Contract versions
Markets created since October 2026 run contracts v0.2.2, whose liquidateTaker / liquidateMaker take a third argument, the amount. Use GET /liquidation-markets to see which version a market runs, and check that your SDK release supports it: Ecosystem lists which do.
WebSocket
WS /ws streams live prices and trades.
- Within 10 seconds of connecting, send
{"api_key": "pc_bot_..."}. The reply is{"status": "authenticated"}. An invalid or expired key closes the socket with code4001. - Subscribe to prices for some markets, or for all of them with
"*":{"method": "subscribe", "channel": "prices", "markets": ["0x...", "*"]} - Subscribe to trades:
{"method": "subscribe", "channel": "trades"}. Send"method": "unsubscribe"with the same fields to stop either channel.
Data frames are {"channel": "prices", "data": ...} and {"channel": "trades", "data": ...}. The server sends {"type": "heartbeat"} every 30 seconds.
Legacy /v1 routes
The /v1/* routes are frozen for older bots and get no new fields. Use the unversioned paths above.
Trading Bots and Agents
How trading bots and AI agents read PerpCity market data and place trades - the Bot API, SDKs, and wallet requirements.
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.