# TxFlow Docs

> TxFlow is a layer-1 exchange for perpetuals and prediction (Outcome) markets. These docs cover trading mechanics, the protocol core, and the API: `POST /info` reads, WebSocket streams, and EIP-712–signed `POST /exchange` writes.

Every page below is plain Markdown, with API schemas fully expanded. Links are relative to the host serving this file. [llms-full.txt](/llms-full.txt) has all of them in one file. For an integration, read Builder API Reference → Signing → the reference pages you need, and follow the rules in the appendix.

- [What is TxFlow](/index.md)

## Introduction

- [Key Concepts](/introduction/key-concepts.md): The vocabulary the rest of these docs assume: accounts, instruments, channels, margin, prices, and networks.

## Getting Started

- [Start Trading](/getting-started/start-trading.md): Connect with email, social or your own wallet, deposit USDC, enable trading, and place your first order on TxFlow.
- [Deposits & Withdrawals](/getting-started/deposits-and-withdrawals.md): Move USDC collateral and spot assets in and out of TxFlow, from a wallet, a CEX, or another chain.
- [Export your email wallet](/getting-started/export-email-wallet.md): Export the private key or seed phrase of the wallet TxFlow created for your email login
- [Builder Code](/getting-started/builder-code.md): Charge your own fee on the order flow you route to TxFlow, on perpetual and outcome markets, through signed actions and on-chain fee logic.
- [Ecosystem](/getting-started/ecosystem.md): Explorers, tools, and apps built on TxFlow

## Trade

- [Trading on TxFlow](/trade.md): How trading works from a trader's point of view: the mechanics, formulas, and worked examples behind margin, liquidation, funding, and fees.
- [Margin & Leverage](/trade/margin-and-leverage.md): Margin is the collateral that backs your perpetual positions.
- [Entry Price & PnL](/trade/entry-price-and-pnl.md): Your entry price is the reference point for every profit-and-loss number you see.
- [Liquidation](/trade/liquidation.md): Liquidation closes a position that can no longer meet its maintenance margin.
- [Auto-deleveraging (ADL)](/trade/adl.md): When a liquidation can't be cleared on the order book, the protocol falls back to auto-deleveraging (ADL): the position is closed against traders holding the opposite side.
- [Funding](/trade/funding.md): Perpetuals have no expiry, so a periodic funding payment between longs and shorts keeps the contract price anchored to the oracle price.
- [Mark vs. Oracle Price](/trade/mark-and-index-price.md): A perpetual has more than one "price." Knowing which one drives what protects you from surprises around liquidation and funding.
- [Orders & Time-in-Force](/trade/orders.md): The order types and time-in-force options available across spot, perpetual, and outcome markets, from a trader's standpoint.
- [Contract Specifications](/trade/contract-specifications.md): TxFlow perpetuals are linear derivatives with no expiration date.
- [Position & Order Limits](/trade/position-and-order-limits.md): The ceilings an order has to clear before it reaches the book: a per-market position cap, order size bounds, price bands relative to the oracle, and slippage protection on market orders.
- [Fees & Discounts](/trade/fees.md): What you pay to trade, how the maker/taker split works, and how volume lowers your rate.
- [Deposit & Withdrawal Fees](/trade/deposit-and-withdrawal-fees.md): What you pay to move USDC in and out of TxFlow.
- [Fee Credits](/trade/fee-credits.md): Platform-issued vouchers that reimburse your perp trading fees.
- [Referral](/trade/referral.md): How to unlock your referral code, how many people you can invite, and what both sides earn.
- [Affiliate](/trade/affiliate.md): A multi-tier version of the Referral program for KOLs, agencies, and professional marketers.
- [Vaults](/trade/vaults.md): A vault is a pooled `USDC` account that trades a strategy and shares the result with its depositors.

## Prediction Markets

- [Prediction Markets](/prediction/overview.md): How prediction markets price probability, how payouts settle at 1 or 0, and how they differ from perpetuals.
- [Market Types](/prediction/market-types.md): TxFlow lists prediction markets with two outcome structures: binary (two outcomes) and category (several outcomes, one winner).
- [Trading Prediction Markets](/prediction/trading.md): Prediction markets trade through an order book, the same as any other market on TxFlow.
- [Resolution & Settlement](/prediction/resolution-and-settlement.md): Every market carries predefined rules that determine its final result.

