> 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/models.md).

# Models

## The JsonRpcRequest object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"JsonRpcRequest":{"type":"object","description":"Standard JSON-RPC 2.0 request object","required":["jsonrpc","method","id"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"],"description":"JSON-RPC protocol version (always \"2.0\")"},"method":{"type":"string","description":"Name of the RPC method to invoke"},"params":{"type":"array","items":{},"description":"Method parameters as an array"},"id":{"oneOf":[{"type":"integer"},{"type":"string"}],"description":"Request identifier for correlating responses"}}}}}}
```

## The JsonRpcResponse object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"JsonRpcResponse":{"type":"object","description":"Standard JSON-RPC 2.0 response object","required":["jsonrpc","id"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"result":{"description":"Result of the method call (mutually exclusive with error)"},"error":{"$ref":"#/components/schemas/JsonRpcError","description":"Error object if the call failed"},"id":{"oneOf":[{"type":"integer"},{"type":"string"}]}}},"JsonRpcError":{"type":"object","description":"JSON-RPC error object","required":["code","message"],"properties":{"code":{"type":"integer","description":"Numeric error code"},"message":{"type":"string","description":"Human-readable error message"},"data":{"description":"Additional error information"}}}}}}
```

## The JsonRpcError object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"JsonRpcError":{"type":"object","description":"JSON-RPC error object","required":["code","message"],"properties":{"code":{"type":"integer","description":"Numeric error code"},"message":{"type":"string","description":"Human-readable error message"},"data":{"description":"Additional error information"}}}}}}
```

## The Address object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"}}}}
```

## The Bytes32 object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"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."}}}}
```

## The HexBytes object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"HexBytes":{"type":"string","pattern":"^0x[a-fA-F0-9]*$","description":"Variable-length bytes (hex-encoded with 0x prefix). Length must be even."}}}}
```

## The BridgeClaimProof object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"BridgeClaimProof":{"type":"object","description":"Everything needed to call the bridged-chain bridge contract's `claim`.\n\n**`proof` and `aux_tx_suffix` serialize as JSON arrays of byte values** (`[247, 78, ...]`),\nnot as `0x` hex strings. Convert before handing them to a web3 library's `bytes` parameter.\n\n**`token` is the Pod-side address, not the one `claim` takes.** Map it to the bridged-chain\nasset with the `tokens` list from `GET /v1/bridge/config`, which is the only source of that\nmapping. `amount` and `to`, by contrast, are already bridged-chain values and pass through\nunchanged.\n","required":["proof","committee_epoch","aux_tx_suffix"],"properties":{"proof":{"type":"array","items":{"type":"integer","minimum":0,"maximum":255},"description":"The packed validator signatures the bridge contract verifies. A JSON array of byte values."},"committee_epoch":{"type":"integer","format":"uint64","description":"Committee epoch the signatures are verified against."},"aux_tx_suffix":{"type":"array","items":{"type":"integer","minimum":0,"maximum":255},"description":"The withdrawal's id (its transaction hash), an input to the claim hash rather than the key itself. A JSON array of byte values."},"token":{"$ref":"#/components/schemas/Address","description":"**Pod-side** token address — not what `claim` takes. Map it via `GET /v1/bridge/config`. Omitted on legacy rows that never recorded it."},"amount":{"$ref":"#/components/schemas/HexUint256","description":"Amount in the token's **bridged-chain** decimals — pass straight to `claim`. Never the 18-decimal value that was signed. Omitted on legacy rows."},"to":{"$ref":"#/components/schemas/Address","description":"Recipient on the bridged chain. Omitted on legacy rows."},"claim_hash":{"$ref":"#/components/schemas/Bytes32","description":"The claim hash, which `Bridge.processedRequests` is keyed on — check it to see whether a claim already landed before spending a transaction. Omitted only where no claim was ever recorded, which is also where no certificate can ever be served."}}},"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"},"HexUint256":{"type":"string","pattern":"^0x[a-fA-F0-9]+$","description":"Unsigned 256-bit integer (hex-encoded with 0x prefix)"},"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."}}}}
```

## The HexUint256 object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"HexUint256":{"type":"string","pattern":"^0x[a-fA-F0-9]+$","description":"Unsigned 256-bit integer (hex-encoded with 0x prefix)"}}}}
```

## The DecimalUint256 object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"DecimalUint256":{"type":"string","pattern":"^[0-9]+$","description":"Unsigned 256-bit integer (decimal string representation)"}}}}
```

## The Timestamp object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"Timestamp":{"type":"integer","format":"int64","description":"Unix timestamp in microseconds (not milliseconds or seconds)"}}}}
```

## The TimestampString object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"TimestampString":{"type":"string","pattern":"^[0-9]+$","description":"Unix timestamp in microseconds as a string"}}}}
```

## The Side object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"Side":{"type":"string","enum":["buy","sell"],"description":"Order side — `buy` (bid) or `sell` (ask). For perps, prefer `direction` (see `OrderDirection`) for the position-effect label."}}}}
```

## The OrderStatus object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"OrderStatus":{"type":"string","enum":["pending","active","filled","expired","canceled","margin_canceled","post_only_refused","invalid"],"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- `margin_canceled`: The engine removed the order because the owner's margin capacity was exhausted\n- `post_only_refused`: The engine removed a `post_only` order that would have taken liquidity in the batch that admitted (or re-priced) it. Distinct from `canceled` so an engine refusal can be told apart from a cancel the trader sent — see [Post-only orders](https://docs.v2.pod.network/api-reference/applications-precompiles/orderbook)\n- `invalid`: Rejected at execution and never entered the book; the reject reason travels with the status\n"}}}}
```

## The MarketType object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"MarketType":{"type":"string","enum":["spot","perpetual"],"description":"Type of market - spot trading or perpetual futures"}}}}
```

## The CandleResolution object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"CandleResolution":{"type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time interval for OHLCV candles"}}}}
```

## The TriggerType object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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"}}}}
```

## The TriggerGrouping object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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"}}}}
```

## The OrderKind object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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"}}}}
```

## The OrderDirection object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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"}}}}
```

## The PartialFill object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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)"}}},"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)"}}}}
```

## The Order object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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`. `post_only` is reported on both. 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":"Nonce of the transaction that created the order — the signing key's nonce, not a\nper-order counter, and the delegate's rather than the master's for a delegated order.\nOrders from one `submitBatch` share it.\n"},"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},"post_only":{"type":"boolean","description":"Add-liquidity-only — the order could not trade in the batch that admitted it. Reported on\nboth market types, and **omitted when false**.\n"},"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}}},"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."},"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"},"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"},"OrderStatus":{"type":"string","enum":["pending","active","filled","expired","canceled","margin_canceled","post_only_refused","invalid"],"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- `margin_canceled`: The engine removed the order because the owner's margin capacity was exhausted\n- `post_only_refused`: The engine removed a `post_only` order that would have taken liquidity in the batch that admitted (or re-priced) it. Distinct from `canceled` so an engine refusal can be told apart from a cancel the trader sent — see [Post-only orders](https://docs.v2.pod.network/api-reference/applications-precompiles/orderbook)\n- `invalid`: Rejected at execution and never entered the book; the reject reason travels with the status\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"}}}}
```

## The Candle object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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"}}},"Timestamp":{"type":"integer","format":"int64","description":"Unix timestamp in microseconds (not milliseconds or seconds)"},"HexUint256":{"type":"string","pattern":"^0x[a-fA-F0-9]+$","description":"Unsigned 256-bit integer (hex-encoded with 0x prefix)"}}}}
```

## The Market object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"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\")"},"status":{"type":"string","enum":["pending","active","disabled","settled"],"description":"Lifecycle status. `pending`: created, not yet trading (waiting for `live_at`\nand, for perps, a first oracle price). `active`: trading. `disabled`: halted\nat `disable_at`; every intent is refused, orders and positions stay put.\n`settled`: orders refunded and positions closed at `settlement_price`; kept\nfor history.\n"},"live_at":{"type":"integer","format":"int64","description":"Batch deadline (microseconds) from which a `pending` market may go `active`. Absent for markets that were live from genesis."},"disable_at":{"type":"integer","format":"int64","description":"Batch deadline (microseconds) of a scheduled halt. Present from the moment the `disableMarket` intent applies, i.e. throughout the notice window."},"settlement_price":{"$ref":"#/components/schemas/HexUint256","description":"Price every position was (or will be) closed at, 1e18-scaled. Present once the market is `disabled`."},"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":{"type":"string","description":"Maker fee rate, a decimal fraction of the quote amount; `\"0.010000\"` is 1%."},"taker_fee":{"type":"string","description":"Taker fee rate, a decimal fraction of the quote amount; `\"0.010000\"` is 1%."},"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."},"HexUint256":{"type":"string","pattern":"^0x[a-fA-F0-9]+$","description":"Unsigned 256-bit integer (hex-encoded with 0x prefix)"},"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"}}}}
```

## The TickSnapshot object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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)"}}},"HexUint256":{"type":"string","pattern":"^0x[a-fA-F0-9]+$","description":"Unsigned 256-bit integer (hex-encoded with 0x prefix)"}}}}
```

## The OrderbookSnapshot object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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."}}},"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."},"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)"}}},"HexUint256":{"type":"string","pattern":"^0x[a-fA-F0-9]+$","description":"Unsigned 256-bit integer (hex-encoded with 0x prefix)"}}}}
```

## The PodAttestation object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"PodAttestation":{"type":"object","description":"Validator attestation for a transaction","properties":{"validator_address":{"$ref":"#/components/schemas/Address","description":"Address of the attesting validator"},"sequence_number":{"type":"integer","format":"int64","description":"Sequence number of the attestation"},"batch_index":{"type":"integer","description":"Index within the attestation batch"},"timestamp":{"$ref":"#/components/schemas/Timestamp","description":"Timestamp when the attestation was created (microseconds)"},"signature":{"type":"string","description":"Hex-encoded secp256k1 ECDSA signature"}}},"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"},"Timestamp":{"type":"integer","format":"int64","description":"Unix timestamp in microseconds (not milliseconds or seconds)"}}}}
```

