Perp CityDocs

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 URLhttps://bot-api.perp.cityhttps://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-Block and X-Indexed-At headers.
  • GET /height returns the same block and its time. It is a lower bound: a block with no PerpCity event writes no indexed row.
  • GET /health reports lag_seconds, the age of the indexed head. GET /time returns 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.

EndpointReturns
GET /marketsAll 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}/liveLive mark, index and funding state
GET /markets/{perp_address}/stats24-hour stats
GET /markets/{perp_address}/snapshotsHistorical snapshots, filtered by start_time / end_time
GET /markets/{perp_address}/tradesRecent trades, filtered by start_time / end_time
GET /markets/{ticker}/historyThe 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:

EndpointDefault limitMaximum
/markets100500
/snapshots1001000
/trades50500
/history5001000

Positions

EndpointReturns
GET /positionsPositions, filtered by holder, perp_address, is_open, is_maker, is_long
GET /positions/{position_id}One position
GET /me/positionsThe calling key's own positions (testnet only for now)

GET /positions and /me/positions take limit (default 100, maximum 500) and offset.

Liquidations

EndpointReturns
GET /positions/liquidatableLiquidation candidates with health, distance to liquidation, and estimated reward
GET /positions/riskEvery open position, makers and unlisted markets included, with keyset pagination
GET /liquidation-marketsThe 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.

  1. Within 10 seconds of connecting, send {"api_key": "pc_bot_..."}. The reply is {"status": "authenticated"}. An invalid or expired key closes the socket with code 4001.
  2. Subscribe to prices for some markets, or for all of them with "*": {"method": "subscribe", "channel": "prices", "markets": ["0x...", "*"]}
  3. 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.

On this page