## Product Notices

- [Product Notices](/notices.md): Trading hours, product-specific terms, and risk disclosures for the TxFlow markets that reference off-chain assets.
- [Stock Perpetuals Trading](/notices/stock-perpetuals.md): Trading hours and risk disclosure for perpetuals that reference listed equities.
- [FX Perpetuals Trading](/notices/fx-perpetuals.md): Trading hours and risk disclosure for perpetuals that reference foreign exchange rates.
- [Pre-IPO Perpetuals Disclaimer](/notices/pre-ipo-perpetuals.md): Terms and risk disclosure for perpetual contracts whose underlying company has not yet completed an IPO.

## Points

- [How Points Work](/points/how-points-work.md): How the TxFlow Points Program measures trading, how each weekly pool is shared out, and what does not earn Points.

## TxCore

- [Consensus & Execution](/txcore/consensus-execution.md): How TxCore orders transactions into finalized blocks with Tx-BFT, and how every node replays those blocks identically.
- [Matching Engine](/txcore/matching-engine.md): Every instrument has its own in-memory matching-engine instance.
- [Clearing & Settlement](/txcore/clearing-settlement.md): The clearing module turns fills produced by the matching engine into balance and position changes.
- [Margin System](/txcore/margin-system.md): The margin system governs how perpetual positions are collateralized and when they become eligible for liquidation.
- [Risk Engine](/txcore/risk-engine.md): The risk engine monitors accounts during block-tail processing and handles liquidation, auto-deleveraging, and funding settlement.
- [Oracle](/txcore/oracle.md): The oracle supplies the prices and funding rates that drive valuation, liquidation, and funding settlement.
- [Channels](/txcore/channels.md): A Channel is an isolated trading venue on TxFlow.
- [Run a Full Node](/fullnode/overview.md): A TxFlow full node subscribes to the validators' gRPC block stream, replays the deterministic state machine locally to verify results, and serves queries and real-time push to clients — without participating in…

## TIP — Improvement Proposal

- [TIP — Improvement Proposal](/tip/overview.md): The unified instrument standard behind every TxFlow market: what all instruments share, and what differs per type.
- [Instruments](/tip/instrument-config.md): An instrument is a single tradable market — a spot pair, a perpetual contract, or an outcome (prediction) market.
- [TIP 1: Spot](/tip/spot.md): Spot is the simplest instrument type: trading the base asset directly against the quote asset, with no position, leverage, or funding.
- [TIP 2: Perpetuals](/tip/perps.md): Perpetual contracts (perps) are the core derivative instrument: a position in a synthetic contract that tracks an underlying via the mark and oracle prices, held with leverage and kept anchored to the oracle price by…
- [TIP 3: Outcome Markets](/tip/outcome.md): Outcome markets are prediction markets expressed as instruments.

## Builder API Reference