## The PodMetadata object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"PodMetadata":{"type":"object","description":"Pod-specific metadata containing validator attestations for finality verification","properties":{"attestations":{"type":"array","items":{"$ref":"#/components/schemas/PodAttestation"},"description":"List of validator attestations for the transaction"},"committee_epoch":{"type":"integer","format":"int64","description":"The committee epoch during which the transaction was attested"}}},"PodAttestation":{"type":"object","description":"Validator attestation for a transaction","properties":{"validator_address":{"$ref":"#/components/schemas/Address","description":"Address of the attesting validator"},"sequence_number":{"type":"integer","format":"int64","description":"Sequence number of the attestation"},"batch_index":{"type":"integer","description":"Index within the attestation batch"},"timestamp":{"$ref":"#/components/schemas/Timestamp","description":"Timestamp when the attestation was created (microseconds)"},"signature":{"type":"string","description":"Hex-encoded secp256k1 ECDSA signature"}}},"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"},"Timestamp":{"type":"integer","format":"int64","description":"Unix timestamp in microseconds (not milliseconds or seconds)"}}}}
```

## The TransactionReceipt object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"TransactionReceipt":{"type":"object","description":"Transaction receipt with execution status, logs, and Pod-specific metadata","properties":{"type":{"type":"string","description":"Transaction type (EIP-2718)"},"status":{"type":"string","enum":["0x0","0x1"],"description":"Execution status - \"0x1\" for success, \"0x0\" for failure"},"cumulativeGasUsed":{"$ref":"#/components/schemas/HexUint256"},"logs":{"type":"array","items":{"$ref":"#/components/schemas/Log"}},"logsBloom":{"type":"string","description":"Bloom filter for logs (hex-encoded)"},"transactionHash":{"$ref":"#/components/schemas/Bytes32"},"transactionIndex":{"type":"string","nullable":true,"description":"Always null. pod does not order the transactions within a block, so a transaction has no\nposition to report. A log is identified by `transactionHash` and `logIndex` instead.\n"},"blockHash":{"nullable":true,"description":"Hash of the block the transaction was sequenced in; null when it is in no block","allOf":[{"$ref":"#/components/schemas/Bytes32"}]},"blockNumber":{"type":"string","nullable":true,"description":"Block number (hex-encoded), or null when the transaction is in no block - `submitSolutions`,\nrecovery transactions, and an orderbook intent whose auction tick has not executed yet. A null\nblock is not a pending state: the receipt is final either way.\n"},"gasUsed":{"$ref":"#/components/schemas/HexUint256"},"effectiveGasPrice":{"$ref":"#/components/schemas/HexUint256"},"from":{"$ref":"#/components/schemas/Address"},"to":{"$ref":"#/components/schemas/Address"},"contractAddress":{"type":"string","nullable":true,"description":"Contract address if this was a contract creation (null otherwise)"},"pod_metadata":{"$ref":"#/components/schemas/PodMetadata","description":"Pod-specific attestation data for transaction finality verification"}}},"HexUint256":{"type":"string","pattern":"^0x[a-fA-F0-9]+$","description":"Unsigned 256-bit integer (hex-encoded with 0x prefix)"},"Log":{"type":"object","description":"Event log emitted during transaction execution","properties":{"address":{"$ref":"#/components/schemas/Address","description":"Address of the contract that emitted the log"},"topics":{"type":"array","items":{"$ref":"#/components/schemas/Bytes32"},"description":"Indexed event parameters"},"data":{"type":"string","description":"Non-indexed event data (hex-encoded)"}}},"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"},"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."},"PodMetadata":{"type":"object","description":"Pod-specific metadata containing validator attestations for finality verification","properties":{"attestations":{"type":"array","items":{"$ref":"#/components/schemas/PodAttestation"},"description":"List of validator attestations for the transaction"},"committee_epoch":{"type":"integer","format":"int64","description":"The committee epoch during which the transaction was attested"}}},"PodAttestation":{"type":"object","description":"Validator attestation for a transaction","properties":{"validator_address":{"$ref":"#/components/schemas/Address","description":"Address of the attesting validator"},"sequence_number":{"type":"integer","format":"int64","description":"Sequence number of the attestation"},"batch_index":{"type":"integer","description":"Index within the attestation batch"},"timestamp":{"$ref":"#/components/schemas/Timestamp","description":"Timestamp when the attestation was created (microseconds)"},"signature":{"type":"string","description":"Hex-encoded secp256k1 ECDSA signature"}}},"Timestamp":{"type":"integer","format":"int64","description":"Unix timestamp in microseconds (not milliseconds or seconds)"}}}}
```

## The Transaction object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"Transaction":{"type":"object","description":"Transaction object returned by eth_getTransactionByHash","properties":{"hash":{"$ref":"#/components/schemas/Bytes32"},"nonce":{"type":"string"},"blockHash":{"$ref":"#/components/schemas/Bytes32","nullable":true},"blockNumber":{"type":"string","nullable":true},"transactionIndex":{"type":"string","nullable":true},"from":{"$ref":"#/components/schemas/Address"},"to":{"$ref":"#/components/schemas/Address","nullable":true},"value":{"$ref":"#/components/schemas/HexUint256"},"gas":{"type":"string"},"gasPrice":{"type":"string"},"input":{"type":"string"},"v":{"type":"string"},"r":{"type":"string"},"s":{"type":"string"}}},"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)"},"HexUint256":{"type":"string","pattern":"^0x[a-fA-F0-9]+$","description":"Unsigned 256-bit integer (hex-encoded with 0x prefix)"}}}}
```

## The Log object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"Log":{"type":"object","description":"Event log emitted during transaction execution","properties":{"address":{"$ref":"#/components/schemas/Address","description":"Address of the contract that emitted the log"},"topics":{"type":"array","items":{"$ref":"#/components/schemas/Bytes32"},"description":"Indexed event parameters"},"data":{"type":"string","description":"Non-indexed event data (hex-encoded)"}}},"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"},"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."}}}}
```

## The CandlesQuery object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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)"}}}}
```

## The OrdersQuery object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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","margin_canceled","post_only_refused","invalid"],"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- `margin_canceled`: The engine removed the order because the owner's margin capacity was exhausted\n- `post_only_refused`: The engine removed a `post_only` order that would have taken liquidity in the batch that admitted (or re-priced) it. Distinct from `canceled` so an engine refusal can be told apart from a cancel the trader sent — see [Post-only orders](https://docs.v2.pod.network/api-reference/applications-precompiles/orderbook)\n- `invalid`: Rejected at execution and never entered the book; the reject reason travels with the status\n"}}}}
```

## The FillsQuery object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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."}}}}
```

## The TriggersQuery object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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."}}}}
```

## The BackstopTransfersQuery object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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."}}}}
```

## The FillResponse object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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"}}},"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)"},"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)"}}}}
```

## The GetFillsResponse object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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"}}},"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)"},"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)"}}}}
```

## The TriggerOrderResponse object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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)."}}},"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)"},"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)"}}}}
```

## The GetTriggersResponse object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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)."}}},"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)"},"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)"}}}}
```

## The BackstopTransferResponse object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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."}}},"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"},"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)"},"Timestamp":{"type":"integer","format":"int64","description":"Unix timestamp in microseconds (not milliseconds or seconds)"}}}}
```

## The GetBackstopTransfersResponse object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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."}}},"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"},"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)"},"Timestamp":{"type":"integer","format":"int64","description":"Unix timestamp in microseconds (not milliseconds or seconds)"}}}}
```

## The OraclePrice object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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."}}},"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)"},"Timestamp":{"type":"integer","format":"int64","description":"Unix timestamp in microseconds (not milliseconds or seconds)"}}}}
```

## The FundingRate object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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."}}},"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)"},"Timestamp":{"type":"integer","format":"int64","description":"Unix timestamp in microseconds (not milliseconds or seconds)"}}}}
```

## The RankedPosition object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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"}}},"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`."}}}}
```

## The RankedAccount object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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"}}},"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`."}}}}
```

## The GetRankedPositionsResponse object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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"}}},"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`."},"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"}}}}}}
```

## The SubscriptionParams object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"SubscriptionParams":{"type":"object","description":"Options object (second `eth_subscribe` param). All fields are optional except that\n`pod_positions` / `pod_triggers` require `account` (alias `bidder`). Which fields take\neffect depends on the subscription type:\n- `orderbook_ids` (alias `clob_ids`) — `pod_orderbook`, `pod_orders`, `pod_orders_v2`,\n  `pod_candles`, `pod_markets`; ignored by `pod_positions` / `pod_triggers` /\n  `pod_withdrawals` / `pod_transfers`.\n- `depth` — `pod_orderbook` only.\n- `bidder` (alias `account`) — optional for `pod_orders` / `pod_orders_v2` /\n  `pod_withdrawals` / `pod_transfers`; **required** for `pod_positions` and `pod_triggers`.\n- `bidders` — `pod_orders_v2` only, to follow several accounts on one subscription.\n  Mutually exclusive with `bidder`.\n- `since` — all channels (catch-up watermark, microseconds).\n- `since_book` — `pod_orders_v2` only, completing its `(batch, book)` resume cursor.\n","properties":{"depth":{"type":"integer","description":"`pod_orderbook` only: maximum price levels per side to include in snapshots. Omit for all levels."},"orderbook_ids":{"type":"array","items":{"$ref":"#/components/schemas/Bytes32"},"description":"Orderbook (clob) IDs to restrict the subscription to (accepted alias: `clob_ids`). Empty or omitted = all orderbooks. Honored by `pod_orderbook`, `pod_orders`, `pod_candles`, `pod_markets`; ignored by the account-scoped channels."},"clob_ids":{"type":"array","items":{"$ref":"#/components/schemas/Bytes32"},"description":"Accepted alias for `orderbook_ids`."},"bidder":{"$ref":"#/components/schemas/Address","description":"Account filter (accepted alias: `account`). For `pod_orders`, when set, streams only this bidder's updates (omit for all bidders). For `pod_positions` / `pod_triggers` this is **required** — the account whose positions / triggers to stream. On `pod_orders_v2` it is the single-account form of `bidders`, and sending both is an error. On `pod_withdrawals` it is optional and matches `withdrawer` — the debited account. On `pod_transfers` it is optional and matches either side of the transfer, `from` or `to`."},"bidders":{"type":"array","items":{"$ref":"#/components/schemas/Address"},"description":"`pod_orders_v2` only: follow several accounts on one subscription, streaming\nonly rows owned by them. One subscription instead of one per account — each\nsubscription costs the server a copy of every batch, a notification and a\nsocket write whether or not your accounts traded, so this is markedly\ncheaper than N of them.\n\nTreated as a **set**: order is irrelevant and repeats are collapsed, so the\n64-account limit counts *distinct* accounts. Exceeding it is an error, as is\nsending it together with `bidder` (which is the single-account form) or on\nany other channel — a filter that silently did not apply would hand you the\nwhole book.\n\n**This changes the frame shape.** With more than one account the frame\ncarries the `accts` table and every row carries an `a` index, exactly as an\nunfiltered stream does, because otherwise its rows would not be\nattributable. With exactly one account (whether via `bidders` or `bidder`)\nboth are omitted, since every row belongs to you. Decode on the presence of\n`accts`, not on whether you sent a filter.\n"},"since":{"type":"integer","format":"int64","description":"Catch-up watermark: a solution time in microseconds. Delta channels replay buffered ticks after it; state channels emit one current snapshot then stream live. Omit for live-only. If a delta channel's `since` predates the retained buffer, the subscription is rejected."},"since_book":{"$ref":"#/components/schemas/Bytes32","description":"`pod_orders_v2` only: the `book` of the last frame accepted at `since`, which together with it forms the resume cursor. A batch is delivered as one frame per orderbook, so a client can hold part of a batch; replay skips every book at or below this one within `since`, then delivers later batches whole. Omit when the whole of `since` arrived (always true when subscribed to a single orderbook)."}}},"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)"}}}}
```

