Skip to main content

Overview

The OrderClient 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).
Wallet-mode preflight. Accepting the one-time “choose your trading wallet” prompt in the app enables 1-click (smart wallet) trading on your Limitless profile. Once that mode is set, self-signed orders are rejected with Signer does not match - you should use embedded address for smart wallet. Switch the profile to EOA trading mode first: see Trading wallet mode.

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.
For standard CLOB markets, approve USDC and Conditional Tokens to the exchange contract:
Approvals are on-chain transactions that cost gas. You only need to perform them once per venue. Use Venue.Exchange for both CLOB and NegRisk, and additionally Venue.Adapter for NegRisk markets.

GTC orders (Good-Til-Cancelled)

GTC orders remain on the orderbook until filled or explicitly cancelled. Specify Price (0.0–1.0, tick-aligned to 0.001) and Size (number of shares):

Post-only GTC order

Use PostOnly: 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

Set StpPolicy 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 same Price 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 of Price and Size, you specify MakerAmount:
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 through sdk.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 trading and delegated_signing scopes, or call the *WithIdentity variants with a Privy identity token. Legacy x-api-key credentials are rejected.
  • The trade runs against a server-wallet sub-account. Set OnBehalfOf to 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 use float64.
  • SlippageBps is optional (*int). nil uses the server default of 100 (1%); values range from 0 to 1000.
  • OutcomeIndex is AMMOutcomeYes (0) or AMMOutcomeNo (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 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’s Index:

Delegated cancel-replace

Partners with the delegated_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. Use errors.As() to inspect them:
See Error Handling & Retry for details on error types and the WithRetry function.

Complete example