- [Builder API Reference](/api.md): Which TxFlow API to use for what, plus endpoints, networks, and conventions
- [Try Testnet](/try-testnet/quickstart.md): Runnable end-to-end testnet client in the browser — faucet, approveBuilderFee, approveAgent, tokenSend, and orders — with the code for each step
- [Connect your coding agent](/api/ai-agents.md): Give Claude, Cursor, ChatGPT, or any coding agent the TxFlow docs as Markdown
- [Integration flows](/api/flows.md): Step-by-step call sequences for setting up an account, depositing, placing orders, trading Outcome markets, withdrawing, and earning builder fees
- [Outcome Integration Guide](/api/outcome-integration.md): End-to-end flow for trading prediction markets: discovery, quotes, orders, positions, and settlement
- [Signing](/api/signing.md): EIP-712 signing scheme for all POST /exchange write operations
- [Rate limits](/api/rate-limits.md): Per-IP request and connection limits for the TxFlow APIs
- [Info API (Beta)](/api/info.md): `POST /info` serves every read-only query — market metadata, balances, positions, orders, the book, fees, and history.
- [l2Book](/api/info/l2Book.md): L2 order-book snapshot
- [trades](/api/info/trades.md): Latest 300 public trades for one instrument
- [clearinghouseState](/api/info/clearinghouseState.md): Full clearinghouse state (positions + margin summary)
- [frontendOpenOrders](/api/info/frontendOpenOrders.md): User open orders with trigger / TP-SL fields
- [userFees](/api/info/userFees.md): User fee rates; returns default rates when `user` is omitted
- [feeTierInfo](/api/info/feeTierInfo.md): Fee-tier ladder
- [feeTierRates](/api/info/feeTierRates.md): Effective fee rates for an account type and optional user
- [builderState](/api/info/builderState.md): Builder-code accrual and eligibility for one builder address
- [referral](/api/info/referral.md): Referral state for a user (referrer, rewards, referrer stage)
- [userRole](/api/info/userRole.md): Referral role of a user: regular, referrer, or affiliate
- [userClaimRewards](/api/info/userClaimRewards.md): Referral reward claims a user has made
- [agentOwner](/api/info/agentOwner.md): Owner of an agent; `user` is null when the agent is not authorized
- [approvedAgents](/api/info/approvedAgents.md): Agents approved by the user
- [getMaxPositions](/api/info/getMaxPositions.md): Maximum tradable size at the given price
- [getLatestBlockNumber](/api/info/getLatestBlockNumber.md): Latest global block number
- [epochHistory](/api/info/epochHistory.md): Recent consensus epochs and the current epoch
- [exchangeRates](/api/info/exchangeRates.md): Stablecoin-to-USD and USD-to-fiat conversion rates
- [tags](/api/info/tags.md): Flat list of market tags
- [marketTags](/api/info/marketTags.md): Two-level market category layout and the tags on each instrument
- [candleSnapshot](/api/info/candleSnapshot.md): OHLCV bars for one instrument over a time window
- [historicalOrders](/api/info/historicalOrders.md): Limit / market order history for one user
- [historicalTpslOrders](/api/info/historicalTpslOrders.md): Take-profit / stop-loss order history for one user
- [historicalTriggerOrders](/api/info/historicalTriggerOrders.md): Trigger order history for one user
- [twapHistory](/api/info/twapHistory.md): Finished or cancelled TWAP orders for one user
- [orderDetails](/api/info/orderDetails.md): One historical order by order id
- [userFills](/api/info/userFills.md): Trade (fill) history for one user
- [userTwapSliceFills](/api/info/userTwapSliceFills.md): Individual TWAP child-order fills for one user
- [userFundings](/api/info/userFundings.md): Funding settlement history for one user
- [userNonFundingLedgerUpdates](/api/info/userNonFundingLedgerUpdates.md): Deposit, withdrawal, and other non-funding ledger history
- [userOverview](/api/info/userOverview.md): PnL, ROE, volume, max drawdown, and equity over a period
- [accountStatus](/api/info/accountStatus.md): Whether an account exists on chain and is eligible to trade
- [accessCodeStatus](/api/info/accessCodeStatus.md): Whether an access code is required on a channel, and whether an account is activated
- [geoCheck](/api/info/geoCheck.md): Whether the caller's region is restricted
- [approvedBuilders](/api/info/approvedBuilders.md): Builders a user has approved, with each maximum fee rate
- [maxBuilderFee](/api/info/maxBuilderFee.md): Approval status and maximum fee rate for one user and builder
- [approveAgentEligibility](/api/info/approveAgentEligibility.md): Whether an account may approve an agent yet
- [settings](/api/info/settings.md): Bridge2 contract address for native USDC deposits
- [depositWithPermit](/api/info/depositWithPermit.md): Deposit USDC into Bridge2 using an EIP-2612 permit
- [dayTotalWithdraw](/api/info/dayTotalWithdraw.md): USDC a user has withdrawn today, and how many withdrawals
- [sendTokenFee](/api/info/sendTokenFee.md): Activation fee for a tokenSend to a destination address
- [builderMeOverview](/api/info/builderMeOverview.md): Builder dashboard overview: users, volume, earned, claimed, and weekly stats
- [builderMeDailySeries](/api/info/builderMeDailySeries.md): Builder daily fee or user-count series with cumulative totals
- [builderMeShare](/api/info/builderMeShare.md): Builder fee share by trading user or instrument
- [builderMeEarned](/api/info/builderMeEarned.md): Paginated builder earnings aggregated by order
- [builderMeClaimed](/api/info/builderMeClaimed.md): Paginated builder reward claim history
- [builderMeClaimable](/api/info/builderMeClaimable.md): Builder claimable balance and lifetime earned/claimed totals
- [vaultDetails](/api/info/vaultDetails.md): Vault profile, TVL, shares, and depositors
- [uservaultequities](/api/info/uservaultequities.md): A user's equity in each vault they hold
- [perpMeta](/api/info/perpMeta.md): Perpetual trading-pair metadata
- [perpMetaDetail](/api/info/perpMetaDetail.md): Detailed perpetual metadata and margin tiers for one base asset
- [marketTicker](/api/info/marketTicker.md): Ticker for one perp instrument: last, mark, oracle, funding, 24h stats
- [activeAssetCtx](/api/info/activeAssetCtx.md): Perps market context for one instrument (mark, oracle, funding, open interest, …)
- [webData2](/api/info/webData2.md): A user's open orders plus 24h stats for every instrument
- [perpClearinghouseState](/api/info/perpClearinghouseState.md): Perp sub-account token balances
- [activeAssetData](/api/info/activeAssetData.md): Per-user, per-asset trading parameters: leverage, max tradeable size, available margin, mark price
- [triggerOrders](/api/info/triggerOrders.md): User trigger orders including TP-SL children
- [tpslOrders](/api/info/tpslOrders.md): Take-profit / stop-loss orders for a user
- [positionTpslOrders](/api/info/positionTpslOrders.md): TP/SL order pairs bound to one position
- [tpslOrderPosition](/api/info/tpslOrderPosition.md): Position bound to a TP-SL child order
- [getLiquidationPrices](/api/info/getLiquidationPrices.md): Estimated liquidation price for the requested buy/sell quantities
- [preCheckIsolatedMarginAdjust](/api/info/preCheckIsolatedMarginAdjust.md): Margin limits and a preview for adjusting an isolated position
- [outcomeMeta](/api/info/outcomeMeta.md): Outcome event and market metadata
- [outcomeNavTags](/api/info/outcomeNavTags.md): Category and tag tree for Outcome market navigation
- [outcomeAssetCtxs](/api/info/outcomeAssetCtxs.md): 24-hour statistics for Outcome instruments
- [outcomeSeriesTimeline](/api/info/outcomeSeriesTimeline.md): Recurring Outcome series timeline
- [cryptoPrice](/api/info/cryptoPrice.md): Open and settlement prices for a crypto Outcome window
- [cryptoPriceHistory](/api/info/cryptoPriceHistory.md): Crypto price samples for Outcome charts
- [outcomeProbability](/api/info/outcomeProbability.md): Historical YES probability samples for one Outcome instrument
- [outcomeMetaByInstrument](/api/info/outcomeMetaByInstrument.md): On-chain trading parameters for one Outcome instrument
- [outcomeL2Book](/api/info/outcomeL2Book.md): Order-book snapshots for several Outcome instruments in one call
- [outcomePositions](/api/info/outcomePositions.md): A user's outcome positions
- [outcomeBalances](/api/info/outcomeBalances.md): A user's Outcome sub-account token balances
- [outcomeFrontendOpenOrders](/api/info/outcomeFrontendOpenOrders.md): A user's open outcome orders
- [WebSocket API (Beta)](/api/websocket.md): Three multiplexed endpoints, all JSON text frames.
- [trades](/api/websocket/trades.md): Public real-time trade stream
- [l2Book](/api/websocket/l2Book.md): Public order-book snapshot, pushed on a fixed server-side tick
- [l2BookDepth](/api/websocket/l2BookDepth.md): Public fixed-depth order-book stream (snapshot then deltas)
- [bbo](/api/websocket/bbo.md): Public best-bid/best-offer stream for one coin
- [allMids](/api/websocket/allMids.md): Public mid price for every coin (Hyperliquid-compatible)
- [orderUpdates](/api/websocket/orderUpdates.md): Private order status updates for one user
- [block](/api/websocket/block.md): Public new-block summary for the explorer (subscribe with type `explorerBlock`)
- [tx](/api/websocket/tx.md): Public transaction list for the explorer (subscribe with type `explorerTxs`)
- [newBlock](/api/websocket/newBlock.md): Public new-block-height ticker, pushed once per second
- [activeAssetCtx](/api/websocket/activeAssetCtx.md): Public perps market context (funding, open interest, oracle/mark price, ...) for one coin
- [allAssetCtxs](/api/websocket/allAssetCtxs.md): Public perps market context for every coin (batched activeAssetCtx)
- [activeAssetData](/api/websocket/activeAssetData.md): Private per-user, per-coin trading parameters (leverage, max tradeable size, available margin)
- [clearinghouseState](/api/websocket/clearinghouseState.md): Private margin summary and position list for one user
- [position](/api/websocket/position.md): Private position update (subscribe with type `positionUpdates`)
- [webData2](/api/websocket/webData2.md): Private aggregate account snapshot (Hyperliquid-compatible): clearinghouse state + open orders in one push
- [userFundings](/api/websocket/userFundings.md): Private funding settlement update (Hyperliquid-compatible)
- [twapStates](/api/websocket/twapStates.md): Private running-state snapshot of every active TWAP order for one user on one dex
- [userTwapHistory](/api/websocket/userTwapHistory.md): Private history of finished/cancelled TWAP orders for one user
- [userTwapSliceFills](/api/websocket/userTwapSliceFills.md): Private stream of individual TWAP child-order fills for one user
- [vaultUpdates](/api/websocket/vaultUpdates.md): Live vault deposits, withdrawals, and leader commissions for one user (subscribe with type `vaultUpdates`)
- [outcomeBbos](/api/websocket/outcomeBbos.md): Batch best-bid/best-offer snapshots for Outcome instruments
- [outcomeTrades](/api/websocket/outcomeTrades.md): Public executed trades across a batch of Outcome instruments
- [outcomeOrderUpdates](/api/websocket/outcomeOrderUpdates.md): Private matching lifecycle for Outcome orders
- [ticker](/api/websocket/ticker.md): 24-hour ticker for one instrument from the API service
- [trades (API service)](/api/websocket/apiTrades.md): Latest 300 trades for one instrument, re-sent from the API service
- [candle](/api/websocket/candle.md): Live OHLCV updates from the API service
- [multiCandle](/api/websocket/multiCandle.md): Live candles for up to 8 coins on one subscription
- [outcomeOrderUpdate](/api/websocket/outcomeOrderUpdate.md): Failures of asynchronously accepted Outcome orders
- [userHistoricalOrders](/api/websocket/userHistoricalOrders.md): Order history for one account, sent once over the API service
- [userFills](/api/websocket/userFills.md): Fill history for one account, sent once over the API service
- [webData2 (API service)](/api/websocket/apiWebData2.md): Open orders for one account, sent once over the API service
- [Exchange API](/api/exchange.md): Signed write operations submitted through POST /exchange
- [approveBuilderFee](/api/exchange/approveBuilderFee.md): Approve or update a builder's maximum fee rate
- [approveAgent](/api/exchange/approveAgent.md): Authorize an agent wallet to sign trading actions on your behalf
- [tokenSend](/api/exchange/tokenSend.md): Move tokens between TxFlow sub-accounts, to another user, or to a TxRelay peg
- [withdraw3](/api/exchange/withdraw3.md): Withdraw USDC to an Arbitrum address through Bridge2
- [vaultTransfer](/api/exchange/vaultTransfer.md): Deposit USDC into a vault, or withdraw from it
- [order](/api/exchange/order.md): Place one or more orders in a single signed action
- [cancel](/api/exchange/cancel.md): Cancel one or more orders by order id
- [cancelByCloid](/api/exchange/cancelByCloid.md): Cancel one or more orders by client order id
- [modify2](/api/exchange/modify2.md): Amend a resting order in place, keeping its order id
- [modifyTpsl](/api/exchange/modifyTpsl.md): Modify or remove a position's take-profit / stop-loss pair
- [twapOrder](/api/exchange/twapOrder.md): Place a TWAP order that executes in slices over a fixed duration
- [twapCancel](/api/exchange/twapCancel.md): Cancel a running TWAP order
- [outcomeOperate](/api/exchange/outcomeOperate.md): Split and merge complete sets of Outcome shares
- [updatePositionMode](/api/exchange/updatePositionMode.md): Switch the account between one-way and hedge position mode
- [updateLeverage](/api/exchange/updateLeverage.md): Set leverage for one instrument
- [updateMarginMode](/api/exchange/updateMarginMode.md): Switch one instrument between cross and isolated margin
- [updateIsolatedMargin](/api/exchange/updateIsolatedMargin.md): Add or remove margin on an isolated position
- [revokeBuilderFee](/api/exchange/revokeBuilderFee.md): Remove a builder-fee approval
- [claimBuilderRewards](/api/exchange/claimBuilderRewards.md): Claim all currently unclaimed builder rewards
- [setReferrer](/api/exchange/setReferrer.md): Bind the account to another user's referral code
- [registerReferrer](/api/exchange/registerReferrer.md): Create your own referral code
- [claimRewards](/api/exchange/claimRewards.md): Claim all unclaimed referral rewards
- [TxRelay API](/api/txrelay.md): Cross-chain deposit and withdrawal routes for TxFlow
- [networks](/api/txrelay/networks.md): List TxRelay chains, tokens, and deposit / withdraw flags
- [deposit-address](/api/txrelay/deposit-address.md): Issue a TxRelay deposit or peg address for one route