## The EthSubscriptionMessage object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"EthSubscriptionMessage":{"type":"object","description":"An asynchronous `eth_subscription` notification pushed over the WebSocket after\n`eth_subscribe`. The `params.result` payload depends on the subscription type:\n- `pod_orderbook` → an `OrderbookSnapshot`.\n- `pod_orders` → an array of `OrderUpdate`.\n- `pod_candles` → a `CandleTick`.\n- `pod_markets` → a `MarketDynamicEntry`.\n- `pod_positions` → a `PositionsUpdate`.\n- `pod_triggers` → a `TriggersUpdate`.\n- `pod_withdrawals` → an array of `WithdrawalUpdate`.\n- `pod_transfers` → an array of `TransferUpdate`.\n","properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"method":{"type":"string","enum":["eth_subscription"]},"params":{"type":"object","properties":{"subscription":{"type":"string","description":"The subscription ID this message belongs to."},"result":{"description":"The streamed payload — shape determined by the subscription type.","oneOf":[{"$ref":"#/components/schemas/OrderbookSnapshot"},{"type":"array","items":{"$ref":"#/components/schemas/OrderUpdate"}},{"$ref":"#/components/schemas/CandleTick"},{"$ref":"#/components/schemas/MarketDynamicEntry"},{"$ref":"#/components/schemas/PositionsUpdate"},{"$ref":"#/components/schemas/TriggersUpdate"},{"type":"array","items":{"$ref":"#/components/schemas/WithdrawalUpdate"}},{"type":"array","items":{"$ref":"#/components/schemas/TransferUpdate"}}]}}}}},"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."}}},"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."},"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)"}}},"HexUint256":{"type":"string","pattern":"^0x[a-fA-F0-9]+$","description":"Unsigned 256-bit integer (hex-encoded with 0x prefix)"},"OrderUpdate":{"type":"object","description":"A single change to an order, pushed in the `pod_orders` notification array. It is a\n`type`-tagged union: the `type` field selects the variant and the remaining fields depend\non it.\n- `new` / `invalid`: the full `Order` fields are inlined alongside `type` (an `invalid`\n  order was rejected at execution and never entered the book; the reason is on its\n  `status`).\n- `expired` / `canceled`: only `type` and `order_id` are present. This variant carries no\n  status, so an engine removal — such as a refused post-only order — is\n  indistinguishable from a cancel the trader sent. Use `pod_orders_v2`, whose `cancel` event\n  carries `st`, if you need to tell them apart.\n- `modified`: a resting order's price and/or size was changed in place by an `update`\n  intent — `type`, `order_id`, and the new `new_price` / `new_size` are present.\n- `fill`: the `OrderFillUpdate` fields are inlined alongside `type`.\n","required":["type"],"properties":{"type":{"type":"string","enum":["new","invalid","expired","canceled","modified","fill"],"description":"Discriminator selecting the variant."},"order_id":{"$ref":"#/components/schemas/Bytes32","description":"Present for `expired`, `canceled`, and `modified` — the affected order id."},"new_price":{"$ref":"#/components/schemas/HexUint256","description":"`modified` only: the order's price after the change (1e18)."},"new_size":{"$ref":"#/components/schemas/HexUint256","description":"`modified` only: the order's remaining base size after the change (1e18, unsigned magnitude — side is unchanged from the original `new`)."}}},"CandleTick":{"type":"object","description":"Per-tick candle hint streamed on the `pod_candles` subscription — one object per orderbook\ncleared this settlement. It is not a closed OHLCV bar (use `ob_getCandles` for those); the\nclient folds it into the forming bar.\n","required":["orderbook","timestamp_us","price","volume"],"properties":{"orderbook":{"$ref":"#/components/schemas/Bytes32"},"timestamp_us":{"type":"integer","format":"int64","description":"Batch deadline (settlement time) in microseconds."},"price":{"type":"string","description":"Clearing price for this tick (decimal, 1e18)."},"volume":{"type":"string","description":"Total volume cleared this tick (decimal, 1e18)."}}},"MarketDynamicEntry":{"type":"object","description":"Live market statistics for one orderbook, streamed on the `pod_markets` subscription (one\nobject per orderbook). Optional fields are omitted (not null) when unset — e.g. perp-only\nfields on a spot market, or stats with no data yet.\n","required":["orderbook_id","volume_24h"],"properties":{"orderbook_id":{"$ref":"#/components/schemas/Bytes32"},"last_clearing_price":{"type":"string","description":"Most recent clearing price (decimal, 1e18). Omitted if the market has not cleared."},"volume_24h":{"type":"string","description":"Rolling 24h traded volume (decimal, 1e18)."},"high_24h":{"type":"string","description":"24h high clearing price (decimal, 1e18). Omitted if unavailable."},"low_24h":{"type":"string","description":"24h low clearing price (decimal, 1e18). Omitted if unavailable."},"price_change_24h":{"type":"integer","format":"int128","description":"24h price change (signed, 1e18), as a JSON number. Omitted if unavailable."},"oracle_price":{"type":"string","description":"Perp only: latest oracle price (decimal, 1e18)."},"mark_price":{"type":"string","description":"Perp only: current mark price (decimal, 1e18)."},"funding_rate":{"type":"string","description":"Perp only: current funding rate (decimal)."},"funding_index":{"type":"string","description":"Perp only: cumulative funding index (decimal)."},"funding_last_updated_us":{"type":"integer","format":"int64","description":"Perp only: last funding update time (microseconds)."},"open_interest":{"type":"string","description":"Perp only: open interest (decimal, 1e18)."}}},"PositionsUpdate":{"type":"object","description":"A `pod_positions` notification — the account's full positions snapshot, pushed for a settlement that touched the account.","required":["account","data"],"properties":{"account":{"$ref":"#/components/schemas/Address"},"data":{"$ref":"#/components/schemas/PositionsResponse"}}},"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)."}}},"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`."},"TriggersUpdate":{"type":"object","description":"A `pod_triggers` notification — the account's armed TP/SL triggers, pushed for a settlement that touched the account. Carries the `GetTriggersResponse` fields inlined alongside `account`.","required":["account","triggers","total_count"],"properties":{"account":{"$ref":"#/components/schemas/Address"},"triggers":{"type":"array","items":{"$ref":"#/components/schemas/TriggerOrderResponse"}},"total_count":{"type":"integer","description":"Count of triggers for the account before pagination."},"next_cursor":{"type":"string","nullable":true,"description":"Pagination cursor, 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)."}}},"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)"},"WithdrawalUpdate":{"type":"object","description":"One outcome from `pod_withdrawals` — what became of a single bridge withdrawal when its\ntick executed. The REST backfill (`GET /v1/bridge/withdrawals[/{account}]?since=`) serves the\nidentical shape, so an outcome read after a reconnect is indistinguishable from one that\narrived live.\n\nA withdrawal debits the account's balance, is burned on Pod, and is claimed on the bridge's\nbridged chain; nothing is credited to a Pod account on the way. No `error` means it is on its\nway there. `insufficient_balance` and `not_included` both mean **nothing was debited** — the\nfunds are still on the account and no claim will ever exist — and this is the only\nsurface that carries the reason, so a client watching only the bridged chain waits forever for\nan event that cannot come.\n\nThe claim itself is not here: read it from `GET /v1/bridge/withdrawals/by-id/{tx_hash}`,\nwhich reports `claimable` / `pending` / `refused` and attaches the proof once a certificate\ncan be assembled, or from `pod_getBridgeClaimProof(txHash)` for the proof alone.\n","required":["tx_hash","withdrawer","to","token","amount","timestamp_us"],"properties":{"tx_hash":{"$ref":"#/components/schemas/Bytes32","description":"The `withdraw` transaction's own hash, which is the withdrawal's identity. A withdrawal is always its own transaction — it targets the bridge precompile, so it can be neither a `submitBatch` sub-intent nor a `delegated` inner call — and this is the key the claim is fetched by. Rows predating this design carry a computed `keccak256(abi.encode(signer, nonce, sequence))` id here instead; the same lookups serve both, but only the current generation is a real transaction hash, so do not feed a historical value to `eth_getTransactionByHash`."},"withdrawer":{"$ref":"#/components/schemas/Address","description":"The debited account, and what the `account` subscription filter matches. It is also the transaction signer for current withdrawals; on rows predating this design it can differ, being the master of a delegated withdrawal rather than the delegate that signed."},"to":{"$ref":"#/components/schemas/Address","description":"Recipient **on the bridged chain**. Nothing is credited on Pod."},"token":{"$ref":"#/components/schemas/Address","description":"Pod-side token address. Map it to the asset the claim pays out using the token list from `GET /v1/bridge/config`."},"amount":{"type":"string","description":"Amount in Pod's 18 decimals, hex-encoded — what the user signed and what left the account. The claim carries this converted to the token's bridged-chain decimals, which differs by 10^12 for a 6-decimal token, so never pass this value to `claim`; take that one from the proof response. A refused withdrawal still reports the amount that was asked for."},"error":{"type":"string","enum":["insufficient_balance","not_included"],"description":"Names why the withdrawal was refused. `insufficient_balance` — the balance did not cover it at execution; admission deliberately does not check the balance, because pending fills can raise it before the tick runs. `not_included` — the solver omitted a finalized intent before its deadline passed. Treat an unrecognised value as a failure rather than as success: the vocabulary can grow. An absent `error` is the normal claimable case but is not a guarantee — a node whose bridge config does not cover the token records the row, signs nothing, and reports `refused` with no reason — so confirm against `status`/`proof` rather than treating absent-`error` as \"on its way\"."},"timestamp_us":{"type":"integer","format":"int64","description":"The tick's batch deadline, in microseconds — also the `since` cursor for this subscription and for the REST backfill, so a value read here can be handed straight to either."}}},"TransferUpdate":{"type":"object","description":"One outcome from `pod_transfers` — what became of a single account-to-account transfer when\nits tick executed.\n\nA transfer has no receipt of its own: it is a solver-gated intent that settles inside the\nsolver's `submitSolutions` transaction, and a refused one still consumes its nonce while\nchanging no state. This channel is therefore the only way to tell refused from succeeded.\n\nThe sibling of `WithdrawalUpdate` rather than the same shape: a transfer's `to` is an account\non **this** ledger and the funds land there, while a withdrawal's `to` is an address on the\nbridged chain. Every error here also means **nothing moved on either side**; retrying means a\nnew transaction, and so a new `transfer_id`.\n","required":["transfer_id","from","to","token","amount","timestamp_us"],"properties":{"transfer_id":{"$ref":"#/components/schemas/Bytes32","description":"Identity of the transfer intent, `keccak256(abi.encode(signer, nonce, sequence))`, where `sequence` is its position inside a `submitBatch` envelope (`0` for a standalone `transfer`). Computable before submitting."},"from":{"$ref":"#/components/schemas/Address","description":"The debited account, which is also the transaction signer — transfers are not delegable. Matched by the `account` subscription filter, as is `to`."},"to":{"$ref":"#/components/schemas/Address","description":"The credited account, **on this ledger**. Unlike a withdrawal's `to`, this is a Pod address and the funds land there."},"token":{"$ref":"#/components/schemas/Address","description":"Token address on Pod."},"amount":{"type":"string","description":"Amount in Pod's 18 decimals, hex-encoded. A refused transfer still reports the amount that was asked for."},"error":{"type":"string","enum":["insufficient_balance","recipient_not_resident","not_included"],"description":"Absent when the funds moved. `insufficient_balance` — the sender's withdrawable balance did not cover it at execution; admission deliberately does not check the balance, because pending fills can raise it before the tick runs. `recipient_not_resident` — the recipient's account was not resident when the tick ran, so the credit had nowhere to land. `not_included` — the solver omitted a finalized intent before its deadline passed. Treat an unrecognised value as a failure rather than as success: the vocabulary can grow."},"timestamp_us":{"type":"integer","format":"int64","description":"The tick's batch deadline, in microseconds — also the `since` cursor for this subscription."}}}}}}
```

## The OrdersFrameV2 object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"OrdersFrameV2":{"type":"object","description":"One `pod_orders_v2` notification: everything that happened to one orderbook in one auction\nbatch.\n\nThe batch and the orderbook are named once, orders created in the batch appear once in\n`orders`, and `events` describes what happened, referencing an order by `o` (an index into\n`orders`) or by `id` (an order resting from an earlier batch). Ignore event kinds and fields\nyou do not recognise — new kinds are added without a new channel version.\n","required":["book","batch","orders","events"],"properties":{"book":{"$ref":"#/components/schemas/Bytes32","description":"The orderbook these actions happened on."},"batch":{"type":"integer","format":"int64","description":"Deadline of the batch the actions **landed in**, in microseconds. For an order this is at\nor before the `deadline` it was signed for, because an intent may be included in an\nearlier batch than the one it targets. Also the first half of the resume cursor\n(`since`); the second is this frame's `book` (`since_book`).\n"},"accts":{"type":"array","items":{"$ref":"#/components/schemas/Address"},"description":"Owner addresses, referenced by index from `orders[].a` and from events that name an\norder by `id`.\n\nOmitted only when the subscription names exactly one account (`bidder`, or a\none-element `bidders`), where every row belongs to you and an index would say\nnothing. A subscription naming *several* accounts carries the table just like an\nunfiltered one. Decode on this field's presence rather than on the filter you sent.\n"},"orders":{"type":"array","items":{"$ref":"#/components/schemas/OrderEntityV2"},"description":"Orders created in this batch, each appearing exactly once."},"events":{"type":"array","items":{"$ref":"#/components/schemas/OrderEventV2"},"description":"What happened, in a deterministic order: new/rejected orders, then cancellations, then\nmodifications, then post-only refusals, then refused amendments, then fills ascending by\norder id, then expirations, then backstop sweeps.\n\nThe order is not arbitrary: apply events as they arrive and your book is never transiently\nwrong. Cancellations precede the fills so you never hold an order that has already been\nremoved, and post-only refusals sit **after** the modifications rather than with the other\ncancellations, so an order repriced onto a crossing level and refused for it ends the frame\nremoved rather than resting at the refused price.\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)"},"OrderEntityV2":{"type":"object","description":"An order as admitted, in a `pod_orders_v2` frame: the facts that do not change. Its status is\n**not** here — that is implied by the events referencing it, which is what lets new event\nkinds be added without changing this object.\n\nOptional fields are omitted at their default rather than sent, so a plain user-signed limit\norder is small. Each omission means a specific thing, noted per field.\n","required":["id","tx","n","px","sz"],"properties":{"id":{"$ref":"#/components/schemas/Bytes32","description":"Resting order id, as used by cancel/update intents and the REST order APIs.\n\nDerived as `keccak256(abi_encode(signer, nonce, sequence))`, where `signer` is the key\nthat signed the transaction, `nonce` is that transaction's nonce (this entity's `n`), and\n`sequence` is the order's position inside a `submitBatch` envelope — `0` for a\nsingle-intent transaction. So you can compute the id yourself before broadcasting and\nmatch your own orders to this stream the first time it mentions them, without waiting on\na receipt.\n\n**For a delegated order, derive from the delegate's address, not the master's.** The id\nkeys on the signer so two delegates of one master cannot collide, whereas `a`/`accts`\nreport the *owner*. The two differ exactly when a delegate placed the order.\n"},"tx":{"$ref":"#/components/schemas/Bytes32","description":"Hash of the creating transaction, or of its parent `submitBatch` envelope. Zero for engine-generated orders."},"a":{"type":"integer","description":"Index into the frame's `accts`. Present if and only if `accts` is — see there."},"n":{"type":"integer","format":"int64","description":"Nonce of the **transaction** that created the order — the signing key's nonce, not a\nper-order counter. For a delegated order that is the *delegate's* nonce, not the\nmaster's.\n\nTwo orders from one `submitBatch` therefore share both `n` and `tx`, and differ only in\n`id`: `n` belongs to the envelope, not to the intents inside it. Use `id` to tell them\napart.\n"},"px":{"type":"string","description":"Limit price in quote/base units, 1e18-scaled, as a decimal string."},"sz":{"type":"string","description":"Signed order size, 1e18-scaled, decimal. Positive = buy/long, negative = sell/short — the sign carries the side, so there is no separate side field."},"end":{"type":"integer","format":"int64","description":"TTL expiry in microseconds. **Omitted means the order never expires** (rather than unknown)."},"kind":{"type":"string","enum":["liquidation","triggered","adl","adl_counterparty","backstop_transfer"],"description":"How the order came about. **Omitted means user-signed.**"},"type":{"type":"string","enum":["market"],"description":"**Omitted means a limit order.**"},"reduce_only":{"type":"boolean","description":"Omitted means false."},"ioc":{"type":"boolean","description":"Immediate-or-cancel. Omitted means false."},"post_only":{"type":"boolean","description":"Add-liquidity-only — the order may not trade in the batch that admitted it, so it can rest\nthrough a batch it appeared to cross. Omitted means false.\n"},"trigger":{"type":"string","enum":["take_profit","stop_loss"],"description":"Which trigger produced this order. Omitted unless it is a fired trigger's synthetic."},"grouping":{"type":"string","enum":["asset"],"description":"Trigger grouping inherited from the parent trigger. Omitted when ungrouped."}}},"OrderEventV2":{"type":"object","description":"One transition in a `pod_orders_v2` frame, discriminated by `k`.\n\nEvery event names the order it concerns by exactly one of `o` (an index into this frame's\n`orders`) or `id` (an order resting from an earlier batch, whose owner is `a`). **Ignore\nvalues of `k` you do not recognise**: new kinds will be added without a new channel version.\n","required":["k"],"properties":{"k":{"type":"string","enum":["new","reject","fill","cancel","expire","modify","modify_reject"],"description":"- `new` — the order entered the book.\n- `reject` — dropped during execution, never rested; `why` carries the reason.\n- `fill` — matched, wholly or partly.\n- `cancel` — removed by a cancel intent or by the engine. An engine removal carries `st`\n  (today only `post_only_refused`); a cancel the owner sent omits it.\n- `expire` — removed on reaching its TTL.\n- `modify` — a resting order's price and/or size changed in place.\n- `modify_reject` — an amendment the engine refused. The order is untouched; `code` says why.\n"},"o":{"type":"integer","description":"Index into this frame's `orders`. Present when the order was created in this batch."},"id":{"$ref":"#/components/schemas/Bytes32","description":"Order id. Present instead of `o` when the order has been resting since an earlier batch."},"a":{"type":"integer","description":"Index into the frame's `accts`, accompanying `id`. Present if and only if `accts` is."},"why":{"type":"string","description":"On `reject`, why the engine dropped the order. On `modify_reject`, detail the `code`\ncannot carry — the amounts on `insufficient_balance`, `invalid_price` and\n`notional_below_minimum`, the pair on `unknown_market`, the whole reason on\n`unspecified`. Absent for every other code, where it would restate the code.\n"},"by":{"type":"integer","description":"`modify_reject` only: index into the frame's `accts` for the account that *asked*, which\nis deliberately not `a`. A refusal says nothing about who owns the order, and on\n`not_order_owner` the requester is precisely who does not. Absent when the subscription\nnames a single account.\n"},"req_px":{"type":"string","description":"`modify_reject` only: the price that was asked for, 1e18-scaled decimal. Echoed so a client with several amendments outstanding on one order can tell which this answers."},"req_sz":{"type":"string","description":"`modify_reject` only: the size that was asked for, 1e18-scaled decimal, unsigned."},"code":{"type":"string","enum":["insufficient_balance","invalid_price","zero_size","notional_below_minimum","unknown_market","order_not_found","not_order_owner","stale_nonce","wrong_pair","engine_managed_order","price_above_maximum","price_off_tick","market_order_must_be_ioc","size_above_maximum","size_off_lot","notional_overflow","notional_above_cap","unspecified"],"description":"`modify_reject` only: the stable reason identifier — branch on this, not on `why`.\nTreat a value you do not recognise as `unspecified`: the set grows as the engine names\nreasons, and `unspecified` itself means it has not named this one yet.\n"},"b":{"type":"string","description":"`fill` only. Base filled **by this fill**, 1e18-scaled decimal — this batch's amount, not a running total."},"q":{"type":"string","description":"`fill` only. Quote filled by this fill, 1e18-scaled decimal."},"tb":{"type":"string","description":"Total base filled over the order's life, 1e18-scaled decimal. On `fill`, the running\ntotal **so far**; on `cancel` and `expire`, the final total the order left the book with.\n\nOn a `fill` it is sent alongside `b` rather than instead of it: `b` is what you apply,\n`tb` is what you check your running figure against, so a divergence surfaces on the next\nfill instead of drifting. On a terminal event it is the settled figure, so you need no\naccumulation at all — see the terminal-totals rule on the method description.\n\nZero is sent rather than the field being omitted, so an order that never filled is\nreported as such rather than being indistinguishable from a field you failed to read.\n"},"tq":{"type":"string","description":"Total quote filled over the order's life, 1e18-scaled decimal. Running total on `fill`, final total on `cancel`/`expire`, as `tb`."},"tf":{"type":"string","description":"Total fee charged over the order's life, 1e18-scaled decimal. Running total on `fill`,\nfinal total on `cancel`/`expire`, as `tb`.\n\nThere is no per-fill fee counterpart — no such figure exists at this boundary to send. For\nthe fee attributable to one fill, subtract the previous `tf` seen for that order, or zero\non its first fill.\n"},"st":{"type":"string","enum":["filled","canceled","margin_canceled","expired","post_only_refused"],"description":"The terminal status an event closed the order with.\n\nOn `fill`: present only on the fill that **closed** the order; its absence there means the\norder is still working.\n\nOn `cancel`: present only when the **engine** removed the order rather than the owner\ncancelling it — today that is `post_only_refused`, a `post_only` order removed because it\nwould have taken liquidity in the batch that admitted or re-priced it. An ordinary cancel\nomits `st`, so a client that ignores the field reads every `cancel` exactly as it did\nbefore.\n\nA refusal is ordered **after** the `modify` events in its frame, unlike every other cancel.\nAn order repriced onto a crossing level and refused for it emits `modify` and then `cancel`:\napply them in the order given and the order ends the frame removed, rather than resurrected\nat the refused price.\n"},"pa":{"type":"string","description":"`fill`: the owner's position after this fill, 1e18-scaled **signed** decimal.\n\nPresent when a fill moved a position — so absent on spot, which has none, and absent\non the two fills the engine fabricates without moving one (the backstop sweep, and the\nzero-size fill a cap-to-filled amendment emits to carry `st`). Do **not** read its\nabsence as \"spot\": take market type from the market. A client tracking positions treats\nan absent `pa` as unchanged, which it is.\nThe position *before* is not sent because it is derivable — `pa - sign(sz) * b`, the same\narithmetic the engine used to produce the pair — and the transition between the two is\nwhat says whether the fill opened, added to, reduced, closed or flipped the position. A\nraw position rather than a label so a client tracking positions off this stream can also\nassert its running figure against it, the way `tb`/`tq` anchor the amounts.\n"},"px":{"type":"string","description":"`modify` only: the order's price after the change, 1e18-scaled decimal."},"sz":{"type":"string","description":"`modify` only: the order's size after the change, 1e18-scaled decimal."}}}}}}
```

