> For the complete documentation index, see [llms.txt](https://docs.pangolin.exchange/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pangolin.exchange/pangoperps/public-info-api.md). # Public Info API Introduction ## Introduction The PangoPerps Public Info API provides read-only market, account, and platform data through one unauthenticated query endpoint. Set the type field to choose from 24 query types. No API key or signature is needed, including for queries that look up an account by wallet address. Monetary values are returned as decimal strings so clients can process the raw data and calculate their own indicators. This interface has a rate-limit pool separate from the REST and WebSocket APIs. It is useful for public dashboards, AI trading agents, quantitative analysis, copy-trading tools, address monitoring, and strategy backtesting. It can retrieve an address's positions, orders, fills, and PnL, as well as aggregated market or platform data. It is read-only: it cannot place orders, move funds, or change account settings. ### Quick start Each request is a JSON POST to the same endpoint. The type field selects the query. Market snapshot: ```sh curl -s -XPOST -H "Content-Type: application/json" \ https://api.orderly.org/v1/public/query \ -d '{"type":"marketSummary"}' ``` Account state for a wallet: ```sh curl -s -XPOST -H "Content-Type: application/json" \ https://api.orderly.org/v1/public/query \ -d '{"type":"accountState","address":"0x1234567890abcdef1234567890abcdef12345678","broker_id":"pangoperps"}' ``` Check the available request quota: ```sh curl -s -XPOST -H "Content-Type: application/json" \ https://api.orderly.org/v1/public/query \ -d '{"type":"rateLimitStatus"}' ``` ### Endpoint ```http POST https://api.orderly.org/v1/public/query Content-Type: application/json ``` ```json { "type": "", "...": "..." } ``` Every query uses this URL. Include the query parameters in the JSON request body. The type value determines which handler processes the request. ### Response format Success: ```json { "success": true, "data": { "...": "query-specific result" }, "ts": 1779269143700 } ``` Error: ```json { "success": false, "code": "INVALID_PARAM", "message": "...", "type": "", "ts": 1779269143700 } ``` ts is the server's response timestamp in milliseconds since the Unix epoch (UTC). ### Error codes | Code | HTTP status | Meaning | | ----------------------- | ----------: | --------------------------------------------------------------------------------------- | | UNKNOWN\_TYPE | 400 | type is missing or does not name a registered query. | | MISSING\_PARAM | 400 | A required field was not supplied. | | INVALID\_PARAM | 400 | A provided field has an unsupported type, value range, or format. | | ADDRESS\_NOT\_FOUND | 404 | The address, optionally narrowed by broker\_id or account\_id, resolves to no accounts. | | ORDER\_NOT\_FOUND | 404 | orderStatus could not find the order in either live or archived data. | | RATE\_LIMIT\_EXCEEDED | 429 | The caller has exceeded its IP-based request quota. | | INTERNAL\_ERROR | 500 | An unexpected server error occurred. | | SERVICE\_UNAVAILABLE | 503 | A downstream service timed out; this is usually temporary and can be retried. | | POSITION\_CALC\_TIMEOUT | 503 | The position-calculation service timed out. | A RATE\_LIMIT\_EXCEEDED response also includes retry\_after as a millisecond epoch and a Retry-After HTTP header in seconds. ### Address resolution For requests with an address, the service looks up the accounts associated with that wallet. Use the optional broker\_id and account\_id fields to narrow the result: | Supplied fields | Accounts included | | ------------------------------------ | ----------------------------------------------------------- | | address | All REGULAR and SUB accounts associated with that address. | | address and broker\_id | All accounts for the address under that broker. | | address and account\_id | One specified account; this commonly returns a flat object. | | address, broker\_id, and account\_id | One account within that broker. | For PangoPerps-scoped account lookups, set broker\_id to pangoperps. If no matching account exists, the API returns ADDRESS\_NOT\_FOUND with HTTP status 404. The accountState and feeRate response formats differ depending on whether an account\_id is included; see their individual sections. ### Pagination Paginated queries return data.next\_cursor. Submit that value as cursor in the next request. The value is an opaque Base64 cursor; pass it back as-is rather than parsing it. It is null when the final page has been reached. Cursor internals differ by query and can change. | Query types | Cursor representation | | ---------------------------- | ------------------------------------------ | | candles, fundingRateHistory | { "last\_ts": } | | openOrders, historicalOrders | { "last\_ts": , "last\_id": \ } | | trades | { "last\_id": \, "src": } | | fundingPayments | { "last\_id": \ } | | liquidations | { "last\_id": \ } | | userDepositsWithdrawals | { "last\_id": \ } | | portfolio | { "last\_date": } | | topAddresses | { "last\_value": "" } | | platformPositions | { "last\_id": \ } | marketSummary, marketTrades, fundingComparison, orderbook, and rateLimitStatus return their bounded result in one response and do not paginate. ### Time conventions * All timestamps are Unix epoch milliseconds in UTC. * Valid timestamp values range from 0 through 253402300799000 (year 9999). Values outside this range return INVALID\_PARAM. * Some queries align their default lookback period to UTC day boundaries; the applicable query section identifies those defaults. ### Rate limits This API uses a quota separate from the REST and WebSocket interfaces: calls here do not use their quota, and their calls do not use this quota. Usage is measured in weight units per IP over a rolling one-minute window. An anonymous IP has a default allowance of 1,200 weight units per minute. Each query type consumes the following weight; lighter queries are preferable for frequent polling. | Weight | Query types | | -----: | ------------------------------------------------------------------------------------------------------------------------------ | | 0 | rateLimitStatus (does not use quota and is safe to poll) | | 1 | feeRate, marketSummary, marketTrades, orderbook | | 2 | agentContext, candles, fundingComparison, fundingRateHistory, liquidations, marketDetail, positionContext | | 3 | whaleContext | | 5 | accounts, accountState, fundingPayments, historicalOrders, openOrders, orderStatus, portfolio, trades, userDepositsWithdrawals | | 10 | topAddresses | | 20 | platformPositions | Every response includes: ```http X-RateLimit-Limit: 1200 X-RateLimit-Remaining: 1148 X-RateLimit-Reset: 1779269200000 X-RateLimit-Weight: 2 ``` X-RateLimit-Weight reports the weight charged for that request. X-RateLimit-Reset gives the end of the current window as a millisecond epoch. When the quota is exceeded, the server responds with HTTP 429 and includes a Retry-After header (seconds): ```json { "success": false, "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Retry after 1779269200000", "retry_after": 1779269200000, "ts": 1779269143700 } ``` #### rateLimitStatus This query reports the calling IP's quota state for the current rolling one-minute window. Its weight is 0, so checking it does not consume quota and it can be called on each polling iteration. Request: ```json { "type": "rateLimitStatus" } ``` Response: ```json { "success": true, "data": { "limit": 1200, "remaining": 500, "reset": 1779269200000, "tier": "default" }, "ts": 1779269143700 } ``` | Field | Type | Meaning | | --------- | ------ | --------------------------------------------------------------------------------- | | limit | int64 | Total weight available in the window (1,200 for the default tier). | | remaining | int64 | Weight left after all requests so far; weighted queries reduce it. | | reset | int64 | Millisecond epoch when this rolling window ends and the allowance is replenished. | | tier | string | Quota tier name; anonymous IPs use default. | ### Data freshness The table gives worst-case age for each query or field; data is often newer. Polling more frequently than these windows does not make the underlying data fresher. X-Data-Freshness records the server response time, not the generation time of the data. | Query | Field | Maximum age | | ------------------------------- | --------------------------------------- | --------------------------------------------------------------- | | orderbook | All | Under 1 second | | marketTrades | All | Under 1 second | | openOrders | All | Under 1 second | | orderStatus | All | Under 1 second | | rateLimitStatus | All | Real time | | marketSummary | All | Under 5 seconds | | marketDetail | orderbook | Under 1 second | | marketDetail | recent\_trades, market\_info | Under 5 seconds | | marketDetail | funding\_history | Under 30 seconds | | marketDetail | candles | About 1 minute | | accountState | All | Under 5 seconds | | platformPositions | All | Under 5 seconds | | liquidations | All | Under 5 seconds | | agentContext | Account, positions, held-market details | Under 5 seconds | | positionContext | Position, orders, market | Under 5 seconds | | fundingComparison | All | About 1 minute | | fundingRateHistory | All | Under 30 seconds | | feeRate | All | About 1 minute | | accounts | All | About 1 minute | | Latest candles | All | About 1 minute | | Closed candles | All | Unchanged after close | | trades within the last 24 hours | All | Under 1 second | | trades older than 24 hours | All | About 1 hour | | fundingPayments | All | Under 1 second | | userDepositsWithdrawals | All | Under 1 second | | historicalOrders | All | Under 1 second | | topAddresses | All | About 30 minutes; use last\_updated\_time to check snapshot age | | portfolio | All | About 1 day; daily snapshots | | whaleContext | account, positions, recent\_trades | Under 5 seconds | For multi-source bundles, sections can have different ages. agentContext and positionContext reflect the oldest section in their bundle. Trade fills within 24 hours are real time; older fills are read from an archive that refreshes hourly. ### Query types The 24 types are grouped as follows: | Data group | Query types | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Market data | marketSummary, marketDetail, orderbook, candles, marketTrades, liquidations, fundingRateHistory, fundingComparison | | Account data (requires address) | accounts, accountState, agentContext, feeRate, fundingPayments, historicalOrders, openOrders, orderStatus, portfolio, positionContext, trades, userDepositsWithdrawals, whaleContext | | Platform data | topAddresses, platformPositions | | Quota | rateLimitStatus | #### Market data * candles * fundingComparison * fundingRateHistory * liquidations * marketDetail * marketSummary * marketTrades * orderbook #### Account data * accountState * accounts * agentContext * feeRate * fundingPayments * historicalOrders * openOrders * orderStatus * portfolio * positionContext * trades * userDepositsWithdrawals * whaleContext #### Platform data * platformPositions * topAddresses ***