## Resources

- [Official Links](/resources/official-links.md): The verified TxFlow domains and accounts
- [Brand Kit](/resources/brand-kit.md): Official TxFlow logos and brand assets
- [Audits](/resources/audits.md): Third-party security audits of TxFlow contracts
- [Bug Bounty Program](/resources/bug-bounty.md): Report a security vulnerability in TxFlow to security@txflow.com.

## Terms

- [Points Program Terms](/terms/points-program-terms.md): The terms you agree to by taking part in the TxFlow Points Program, part of the TxFlow Terms of Use.

## Appendix: integration rules for coding agents

Hard rules for generating TxFlow client code. Each links the page that states it.

### Endpoints
- Testnet (use it for every example and test): `https://rpc.txflow-testnet.xyz` serves `POST /info`, `POST /exchange`, `wss://…/ws`, `wss://…/api-ws`, and the faucet `POST /request-fund` with `{"address":"0x…"}`. Mainnet: `https://rpc.txflow.com`. TxRelay (`/api/v1/bridge`) is on its own host. — [Networks](/api.md)
- Reads need no auth. There are no API keys: writes are signed locally. — [Builder API Reference](/api.md)
- Send `x-api-version: 2026-08-16` on every `/info` and `/exchange` request; every documented response assumes it. — [Conventions](/api.md)