## The OrderEntityV2 object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"OrderEntityV2":{"type":"object","description":"An order as admitted, in a `pod_orders_v2` frame: the facts that do not change. Its status is\n**not** here — that is implied by the events referencing it, which is what lets new event\nkinds be added without changing this object.\n\nOptional fields are omitted at their default rather than sent, so a plain user-signed limit\norder is small. Each omission means a specific thing, noted per field.\n","required":["id","tx","n","px","sz"],"properties":{"id":{"$ref":"#/components/schemas/Bytes32","description":"Resting order id, as used by cancel/update intents and the REST order APIs.\n\nDerived as `keccak256(abi_encode(signer, nonce, sequence))`, where `signer` is the key\nthat signed the transaction, `nonce` is that transaction's nonce (this entity's `n`), and\n`sequence` is the order's position inside a `submitBatch` envelope — `0` for a\nsingle-intent transaction. So you can compute the id yourself before broadcasting and\nmatch your own orders to this stream the first time it mentions them, without waiting on\na receipt.\n\n**For a delegated order, derive from the delegate's address, not the master's.** The id\nkeys on the signer so two delegates of one master cannot collide, whereas `a`/`accts`\nreport the *owner*. The two differ exactly when a delegate placed the order.\n"},"tx":{"$ref":"#/components/schemas/Bytes32","description":"Hash of the creating transaction, or of its parent `submitBatch` envelope. Zero for engine-generated orders."},"a":{"type":"integer","description":"Index into the frame's `accts`. Present if and only if `accts` is — see there."},"n":{"type":"integer","format":"int64","description":"Nonce of the **transaction** that created the order — the signing key's nonce, not a\nper-order counter. For a delegated order that is the *delegate's* nonce, not the\nmaster's.\n\nTwo orders from one `submitBatch` therefore share both `n` and `tx`, and differ only in\n`id`: `n` belongs to the envelope, not to the intents inside it. Use `id` to tell them\napart.\n"},"px":{"type":"string","description":"Limit price in quote/base units, 1e18-scaled, as a decimal string."},"sz":{"type":"string","description":"Signed order size, 1e18-scaled, decimal. Positive = buy/long, negative = sell/short — the sign carries the side, so there is no separate side field."},"end":{"type":"integer","format":"int64","description":"TTL expiry in microseconds. **Omitted means the order never expires** (rather than unknown)."},"kind":{"type":"string","enum":["liquidation","triggered","adl","adl_counterparty","backstop_transfer"],"description":"How the order came about. **Omitted means user-signed.**"},"type":{"type":"string","enum":["market"],"description":"**Omitted means a limit order.**"},"reduce_only":{"type":"boolean","description":"Omitted means false."},"ioc":{"type":"boolean","description":"Immediate-or-cancel. Omitted means false."},"post_only":{"type":"boolean","description":"Add-liquidity-only — the order may not trade in the batch that admitted it, so it can rest\nthrough a batch it appeared to cross. Omitted means false.\n"},"trigger":{"type":"string","enum":["take_profit","stop_loss"],"description":"Which trigger produced this order. Omitted unless it is a fired trigger's synthetic."},"grouping":{"type":"string","enum":["asset"],"description":"Trigger grouping inherited from the parent trigger. Omitted when ungrouped."}}},"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."}}}}
```

## The OrderEventV2 object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"OrderEventV2":{"type":"object","description":"One transition in a `pod_orders_v2` frame, discriminated by `k`.\n\nEvery event names the order it concerns by exactly one of `o` (an index into this frame's\n`orders`) or `id` (an order resting from an earlier batch, whose owner is `a`). **Ignore\nvalues of `k` you do not recognise**: new kinds will be added without a new channel version.\n","required":["k"],"properties":{"k":{"type":"string","enum":["new","reject","fill","cancel","expire","modify","modify_reject"],"description":"- `new` — the order entered the book.\n- `reject` — dropped during execution, never rested; `why` carries the reason.\n- `fill` — matched, wholly or partly.\n- `cancel` — removed by a cancel intent or by the engine. An engine removal carries `st`\n  (today only `post_only_refused`); a cancel the owner sent omits it.\n- `expire` — removed on reaching its TTL.\n- `modify` — a resting order's price and/or size changed in place.\n- `modify_reject` — an amendment the engine refused. The order is untouched; `code` says why.\n"},"o":{"type":"integer","description":"Index into this frame's `orders`. Present when the order was created in this batch."},"id":{"$ref":"#/components/schemas/Bytes32","description":"Order id. Present instead of `o` when the order has been resting since an earlier batch."},"a":{"type":"integer","description":"Index into the frame's `accts`, accompanying `id`. Present if and only if `accts` is."},"why":{"type":"string","description":"On `reject`, why the engine dropped the order. On `modify_reject`, detail the `code`\ncannot carry — the amounts on `insufficient_balance`, `invalid_price` and\n`notional_below_minimum`, the pair on `unknown_market`, the whole reason on\n`unspecified`. Absent for every other code, where it would restate the code.\n"},"by":{"type":"integer","description":"`modify_reject` only: index into the frame's `accts` for the account that *asked*, which\nis deliberately not `a`. A refusal says nothing about who owns the order, and on\n`not_order_owner` the requester is precisely who does not. Absent when the subscription\nnames a single account.\n"},"req_px":{"type":"string","description":"`modify_reject` only: the price that was asked for, 1e18-scaled decimal. Echoed so a client with several amendments outstanding on one order can tell which this answers."},"req_sz":{"type":"string","description":"`modify_reject` only: the size that was asked for, 1e18-scaled decimal, unsigned."},"code":{"type":"string","enum":["insufficient_balance","invalid_price","zero_size","notional_below_minimum","unknown_market","order_not_found","not_order_owner","stale_nonce","wrong_pair","engine_managed_order","price_above_maximum","price_off_tick","market_order_must_be_ioc","size_above_maximum","size_off_lot","notional_overflow","notional_above_cap","unspecified"],"description":"`modify_reject` only: the stable reason identifier — branch on this, not on `why`.\nTreat a value you do not recognise as `unspecified`: the set grows as the engine names\nreasons, and `unspecified` itself means it has not named this one yet.\n"},"b":{"type":"string","description":"`fill` only. Base filled **by this fill**, 1e18-scaled decimal — this batch's amount, not a running total."},"q":{"type":"string","description":"`fill` only. Quote filled by this fill, 1e18-scaled decimal."},"tb":{"type":"string","description":"Total base filled over the order's life, 1e18-scaled decimal. On `fill`, the running\ntotal **so far**; on `cancel` and `expire`, the final total the order left the book with.\n\nOn a `fill` it is sent alongside `b` rather than instead of it: `b` is what you apply,\n`tb` is what you check your running figure against, so a divergence surfaces on the next\nfill instead of drifting. On a terminal event it is the settled figure, so you need no\naccumulation at all — see the terminal-totals rule on the method description.\n\nZero is sent rather than the field being omitted, so an order that never filled is\nreported as such rather than being indistinguishable from a field you failed to read.\n"},"tq":{"type":"string","description":"Total quote filled over the order's life, 1e18-scaled decimal. Running total on `fill`, final total on `cancel`/`expire`, as `tb`."},"tf":{"type":"string","description":"Total fee charged over the order's life, 1e18-scaled decimal. Running total on `fill`,\nfinal total on `cancel`/`expire`, as `tb`.\n\nThere is no per-fill fee counterpart — no such figure exists at this boundary to send. For\nthe fee attributable to one fill, subtract the previous `tf` seen for that order, or zero\non its first fill.\n"},"st":{"type":"string","enum":["filled","canceled","margin_canceled","expired","post_only_refused"],"description":"The terminal status an event closed the order with.\n\nOn `fill`: present only on the fill that **closed** the order; its absence there means the\norder is still working.\n\nOn `cancel`: present only when the **engine** removed the order rather than the owner\ncancelling it — today that is `post_only_refused`, a `post_only` order removed because it\nwould have taken liquidity in the batch that admitted or re-priced it. An ordinary cancel\nomits `st`, so a client that ignores the field reads every `cancel` exactly as it did\nbefore.\n\nA refusal is ordered **after** the `modify` events in its frame, unlike every other cancel.\nAn order repriced onto a crossing level and refused for it emits `modify` and then `cancel`:\napply them in the order given and the order ends the frame removed, rather than resurrected\nat the refused price.\n"},"pa":{"type":"string","description":"`fill`: the owner's position after this fill, 1e18-scaled **signed** decimal.\n\nPresent when a fill moved a position — so absent on spot, which has none, and absent\non the two fills the engine fabricates without moving one (the backstop sweep, and the\nzero-size fill a cap-to-filled amendment emits to carry `st`). Do **not** read its\nabsence as \"spot\": take market type from the market. A client tracking positions treats\nan absent `pa` as unchanged, which it is.\nThe position *before* is not sent because it is derivable — `pa - sign(sz) * b`, the same\narithmetic the engine used to produce the pair — and the transition between the two is\nwhat says whether the fill opened, added to, reduced, closed or flipped the position. A\nraw position rather than a label so a client tracking positions off this stream can also\nassert its running figure against it, the way `tb`/`tq` anchor the amounts.\n"},"px":{"type":"string","description":"`modify` only: the order's price after the change, 1e18-scaled decimal."},"sz":{"type":"string","description":"`modify` only: the order's size after the change, 1e18-scaled decimal."}}},"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."}}}}
```

