Skip to main content
POST
Execute quote

Integration guide

Authorizations

x-app-id
string
header
required

Your application ID. Required on app-tier and user-tier routes. Omitted on routes that authenticate with x-app-api-key only.

Authorization
string
header
required

JWT access token from POST /auth/verify. Required with x-app-id on user routes. On the smart-route quote it is optional and turns a preview into an executable quote.

Body

application/json
quoteId
string
required

quoteId from GET /orderbook/{venueMarketOutcomeId}/route.

externalId
string

Idempotency key. Your own id for this trade, unique within your app. Saved on every order the quote splits into, so GET /execution/orders?externalId= returns all legs, and carried on each trades.filled webhook. Reusing it on a different quote is rejected with 409, unless the earlier fill was rejected before its orders were queued. Live mode only.

Required string length: 1 - 128
mode
enum<string>

live (default) or paper to fill against the user's paper account.

Available options:
live,
paper
fallbackToLatest
object

Used only when quoteId has expired: the server fills against the user's latest quote with this same intent instead of returning 400. A different spend, mode or venue scope is a different intent and does not match.

signingAddress
string

Self-custody: the wallet that signs this fill. Must already be linked to the account. Omit for managed custody (the default).

Required string length: 42
fundingAddresses
string[]

Self-custody: other linked wallets this fill may spend from (signingAddress is always included). Order does not matter: per token, the wallet with the largest balance is used first. Omit to fund from the signing wallet only. Entries are EVM or Solana; a Solana entry only funds (the signer stays EVM) and is asked for one solana_transaction signature per bridge.

Linked funding wallet: EVM 0x-prefixed 20-byte hex, or Solana base58 (32–44 chars).

Pattern: ^(0x[a-fA-F0-9]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$
approveMode
enum<string>

Self-custody, cross-chain fills only: how the token approval a bridge needs is made. sponsored (default): the wallet does not send the approve itself; it signs a one-time EIP-7702 authorization per chain, over a raw digest (not EIP-191 or EIP-712), which many wallets cannot produce. user_broadcast: the user sends the approve transaction from their wallet and pays its gas, on every bridge. Pick based on what the wallet software supports. Neither mode makes bridging free: quote with deepEstimate and read feeBreakdown.bridgeFees and feeBreakdown.setupCosts.

Available options:
sponsored,
user_broadcast
replaceForeignDelegation
boolean

Self-custody buys, sponsored approvals only. true: if the funding wallet is EIP-7702 delegated to another application on the source chain, ask it for an eip7702_authorization that replaces that delegation instead of failing the fill. The previous delegation stops working on that chain until the user sets it again. Only send this for wallets whose owner has accepted that. Rejected with a 400 under approveMode: "user_broadcast". Default false.

Response

200

quoteId
string
required

The quote being filled. Poll GET /execution/status with it.

orderIds
string[]
required

Orders created for the fill, including tracking orders for shares redeemed instead of sold.

status
enum<string>
required

Always pending: accepted, not yet executed. Poll GET /execution/status.

Available options:
pending
alreadyAccepted
boolean

true when this quote was already accepted; the call had no new effect.

redeemId
string

Present when a sell quote includes resolved shares that are redeemed rather than sold.

message
string

Readable note about redemption, when relevant.

pendingSignatures
object[]

Self-custody only: requests the user's wallet must sign before execution continues. Absent for managed custody. Answer them on POST /execution/fill/{quoteId}/signatures.