docs: REST API reference and JSON-RPC parity with the node

[majesticwizardcat]

Brings the API docs in line with the node, treating the node code as the source of truth, and adds a reference for the REST API, which was previously undocumented apart from the bridge routes.

REST reference (new)

doc/api-reference/rest/openapi.yaml and rest/README.md, published as a second GitBook spec, pod-rest, next to pod-docs.

• Markets: /v1/clob/status, /markets, /markets/stats, /candles/{orderbook}, /orderbook/{orderbook}, /solutions
• Account: /v1/clob/orders/{account}, /fills/{account}, /positions/{account}, /balances/{account}, /triggers/{account}, /backstop-transfers/{account}, /activity/{account}
• Explorer: /v1/tx/{hash}, /v1/transactions
• Bridge: /v1/bridge/config, /withdrawals, /withdrawals/{account}, /withdrawals/by-id/{tx_hash}, with the full claim-proof response and what pending means

Each route documents its parameters, defaults, caps, errors and Cache-Control. The README covers the /v1 prefix on the RPC port, which routes need the indexer, caching, number encodings, and seeding from REST before subscribing.

JSON-RPC reference

The highest-impact fixes:

• eth_getBalance: plain CLOB cash, not the withdrawable balance.
• eth_estimateGas: a table lookup, not a fixed 21000.
• eth_getTransactionCount: honours the pending tag.
• README block methods: blocks are real.
• pod_getVoteBatches: the params are now correct; the old example failed.
• ob_getOrderbook: bids are ascending, and the example is flipped.
• ob_getCandles: the window is half-open, and limit is capped.
• Order and triggers: the field encodings are corrected.
• ob_getPositions: a perp position's realized_pnl is always 0.
• pod_orders_v2: the status and reject-code lists now match the node.

Also:

• Added: ob_getSolutions, newHeads and pod_activity.
• Fixed: the subscription replay and snapshot rules, and the missing schema fields.
• Removed: pod_getBridgeClaimProof, which no longer exists.

Guides and other pages

• read-market-data.md: rewritten around REST plus subscriptions.
• recover-locked-account.md: reads TargetTx as {hash, nonce}.
• bridge-from-pod.md: the Rust tab polls the by-id route; it used to loop forever.
• json-rpc-errors.md: adds the missing error codes and the up-front since too old rejection.
• SDK README: restUrl is the RPC host plus /v1.

Depends on

• Node PR POD-158 Adds pod precompiles documentation #113 (activity feed, still open). /v1/clob/activity, pod_activity, ADL frames on pod_orders_v2, cash-sweep backstop rows and the extra pod_positions pushes are documented as they stand on that branch. Merge this after POD-158 Adds pod precompiles documentation #113.
• GitBook. The pod-rest spec has to be accepted in the GitBook organization. The publish workflow now uploads both specs.

Left out on purpose

• POST /v1/raw-txs: its binary frame format would need describing first.
• eth_syncing, eth_gasPrice, eth_maxFeePerGas, eth_maxPriorityFeePerGas, eth_getCode, eth_feeHistory, net_version and web3_clientVersion, which return fixed or placeholder answers.
• Internal node methods: pod_getAccountRepair, pod_pushAccountRepair, pod_getBridgeClaimSignatures, pod_subscribeVotes, and admin and dev methods.
• ob_* deprecation, left for a later pass.
• SDK activity and accountValue, which belong with SDK PRs feat(ts-sdk): account activity resource #310 and feat(ts-sdk): account value on the PnL history #311.

Known gap

pod_orders (v1) new and invalid events serialize the engine's order type, not OrderResponse. Their real shape differs from the documented one: end is a string and several fields are absent. This is not fixed here.

Verification

• Both specs parse.
• redocly lint: the REST spec has 0 errors. The JSON-RPC spec adds no new errors (44 before and after, all pre-existing).
• A review pass checked the docs against node code and found four issues, all fixed: price_change_24h is in basis points, the guide's pod_orderbook since now uses the solution-time watermark, pod_activity was missing from the stale-since list, and the README no longer documents unmerged SDK methods.

🤖 Generated with Claude Code