## The OrderUpdate object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"OrderUpdate":{"type":"object","description":"A single change to an order, pushed in the `pod_orders` notification array. It is a\n`type`-tagged union: the `type` field selects the variant and the remaining fields depend\non it.\n- `new` / `invalid`: the full `Order` fields are inlined alongside `type` (an `invalid`\n  order was rejected at execution and never entered the book; the reason is on its\n  `status`).\n- `expired` / `canceled`: only `type` and `order_id` are present. This variant carries no\n  status, so an engine removal — such as a refused post-only order — is\n  indistinguishable from a cancel the trader sent. Use `pod_orders_v2`, whose `cancel` event\n  carries `st`, if you need to tell them apart.\n- `modified`: a resting order's price and/or size was changed in place by an `update`\n  intent — `type`, `order_id`, and the new `new_price` / `new_size` are present.\n- `fill`: the `OrderFillUpdate` fields are inlined alongside `type`.\n","required":["type"],"properties":{"type":{"type":"string","enum":["new","invalid","expired","canceled","modified","fill"],"description":"Discriminator selecting the variant."},"order_id":{"$ref":"#/components/schemas/Bytes32","description":"Present for `expired`, `canceled`, and `modified` — the affected order id."},"new_price":{"$ref":"#/components/schemas/HexUint256","description":"`modified` only: the order's price after the change (1e18)."},"new_size":{"$ref":"#/components/schemas/HexUint256","description":"`modified` only: the order's remaining base size after the change (1e18, unsigned magnitude — side is unchanged from the original `new`)."}}},"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)"}}}}
```

## The OrderFillUpdate object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"OrderFillUpdate":{"type":"object","description":"A fill applied to a resting order in a settlement round, as carried by the `fill` variant of `OrderUpdate`.","properties":{"orderbook_id":{"$ref":"#/components/schemas/Bytes32"},"order_id":{"$ref":"#/components/schemas/Bytes32","description":"Identifier of the filled order."},"tx_hash":{"$ref":"#/components/schemas/Bytes32","description":"Hash of the transaction that created the filled order."},"bidder":{"$ref":"#/components/schemas/Address","description":"Owner of the filled order. Use this to attribute the fill client-side."},"status":{"$ref":"#/components/schemas/OrderStatus","description":"Order status after this fill (`filled` or `active` if partially filled)."},"base_amount":{"$ref":"#/components/schemas/HexUint256","description":"Base tokens filled in this round (1e18)."},"quote_amount":{"$ref":"#/components/schemas/HexUint256","description":"Quote tokens filled in this round (1e18)."},"filled_base_amount":{"$ref":"#/components/schemas/HexUint256","description":"Cumulative base filled across all rounds (1e18)."},"filled_quote_amount":{"$ref":"#/components/schemas/HexUint256","description":"Cumulative quote filled across all rounds (1e18)."},"effective_price":{"$ref":"#/components/schemas/HexUint256","description":"Effective fill price so far (filled_quote / filled_base, 1e18)."},"fee":{"$ref":"#/components/schemas/HexUint256","description":"Cumulative fee for the order (1e18). Currently always zero."},"position_before":{"type":"string","nullable":true,"description":"Perp only — signed position (1e18) before the first fill on this order."},"position_after":{"type":"string","nullable":true,"description":"Perp only — signed position (1e18) after this fill."}}},"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)"},"OrderStatus":{"type":"string","enum":["pending","active","filled","expired","canceled","margin_canceled","post_only_refused","invalid"],"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- `margin_canceled`: The engine removed the order because the owner's margin capacity was exhausted\n- `post_only_refused`: The engine removed a `post_only` order that would have taken liquidity in the batch that admitted (or re-priced) it. Distinct from `canceled` so an engine refusal can be told apart from a cancel the trader sent — see [Post-only orders](https://docs.v2.pod.network/api-reference/applications-precompiles/orderbook)\n- `invalid`: Rejected at execution and never entered the book; the reject reason travels with the status\n"},"HexUint256":{"type":"string","pattern":"^0x[a-fA-F0-9]+$","description":"Unsigned 256-bit integer (hex-encoded with 0x prefix)"}}}}
```

