> For the complete documentation index, see [llms.txt](https://docs.v2.pod.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.v2.pod.network/guides-references/references/json-rpc/orderbook-data-ob.md).
# Orderbook Data (ob )
Orderbook Data (`ob_`) is a read-focused API surface that provides access to markets and orderbook activity without requiring clients to run their own indexer or interact with the orderbook contracts directly. It is powered by a native indexer built into the Pod protocol, ensuring fast, consistent, and up-to-date views of on-chain state.
The API exposes live orderbook snapshots, historical OHLCV candles, account-level order history and positions, making it ideal for trading interfaces, analytics, and monitoring services.
š This is a JSON-RPC 2.0 API. The request path is not important; the method to execute is defined by the method field in the request body. You can send all requests to /, and any path after / is optional and used only for documentation clarity.
## Get All Markets
> Retrieves a list of all available markets/orderbooks with their metadata\
> and statistics. Each market includes token information, current pricing,\
> 24-hour statistics, and fee structure.
```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"tags":[{"name":"Orderbook Data (ob_)","description":"Orderbook Data (`ob_`) is a read-focused API surface that provides access to\nmarkets and orderbook activity without requiring clients to run their own\nindexer or interact with the orderbook contracts directly. It is powered\nby a native indexer built into the Pod protocol, ensuring fast, consistent,\nand up-to-date views of on-chain state.\n\nThe API exposes live orderbook snapshots, historical OHLCV candles,\naccount-level order history and positions, making it ideal for trading\ninterfaces, analytics, and monitoring services.\n\nš This is a JSON-RPC 2.0 API. The request path is not important; the\nmethod to execute is defined by the method field in the request body. You\ncan send all requests to /, and any path after / is optional and used only\nfor documentation clarity.\n\n \n"}],"servers":[{"url":"https://rpc.podtestnet.dev/","description":"Pod testnet"}],"paths":{"/ob_getMarkets":{"post":{"tags":["Orderbook Data (ob_)"],"summary":"Get All Markets","operationId":"ob_getMarkets","description":"Retrieves a list of all available markets/orderbooks with their metadata\nand statistics. Each market includes token information, current pricing,\n24-hour statistics, and fee structure.\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method","id"],"properties":{"jsonrpc":{"type":"string","default":"2.0"},"method":{"type":"string","default":"ob_getMarkets"},"id":{"type":"integer","default":1},"params":{"type":"array","default":[]}}}}}},"responses":{"200":{"description":"Array of market objects with metadata and statistics","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string"},"result":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"id":{"type":"integer"}}}}}}}}}},"components":{"schemas":{"Market":{"type":"object","description":"Market/orderbook metadata and 24-hour statistics","properties":{"id":{"$ref":"#/components/schemas/Bytes32","description":"Unique 32-byte orderbook identifier"},"name":{"type":"string","description":"Market name in format `{base_token}/{quote_token}` (e.g. \"NVDAx/USD\")"},"base_token_address":{"$ref":"#/components/schemas/Address","description":"Contract address of the base token"},"quote_token_address":{"$ref":"#/components/schemas/Address","description":"Contract address of the quote token"},"base_token_symbol":{"type":"string","description":"Symbol of the base token (e.g., \"NVDAx\")"},"quote_token_symbol":{"type":"string","description":"Symbol of the quote token (e.g., \"USD\")"},"base_token_name":{"type":"string","description":"Full name of the base token"},"quote_token_name":{"type":"string","description":"Full name of the quote token"},"market_type":{"$ref":"#/components/schemas/MarketType"},"last_clearing_price":{"$ref":"#/components/schemas/HexUint256","description":"Last auction clearing price (quote/base with 1e18 scale)"},"auction_interval":{"type":"integer","format":"int64","description":"Length of a matching round, in microseconds."},"volume_24h":{"$ref":"#/components/schemas/HexUint256","description":"24-hour trading volume"},"high_24h":{"$ref":"#/components/schemas/HexUint256","description":"24-hour highest price"},"low_24h":{"$ref":"#/components/schemas/HexUint256","description":"24-hour lowest price"},"price_change_24h":{"type":"integer","format":"int64","description":"24-hour price change (signed integer)"},"tick_precision":{"$ref":"#/components/schemas/HexUint256","description":"Minimum price tick size, hex-encoded with `1e18` scale (e.g. `0xde0b6b3a7640000` = `1e18` = one whole tick)."},"lot_size":{"$ref":"#/components/schemas/HexUint256","description":"Minimum order size increment, hex-encoded with `1e18` scale. Order sizes must be multiples of this value."},"maker_fee":{"$ref":"#/components/schemas/HexUint256","description":"Maker fee rate (1e18-scaled)"},"taker_fee":{"$ref":"#/components/schemas/HexUint256","description":"Taker fee rate (1e18-scaled)"},"max_leverage":{"type":"integer","description":"Maximum allowed leverage. Returned for both spot and perp markets, but only meaningful for perp."},"oracle_price":{"type":"string","nullable":true,"description":"Perp markets only. Latest Pyth oracle price as a hex-encoded\nunsigned 256-bit integer (1e18-scaled), used as the mark for funding\nand liquidation. `null` for spot markets.\n"},"mark_price":{"type":"string","nullable":true,"description":"Perp markets only. True mark price (oracle-anchored) as a hex-encoded\nunsigned 256-bit integer (1e18-scaled). `null` for spot markets.\n"},"funding_rate":{"type":"string","nullable":true,"description":"Perp markets only. Per-`funding_window` funding rate as a signed\ndecimal string (1e18-scaled, may be negative). `null` for spot markets.\n"},"funding_index":{"type":"string","nullable":true,"description":"Perp markets only. Cumulative per-unit-size funding accumulator as\na signed decimal string (1e18-scaled, may be negative). `null` for\nspot markets.\n"},"funding_last_updated":{"type":"integer","format":"int64","nullable":true,"description":"Perp markets only. Microsecond Unix timestamp of the batch that produced\nthe most recent funding update. `null` for spot markets.\n"},"open_interest":{"type":"string","nullable":true,"description":"Perp markets only. Open interest in 1e18-scaled USD notional as a\nhex-encoded unsigned 256-bit integer ā\n`mark_price * Ī£ |position.size|` across every open cross-margin\nposition on this market. `null` for spot markets.\n"}}},"Bytes32":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$","description":"32-byte value (hex-encoded with 0x prefix). Used for transaction hashes, orderbook IDs, etc."},"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"},"MarketType":{"type":"string","enum":["spot","perpetual"],"description":"Type of market - spot trading or perpetual futures"},"HexUint256":{"type":"string","pattern":"^0x[a-fA-F0-9]+$","description":"Unsigned 256-bit integer (hex-encoded with 0x prefix)"}}}}
```
## Get Orderbook Snapshot
> Retrieves the current orderbook snapshot for a specified market, showing buy and sell orders aggregated by price level.\
> \
> Orders are grouped by price and include total volume and minimum expiry at each level.\
> Buy orders are sorted by price descending (best bid first), sell orders by price ascending (best ask first).
```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"tags":[{"name":"Orderbook Data (ob_)","description":"Orderbook Data (`ob_`) is a read-focused API surface that provides access to\nmarkets and orderbook activity without requiring clients to run their own\nindexer or interact with the orderbook contracts directly. It is powered\nby a native indexer built into the Pod protocol, ensuring fast, consistent,\nand up-to-date views of on-chain state.\n\nThe API exposes live orderbook snapshots, historical OHLCV candles,\naccount-level order history and positions, making it ideal for trading\ninterfaces, analytics, and monitoring services.\n\nš This is a JSON-RPC 2.0 API. The request path is not important; the\nmethod to execute is defined by the method field in the request body. You\ncan send all requests to /, and any path after / is optional and used only\nfor documentation clarity.\n\n \n"}],"servers":[{"url":"https://rpc.podtestnet.dev/","description":"Pod testnet"}],"paths":{"/ob_getOrderbook":{"post":{"tags":["Orderbook Data (ob_)"],"summary":"Get Orderbook Snapshot","operationId":"ob_getOrderbook","description":"Retrieves the current orderbook snapshot for a specified market, showing buy and sell orders aggregated by price level.\n\nOrders are grouped by price and include total volume and minimum expiry at each level.\nBuy orders are sorted by price descending (best bid first), sell orders by price ascending (best ask first).\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method","params","id"],"properties":{"jsonrpc":{"type":"string","default":"2.0"},"method":{"type":"string","default":"ob_getOrderbook"},"id":{"type":"integer","default":1},"params":{"type":"array","description":"Parameters:\n1. `orderbook_id` (bytes32): The 32-byte orderbook identifier\n2. `depth` (integer, optional): Maximum number of price levels to return for each side. If omitted, all available price levels are returned.\n","items":{"oneOf":[{"$ref":"#/components/schemas/Bytes32"},{"type":"integer","description":"Depth - maximum price levels per side"}]}}}}}}},"responses":{"200":{"description":"Orderbook snapshot with aggregated buy and sell orders","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string"},"result":{"$ref":"#/components/schemas/OrderbookSnapshot"},"id":{"type":"integer"}}}}}}}}}},"components":{"schemas":{"Bytes32":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$","description":"32-byte value (hex-encoded with 0x prefix). Used for transaction hashes, orderbook IDs, etc."},"OrderbookSnapshot":{"type":"object","description":"Current state of an orderbook with aggregated buy/sell levels.\nThe response field is `orderbook_id`; `clob_id` is accepted as an input alias when deserializing.\n","properties":{"orderbook_id":{"$ref":"#/components/schemas/Bytes32","description":"Orderbook identifier. Also accepts `clob_id` as an alias on input."},"buys":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/TickSnapshot"},"description":"Buy orders keyed by price (decimal string), sorted by price descending"},"sells":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/TickSnapshot"},"description":"Sell orders keyed by price (decimal string), sorted by price ascending"},"clearing_price":{"$ref":"#/components/schemas/HexUint256","description":"Current/last clearing price"},"grouping_precision":{"$ref":"#/components/schemas/HexUint256","description":"Price grouping precision used for aggregation (1e18, hex-encoded)"},"timestamp":{"type":"integer","description":"Snapshot timestamp in microseconds"},"new_orders_count":{"type":"integer","description":"Number of new orders since the last snapshot"},"buys_count":{"type":"integer","description":"Total number of buy orders in the orderbook (regardless of depth parameter)"},"sells_count":{"type":"integer","description":"Total number of sell orders in the orderbook (regardless of depth parameter)"},"oracle_price":{"type":"string","nullable":true,"description":"Perp orderbooks only. Pyth oracle price from the most recent perp solution's `priceProof` (1e18, hex-encoded). `null` for spot orderbooks."},"funding_rate":{"type":"string","nullable":true,"description":"Perp orderbooks only. Funding rate computed for this batch (per-`funding_window`, signed 1e18 decimal string). `null` for spot orderbooks."},"funding_index":{"type":"string","nullable":true,"description":"Perp orderbooks only. Cumulative per-unit-size funding accumulator after this batch (signed 1e18 decimal string). `null` for spot orderbooks."},"funding_last_updated":{"type":"integer","format":"int64","nullable":true,"description":"Perp orderbooks only. Microsecond timestamp of the batch that produced the funding update. `null` for spot orderbooks."}}},"TickSnapshot":{"type":"object","description":"Aggregated order volume at a specific price level","properties":{"volume":{"$ref":"#/components/schemas/HexUint256","description":"Total volume available at this price level (1e18, hex-encoded)"},"minimum_expiry":{"type":"integer","description":"Minimum expiry timestamp (microseconds) for orders at this price level"}}},"HexUint256":{"type":"string","pattern":"^0x[a-fA-F0-9]+$","description":"Unsigned 256-bit integer (hex-encoded with 0x prefix)"}}}}
```
## Get Historical Candles
> Retrieves historical candle (OHLCV) data for a specified orderbook.\
> \
> Candles represent aggregated price and volume data over specified time intervals.\
> Results are returned sorted by timestamp in descending order (newest first).\
> \
> All prices are in quote/base units with 1e18 scale (hex-encoded).
```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"tags":[{"name":"Orderbook Data (ob_)","description":"Orderbook Data (`ob_`) is a read-focused API surface that provides access to\nmarkets and orderbook activity without requiring clients to run their own\nindexer or interact with the orderbook contracts directly. It is powered\nby a native indexer built into the Pod protocol, ensuring fast, consistent,\nand up-to-date views of on-chain state.\n\nThe API exposes live orderbook snapshots, historical OHLCV candles,\naccount-level order history and positions, making it ideal for trading\ninterfaces, analytics, and monitoring services.\n\nš This is a JSON-RPC 2.0 API. The request path is not important; the\nmethod to execute is defined by the method field in the request body. You\ncan send all requests to /, and any path after / is optional and used only\nfor documentation clarity.\n\n \n"}],"servers":[{"url":"https://rpc.podtestnet.dev/","description":"Pod testnet"}],"paths":{"/ob_getCandles":{"post":{"tags":["Orderbook Data (ob_)"],"summary":"Get Historical Candles","operationId":"ob_getCandles","description":"Retrieves historical candle (OHLCV) data for a specified orderbook.\n\nCandles represent aggregated price and volume data over specified time intervals.\nResults are returned sorted by timestamp in descending order (newest first).\n\nAll prices are in quote/base units with 1e18 scale (hex-encoded).\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method","params","id"],"properties":{"jsonrpc":{"type":"string","default":"2.0"},"method":{"type":"string","default":"ob_getCandles"},"id":{"type":"integer","default":1},"params":{"type":"array","description":"Positional parameters:\n1. `orderbook_id` (Bytes32): The 32-byte orderbook identifier\n2. `query` (CandlesQuery): Query parameters with resolution, time range, and limit\n","items":{"oneOf":[{"$ref":"#/components/schemas/Bytes32"},{"$ref":"#/components/schemas/CandlesQuery"}]}}}}}}},"responses":{"200":{"description":"Array of candle objects sorted by timestamp (newest first)","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string"},"result":{"type":"array","items":{"$ref":"#/components/schemas/Candle"}},"id":{"type":"integer"}}}}}}}}}},"components":{"schemas":{"Bytes32":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$","description":"32-byte value (hex-encoded with 0x prefix). Used for transaction hashes, orderbook IDs, etc."},"CandlesQuery":{"type":"object","description":"Query parameters for fetching historical candles","required":["resolution","from_ts"],"properties":{"resolution":{"$ref":"#/components/schemas/CandleResolution","description":"Candle time interval"},"from_ts":{"$ref":"#/components/schemas/Timestamp","description":"Start timestamp (inclusive) in microseconds"},"to_ts":{"$ref":"#/components/schemas/Timestamp","description":"End timestamp (inclusive) in microseconds. Defaults to current time if omitted."},"limit":{"type":"integer","description":"Maximum number of candles to return. No limit if omitted."}}},"CandleResolution":{"type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time interval for OHLCV candles"},"Timestamp":{"type":"integer","format":"int64","description":"Unix timestamp in microseconds (not milliseconds or seconds)"},"Candle":{"type":"object","description":"OHLCV candle representing price/volume data for a time period","properties":{"timestamp":{"$ref":"#/components/schemas/Timestamp","description":"Candle timestamp in microseconds"},"open":{"$ref":"#/components/schemas/HexUint256","description":"Opening price (quote/base with 1e18 scale)"},"close":{"$ref":"#/components/schemas/HexUint256","description":"Closing price (quote/base with 1e18 scale)"},"high":{"$ref":"#/components/schemas/HexUint256","description":"Highest price (quote/base with 1e18 scale)"},"low":{"$ref":"#/components/schemas/HexUint256","description":"Lowest price (quote/base with 1e18 scale)"},"volume":{"$ref":"#/components/schemas/HexUint256","description":"Total volume traded during this candle period"}}},"HexUint256":{"type":"string","pattern":"^0x[a-fA-F0-9]+$","description":"Unsigned 256-bit integer (hex-encoded with 0x prefix)"}}}}
```
## Get Account Orders
> Retrieves orders for a specific address in a given orderbook, with support for cursor-based pagination.\
> \
> Orders are returned in descending order by timestamp/nonce.\
> Use the \`next\_cursor\` from the response to fetch subsequent pages.
```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"tags":[{"name":"Orderbook Data (ob_)","description":"Orderbook Data (`ob_`) is a read-focused API surface that provides access to\nmarkets and orderbook activity without requiring clients to run their own\nindexer or interact with the orderbook contracts directly. It is powered\nby a native indexer built into the Pod protocol, ensuring fast, consistent,\nand up-to-date views of on-chain state.\n\nThe API exposes live orderbook snapshots, historical OHLCV candles,\naccount-level order history and positions, making it ideal for trading\ninterfaces, analytics, and monitoring services.\n\nš This is a JSON-RPC 2.0 API. The request path is not important; the\nmethod to execute is defined by the method field in the request body. You\ncan send all requests to /, and any path after / is optional and used only\nfor documentation clarity.\n\n \n"}],"servers":[{"url":"https://rpc.podtestnet.dev/","description":"Pod testnet"}],"paths":{"/ob_getOrders":{"post":{"tags":["Orderbook Data (ob_)"],"summary":"Get Account Orders","operationId":"ob_getOrders","description":"Retrieves orders for a specific address in a given orderbook, with support for cursor-based pagination.\n\nOrders are returned in descending order by timestamp/nonce.\nUse the `next_cursor` from the response to fetch subsequent pages.\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method","params","id"],"properties":{"jsonrpc":{"type":"string","default":"2.0"},"method":{"type":"string","default":"ob_getOrders"},"id":{"type":"integer","default":1},"params":{"type":"array","description":"Positional parameters:\n1. `address` (Address): The address to get orders for\n2. `query` (OrdersQuery): Query parameters with optional orderbook_id, limit, cursor, and status filter\n","items":{"oneOf":[{"$ref":"#/components/schemas/Address"},{"$ref":"#/components/schemas/OrdersQuery"}]}}}}}}},"responses":{"200":{"description":"Object containing orders array and pagination cursor","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string"},"result":{"type":"object","properties":{"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"total_count":{"type":"integer","description":"Total number of orders matching the query, regardless of pagination. Present only when the request set `with_total` (omitted otherwise, not null). Older nodes always return it."},"next_cursor":{"type":"string","nullable":true,"description":"Cursor for fetching the next page (wire format `\"{ts}:{nonce}:{order_id_hex}\"`). Null if no more results."}}},"id":{"type":"integer"}}}}}}}}}},"components":{"schemas":{"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"},"OrdersQuery":{"type":"object","description":"Query parameters for ob_getOrders (address is passed as first param)","properties":{"orderbook_id":{"$ref":"#/components/schemas/Bytes32","description":"Optional filter by orderbook; omit for all orderbooks"},"limit":{"type":"integer","description":"Maximum number of orders to return"},"cursor":{"type":"string","description":"Pagination cursor from previous response"},"status":{"$ref":"#/components/schemas/OrderStatus","description":"Filter orders by status"},"with_fills":{"type":"boolean","description":"When true, include each order's per-batch partial `fills` array in the response. Defaults to false."},"with_total":{"type":"boolean","description":"When true, compute and return `total_count`. Defaults to false ā the count walks every order the account ever placed (expensive for high-churn accounts), and cursor pagination does not need it. Nodes running builds predating this flag ignore it and always return `total_count`."}}},"Bytes32":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$","description":"32-byte value (hex-encoded with 0x prefix). Used for transaction hashes, orderbook IDs, etc."},"OrderStatus":{"type":"string","enum":["pending","active","filled","expired","canceled"],"description":"Current status of an order:\n- `pending`: Order submitted but not yet included in orderbook\n- `active`: Order is live in the orderbook\n- `filled`: Order completely filled\n- `expired`: Order expired (TTL exceeded)\n- `canceled`: Order was canceled by user\n"},"Order":{"type":"object","description":"An order returned by `ob_getOrders`. Carries spot and perp shapes ā perp-only fields (`reduce_only`, `ioc`, `direction`) are present only when `market_type = perpetual`. The `initial_size` is signed: positive for Buy/Long, negative for Sell/Short.\n","properties":{"orderbook_id":{"$ref":"#/components/schemas/Bytes32","description":"The orderbook this order belongs to"},"market_type":{"$ref":"#/components/schemas/MarketType"},"kind":{"$ref":"#/components/schemas/OrderKind"},"order_id":{"$ref":"#/components/schemas/Bytes32","description":"Computed order identifier `keccak256(abi.encode(signer, nonce, sequence))` ā the id orders, cancels, and updates are keyed by."},"tx_hash":{"$ref":"#/components/schemas/Bytes32","description":"Transaction hash that created this order. Zero for engine-generated orders (liquidations, fired-trigger synthetics)."},"bidder":{"$ref":"#/components/schemas/Address","description":"Address of the order creator"},"nonce":{"type":"integer","format":"int64","description":"Order nonce for the account"},"order_type":{"type":"string","enum":["limit","market"],"description":"Limit or market"},"status":{"$ref":"#/components/schemas/OrderStatus"},"side":{"type":"string","enum":["buy","sell"],"description":"Bid (buy) or ask (sell). For perps, prefer `direction` for the position-effect label."},"price":{"$ref":"#/components/schemas/HexUint256","description":"Limit price in quote/base units with 1e18 scale"},"initial_size":{"type":"string","description":"Original signed order size (positive = Buy/Long, negative = Sell/Short)"},"filled_base_amount":{"$ref":"#/components/schemas/HexUint256","description":"Cumulative amount of base tokens filled"},"filled_quote_amount":{"$ref":"#/components/schemas/HexUint256","description":"Cumulative amount of quote tokens filled"},"fee":{"$ref":"#/components/schemas/HexUint256","description":"Accumulated trading fee. Currently always zero."},"deadline":{"$ref":"#/components/schemas/Timestamp","description":"Timestamp by which order must be included in the orderbook (microseconds)"},"end":{"$ref":"#/components/schemas/Timestamp","description":"Timestamp when order expires (microseconds)"},"effective_price":{"$ref":"#/components/schemas/HexUint256","description":"Effective price the order has been filled at so far (filled_quote / filled_base, 1e18)"},"fills":{"type":"array","items":{"$ref":"#/components/schemas/PartialFill"},"description":"Per-batch partial fills against this order"},"reduce_only":{"type":"boolean","description":"Perp only. If true, the order can only reduce existing exposure. Omitted for spot orders.","nullable":true},"ioc":{"type":"boolean","description":"Perp only. Immediate-or-cancel ā any unfilled remainder is canceled at end of batch. Omitted for spot orders.","nullable":true},"direction":{"$ref":"#/components/schemas/OrderDirection","description":"Composite direction label (set for spot, and for perps once fills land or for liquidation orders).","nullable":true},"grouping":{"$ref":"#/components/schemas/TriggerGrouping","description":"Trigger-grouping mode inherited from the parent trigger. Omitted when it is the default `none`."},"trigger_type":{"$ref":"#/components/schemas/TriggerType","description":"Trigger type (`take_profit` / `stop_loss`) inherited from the parent `TriggerOrder` when this order is the synthetic produced by a fired trigger (`kind = triggered`). Omitted for every other order.","nullable":true}}},"MarketType":{"type":"string","enum":["spot","perpetual"],"description":"Type of market - spot trading or perpetual futures"},"OrderKind":{"type":"string","enum":["user_signed","liquidation","triggered"],"description":"Origin of the order:\n- `user_signed`: a normal user-submitted order (every order placed via the `submitOrder` contract call)\n- `liquidation`: synthesized by the engine, per (user, pair), when an account falls below maintenance margin\n- `triggered`: the synthetic order emitted deterministically by validators when an armed TP/SL trigger crosses its threshold against the pair's mark price. Carries `trigger_type` and `grouping` inherited from the parent trigger.\n"},"HexUint256":{"type":"string","pattern":"^0x[a-fA-F0-9]+$","description":"Unsigned 256-bit integer (hex-encoded with 0x prefix)"},"Timestamp":{"type":"integer","format":"int64","description":"Unix timestamp in microseconds (not milliseconds or seconds)"},"PartialFill":{"type":"object","description":"A single fill round against this order.","properties":{"base_amount":{"$ref":"#/components/schemas/HexUint256","description":"Base token amount filled in this round (1e18)"},"quote_amount":{"$ref":"#/components/schemas/HexUint256","description":"Quote token amount filled in this round (1e18)"},"timestamp":{"$ref":"#/components/schemas/Timestamp","description":"Batch settlement timestamp (microseconds)"},"price":{"$ref":"#/components/schemas/HexUint256","description":"Clearing price of the batch (1e18)"}}},"OrderDirection":{"type":"string","enum":["buy","sell","open_long","add_long","reduce_long","close_long","open_short","add_short","reduce_short","close_short","long_to_short","short_to_long","liquidation"],"description":"Composite per-order direction for history and open-orders UIs.\nSpot orders use `buy`/`sell`. Perp orders use the position-effect labels (`open_long`, `reduce_long`, `close_long`, `long_to_short`, etc.) computed from the position before/after the fill. `liquidation` is set when `kind = liquidation`.\n"},"TriggerGrouping":{"type":"string","enum":["none","asset","position"],"description":"Whether a trigger (and any synthetic order it produces) is bound to the bidder's exposure on the pair:\n- `none`: standalone ā the trigger is removed only by a user cancel, TTL expiry, or its own fire; any synthetic order it produced survives independently\n- `asset`: exposure-bound ā on perp markets the venue removes the armed trigger *and* any resting synthetic order it produced once the bidder's position on the pair reaches size 0; on spot markets, once the bidder's base-asset holdings reach 0\n\n`asset` was formerly named `position` (same semantics, same ABI value); nodes running older builds still emit `position` and clients should treat the two as equivalent.\n\nOmitted from an `Order` response when it is the default `none`.\n"},"TriggerType":{"type":"string","enum":["take_profit","stop_loss"],"description":"Type of a TP/SL trigger order on a perp market:\n- `take_profit`: fires when the mark price moves favorably across `trigger_price`\n- `stop_loss`: fires when the mark price moves adversely across `trigger_price`\n\nAlso set on a synthetic order (`kind = triggered`) that a fired trigger produced.\n"}}}}
```
## Get Account Positions
> Retrieves trading positions for a specific address across all orderbooks.\
> \
> Positions track the cost basis of acquired tokens (from buys and deposits) and compute\
> unrealized PnL using the current clearing price. The response includes per-token positions\
> (balance, position size, unrealized PnL) and aggregate metrics (total realized PnL,\
> total invested, total unrealized PnL).\
> \
> All amounts use 1e18 fixed-point scale.
```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"tags":[{"name":"Orderbook Data (ob_)","description":"Orderbook Data (`ob_`) is a read-focused API surface that provides access to\nmarkets and orderbook activity without requiring clients to run their own\nindexer or interact with the orderbook contracts directly. It is powered\nby a native indexer built into the Pod protocol, ensuring fast, consistent,\nand up-to-date views of on-chain state.\n\nThe API exposes live orderbook snapshots, historical OHLCV candles,\naccount-level order history and positions, making it ideal for trading\ninterfaces, analytics, and monitoring services.\n\nš This is a JSON-RPC 2.0 API. The request path is not important; the\nmethod to execute is defined by the method field in the request body. You\ncan send all requests to /, and any path after / is optional and used only\nfor documentation clarity.\n\n \n"}],"servers":[{"url":"https://rpc.podtestnet.dev/","description":"Pod testnet"}],"paths":{"/ob_getPositions":{"post":{"tags":["Orderbook Data (ob_)"],"summary":"Get Account Positions","operationId":"ob_getPositions","description":"Retrieves trading positions for a specific address across all orderbooks.\n\nPositions track the cost basis of acquired tokens (from buys and deposits) and compute\nunrealized PnL using the current clearing price. The response includes per-token positions\n(balance, position size, unrealized PnL) and aggregate metrics (total realized PnL,\ntotal invested, total unrealized PnL).\n\nAll amounts use 1e18 fixed-point scale.\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method","params","id"],"properties":{"jsonrpc":{"type":"string","default":"2.0"},"method":{"type":"string","default":"ob_getPositions"},"id":{"type":"integer","default":1},"params":{"type":"array","description":"Parameters:\n1. `address` (address): The address to get positions for\n","items":{"$ref":"#/components/schemas/Address"}}}}}}},"responses":{"200":{"description":"Positions response with per-token positions and aggregate PnL","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string"},"result":{"$ref":"#/components/schemas/PositionsResponse"},"id":{"type":"integer"}}}}}}}}}},"components":{"schemas":{"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"},"PositionsResponse":{"type":"object","description":"Account positions across all orderbooks with aggregate PnL.","properties":{"positions":{"type":"array","items":{"$ref":"#/components/schemas/Position"},"description":"Heterogeneous list of spot holdings and open perp positions."},"total_unrealized_pnl":{"type":"string","description":"Sum of `unrealized_pnl` across every spot holding and perp position (signed, 1e18 USD)."},"total_realized_pnl":{"type":"string","description":"Lifetime portfolio-wide spot realized PnL plus the account-level perp realized-PnL counter. Both are cumulative across the account's history ā closing a perp does not zero its contribution (signed, 1e18 USD).\n"},"perps_equity":{"type":"string","description":"Cash adjusted for unsettled funding plus unrealized PnL across all open perp positions. Excludes spot holdings (signed, 1e18 USD)."},"account_value":{"type":"string","description":"`perps_equity` plus the mark value of all spot holdings (signed, 1e18 USD)."},"cash":{"type":"string","description":"Deposited collateral adjusted for unsettled funding. Signed ā can be negative if the account is underwater (1e18 USD)."},"withdrawable_cash":{"$ref":"#/components/schemas/HexUint256","description":"Free margin ā `cash` minus the initial margin reserved by open positions (1e18 USD)."},"net_deposits":{"type":"string","description":"Net native collateral deposited minus withdrawn (signed, 1e18 USD). Negative once realized profit is withdrawn; lifetime PnL is `account_value ā net_deposits`."}}},"Position":{"description":"Tagged union: a single entry in `PositionsResponse.positions`. The `kind` field selects between a `SpotHolding` (one per token) or a `PerpPosition` (one per pair).\n","oneOf":[{"$ref":"#/components/schemas/SpotHolding"},{"$ref":"#/components/schemas/PerpPosition"}],"discriminator":{"propertyName":"kind","mapping":{"spot":"#/components/schemas/SpotHolding","perp":"#/components/schemas/PerpPosition"}}},"SpotHolding":{"type":"object","description":"A token balance with cost-basis tracking. One per token the wallet has touched on a spot market.","properties":{"kind":{"type":"string","enum":["spot"],"description":"Discriminator for the `Position` union."},"orderbook_id":{"$ref":"#/components/schemas/Bytes32"},"base_symbol":{"type":"string"},"quote_symbol":{"type":"string"},"balance":{"$ref":"#/components/schemas/HexUint256","description":"Total base tokens held for this market (free + locked, 1e18)."},"free_balance":{"$ref":"#/components/schemas/HexUint256","description":"Spendable portion of `balance` after sell-side order locks (1e18)."},"locked_balance":{"$ref":"#/components/schemas/HexUint256","description":"Base tokens locked in open sell orders (`balance - free_balance`, 1e18)."},"cost_basis":{"$ref":"#/components/schemas/HexUint256","description":"Total quote spent to acquire `balance` (1e18 USD)."},"mark_price":{"$ref":"#/components/schemas/HexUint256","description":"Last clearing price for this token's market (1e18)."},"unrealized_pnl":{"type":"string","description":"`(mark - avg_cost) Ć balance` (signed, 1e18 USD)."},"realized_pnl":{"type":"string","description":"Lifetime realized PnL on the user's spot trading (signed, 1e18 USD; portfolio-wide for v1)."}}},"Bytes32":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$","description":"32-byte value (hex-encoded with 0x prefix). Used for transaction hashes, orderbook IDs, etc."},"HexUint256":{"type":"string","pattern":"^0x[a-fA-F0-9]+$","description":"Unsigned 256-bit integer (hex-encoded with 0x prefix)"},"PerpPosition":{"type":"object","description":"A leveraged perp position. One per (user, pair).","properties":{"kind":{"type":"string","enum":["perp"],"description":"Discriminator for the `Position` union."},"orderbook_id":{"$ref":"#/components/schemas/Bytes32"},"base_symbol":{"type":"string"},"quote_symbol":{"type":"string"},"side":{"$ref":"#/components/schemas/PerpPositionSide"},"size":{"type":"string","description":"Signed position size in base units (1e18). Positive = long, negative = short."},"notional":{"$ref":"#/components/schemas/HexUint256","description":"`|size| Ć mark_price / 1e18` ā dollar value of exposure (1e18)."},"entry_price":{"$ref":"#/components/schemas/HexUint256","description":"Volume-weighted average entry price; updated only on opening fills (1e18)."},"mark_price":{"$ref":"#/components/schemas/HexUint256","description":"Latest mark price for the pair, post batch clearing (1e18)."},"margin":{"$ref":"#/components/schemas/HexUint256","description":"Allocated initial margin; cumulative across opens/increases, released proportionally on partial closes (1e18)."},"leverage":{"$ref":"#/components/schemas/HexUint256","description":"`notional Ć 1e18 / margin`. Effective leverage (0 if `margin` is 0)."},"funding_accrued":{"type":"string","description":"`(market.funding ā position.entry_funding) Ć size` (signed, 1e18 USD)."},"liquidation_price":{"$ref":"#/components/schemas/HexUint256","description":"Mark price at which this position would be liquidated against its own `margin` and the market's maintenance-margin rate. Funding ignored. 0 when position is empty."},"unrealized_pnl":{"type":"string","description":"`((mark ā entry) ā (funding ā entry_funding)) Ć size` (signed, 1e18 USD)."},"realized_pnl":{"type":"string","description":"Lifetime realized PnL on this position (signed, 1e18 USD). Resets to 0 when the position closes ā the next open of the same pair starts fresh."},"stop_loss":{"$ref":"#/components/schemas/HexUint256","description":"Reserved ā stop-loss not yet supported.","nullable":true},"take_profit":{"$ref":"#/components/schemas/HexUint256","description":"Reserved ā take-profit not yet supported.","nullable":true}}},"PerpPositionSide":{"type":"string","enum":["long","short"],"description":"Side of a perpetual position, derived from the sign of `size`."}}}}
```
## Get Account Fills
> Retrieves trade fills for a specific address within a time range.\
> \
> Fills represent individual trade executions from batch auction settlements.\
> A single order may produce multiple fills across different batches. Each fill\
> includes the clearing price, base and quote amounts, and the associated\
> orderbook and token addresses.\
> \
> Results are returned in descending order by timestamp (most recent first).
```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"tags":[{"name":"Orderbook Data (ob_)","description":"Orderbook Data (`ob_`) is a read-focused API surface that provides access to\nmarkets and orderbook activity without requiring clients to run their own\nindexer or interact with the orderbook contracts directly. It is powered\nby a native indexer built into the Pod protocol, ensuring fast, consistent,\nand up-to-date views of on-chain state.\n\nThe API exposes live orderbook snapshots, historical OHLCV candles,\naccount-level order history and positions, making it ideal for trading\ninterfaces, analytics, and monitoring services.\n\nš This is a JSON-RPC 2.0 API. The request path is not important; the\nmethod to execute is defined by the method field in the request body. You\ncan send all requests to /, and any path after / is optional and used only\nfor documentation clarity.\n\n \n"}],"servers":[{"url":"https://rpc.podtestnet.dev/","description":"Pod testnet"}],"paths":{"/ob_getFills":{"post":{"tags":["Orderbook Data (ob_)"],"summary":"Get Account Fills","operationId":"ob_getFills","description":"Retrieves trade fills for a specific address within a time range.\n\nFills represent individual trade executions from batch auction settlements.\nA single order may produce multiple fills across different batches. Each fill\nincludes the clearing price, base and quote amounts, and the associated\norderbook and token addresses.\n\nResults are returned in descending order by timestamp (most recent first).\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method","params","id"],"properties":{"jsonrpc":{"type":"string","default":"2.0"},"method":{"type":"string","default":"ob_getFills"},"id":{"type":"integer","default":1},"params":{"type":"array","description":"Positional parameters:\n1. `address` (Address): The address to get fills for\n2. `query` (FillsQuery): Query parameters with required from_ts and optional to_ts, orderbook_id, and limit\n","items":{"oneOf":[{"$ref":"#/components/schemas/Address"},{"$ref":"#/components/schemas/FillsQuery"}]}}}}}}},"responses":{"200":{"description":"Object containing fills array","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string"},"result":{"$ref":"#/components/schemas/GetFillsResponse"},"id":{"type":"integer"}}}}}}}}}},"components":{"schemas":{"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"},"FillsQuery":{"type":"object","description":"Query parameters for ob_getFills (address is passed as first param)","required":["from_ts"],"properties":{"from_ts":{"$ref":"#/components/schemas/Timestamp","description":"Start timestamp (inclusive) in microseconds"},"to_ts":{"$ref":"#/components/schemas/Timestamp","description":"End timestamp (exclusive) in microseconds. Defaults to current time if omitted."},"orderbook_id":{"$ref":"#/components/schemas/Bytes32","description":"Optional filter by orderbook; omit for all orderbooks"},"limit":{"type":"integer","description":"Maximum number of fills to return (max 500). Defaults to 500."}}},"Timestamp":{"type":"integer","format":"int64","description":"Unix timestamp in microseconds (not milliseconds or seconds)"},"Bytes32":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$","description":"32-byte value (hex-encoded with 0x prefix). Used for transaction hashes, orderbook IDs, etc."},"GetFillsResponse":{"type":"object","description":"Response containing a list of fills","properties":{"fills":{"type":"array","items":{"$ref":"#/components/schemas/FillResponse"},"description":"List of fills ordered by timestamp descending"}}},"FillResponse":{"type":"object","description":"A single trade fill from a batch auction settlement","properties":{"orderbook_id":{"$ref":"#/components/schemas/Bytes32","description":"The orderbook this fill belongs to"},"base_token":{"$ref":"#/components/schemas/Address","description":"Base token contract address"},"quote_token":{"$ref":"#/components/schemas/Address","description":"Quote token contract address"},"order_id":{"$ref":"#/components/schemas/Bytes32","description":"Identifier of the order that was filled"},"order_type":{"type":"string","enum":["limit","market"],"description":"Type of the order"},"initial_size":{"type":"string","description":"Initial order size (1e18); decimal string (signed int256). Positive for buy, negative for sell."},"fee":{"$ref":"#/components/schemas/HexUint256","description":"Accumulated fee for this order (1e18); hex-encoded. Currently always zero."},"base_amount":{"$ref":"#/components/schemas/HexUint256","description":"Base token amount filled in this settlement round (1e18); hex-encoded"},"quote_amount":{"$ref":"#/components/schemas/HexUint256","description":"Quote token amount filled in this settlement round (1e18); hex-encoded"},"timestamp":{"$ref":"#/components/schemas/Timestamp","description":"Timestamp of the batch settlement, in microseconds."},"price":{"$ref":"#/components/schemas/HexUint256","description":"Clearing price of the batch (1e18); hex-encoded"}}},"HexUint256":{"type":"string","pattern":"^0x[a-fA-F0-9]+$","description":"Unsigned 256-bit integer (hex-encoded with 0x prefix)"}}}}
```
## Get Account Backstop Transfers
> Retrieves the backstop transfers for a specific address, with cursor-based pagination.\
> \
> A backstop transfer is recorded when a perp position is swept to the backstop during\
> liquidation: the position's remaining size and cash are moved off the account. Each entry\
> captures the swept size, cash, the mark price at the sweep, and the account equity at that\
> moment.\
> \
> Results are returned in descending order by timestamp (most recent first). Use \`next\_cursor\`\
> from the response to fetch subsequent pages.
```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"tags":[{"name":"Orderbook Data (ob_)","description":"Orderbook Data (`ob_`) is a read-focused API surface that provides access to\nmarkets and orderbook activity without requiring clients to run their own\nindexer or interact with the orderbook contracts directly. It is powered\nby a native indexer built into the Pod protocol, ensuring fast, consistent,\nand up-to-date views of on-chain state.\n\nThe API exposes live orderbook snapshots, historical OHLCV candles,\naccount-level order history and positions, making it ideal for trading\ninterfaces, analytics, and monitoring services.\n\nš This is a JSON-RPC 2.0 API. The request path is not important; the\nmethod to execute is defined by the method field in the request body. You\ncan send all requests to /, and any path after / is optional and used only\nfor documentation clarity.\n\n \n"}],"servers":[{"url":"https://rpc.podtestnet.dev/","description":"Pod testnet"}],"paths":{"/ob_getBackstopTransfers":{"post":{"tags":["Orderbook Data (ob_)"],"summary":"Get Account Backstop Transfers","operationId":"ob_getBackstopTransfers","description":"Retrieves the backstop transfers for a specific address, with cursor-based pagination.\n\nA backstop transfer is recorded when a perp position is swept to the backstop during\nliquidation: the position's remaining size and cash are moved off the account. Each entry\ncaptures the swept size, cash, the mark price at the sweep, and the account equity at that\nmoment.\n\nResults are returned in descending order by timestamp (most recent first). Use `next_cursor`\nfrom the response to fetch subsequent pages.\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method","params","id"],"properties":{"jsonrpc":{"type":"string","default":"2.0"},"method":{"type":"string","default":"ob_getBackstopTransfers"},"id":{"type":"integer","default":1},"params":{"type":"array","description":"Positional parameters:\n1. `address` (Address): The address to get backstop transfers for\n2. `query` (BackstopTransfersQuery): Optional filters ā `orderbook_id`, `limit` (clamped to `[1, 200]`), and `cursor`\n","items":{"oneOf":[{"$ref":"#/components/schemas/Address"},{"$ref":"#/components/schemas/BackstopTransfersQuery"}]}}}}}}},"responses":{"200":{"description":"Object containing the backstop transfers array, total count, and pagination cursor","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string"},"result":{"$ref":"#/components/schemas/GetBackstopTransfersResponse"},"id":{"type":"integer"}}}}}}}}}},"components":{"schemas":{"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"},"BackstopTransfersQuery":{"type":"object","description":"Query parameters for ob_getBackstopTransfers (address is passed as first param). All fields optional.","properties":{"orderbook_id":{"$ref":"#/components/schemas/Bytes32","description":"Optional filter by orderbook; omit for all orderbooks."},"limit":{"type":"integer","description":"Maximum number of transfers to return. Clamped to `[1, 200]`."},"cursor":{"type":"string","description":"Pagination cursor ā pass `next_cursor` from the previous response. Wire format `\"{ts}:{id}\"`."}}},"Bytes32":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$","description":"32-byte value (hex-encoded with 0x prefix). Used for transaction hashes, orderbook IDs, etc."},"GetBackstopTransfersResponse":{"type":"object","description":"Paginated result of `ob_getBackstopTransfers`.","properties":{"transfers":{"type":"array","items":{"$ref":"#/components/schemas/BackstopTransferResponse"},"description":"List of backstop transfers ordered by timestamp descending."},"total_count":{"type":"integer","description":"Count of transfers matching `(address, orderbook_id)` *before* pagination."},"next_cursor":{"type":"string","nullable":true,"description":"Pass back as `query.cursor` to fetch the next page. Wire format `\"{ts}:{id}\"`. Null if no more results."}}},"BackstopTransferResponse":{"type":"object","description":"A perp position swept to the backstop during liquidation, as returned by `ob_getBackstopTransfers`.","properties":{"user":{"$ref":"#/components/schemas/Address","description":"Account whose position was swept."},"orderbook_id":{"$ref":"#/components/schemas/Bytes32","description":"The orderbook the swept position belonged to. Omitted when not recorded."},"size":{"type":"string","description":"Signed position size moved to the backstop (decimal int256, 1e18). Positive = long, negative = short."},"cash":{"type":"string","description":"Signed cash moved with the position (decimal int256, 1e18)."},"mark_price":{"$ref":"#/components/schemas/HexUint256","description":"Mark price at the sweep (1e18); hex-encoded."},"equity":{"type":"string","description":"Account equity at the moment of the sweep (decimal int256, 1e18)."},"timestamp":{"$ref":"#/components/schemas/Timestamp","description":"Timestamp of the batch that produced the sweep, in microseconds."}}},"HexUint256":{"type":"string","pattern":"^0x[a-fA-F0-9]+$","description":"Unsigned 256-bit integer (hex-encoded with 0x prefix)"},"Timestamp":{"type":"integer","format":"int64","description":"Unix timestamp in microseconds (not milliseconds or seconds)"}}}}
```
## Get Account Triggers
> Retrieves the armed TP/SL trigger orders owned by an address, with cursor-based pagination.\
> \
> Triggers are conditional perp orders: when the pair's mark price crosses \`trigger\_price\`\
> in the direction implied by \`trigger\_type\` and the sign of \`size\`, the engine emits a\
> synthetic order (surfaced through \`ob\_getOrders\` with \`kind = triggered\`). Triggers\
> themselves have no fill history, so this response is leaner than \`ob\_getOrders\`.\
> \
> Triggers are returned sorted by \`(orderbook\_id, order\_id)\`. Use \`next\_cursor\` from the\
> response to fetch subsequent pages.
```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"tags":[{"name":"Orderbook Data (ob_)","description":"Orderbook Data (`ob_`) is a read-focused API surface that provides access to\nmarkets and orderbook activity without requiring clients to run their own\nindexer or interact with the orderbook contracts directly. It is powered\nby a native indexer built into the Pod protocol, ensuring fast, consistent,\nand up-to-date views of on-chain state.\n\nThe API exposes live orderbook snapshots, historical OHLCV candles,\naccount-level order history and positions, making it ideal for trading\ninterfaces, analytics, and monitoring services.\n\nš This is a JSON-RPC 2.0 API. The request path is not important; the\nmethod to execute is defined by the method field in the request body. You\ncan send all requests to /, and any path after / is optional and used only\nfor documentation clarity.\n\n \n"}],"servers":[{"url":"https://rpc.podtestnet.dev/","description":"Pod testnet"}],"paths":{"/ob_getTriggers":{"post":{"tags":["Orderbook Data (ob_)"],"summary":"Get Account Triggers","operationId":"ob_getTriggers","description":"Retrieves the armed TP/SL trigger orders owned by an address, with cursor-based pagination.\n\nTriggers are conditional perp orders: when the pair's mark price crosses `trigger_price`\nin the direction implied by `trigger_type` and the sign of `size`, the engine emits a\nsynthetic order (surfaced through `ob_getOrders` with `kind = triggered`). Triggers\nthemselves have no fill history, so this response is leaner than `ob_getOrders`.\n\nTriggers are returned sorted by `(orderbook_id, order_id)`. Use `next_cursor` from the\nresponse to fetch subsequent pages.\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method","params","id"],"properties":{"jsonrpc":{"type":"string","default":"2.0"},"method":{"type":"string","default":"ob_getTriggers"},"id":{"type":"integer","default":1},"params":{"type":"array","description":"Positional parameters:\n1. `address` (Address): The address to get triggers for\n2. `query` (TriggersQuery): Optional filters ā `orderbook_id`, `limit` (clamped to `[1, 200]`), and `cursor`\n","items":{"oneOf":[{"$ref":"#/components/schemas/Address"},{"$ref":"#/components/schemas/TriggersQuery"}]}}}}}}},"responses":{"200":{"description":"Object containing the triggers array, total count, and pagination cursor","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string"},"result":{"$ref":"#/components/schemas/GetTriggersResponse"},"id":{"type":"integer"}}}}}}}}}},"components":{"schemas":{"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"},"TriggersQuery":{"type":"object","description":"Query parameters for ob_getTriggers (address is passed as first param). All fields optional ā an empty object returns every armed trigger owned by the address, capped at the server-side limit.","properties":{"orderbook_id":{"$ref":"#/components/schemas/Bytes32","description":"Optional filter by orderbook; omit for all orderbooks."},"limit":{"type":"integer","description":"Maximum number of triggers to return. Clamped to `[1, 200]`."},"cursor":{"type":"string","description":"Pagination cursor ā pass `next_cursor` from the previous response. Wire format `\"{orderbook_id}:{order_id}\"`."}}},"Bytes32":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$","description":"32-byte value (hex-encoded with 0x prefix). Used for transaction hashes, orderbook IDs, etc."},"GetTriggersResponse":{"type":"object","description":"Paginated result of `ob_getTriggers`.","properties":{"triggers":{"type":"array","items":{"$ref":"#/components/schemas/TriggerOrderResponse"}},"total_count":{"type":"integer","description":"Count of triggers matching `(address, orderbook_id)` *before* pagination."},"next_cursor":{"type":"string","nullable":true,"description":"Pass back as `query.cursor` to fetch the next page. Wire format `\"{orderbook_id}:{order_id}\"`. Null if no more results."}}},"TriggerOrderResponse":{"type":"object","description":"An armed TP/SL trigger order, as returned by `ob_getTriggers`.","properties":{"orderbook_id":{"$ref":"#/components/schemas/Bytes32"},"order_id":{"$ref":"#/components/schemas/Bytes32","description":"Identifier of the trigger (and of the synthetic order it produces when it fires)."},"tx_hash":{"$ref":"#/components/schemas/Bytes32","description":"Hash of the `submitTrigger` transaction that armed this trigger."},"bidder":{"$ref":"#/components/schemas/Address"},"nonce":{"type":"integer","format":"int64"},"size":{"type":"string","description":"Signed size of the synthetic order produced when the trigger fires (decimal int256). Positive = buy/long, negative = sell/short."},"limit_price":{"$ref":"#/components/schemas/HexUint256","description":"Limit price of the synthetic order produced when the trigger fires (1e18)."},"trigger_price":{"$ref":"#/components/schemas/HexUint256","description":"Mark-price threshold that arms the trigger (1e18)."},"trigger_type":{"$ref":"#/components/schemas/TriggerType"},"grouping":{"$ref":"#/components/schemas/TriggerGrouping"},"reduce_only":{"type":"boolean"},"ioc":{"type":"boolean","description":"Immediate-or-cancel ā any unfilled remainder of the fired order is canceled at end of batch."},"deadline":{"$ref":"#/components/schemas/Timestamp"},"end":{"$ref":"#/components/schemas/Timestamp","description":"TTL expiry ā the trigger is swept once `end < batch_deadline` (microseconds)."}}},"HexUint256":{"type":"string","pattern":"^0x[a-fA-F0-9]+$","description":"Unsigned 256-bit integer (hex-encoded with 0x prefix)"},"TriggerType":{"type":"string","enum":["take_profit","stop_loss"],"description":"Type of a TP/SL trigger order on a perp market:\n- `take_profit`: fires when the mark price moves favorably across `trigger_price`\n- `stop_loss`: fires when the mark price moves adversely across `trigger_price`\n\nAlso set on a synthetic order (`kind = triggered`) that a fired trigger produced.\n"},"TriggerGrouping":{"type":"string","enum":["none","asset","position"],"description":"Whether a trigger (and any synthetic order it produces) is bound to the bidder's exposure on the pair:\n- `none`: standalone ā the trigger is removed only by a user cancel, TTL expiry, or its own fire; any synthetic order it produced survives independently\n- `asset`: exposure-bound ā on perp markets the venue removes the armed trigger *and* any resting synthetic order it produced once the bidder's position on the pair reaches size 0; on spot markets, once the bidder's base-asset holdings reach 0\n\n`asset` was formerly named `position` (same semantics, same ABI value); nodes running older builds still emit `position` and clients should treat the two as equivalent.\n\nOmitted from an `Order` response when it is the default `none`.\n"},"Timestamp":{"type":"integer","format":"int64","description":"Unix timestamp in microseconds (not milliseconds or seconds)"}}}}
```
## Get Ranked Positions (Leaderboard)
> Returns accounts ranked by combined realized + unrealized PnL\
> (\`total\_realized\_pnl + total\_unrealized\_pnl\`) descending, paginated by \`offset\`/\`limit\`.\
> \
> Because the unrealized component moves with mark prices, the ordering can shift between\
> calls even without trades. When an \`address\` is supplied, the response also includes that\
> account's own positions and rank (\`queried\`), independent of the returned page.
```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"tags":[{"name":"Orderbook Data (ob_)","description":"Orderbook Data (`ob_`) is a read-focused API surface that provides access to\nmarkets and orderbook activity without requiring clients to run their own\nindexer or interact with the orderbook contracts directly. It is powered\nby a native indexer built into the Pod protocol, ensuring fast, consistent,\nand up-to-date views of on-chain state.\n\nThe API exposes live orderbook snapshots, historical OHLCV candles,\naccount-level order history and positions, making it ideal for trading\ninterfaces, analytics, and monitoring services.\n\nš This is a JSON-RPC 2.0 API. The request path is not important; the\nmethod to execute is defined by the method field in the request body. You\ncan send all requests to /, and any path after / is optional and used only\nfor documentation clarity.\n\n \n"}],"servers":[{"url":"https://rpc.podtestnet.dev/","description":"Pod testnet"}],"paths":{"/ob_getRankedPositions":{"post":{"tags":["Orderbook Data (ob_)"],"summary":"Get Ranked Positions (Leaderboard)","operationId":"ob_getRankedPositions","description":"Returns accounts ranked by combined realized + unrealized PnL\n(`total_realized_pnl + total_unrealized_pnl`) descending, paginated by `offset`/`limit`.\n\nBecause the unrealized component moves with mark prices, the ordering can shift between\ncalls even without trades. When an `address` is supplied, the response also includes that\naccount's own positions and rank (`queried`), independent of the returned page.\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method","id"],"properties":{"jsonrpc":{"type":"string","default":"2.0"},"method":{"type":"string","default":"ob_getRankedPositions"},"id":{"type":"integer","default":1},"params":{"type":"array","description":"Positional parameters (all optional):\n1. `limit` (integer, nullable): Page size\n2. `offset` (integer, nullable): Number of ranked accounts to skip\n3. `address` (Address, nullable): When supplied, also return this account's positions and rank in `queried`\n","items":{"oneOf":[{"type":"integer","nullable":true},{"$ref":"#/components/schemas/Address"}]}}}}}}},"responses":{"200":{"description":"Ranked window of accounts plus the total count and optional queried account","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string"},"result":{"$ref":"#/components/schemas/GetRankedPositionsResponse"},"id":{"type":"integer"}}}}}}}}}},"components":{"schemas":{"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"},"GetRankedPositionsResponse":{"type":"object","description":"Paginated leaderboard of accounts ordered by combined realized + unrealized PnL descending.","properties":{"ranked":{"type":"array","items":{"$ref":"#/components/schemas/RankedPosition"},"description":"The requested `[offset, offset + limit)` window, ordered by combined PnL descending."},"total":{"type":"integer","description":"Full count of ranked accounts before pagination."},"queried":{"$ref":"#/components/schemas/RankedAccount","nullable":true,"description":"Populated only when the request supplies an `address` ā that account's positions and rank. Null if no address was given, or the account has no PnL-bearing state."}}},"RankedPosition":{"type":"object","description":"One account's full positions snapshot, as an entry in `GetRankedPositionsResponse.ranked`.","properties":{"account":{"$ref":"#/components/schemas/Address"},"positions":{"$ref":"#/components/schemas/PositionsResponse"}}},"PositionsResponse":{"type":"object","description":"Account positions across all orderbooks with aggregate PnL.","properties":{"positions":{"type":"array","items":{"$ref":"#/components/schemas/Position"},"description":"Heterogeneous list of spot holdings and open perp positions."},"total_unrealized_pnl":{"type":"string","description":"Sum of `unrealized_pnl` across every spot holding and perp position (signed, 1e18 USD)."},"total_realized_pnl":{"type":"string","description":"Lifetime portfolio-wide spot realized PnL plus the account-level perp realized-PnL counter. Both are cumulative across the account's history ā closing a perp does not zero its contribution (signed, 1e18 USD).\n"},"perps_equity":{"type":"string","description":"Cash adjusted for unsettled funding plus unrealized PnL across all open perp positions. Excludes spot holdings (signed, 1e18 USD)."},"account_value":{"type":"string","description":"`perps_equity` plus the mark value of all spot holdings (signed, 1e18 USD)."},"cash":{"type":"string","description":"Deposited collateral adjusted for unsettled funding. Signed ā can be negative if the account is underwater (1e18 USD)."},"withdrawable_cash":{"$ref":"#/components/schemas/HexUint256","description":"Free margin ā `cash` minus the initial margin reserved by open positions (1e18 USD)."},"net_deposits":{"type":"string","description":"Net native collateral deposited minus withdrawn (signed, 1e18 USD). Negative once realized profit is withdrawn; lifetime PnL is `account_value ā net_deposits`."}}},"Position":{"description":"Tagged union: a single entry in `PositionsResponse.positions`. The `kind` field selects between a `SpotHolding` (one per token) or a `PerpPosition` (one per pair).\n","oneOf":[{"$ref":"#/components/schemas/SpotHolding"},{"$ref":"#/components/schemas/PerpPosition"}],"discriminator":{"propertyName":"kind","mapping":{"spot":"#/components/schemas/SpotHolding","perp":"#/components/schemas/PerpPosition"}}},"SpotHolding":{"type":"object","description":"A token balance with cost-basis tracking. One per token the wallet has touched on a spot market.","properties":{"kind":{"type":"string","enum":["spot"],"description":"Discriminator for the `Position` union."},"orderbook_id":{"$ref":"#/components/schemas/Bytes32"},"base_symbol":{"type":"string"},"quote_symbol":{"type":"string"},"balance":{"$ref":"#/components/schemas/HexUint256","description":"Total base tokens held for this market (free + locked, 1e18)."},"free_balance":{"$ref":"#/components/schemas/HexUint256","description":"Spendable portion of `balance` after sell-side order locks (1e18)."},"locked_balance":{"$ref":"#/components/schemas/HexUint256","description":"Base tokens locked in open sell orders (`balance - free_balance`, 1e18)."},"cost_basis":{"$ref":"#/components/schemas/HexUint256","description":"Total quote spent to acquire `balance` (1e18 USD)."},"mark_price":{"$ref":"#/components/schemas/HexUint256","description":"Last clearing price for this token's market (1e18)."},"unrealized_pnl":{"type":"string","description":"`(mark - avg_cost) Ć balance` (signed, 1e18 USD)."},"realized_pnl":{"type":"string","description":"Lifetime realized PnL on the user's spot trading (signed, 1e18 USD; portfolio-wide for v1)."}}},"Bytes32":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$","description":"32-byte value (hex-encoded with 0x prefix). Used for transaction hashes, orderbook IDs, etc."},"HexUint256":{"type":"string","pattern":"^0x[a-fA-F0-9]+$","description":"Unsigned 256-bit integer (hex-encoded with 0x prefix)"},"PerpPosition":{"type":"object","description":"A leveraged perp position. One per (user, pair).","properties":{"kind":{"type":"string","enum":["perp"],"description":"Discriminator for the `Position` union."},"orderbook_id":{"$ref":"#/components/schemas/Bytes32"},"base_symbol":{"type":"string"},"quote_symbol":{"type":"string"},"side":{"$ref":"#/components/schemas/PerpPositionSide"},"size":{"type":"string","description":"Signed position size in base units (1e18). Positive = long, negative = short."},"notional":{"$ref":"#/components/schemas/HexUint256","description":"`|size| Ć mark_price / 1e18` ā dollar value of exposure (1e18)."},"entry_price":{"$ref":"#/components/schemas/HexUint256","description":"Volume-weighted average entry price; updated only on opening fills (1e18)."},"mark_price":{"$ref":"#/components/schemas/HexUint256","description":"Latest mark price for the pair, post batch clearing (1e18)."},"margin":{"$ref":"#/components/schemas/HexUint256","description":"Allocated initial margin; cumulative across opens/increases, released proportionally on partial closes (1e18)."},"leverage":{"$ref":"#/components/schemas/HexUint256","description":"`notional Ć 1e18 / margin`. Effective leverage (0 if `margin` is 0)."},"funding_accrued":{"type":"string","description":"`(market.funding ā position.entry_funding) Ć size` (signed, 1e18 USD)."},"liquidation_price":{"$ref":"#/components/schemas/HexUint256","description":"Mark price at which this position would be liquidated against its own `margin` and the market's maintenance-margin rate. Funding ignored. 0 when position is empty."},"unrealized_pnl":{"type":"string","description":"`((mark ā entry) ā (funding ā entry_funding)) Ć size` (signed, 1e18 USD)."},"realized_pnl":{"type":"string","description":"Lifetime realized PnL on this position (signed, 1e18 USD). Resets to 0 when the position closes ā the next open of the same pair starts fresh."},"stop_loss":{"$ref":"#/components/schemas/HexUint256","description":"Reserved ā stop-loss not yet supported.","nullable":true},"take_profit":{"$ref":"#/components/schemas/HexUint256","description":"Reserved ā take-profit not yet supported.","nullable":true}}},"PerpPositionSide":{"type":"string","enum":["long","short"],"description":"Side of a perpetual position, derived from the sign of `size`."},"RankedAccount":{"type":"object","description":"An account's positions plus its zero-based rank (0 = top) in the full combined-PnL ordering.","properties":{"account":{"$ref":"#/components/schemas/Address"},"rank":{"type":"integer","description":"Zero-based rank in the full ordering (0 = top), independent of the returned page."},"positions":{"$ref":"#/components/schemas/PositionsResponse"}}}}}}
```
## Get Oracle & Mark Prices
> Returns the latest oracle and mark prices recorded for perp orderbooks by the indexer.\
> \
> Pass an \`orderbook\_id\` to fetch a single orderbook, or omit it for every perp orderbook.\
> Numeric fields are \`0\` and \`as\_of\` is epoch until the orderbook has run a perp batch.\
> Funding state is not included here ā call \`ob\_getFundingRates\` for that.
```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"tags":[{"name":"Orderbook Data (ob_)","description":"Orderbook Data (`ob_`) is a read-focused API surface that provides access to\nmarkets and orderbook activity without requiring clients to run their own\nindexer or interact with the orderbook contracts directly. It is powered\nby a native indexer built into the Pod protocol, ensuring fast, consistent,\nand up-to-date views of on-chain state.\n\nThe API exposes live orderbook snapshots, historical OHLCV candles,\naccount-level order history and positions, making it ideal for trading\ninterfaces, analytics, and monitoring services.\n\nš This is a JSON-RPC 2.0 API. The request path is not important; the\nmethod to execute is defined by the method field in the request body. You\ncan send all requests to /, and any path after / is optional and used only\nfor documentation clarity.\n\n \n"}],"servers":[{"url":"https://rpc.podtestnet.dev/","description":"Pod testnet"}],"paths":{"/ob_getOraclePrices":{"post":{"tags":["Orderbook Data (ob_)"],"summary":"Get Oracle & Mark Prices","operationId":"ob_getOraclePrices","description":"Returns the latest oracle and mark prices recorded for perp orderbooks by the indexer.\n\nPass an `orderbook_id` to fetch a single orderbook, or omit it for every perp orderbook.\nNumeric fields are `0` and `as_of` is epoch until the orderbook has run a perp batch.\nFunding state is not included here ā call `ob_getFundingRates` for that.\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method","id"],"properties":{"jsonrpc":{"type":"string","default":"2.0"},"method":{"type":"string","default":"ob_getOraclePrices"},"id":{"type":"integer","default":1},"params":{"type":"array","description":"Positional parameters:\n1. `orderbook_id` (Bytes32, optional): Restrict to a single orderbook; omit for all perp orderbooks\n","items":{"$ref":"#/components/schemas/Bytes32"}}}}}}},"responses":{"200":{"description":"Array of oracle/mark price objects","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string"},"result":{"type":"array","items":{"$ref":"#/components/schemas/OraclePrice"}},"id":{"type":"integer"}}}}}}}}}},"components":{"schemas":{"Bytes32":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$","description":"32-byte value (hex-encoded with 0x prefix). Used for transaction hashes, orderbook IDs, etc."},"OraclePrice":{"type":"object","description":"Latest oracle and mark prices recorded for a perp orderbook by the indexer.","properties":{"orderbook_id":{"$ref":"#/components/schemas/Bytes32"},"oracle_price":{"$ref":"#/components/schemas/HexUint256","description":"Latest Pyth oracle price (1e18). `0` until the orderbook has run a perp batch."},"mark_price":{"$ref":"#/components/schemas/HexUint256","description":"Most recent non-zero clearing price (1e18). `0` until the orderbook has run a perp batch."},"as_of":{"$ref":"#/components/schemas/Timestamp","description":"Deadline of the batch that produced this row (microseconds). Epoch until the orderbook has run a perp batch."}}},"HexUint256":{"type":"string","pattern":"^0x[a-fA-F0-9]+$","description":"Unsigned 256-bit integer (hex-encoded with 0x prefix)"},"Timestamp":{"type":"integer","format":"int64","description":"Unix timestamp in microseconds (not milliseconds or seconds)"}}}}
```
## Get Funding Rates
> Returns the latest funding state for perp orderbooks, with the mark and oracle prices\
> included for context.\
> \
> Pass an \`orderbook\_id\` to fetch a single orderbook, or omit it for every perp orderbook.
```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"tags":[{"name":"Orderbook Data (ob_)","description":"Orderbook Data (`ob_`) is a read-focused API surface that provides access to\nmarkets and orderbook activity without requiring clients to run their own\nindexer or interact with the orderbook contracts directly. It is powered\nby a native indexer built into the Pod protocol, ensuring fast, consistent,\nand up-to-date views of on-chain state.\n\nThe API exposes live orderbook snapshots, historical OHLCV candles,\naccount-level order history and positions, making it ideal for trading\ninterfaces, analytics, and monitoring services.\n\nš This is a JSON-RPC 2.0 API. The request path is not important; the\nmethod to execute is defined by the method field in the request body. You\ncan send all requests to /, and any path after / is optional and used only\nfor documentation clarity.\n\n \n"}],"servers":[{"url":"https://rpc.podtestnet.dev/","description":"Pod testnet"}],"paths":{"/ob_getFundingRates":{"post":{"tags":["Orderbook Data (ob_)"],"summary":"Get Funding Rates","operationId":"ob_getFundingRates","description":"Returns the latest funding state for perp orderbooks, with the mark and oracle prices\nincluded for context.\n\nPass an `orderbook_id` to fetch a single orderbook, or omit it for every perp orderbook.\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method","id"],"properties":{"jsonrpc":{"type":"string","default":"2.0"},"method":{"type":"string","default":"ob_getFundingRates"},"id":{"type":"integer","default":1},"params":{"type":"array","description":"Positional parameters:\n1. `orderbook_id` (Bytes32, optional): Restrict to a single orderbook; omit for all perp orderbooks\n","items":{"$ref":"#/components/schemas/Bytes32"}}}}}}},"responses":{"200":{"description":"Array of funding rate objects","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string"},"result":{"type":"array","items":{"$ref":"#/components/schemas/FundingRate"}},"id":{"type":"integer"}}}}}}}}}},"components":{"schemas":{"Bytes32":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$","description":"32-byte value (hex-encoded with 0x prefix). Used for transaction hashes, orderbook IDs, etc."},"FundingRate":{"type":"object","description":"Funding state for a perp orderbook, with the latest mark and oracle prices for context. Returned by `ob_getFundingRates`.","properties":{"orderbook_id":{"$ref":"#/components/schemas/Bytes32"},"funding_rate":{"type":"string","description":"Per-`funding_window` funding rate (signed decimal int256, 1e18; may be negative)."},"funding_index":{"type":"string","description":"Cumulative per-unit-size funding accumulator (signed decimal int256, 1e18; may be negative)."},"mark_price":{"$ref":"#/components/schemas/HexUint256","description":"Most recent mark price for the pair (1e18)."},"oracle_price":{"$ref":"#/components/schemas/HexUint256","description":"Latest Pyth oracle price (1e18)."},"as_of":{"$ref":"#/components/schemas/Timestamp","description":"Deadline of the batch that produced this funding update (microseconds). Epoch until the orderbook has run a perp batch."}}},"HexUint256":{"type":"string","pattern":"^0x[a-fA-F0-9]+$","description":"Unsigned 256-bit integer (hex-encoded with 0x prefix)"},"Timestamp":{"type":"integer","format":"int64","description":"Unix timestamp in microseconds (not milliseconds or seconds)"}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.v2.pod.network/guides-references/references/json-rpc/orderbook-data-ob.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.