### Data
- Prices and sizes are strings. They are hashed exactly as written, so `"50000.0"` and `"50000"` sign differently. — [Signing](/api/signing.md)
- An instrument id is the `index` from `perpMeta`, or an Outcome market's `instrument_id` from `outcomeMeta`. In requests, `coin` and the `/info` `asset` filter take it as a numeric **string** (`"coin":"1"`) — every endpoint accepts that, and node reads such as `l2Book` accept nothing else; `instrumentId` / `instrumentIds` and the `/exchange` fields `a` / `asset` take it as an **integer** (`"a":1`). A string `a` changes the MessagePack bytes and breaks the signature. In responses `coin` is a display name whose form varies (`BTC-USDC`, `BTC`, `OUTCOME-4991183`): match rows on `asset` / `instrumentId`, compared as numbers (`asset` is `"1"` in some responses, `1` in others). — [Conventions](/api.md)
- `accountType` is `perp` or `outcome`.
- Private subscriptions and `/info` reads take the **account** address as `user`, never the agent's.
- Outcome metadata responses are snake_case; everything else is camelCase.
- Order prices must be a multiple of `priceTick` and sizes have at most `szDecimals` decimals (both from `perpMeta`). A cloid (`c`) is any string up to 64 bytes; do not start it with `0x` (reserved, rejected with `Invalid cloid format`). — [order](/api/exchange/order.md)
- The Outcome book and balance come from the shared `l2Book` and `clearinghouseState` (`accountType: "outcome"`). — [Info API](/api/info.md)