## The PerpPositionSide object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"PerpPositionSide":{"type":"string","enum":["long","short"],"description":"Side of a perpetual position, derived from the sign of `size`."}}}}
```

## The SpotHolding object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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)"}}}}
```

## The PerpPosition object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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}}},"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."},"PerpPositionSide":{"type":"string","enum":["long","short"],"description":"Side of a perpetual position, derived from the sign of `size`."},"HexUint256":{"type":"string","pattern":"^0x[a-fA-F0-9]+$","description":"Unsigned 256-bit integer (hex-encoded with 0x prefix)"}}}}
```

## The Position object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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`."}}}}
```

## The PositionsResponse object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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`."}}}}
```

## The Secp256k1PublicKey object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"Secp256k1PublicKey":{"type":"string","pattern":"^[0-9a-fA-F]{66}$","description":"A 33-byte compressed secp256k1 public key, lowercase hex, with **no** `0x` prefix (66 hex characters)."}}}}
```

## The VoterResponse object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"VoterResponse":{"type":"object","description":"A validator that cast a vote, resolved from the committee vote bitmap.","required":["validator_index","validator_address"],"properties":{"validator_index":{"type":"integer","description":"Index of the validator within the committee."},"validator_address":{"$ref":"#/components/schemas/Address"}}},"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"}}}}
```

## The TxVotesResponse object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"TxVotesResponse":{"type":"object","description":"The set of validators that voted for one specific transaction hash at a given (account, nonce).","required":["tx_hash","voters"],"properties":{"tx_hash":{"$ref":"#/components/schemas/Bytes32"},"voters":{"type":"array","items":{"$ref":"#/components/schemas/VoterResponse"}}}},"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."},"VoterResponse":{"type":"object","description":"A validator that cast a vote, resolved from the committee vote bitmap.","required":["validator_index","validator_address"],"properties":{"validator_index":{"type":"integer","description":"Index of the validator within the committee."},"validator_address":{"$ref":"#/components/schemas/Address"}}},"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"}}}}
```

## The AccountNonceVotesResponse object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"AccountNonceVotesResponse":{"type":"object","description":"Votes observed for a given (account, nonce), as tracked by this node's vote accounting. Returned by `pod_getVotes` and embedded in a pending `pod_getTxStatus`.","required":["account","nonce","txs","bot_voters","total_tx_votes","quorum"],"properties":{"account":{"$ref":"#/components/schemas/Address"},"nonce":{"type":"integer","format":"int64"},"txs":{"type":"array","items":{"$ref":"#/components/schemas/TxVotesResponse"},"description":"Voter sets per transaction hash seen at this (account, nonce)."},"bot_voters":{"type":"array","items":{"$ref":"#/components/schemas/VoterResponse"},"description":"Validators that voted BOT (bottom / no-op) at this (account, nonce)."},"total_tx_votes":{"type":"integer","description":"Distinct validators that voted for any tx (each counted once even when equivocating)."},"quorum":{"type":"integer","description":"Votes required for a certificate (n − f)."}}},"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"},"TxVotesResponse":{"type":"object","description":"The set of validators that voted for one specific transaction hash at a given (account, nonce).","required":["tx_hash","voters"],"properties":{"tx_hash":{"$ref":"#/components/schemas/Bytes32"},"voters":{"type":"array","items":{"$ref":"#/components/schemas/VoterResponse"}}}},"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."},"VoterResponse":{"type":"object","description":"A validator that cast a vote, resolved from the committee vote bitmap.","required":["validator_index","validator_address"],"properties":{"validator_index":{"type":"integer","description":"Index of the validator within the committee."},"validator_address":{"$ref":"#/components/schemas/Address"}}}}}}
```

## The ProcessedDepositsResponse object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"ProcessedDepositsResponse":{"type":"object","description":"The bridge deposit replay-protection set. Every deposit id strictly below `watermark` has\nbeen processed; `above_watermark` lists the processed ids at or above it. The relayer uses\nthis to drop already-processed deposits from a batch before (re)submitting it.\n","required":["watermark","above_watermark"],"properties":{"watermark":{"$ref":"#/components/schemas/HexUint256"},"above_watermark":{"type":"array","items":{"$ref":"#/components/schemas/HexUint256"},"description":"Processed deposit ids `>= watermark`, sorted ascending."}}},"HexUint256":{"type":"string","pattern":"^0x[a-fA-F0-9]+$","description":"Unsigned 256-bit integer (hex-encoded with 0x prefix)"}}}}
```

## The TargetTx object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"TargetTx":{"type":"object","description":"A transaction an account must recover past before it can make progress again.","required":["hash","nonce"],"properties":{"hash":{"$ref":"#/components/schemas/Bytes32"},"nonce":{"type":"integer","format":"int64"}}},"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."}}}}
```

## The AccountInfoResponse object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"AccountInfoResponse":{"type":"object","description":"An account's finalized/expected nonces and last finalized tx, as this node sees them.","required":["next_finalized_nonce","expected_nonce","last_finalized_tx"],"properties":{"next_finalized_nonce":{"type":"integer","format":"int64","description":"The next nonce to finalize; every lower nonce is already finalized."},"expected_nonce":{"type":"integer","format":"int64","description":"The next nonce the account is expected to submit."},"last_finalized_tx":{"$ref":"#/components/schemas/Bytes32"}}},"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."}}}}
```

## The Precompile object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"Precompile":{"type":"object","description":"An enshrined precompile contract (bridge, CLOB, recovery, ...).","required":["address","name"],"properties":{"address":{"$ref":"#/components/schemas/Address"},"name":{"type":"string"}}},"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"}}}}
```

## The PrecompileInfo object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"PrecompileInfo":{"type":"object","description":"A precompile plus its callable interface. The `Precompile` fields (`address`, `name`) are flattened to the top level alongside `interface`.","required":["address","name","interface"],"properties":{"address":{"$ref":"#/components/schemas/Address"},"name":{"type":"string"},"interface":{"type":"string","description":"The precompile's callable interface (human-readable descriptor)."}}},"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"}}}}
```

## The SolverBatchInfo object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"SolverBatchInfo":{"type":"object","description":"Identifies a solver solution batch by its auction deadline and transaction hash.","required":["deadline","tx_hash"],"properties":{"deadline":{"$ref":"#/components/schemas/Timestamp"},"tx_hash":{"$ref":"#/components/schemas/Bytes32"}}},"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."}}}}
```

## The SolverStateResponse object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"SolverStateResponse":{"type":"object","description":"The solver node's current state. Only meaningful when queried against the solver node.","required":["solver_address","solver_pub_key","next_finalized_nonce","next_solution_votes"],"properties":{"solver_address":{"$ref":"#/components/schemas/Address"},"solver_pub_key":{"$ref":"#/components/schemas/Secp256k1PublicKey"},"next_finalized_nonce":{"type":"integer","format":"int64"},"last_executed_batch":{"$ref":"#/components/schemas/SolverBatchInfo","nullable":true,"description":"The most recently executed solution batch, or null if none."},"last_generated_batch":{"$ref":"#/components/schemas/SolverBatchInfo","nullable":true,"description":"The most recently generated (proposed) solution batch, or null if none."},"next_solution_votes":{"type":"object","additionalProperties":{"type":"array","items":{"type":"integer"}},"description":"Votes for the next solution: an object mapping each candidate solution tx hash (bytes32, hex string key) to the list of validator indices that voted for it."}}},"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"},"Secp256k1PublicKey":{"type":"string","pattern":"^[0-9a-fA-F]{66}$","description":"A 33-byte compressed secp256k1 public key, lowercase hex, with **no** `0x` prefix (66 hex characters)."},"SolverBatchInfo":{"type":"object","description":"Identifies a solver solution batch by its auction deadline and transaction hash.","required":["deadline","tx_hash"],"properties":{"deadline":{"$ref":"#/components/schemas/Timestamp"},"tx_hash":{"$ref":"#/components/schemas/Bytes32"}}},"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."}}}}
```

## The PodStatus object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"PodStatus":{"type":"object","description":"Operational status of the node.","required":["read_only"],"properties":{"read_only":{"type":"boolean","description":"When true, the node rejects `sendRawTransaction` submissions (both `eth_` and `pod_`)."}}}}}}
```

## The ValidatorVoteKind object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"ValidatorVoteKind":{"type":"object","description":"A validator's vote at a single nonce. Tagged union on `kind`:\n- `tx`: voted for a specific transaction hash — `tx_hash` is present.\n- `bot`: cast a BOT (bottom / no-op) vote — only `kind` is present.\n- `not_seen`: no vote observed from this validator at this nonce — only `kind` is present.\n","required":["kind"],"properties":{"kind":{"type":"string","enum":["tx","bot","not_seen"]},"tx_hash":{"$ref":"#/components/schemas/Bytes32","description":"Present only when `kind` is `tx`."}}},"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."}}}}
```

