Integration flows

Each flow is the order in which a client calls the API for one job. Steps run top to bottom. A box's colour shows the transport — green for /info, blue for WebSocket, yellow for /exchange — and signed actions say which key signs them. See Signing for the two signing flows.

Place and track a perp order

Authorize an agent once, then let it sign. Watch the order on the stream; reconcile from history.

POST /exchangeAccount-signed
approveAgent
Once per agent key. The account key signs it; from here on the agent signs trading actions.
Agent authorized
POST /exchangeAgent-signed
order
Agent-signed. One action can carry a batch of orders, applied in order.
One success for the whole action — the oid and fills come from the stream below
Do all of these
WebSocket
orderUpdates
Order status as it changes: open, filled, cancelled, rejected.
WebSocket
clearinghouseState
Position and margin after each fill.
POST /info
userFills
Executions for history and reconciliation. Indexed, so it can lag the stream briefly.

Trade an Outcome market

Fund the Outcome sub-account, place the order, then follow two channels on two endpoints.

A successful order response can mean queued, not matched. Subscribe to both channels in step 4, or a rejected queue entry looks like an order that never filled.

POST /info
outcomeMeta
Find the event and market.
instrument_id — every later step needs it
POST /exchangeAccount-signed
tokenSend
Move USDC from perp to outcome. Account-signed; an agent cannot move funds.
POST /exchangeAgent-signed
order
a is the instrument_id; b/r encode the leg (buy NO = b: false, r: false) and p is that leg's price. TIF Gtc, Gtd, or Alo — Ioc is rejected.
Possibly an async acceptance with a traceId
Do all of these
WebSocket
outcomeOrderUpdate
On /api-ws. Pushed only if the queued order fails; match on traceId.
WebSocket
outcomeOrderUpdates
On /ws. What the book did: filled, cancelled, rejected.
POST /info
outcomePositions
Positions only — no margin summary. Use clearinghouseState with accountType=outcome for that.

The Outcome Integration Guide walks through the same flow with TypeScript SDK code.

Deposit USDC

Look up Bridge2, fund it one of three ways, then confirm the balance.

POST /info
settings
Read the Bridge2 contract address.
bridge2_contract_address
Pick one of 3
Arbitrum
USDC transfer
User holds ETH for gas: send USDC to Bridge2 directly.
POST /infoAccount-signed
depositWithPermit
User has no ETH: sign an EIP-2612 permit and the API host submits it.
TxRelay
deposit-address
Funds on another chain: get a one-time deposit address and send there.
POST /info
clearinghouseState
Confirm the credited balance.
POST /info
userNonFundingLedgerUpdates
Show the deposit in the ledger.

Withdraw funds

USDC to Arbitrum has its own action; everything else goes out through a TxRelay peg.

Pick one of 2
POST /exchangeAccount-signed
withdraw3
USDC to an Arbitrum address. Account-signed; minimum 2 USDC.
TxRelay
deposit-address
Other chains: request a peg address with src_chain: "txflow", then send to it with tokenSend.
POST /info
userNonFundingLedgerUpdates
Show the withdrawal in the ledger.

Earn builder fees

Each user approves a cap once; your orders carry the fee; you claim what accrues.

If the user has not approved you, or the fee exceeds the cap, the builder fee is silently ignored and the order still goes through.

POST /exchangeAccount-signed
approveBuilderFee
Signed by the user’s account key, once per builder. Sets maxFeeRate.
POST /exchangeAgent-signed
order
Add the action-level builder object (b address, f fee) beside orders.
POST /info
builderState
Your claimable balance and whether you are eligible to accrue.
POST /exchangeAgent-signed
claimBuilderRewards
Claim the full balance. Agent-signed.

See Builder Code for fee caps and eligibility.