### Signing
- Two flows. Account key, direct EIP-712: `approveAgent`, `tokenSend`, `withdraw3`, `approveBuilderFee`, `revokeBuilderFee`. Agent key, MessagePack + `Agent` type: `order`, `cancel`, `cancelByCloid`, `modify2`, `outcomeOperate`, `update*`, `claimBuilderRewards`. — [Signing](/api/signing.md)
- EIP-712 domain: `name` `TxFlow-Testnet` / `TxFlow-Mainnet`, `version` `"1"`, `chainId` `2511` / `869`, `verifyingContract` zero address.
- Agent hash: MessagePack the action **without** `type` (exception: `claimBuilderRewards` keeps it) as a map with named keys, append the nonce as 8 bytes big-endian, then the vault flag (`0x00`, or `0x01` + 20 address bytes; `vaultTransfer` always uses `0x00`); `connectionId = keccak256(…)`.
- Keep the node's key order — the key order of each action's request example, which is also the order its `.md` page lists the action fields in; for an order body `a, b, p, s, r, t, c, m, expiresAt`. Never sort keys.
- Omit null optional fields instead of sending `null` (a plain `modify2` has no `tpsl` key). Extra keys break the signature.
- The agent key must be authorized first with `approveAgent`, signed by the account key. The account must be funded first (testnet: the faucet), or it fails with `Please deposit first`. An agent address can be bound to only one account at a time (`Agent address is already used`); revoking frees it. — [approveAgent](/api/exchange/approveAgent.md)
- Signatures must be low-S. `v` is `27`/`28` in JSON. Test vectors are on the Signing page.