## The ValidatorNonceVote object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"ValidatorNonceVote":{"type":"object","description":"A single validator's vote at one pending nonce.","required":["nonce","vote"],"properties":{"nonce":{"type":"integer","format":"int64"},"vote":{"$ref":"#/components/schemas/ValidatorVoteKind"}}},"ValidatorVoteKind":{"type":"object","description":"A validator's vote at a single nonce. Tagged union on `kind`:\n- `tx`: voted for a specific transaction hash — `tx_hash` is present.\n- `bot`: cast a BOT (bottom / no-op) vote — only `kind` is present.\n- `not_seen`: no vote observed from this validator at this nonce — only `kind` is present.\n","required":["kind"],"properties":{"kind":{"type":"string","enum":["tx","bot","not_seen"]},"tx_hash":{"$ref":"#/components/schemas/Bytes32","description":"Present only when `kind` is `tx`."}}},"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."}}}}
```

## The ValidatorAccountStatusResponse object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"ValidatorAccountStatusResponse":{"type":"object","description":"How one validator has voted for one account across its pending nonces, as seen by this node.","required":["validator_index","validator_address","account","account_next_finalized_nonce","account_expected_nonce","quorum","pending_nonces"],"properties":{"validator_index":{"type":"integer"},"validator_address":{"$ref":"#/components/schemas/Address"},"account":{"$ref":"#/components/schemas/Address"},"account_next_finalized_nonce":{"type":"integer","format":"int64","description":"This node's `next_finalized_nonce` for the account (votes at lower nonces are already gone)."},"account_expected_nonce":{"type":"integer","format":"int64","description":"This node's `expected_nonce` for the account."},"quorum":{"type":"integer","description":"Votes required for a certificate (n − f)."},"pending_nonces":{"type":"array","items":{"$ref":"#/components/schemas/ValidatorNonceVote"},"description":"One entry per pending nonce in `[next_finalized_nonce, expected_nonce)`. Capped at 256 entries; if the gap is larger the oldest nonces are omitted."}}},"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"},"ValidatorNonceVote":{"type":"object","description":"A single validator's vote at one pending nonce.","required":["nonce","vote"],"properties":{"nonce":{"type":"integer","format":"int64"},"vote":{"$ref":"#/components/schemas/ValidatorVoteKind"}}},"ValidatorVoteKind":{"type":"object","description":"A validator's vote at a single nonce. Tagged union on `kind`:\n- `tx`: voted for a specific transaction hash — `tx_hash` is present.\n- `bot`: cast a BOT (bottom / no-op) vote — only `kind` is present.\n- `not_seen`: no vote observed from this validator at this nonce — only `kind` is present.\n","required":["kind"],"properties":{"kind":{"type":"string","enum":["tx","bot","not_seen"]},"tx_hash":{"$ref":"#/components/schemas/Bytes32","description":"Present only when `kind` is `tx`."}}},"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."}}}}
```

## The FinalizedTxStatus object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"FinalizedTxStatus":{"type":"object","description":"Execution outcome of a finalized transaction. In `pod_getTxStatus` these fields are flattened alongside the `finalized` status tag.","required":["tx_hash","account","nonce","success","gas_used"],"properties":{"tx_hash":{"$ref":"#/components/schemas/Bytes32"},"account":{"$ref":"#/components/schemas/Address"},"nonce":{"type":"integer","format":"int64"},"success":{"type":"boolean"},"gas_used":{"type":"integer","format":"int64"}}},"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)"}}}}
```

## The PendingTxStatus object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"PendingTxStatus":{"type":"object","description":"In-flight status of a not-yet-finalized transaction. In `pod_getTxStatus` these fields are flattened alongside the `pending` status tag.","required":["tx_hash","account","nonce","account_next_finalized_nonce","account_expected_nonce","quorum","votes"],"properties":{"tx_hash":{"$ref":"#/components/schemas/Bytes32"},"account":{"$ref":"#/components/schemas/Address"},"nonce":{"type":"integer","format":"int64"},"account_next_finalized_nonce":{"type":"integer","format":"int64"},"account_expected_nonce":{"type":"integer","format":"int64"},"quorum":{"type":"integer","description":"Votes needed for a certificate (n − f)."},"votes":{"$ref":"#/components/schemas/AccountNonceVotesResponse"}}},"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)"},"AccountNonceVotesResponse":{"type":"object","description":"Votes observed for a given (account, nonce), as tracked by this node's vote accounting. Returned by `pod_getVotes` and embedded in a pending `pod_getTxStatus`.","required":["account","nonce","txs","bot_voters","total_tx_votes","quorum"],"properties":{"account":{"$ref":"#/components/schemas/Address"},"nonce":{"type":"integer","format":"int64"},"txs":{"type":"array","items":{"$ref":"#/components/schemas/TxVotesResponse"},"description":"Voter sets per transaction hash seen at this (account, nonce)."},"bot_voters":{"type":"array","items":{"$ref":"#/components/schemas/VoterResponse"},"description":"Validators that voted BOT (bottom / no-op) at this (account, nonce)."},"total_tx_votes":{"type":"integer","description":"Distinct validators that voted for any tx (each counted once even when equivocating)."},"quorum":{"type":"integer","description":"Votes required for a certificate (n − f)."}}},"TxVotesResponse":{"type":"object","description":"The set of validators that voted for one specific transaction hash at a given (account, nonce).","required":["tx_hash","voters"],"properties":{"tx_hash":{"$ref":"#/components/schemas/Bytes32"},"voters":{"type":"array","items":{"$ref":"#/components/schemas/VoterResponse"}}}},"VoterResponse":{"type":"object","description":"A validator that cast a vote, resolved from the committee vote bitmap.","required":["validator_index","validator_address"],"properties":{"validator_index":{"type":"integer","description":"Index of the validator within the committee."},"validator_address":{"$ref":"#/components/schemas/Address"}}}}}}
```

## The TxStatusResponse object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"TxStatusResponse":{"type":"object","description":"Full pipeline status of a transaction, returned by `pod_getTxStatus`. It is a `status`-tagged\nunion; the fields present depend on `status`:\n- `not_found`: unknown to this node (no cached tx and no receipt) — only `status` is present.\n- `pending`: in-flight — the `PendingTxStatus` fields are inlined alongside `status`.\n- `finalized`: executed — the `FinalizedTxStatus` fields are inlined alongside `status`.\n","required":["status"],"properties":{"status":{"type":"string","enum":["not_found","pending","finalized"],"description":"Discriminator selecting the variant."},"tx_hash":{"$ref":"#/components/schemas/Bytes32","description":"Present for `pending` and `finalized`."},"account":{"$ref":"#/components/schemas/Address","description":"Present for `pending` and `finalized`."},"nonce":{"type":"integer","format":"int64","description":"Present for `pending` and `finalized`."},"account_next_finalized_nonce":{"type":"integer","format":"int64","description":"`pending` only."},"account_expected_nonce":{"type":"integer","format":"int64","description":"`pending` only."},"quorum":{"type":"integer","description":"`pending` only: votes needed for a certificate (n − f)."},"votes":{"$ref":"#/components/schemas/AccountNonceVotesResponse","description":"`pending` only: the votes observed at this (account, nonce)."},"success":{"type":"boolean","description":"`finalized` only: whether execution succeeded."},"gas_used":{"type":"integer","format":"int64","description":"`finalized` only."}}},"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)"},"AccountNonceVotesResponse":{"type":"object","description":"Votes observed for a given (account, nonce), as tracked by this node's vote accounting. Returned by `pod_getVotes` and embedded in a pending `pod_getTxStatus`.","required":["account","nonce","txs","bot_voters","total_tx_votes","quorum"],"properties":{"account":{"$ref":"#/components/schemas/Address"},"nonce":{"type":"integer","format":"int64"},"txs":{"type":"array","items":{"$ref":"#/components/schemas/TxVotesResponse"},"description":"Voter sets per transaction hash seen at this (account, nonce)."},"bot_voters":{"type":"array","items":{"$ref":"#/components/schemas/VoterResponse"},"description":"Validators that voted BOT (bottom / no-op) at this (account, nonce)."},"total_tx_votes":{"type":"integer","description":"Distinct validators that voted for any tx (each counted once even when equivocating)."},"quorum":{"type":"integer","description":"Votes required for a certificate (n − f)."}}},"TxVotesResponse":{"type":"object","description":"The set of validators that voted for one specific transaction hash at a given (account, nonce).","required":["tx_hash","voters"],"properties":{"tx_hash":{"$ref":"#/components/schemas/Bytes32"},"voters":{"type":"array","items":{"$ref":"#/components/schemas/VoterResponse"}}}},"VoterResponse":{"type":"object","description":"A validator that cast a vote, resolved from the committee vote bitmap.","required":["validator_index","validator_address"],"properties":{"validator_index":{"type":"integer","description":"Index of the validator within the committee."},"validator_address":{"$ref":"#/components/schemas/Address"}}}}}}
```

## The ValidatorStatusResponse object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"ValidatorStatusResponse":{"type":"object","description":"This node's own in-memory validator state. `validator_index` / `validator_address` are\npresent on a validator node and null on a full node. Values reflect the queried node's local\nstate, not a consensus view.\n","required":["append_log_sequence","current_ppt","quorum","committee_size"],"properties":{"validator_index":{"type":"integer","nullable":true},"validator_address":{"$ref":"#/components/schemas/Address","nullable":true},"append_log_sequence":{"type":"integer","format":"int64","description":"The node's current append-log sequence number."},"current_ppt":{"$ref":"#/components/schemas/Timestamp","description":"This node's local past-perfect time (microseconds)."},"last_executed_batch":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"Deadline of the last executed solution batch (microseconds), or null if none."},"next_solution_deadline":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"`last_executed_batch + auction_interval`, or null if no batch has executed yet."},"quorum":{"type":"integer","description":"Votes required for a certificate (n − f)."},"committee_size":{"type":"integer"}}},"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"},"Timestamp":{"type":"integer","format":"int64","description":"Unix timestamp in microseconds (not milliseconds or seconds)"}}}}
```

## The ValidatorDiagnostics object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"ValidatorDiagnostics":{"type":"object","description":"Per-validator vote state for a single account, as seen by the queried node. Part of `AccountDiagnosticsResponse`.","required":["validator_index","validator_address","current_vote","equivocating"],"properties":{"validator_index":{"type":"integer"},"validator_address":{"$ref":"#/components/schemas/Address"},"highest_attested_nonce":{"type":"integer","format":"int64","nullable":true,"description":"Highest nonce in the current pending window where this validator has voted. Null when there are no pending nonces or the validator has not voted."},"current_vote":{"$ref":"#/components/schemas/ValidatorVoteKind","description":"Vote cast at the latest pending nonce (`expected_nonce − 1`); `not_seen` if none."},"equivocating":{"type":"boolean","description":"True if this validator voted for two different tx hashes at the same nonce."}}},"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"},"ValidatorVoteKind":{"type":"object","description":"A validator's vote at a single nonce. Tagged union on `kind`:\n- `tx`: voted for a specific transaction hash — `tx_hash` is present.\n- `bot`: cast a BOT (bottom / no-op) vote — only `kind` is present.\n- `not_seen`: no vote observed from this validator at this nonce — only `kind` is present.\n","required":["kind"],"properties":{"kind":{"type":"string","enum":["tx","bot","not_seen"]},"tx_hash":{"$ref":"#/components/schemas/Bytes32","description":"Present only when `kind` is `tx`."}}},"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."}}}}
```

## The AccountDiagnosticsResponse object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"AccountDiagnosticsResponse":{"type":"object","description":"Full diagnostic snapshot of a single account across all committee validators, returned by `pod_getAccountDiagnostics`.","required":["account","next_finalized_nonce","expected_nonce","last_finalized_tx","is_locked","quorum","validators","needs_recovery","has_clob_order_pending_solution","equivocating"],"properties":{"account":{"$ref":"#/components/schemas/Address"},"next_finalized_nonce":{"type":"integer","format":"int64"},"expected_nonce":{"type":"integer","format":"int64"},"last_finalized_tx":{"$ref":"#/components/schemas/Bytes32"},"is_locked":{"type":"boolean","description":"True when the account is locked (a tx is pending decision)."},"quorum":{"type":"integer","description":"Votes required for a certificate (n − f)."},"validators":{"type":"array","items":{"$ref":"#/components/schemas/ValidatorDiagnostics"},"description":"Per-validator vote state."},"needs_recovery":{"type":"boolean"},"recovery_target":{"$ref":"#/components/schemas/TargetTx","nullable":true,"description":"The tx the account needs to recover past, if any."},"has_clob_order_pending_solution":{"type":"boolean","description":"True if this account has at least one order in the CLOB's pending-solution window."},"equivocating":{"type":"boolean","description":"True if two competing tx hashes at the same nonce both reached the certificate threshold (n − 3f)."}}},"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"},"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."},"ValidatorDiagnostics":{"type":"object","description":"Per-validator vote state for a single account, as seen by the queried node. Part of `AccountDiagnosticsResponse`.","required":["validator_index","validator_address","current_vote","equivocating"],"properties":{"validator_index":{"type":"integer"},"validator_address":{"$ref":"#/components/schemas/Address"},"highest_attested_nonce":{"type":"integer","format":"int64","nullable":true,"description":"Highest nonce in the current pending window where this validator has voted. Null when there are no pending nonces or the validator has not voted."},"current_vote":{"$ref":"#/components/schemas/ValidatorVoteKind","description":"Vote cast at the latest pending nonce (`expected_nonce − 1`); `not_seen` if none."},"equivocating":{"type":"boolean","description":"True if this validator voted for two different tx hashes at the same nonce."}}},"ValidatorVoteKind":{"type":"object","description":"A validator's vote at a single nonce. Tagged union on `kind`:\n- `tx`: voted for a specific transaction hash — `tx_hash` is present.\n- `bot`: cast a BOT (bottom / no-op) vote — only `kind` is present.\n- `not_seen`: no vote observed from this validator at this nonce — only `kind` is present.\n","required":["kind"],"properties":{"kind":{"type":"string","enum":["tx","bot","not_seen"]},"tx_hash":{"$ref":"#/components/schemas/Bytes32","description":"Present only when `kind` is `tx`."}}},"TargetTx":{"type":"object","description":"A transaction an account must recover past before it can make progress again.","required":["hash","nonce"],"properties":{"hash":{"$ref":"#/components/schemas/Bytes32"},"nonce":{"type":"integer","format":"int64"}}}}}}
```

