Overview
TheOrderClient handles order creation, EIP-712 signing, and order management. It supports Good-Til-Cancelled (GTC), Fill-And-Kill (FAK), and Fill-or-Kill (FOK) orders.
Prerequisites
Before placing orders, you need three components:The
OrderClient lazily fetches your user profile on the first order to determine your fee rate. The CHAIN_ID environment variable defaults to 8453 (Base mainnet).Token approvals
Before your first trade on a given venue, you must approve the exchange contracts to spend your tokens. This is a one-time on-chain setup per venue.- Standard CLOB
- NegRisk
For standard CLOB markets, approve USDC and Conditional Tokens to the exchange contract:
GTC orders (Good-Til-Cancelled)
GTC orders remain on the orderbook until filled or explicitly cancelled. SpecifyPrice (0.0–1.0, tick-aligned to 0.001) and Size (number of shares):
Post-only GTC order
UsePostOnly: true to ensure your order is never filled immediately as a taker. If the order would cross the spread (i.e., match against existing orders), it is rejected instead. This guarantees you always receive maker fees.
GTCOrderArgs
Self-trade prevention
SetStpPolicy on CreateOrderParams to control what happens when your incoming order would match your own resting order on the same token. It is a top-level request field — not part of the EIP-712 signed order args — and applies to any order type. Leave it empty to keep the server default, cancel_maker.
The create-order response carries an
Execution field with the outcome:
Self-trade prevention blocks same-profile matches on the same token only. Orders on a different token of the same profile are unaffected. The wire field is always
stpPolicy, regardless of the SDK.FAK orders (Fill-And-Kill)
FAK orders use the samePrice and Size inputs as GTC, but they only consume immediately available liquidity and cancel any unmatched remainder.
PostOnly is not supported for FAK orders.
FAKOrderArgs
FOK orders (Fill-or-Kill)
FOK orders execute immediately and fully, or are rejected entirely. Instead ofPrice and Size, you specify MakerAmount:
- FOK BUY
- FOK SELL
When buying,
MakerAmount is the total USDC you want to spend (max 6 decimal places). The exchange fills as many shares as possible at the best available price:FOKOrderArgs
Advanced: Build and sign separately
For advanced use cases, you can build and sign orders without submitting them:AMM trading
CLOB orders trade against the orderbook. AMM (FPMM) markets trade against a pool, and the SDK exposes them throughsdk.AMM. The service calls POST /amm/allowances/check, POST /amm/allowances/approve, POST /amm/buy, and POST /amm/sell on behalf of a partner server wallet.
Use it when the market is an AMM market and you want the server to hold custody, sign the trade, and pay gas. See AMM Trading (Server Wallets) for the underlying endpoints and market model.
Requirements
- Authenticate with an HMAC API token that holds both the
tradinganddelegated_signingscopes, or call the*WithIdentityvariants with a Privy identity token. Legacyx-api-keycredentials are rejected. - The trade runs against a server-wallet sub-account. Set
OnBehalfOfto the sub-account profile ID (1..=2147483647), or omit it (zero value) to trade from the authenticated profile. - Amounts are positive integer strings in the collateral token’s base units (for USDC:
"1000000"= 1 USDC). Never usefloat64. SlippageBpsis optional (*int).niluses the server default of100(1%); values range from0to1000.OutcomeIndexisAMMOutcomeYes(0) orAMMOutcomeNo(1).
One-time approval per wallet and market
BUY and SELL approvals are independent and set up once per wallet and market. Buy and Sell do not preflight allowances themselves. Confirm the allowance first.
EnsureAllowance runs CheckAllowance, submits ApproveAllowance at most once when missing, then polls the check until Confirmed is true. Polling defaults to every two seconds; use the context timeout to bound how long it waits.
A
submitted response from ApproveAllowance (HTTP 202) is not confirmation. Either use EnsureAllowance, or poll CheckAllowance until Confirmed is true.Buy shares
Buy spends an exact collateral amount on the chosen outcome. Pass a unique IdempotencyKey per trade. On a timeout retry, reuse the same immutable params value so the serialized body and idempotency key stay byte-identical.
Sell shares
Sell requests an exact collateral return by selling outcome shares.
Reusing an
IdempotencyKey with different params raises ConflictError (HTTP 409). The four AMM routes share a rate limit of 10 requests / 10 seconds per actor. Use the *WithRawResponse variants (e.g. sdk.AMM.BuyWithRawResponse) when you need the underlying HTTP status and headers.Cancelling orders
- Cancel a single order
- Cancel all orders on a market
Cancel a specific order by its ID:
Cancel and replace
CancelReplace cancels one open order and submits a replacement in the same request. Use it to reprice or resize a resting order in one round-trip instead of separate cancel and create calls. CancelReplaceBatch runs several of these operations in a single call.
The cancel and the replacement are not atomic: they report independent outcomes, and a successful cancel does not guarantee a successful replacement. Choose the failure mode with CancelReplaceMode:
Identify the order to cancel with
CancelByOrderID or CancelByClientOrderID. The replacement is a normal signed order and uses the same OrderArgs fields as CreateOrder.
Single cancel-replace
Batch cancel-replace
Each operation runs independently and its result is returned with the caller’sIndex:
Delegated cancel-replace
Partners with thedelegated_signing scope call delegatedOrders.CancelReplace and delegatedOrders.CancelReplaceBatch. The server signs the replacement using the sub-account’s managed wallet, so no signing key is required. Set OnBehalfOf (the sub-account profile ID) on every operation:
See
POST /orders/cancel-replace and POST /orders/cancel-replace/batch for the full request and response shapes, per-status fields, and failure semantics.Enums reference
Side
OrderType
Error handling
The SDK returns typed errors for order failures. Useerrors.As() to inspect them:
See Error Handling & Retry for details on error types and the
WithRetry function.