### Nonces
- Millisecond timestamp, unique per signer, within 2 days before / 1 day after the block time. Each address keeps its 100 highest nonces. Use a fresh `Date.now()` per request. — [Signing § Nonces](/api/signing.md)
- For direct EIP-712 actions the nonce is also inside `action`; the envelope must repeat the same value.

### Responses
- `/info` returns `{"success":true,"code":0,"data":…}`; on error `success` is `false` with `code` and `message`. Each reference page documents the `data` payload.
- `/exchange` returns `{"status":"ok","code":0,"data":{"type":…,"data":{"statuses":["success"]}}}` — one status for the whole action. `success` means accepted by consensus, not executed; add `"confirm":"executed"` to the request body to wait for execution. The response never reports resting/filled/cancelled or an oid: read those from `orderUpdates` or `frontendOpenOrders`. `data.type` may differ from the request type (`order` → `PlaceOrder`). — [Exchange API § Response](/api/exchange.md)
- A rejection is `{"status":"err","code":<n>,"message":"…"}`; some gateway rejections (rate limits, disabled interfaces) carry the text in `response` instead. Read whichever is present.
- An Outcome order can instead be acknowledged asynchronously as `{"status":"ok","traceId":"…"}` (no `data`), which means queued. With `"confirm":"executed"`, a timeout returns HTTP 202 `{"status":"pending","txHash":"…"}`.
- If a queued Outcome order fails, WebSocket `outcomeOrderUpdate` on `/api-ws` pushes the reason under its `traceId`; successes are not pushed — follow fills on `outcomeOrderUpdates` (`/ws`). Outcome orders accept `Gtc`, `Gtd`, `Alo` only. — [order](/api/exchange/order.md)

### WebSocket
- On `/ws`, every subscribe/unsubscribe frame needs the channel's subscribe type at the **top level** as well as inside `subscription`: `{"method":"subscribe","type":"orderUpdates","subscription":{"type":"orderUpdates","user":"0x…"}}`. Without it the node silently ignores the frame. `/api-ws` takes `subscription` alone. — [WebSocket API](/api/websocket.md)
- Send `{"method":"ping"}` every 10 s on both `/ws` and `/api-ws`; a connection that sends nothing for ~16 s is closed (1006). Pongs are `{"method":"PONG"}` on `/ws` and `{"channel":"pong"}` on `/api-ws` — drop them before dispatching by `channel`. — [WebSocket API](/api/websocket.md)
- On reconnect, re-subscribe every channel; subscriptions do not survive the socket.

### Limits
- Per IP: `/info` 50 req/s, `/exchange` 10 req/s, 10 live connections each on `/ws` and `/api-ws`. Over the limit: HTTP 429 with `Retry-After`; a rate-limited action did not execute, so re-sign it with a fresh nonce. — [Rate limits](/api/rate-limits.md)
- Prefer WebSocket streams to polling, batch orders (≤ 50) and cancels (≤ 200), and cache `perpMeta`.