## The MarketDynamicEntry object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"MarketDynamicEntry":{"type":"object","description":"Live market statistics for one orderbook, streamed on the `pod_markets` subscription (one\nobject per orderbook). Optional fields are omitted (not null) when unset — e.g. perp-only\nfields on a spot market, or stats with no data yet.\n","required":["orderbook_id","volume_24h"],"properties":{"orderbook_id":{"$ref":"#/components/schemas/Bytes32"},"last_clearing_price":{"type":"string","description":"Most recent clearing price (decimal, 1e18). Omitted if the market has not cleared."},"volume_24h":{"type":"string","description":"Rolling 24h traded volume (decimal, 1e18)."},"high_24h":{"type":"string","description":"24h high clearing price (decimal, 1e18). Omitted if unavailable."},"low_24h":{"type":"string","description":"24h low clearing price (decimal, 1e18). Omitted if unavailable."},"price_change_24h":{"type":"integer","format":"int128","description":"24h price change (signed, 1e18), as a JSON number. Omitted if unavailable."},"oracle_price":{"type":"string","description":"Perp only: latest oracle price (decimal, 1e18)."},"mark_price":{"type":"string","description":"Perp only: current mark price (decimal, 1e18)."},"funding_rate":{"type":"string","description":"Perp only: current funding rate (decimal)."},"funding_index":{"type":"string","description":"Perp only: cumulative funding index (decimal)."},"funding_last_updated_us":{"type":"integer","format":"int64","description":"Perp only: last funding update time (microseconds)."},"open_interest":{"type":"string","description":"Perp only: open interest (decimal, 1e18)."}}},"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."}}}}
```

## The CandleTick object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"CandleTick":{"type":"object","description":"Per-tick candle hint streamed on the `pod_candles` subscription — one object per orderbook\ncleared this settlement. It is not a closed OHLCV bar (use `ob_getCandles` for those); the\nclient folds it into the forming bar.\n","required":["orderbook","timestamp_us","price","volume"],"properties":{"orderbook":{"$ref":"#/components/schemas/Bytes32"},"timestamp_us":{"type":"integer","format":"int64","description":"Batch deadline (settlement time) in microseconds."},"price":{"type":"string","description":"Clearing price for this tick (decimal, 1e18)."},"volume":{"type":"string","description":"Total volume cleared this tick (decimal, 1e18)."}}},"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."}}}}
```

## The PositionsUpdate object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"PositionsUpdate":{"type":"object","description":"A `pod_positions` notification — the account's full positions snapshot, pushed for a settlement that touched the account.","required":["account","data"],"properties":{"account":{"$ref":"#/components/schemas/Address"},"data":{"$ref":"#/components/schemas/PositionsResponse"}}},"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`."}}}}
```

## The TriggersUpdate object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"TriggersUpdate":{"type":"object","description":"A `pod_triggers` notification — the account's armed TP/SL triggers, pushed for a settlement that touched the account. Carries the `GetTriggersResponse` fields inlined alongside `account`.","required":["account","triggers","total_count"],"properties":{"account":{"$ref":"#/components/schemas/Address"},"triggers":{"type":"array","items":{"$ref":"#/components/schemas/TriggerOrderResponse"}},"total_count":{"type":"integer","description":"Count of triggers for the account before pagination."},"next_cursor":{"type":"string","nullable":true,"description":"Pagination cursor, wire format `\"{orderbook_id}:{order_id}\"`. Null if no more results."}}},"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"},"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)."}}},"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)"},"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)"}}}}
```

## The WithdrawalUpdate object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"WithdrawalUpdate":{"type":"object","description":"One outcome from `pod_withdrawals` — what became of a single bridge withdrawal when its\ntick executed. The REST backfill (`GET /v1/bridge/withdrawals[/{account}]?since=`) serves the\nidentical shape, so an outcome read after a reconnect is indistinguishable from one that\narrived live.\n\nA withdrawal debits the account's balance, is burned on Pod, and is claimed on the bridge's\nbridged chain; nothing is credited to a Pod account on the way. No `error` means it is on its\nway there. `insufficient_balance` and `not_included` both mean **nothing was debited** — the\nfunds are still on the account and no claim will ever exist — and this is the only\nsurface that carries the reason, so a client watching only the bridged chain waits forever for\nan event that cannot come.\n\nThe claim itself is not here: read it from `GET /v1/bridge/withdrawals/by-id/{tx_hash}`,\nwhich reports `claimable` / `pending` / `refused` and attaches the proof once a certificate\ncan be assembled, or from `pod_getBridgeClaimProof(txHash)` for the proof alone.\n","required":["tx_hash","withdrawer","to","token","amount","timestamp_us"],"properties":{"tx_hash":{"$ref":"#/components/schemas/Bytes32","description":"The `withdraw` transaction's own hash, which is the withdrawal's identity. A withdrawal is always its own transaction — it targets the bridge precompile, so it can be neither a `submitBatch` sub-intent nor a `delegated` inner call — and this is the key the claim is fetched by. Rows predating this design carry a computed `keccak256(abi.encode(signer, nonce, sequence))` id here instead; the same lookups serve both, but only the current generation is a real transaction hash, so do not feed a historical value to `eth_getTransactionByHash`."},"withdrawer":{"$ref":"#/components/schemas/Address","description":"The debited account, and what the `account` subscription filter matches. It is also the transaction signer for current withdrawals; on rows predating this design it can differ, being the master of a delegated withdrawal rather than the delegate that signed."},"to":{"$ref":"#/components/schemas/Address","description":"Recipient **on the bridged chain**. Nothing is credited on Pod."},"token":{"$ref":"#/components/schemas/Address","description":"Pod-side token address. Map it to the asset the claim pays out using the token list from `GET /v1/bridge/config`."},"amount":{"type":"string","description":"Amount in Pod's 18 decimals, hex-encoded — what the user signed and what left the account. The claim carries this converted to the token's bridged-chain decimals, which differs by 10^12 for a 6-decimal token, so never pass this value to `claim`; take that one from the proof response. A refused withdrawal still reports the amount that was asked for."},"error":{"type":"string","enum":["insufficient_balance","not_included"],"description":"Names why the withdrawal was refused. `insufficient_balance` — the balance did not cover it at execution; admission deliberately does not check the balance, because pending fills can raise it before the tick runs. `not_included` — the solver omitted a finalized intent before its deadline passed. Treat an unrecognised value as a failure rather than as success: the vocabulary can grow. An absent `error` is the normal claimable case but is not a guarantee — a node whose bridge config does not cover the token records the row, signs nothing, and reports `refused` with no reason — so confirm against `status`/`proof` rather than treating absent-`error` as \"on its way\"."},"timestamp_us":{"type":"integer","format":"int64","description":"The tick's batch deadline, in microseconds — also the `since` cursor for this subscription and for the REST backfill, so a value read here can be handed straight to either."}}},"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)"}}}}
```

## The TransferUpdate object

```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"TransferUpdate":{"type":"object","description":"One outcome from `pod_transfers` — what became of a single account-to-account transfer when\nits tick executed.\n\nA transfer has no receipt of its own: it is a solver-gated intent that settles inside the\nsolver's `submitSolutions` transaction, and a refused one still consumes its nonce while\nchanging no state. This channel is therefore the only way to tell refused from succeeded.\n\nThe sibling of `WithdrawalUpdate` rather than the same shape: a transfer's `to` is an account\non **this** ledger and the funds land there, while a withdrawal's `to` is an address on the\nbridged chain. Every error here also means **nothing moved on either side**; retrying means a\nnew transaction, and so a new `transfer_id`.\n","required":["transfer_id","from","to","token","amount","timestamp_us"],"properties":{"transfer_id":{"$ref":"#/components/schemas/Bytes32","description":"Identity of the transfer intent, `keccak256(abi.encode(signer, nonce, sequence))`, where `sequence` is its position inside a `submitBatch` envelope (`0` for a standalone `transfer`). Computable before submitting."},"from":{"$ref":"#/components/schemas/Address","description":"The debited account, which is also the transaction signer — transfers are not delegable. Matched by the `account` subscription filter, as is `to`."},"to":{"$ref":"#/components/schemas/Address","description":"The credited account, **on this ledger**. Unlike a withdrawal's `to`, this is a Pod address and the funds land there."},"token":{"$ref":"#/components/schemas/Address","description":"Token address on Pod."},"amount":{"type":"string","description":"Amount in Pod's 18 decimals, hex-encoded. A refused transfer still reports the amount that was asked for."},"error":{"type":"string","enum":["insufficient_balance","recipient_not_resident","not_included"],"description":"Absent when the funds moved. `insufficient_balance` — the sender's withdrawable balance did not cover it at execution; admission deliberately does not check the balance, because pending fills can raise it before the tick runs. `recipient_not_resident` — the recipient's account was not resident when the tick ran, so the credit had nowhere to land. `not_included` — the solver omitted a finalized intent before its deadline passed. Treat an unrecognised value as a failure rather than as success: the vocabulary can grow."},"timestamp_us":{"type":"integer","format":"int64","description":"The tick's batch deadline, in microseconds — also the `since` cursor for this subscription."}}},"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)"}}}}
```


---

# 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/models.md?ask=<question>&goal=<endgoal>
```

`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.