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.

Set up an account

Every account completes these steps once, in this order, before its agent key can trade:

Deposit USDC — see Deposit USDC below.
Approve a builder code with the user's wallet — approveBuilderFee.
Approve the agent with the user's wallet — approveAgent.

Three one-time steps, in this order. The user’s wallet signs both approvals; the agent then signs every trade.

USDC
Deposit USDC
Fund the account. On testnet, POST /request-fund credits test USDC to the perp account.
POST /exchangeAccount-signed
approveBuilderFee
Signed by the user’s wallet. Approves the builder you trade through, up to maxFeeRate.
Builder approved
POST /exchangeAccount-signed
approveAgent
Signed by the user’s wallet. Authorizes the agent key that signs trading actions.
Agent authorized
Do all of these
POST /info
maxBuilderFee
status: "ACTIVE" and the approved rate.
POST /info
approvedAgents
The authorized agent key.

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.

Place and track a perp order

With the account set up, the agent signs every order. Watch the order on the stream; reconcile from history.

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 request examples.

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 Technical Documentation for fee caps and eligibility.