Skip to main content
POST
Place an order directly

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
venue
enum<string>
required

The venue to trade on. Singular by design — this endpoint never splits an order.

Available options:
kalshi,
polymarket,
limitless,
predict,
pred,
tiprun,
myriad,
hyperliquid,
novig,
prophetx,
betdex,
lighter
venueMarketOutcomeId
string
required

The outcome to trade. May be the outcome on another venue: it is resolved through matched-outcome links to the equivalent outcome on venue. Passing the id that already lives on venue is the unambiguous form.

Minimum string length: 1
side
enum<string>
required

Trade direction. sell closes an existing position on venue.

Available options:
buy,
sell
externalId
string
required

Idempotency key. Your own id for this trade — required, and unique within your app: two different users of the same app cannot share one. A repeat is rejected with 409 rather than trading twice, so it is safe to retry a request that timed out using the same value. A request rejected before its order was queued leaves the value free to reuse.

Required string length: 1 - 36
maxSpend
number

Buy only. Maximum all-in USD spend, inclusive of app fee.

Required range: x > 0
sellShares
number

Sell only. Number of contracts to sell.

Required range: x > 0
slipCapBps
number

Slippage cap in basis points. Defaults to 500 (5%) when omitted. On sells set this explicitly: sellShares bounds the shares sold, not the proceeds.

Required range: x >= 0
allowedSourceChainIds
integer[]

Restrict funding to these source chains. Omitted, the order may be funded from any chain the user holds, bridging in when the venue's own chain is short. Listing only the venue's chain (56 for predict.fun, 137 for Polymarket) makes the order fail with insufficient funding instead of bridging. Balances are still read on-chain: this narrows which of them may be spent, it never adds capacity.

Minimum array length: 1
Required range: x >= 1
chainBalances
object

Per-chain USD funding budgets, e.g. {"56": 50}. Caps refreshed wallet balances; never adds capacity. A chain-only budget is shared across its token buckets. Omitted chains cannot fund the order; an empty map allows no on-chain funding. Combines with allowedSourceChainIds: excluded chains cannot fund the order.

appFeeBips
number

Per-trade app fee in basis points of routed notional, 0..10000. Replaces the app's configured rate for this order only. Honoured only when the request carries x-app-api-key; otherwise 400 app_fee_override_requires_api_key. Buy only.

Required range: 0 <= x <= 10000Must be a multiple of 1
appFeeBipsByVenue
object

Per-venue app fee in basis points, e.g. {"polymarket":20,"hyperliquid":10}. Keys are venue names; a rate applies to the legs filled on that venue and overrides appFeeBips there. The scalar appFeeBips still applies to venues the map omits. Honoured only when the request carries x-app-api-key; otherwise 400 app_fee_override_requires_api_key. Buy only.

referrerFeeBipsByVenue
object

Per-venue referral fee in basis points, e.g. {"polymarket":20,"hyperliquid":10}. Keys are venue names; a rate applies to the legs filled on that venue and overrides referrerFeeBips there, which still applies to venues the map omits. referrerFeeBips is optional when this is sent; 0 = no referral on that venue, but at least one venue must end up with a positive rate. Needs referrer. Same rules as referrerFeeBips: x-app-api-key required, buy only.

referrer
string

Referral: the EVM address that receives the referral fee. Requires referrerFeeBips or referrerFeeBipsByVenue. Honoured only when the request carries x-app-api-key; a JWT-only request that sends it is rejected with 400 referral_requires_api_key. Buy only.

Required string length: 42
referrerFeeBips
number

Referral fee in basis points of the routed notional, 1..10000. AGG takes no share of it. With referralPayer "user" it is reserved from maxSpend next to the app fee; with "app" the user pays nothing.

Required range: 1 <= x <= 10000Must be a multiple of 1
referralPayer
enum<string>

Who funds the referral. Default "user".

Available options:
user,
app
referralPayerAddress
string

Required when referralPayer is "app": the wallet that settles the payout. After the fill, a pendingSignatures entry appears with signerAddress set to this address and purpose "referral_payout"; answer it on POST /execution/fill/:quoteId/signatures. Read its type: on an EVM chain it is a transaction to broadcast (post the hash), on HyperCore an eip712 to sign (post the signature).

Required string length: 42
referralPayoutChainId
number

Optional, and only with referralPayer "app": the chain the referrer is paid on. Must carry USDC. On an EVM chain the payout is an ERC-20 transfer the partner's wallet broadcasts, needing USDC plus native gas there; on HyperCore (1337) it is a user-signed sendAsset from the partner's HyperCore spot balance — a signature, nothing to broadcast — and the referrer receives spot USDC on Hyperliquid. A first payout to a referrer with no Hyperliquid account costs the partner an extra 1 USDC that Hyperliquid charges to create it; later payouts to the same referrer cost nothing. Solana does not support app-paid payouts and is refused. Defaults to the trade's fee chain, or Polygon when that chain is not EVM. Sending it with a user-paid referral is rejected with 400 referral_invalid.

Required range: x >= 1Must be a multiple of 1
referralActivationSponsorAddress
string

Optional, and only with a user-paid referral (referralPayer "user" or absent): a wallet that pays Hyperliquid's one-time 1 USDC account-activation fee when the referrer has never received anything on HyperCore. Honoured on self-custody Hyperliquid buys only; ignored otherwise. Before the fill a pendingSignatures entry appears with signerAddress set to this address, purpose "hl_activation_sponsor" and optional: true — an eip712 sendAsset of 0.000001 USDC to the referrer. Sign it and post the signature on POST /execution/fill/:quoteId/signatures. After the fill it is posted just before the referral transfer, only if the referrer still has no HyperCore account. This wallet's HyperCore spot balance must hold at least 1.000001 USDC. Declining it is safe: the trade proceeds and the referral is attempted as usual. Must differ from referrer; rejected with referralPayer "app". The request reaches your signer through the user's client: sign only the exact transfer described here (see Fees → Securing the paying wallet's signer).

Required string length: 42
skipQuote
boolean

Skip the smart-route solver and send one order straight to venue. predict, hyperliquid, kalshi, novig and prophetx only; any other venue returns 400. Requires a read_write x-app-api-key (401 without a key, 403 with a read key). No bridging: the funds must already sit on the venue's own chain, and allowedSourceChainIds / chainBalances are ignored. A buy the stored balance cannot fund returns 400 quote_insufficient_balance before acceptance. Referral fields apply to buys as on a routed order; on a sell they return 400. You own the price and minimum checks — an order the venue refuses fails after acceptance and uses up its externalId. Kalshi and connected ProphetX/Novig API buys use fixed-price admission automatically; the venue decides available cash when accepting the order.

skipBalance
boolean

With skipQuote, skip the balance check and fund hold on a buy: nothing checks the balance and an underfunded order fails at the venue. Sells still check and hold the position. Without skipQuote, skip only the quote-time balance refresh: the route uses the last stored balances, and the fund hold and balance check still run, so a stale balance can fail the order after acceptance but never overspend. Requires a read_write x-app-api-key.

price
number

With skipQuote or a native API buy, the price limit, e.g. 0.52. Optional: omitted, the best available price at submission is used (best ask for a buy, best bid for a sell), and an empty side returns 400. A hyperliquid buy is sized as the whole contracts that fit maxSpend at this price plus slippage. Ignored on clearinghouse prophetx, which prices the order itself within slipCapBps.

Required range: 0 < x < 1

Response

200

orderId
string
required

The single order this call created.

externalId
string
required

Echoed back so a webhook or socket event can be tied to this response.

venue
enum<string>
required

The venue the order was placed on.

Available options:
kalshi,
polymarket,
limitless,
predict,
pred,
tiprun,
myriad,
hyperliquid,
novig,
prophetx,
betdex,
lighter
status
enum<string>
required

Always pending: the order is accepted and queued for execution, not yet filled. Poll GET /execution/orders or listen for order events for the terminal state.

Available options:
pending
quoteId
string
required

Server-minted quote backing this order. Useful for support, not required.

quotedPriceRaw
string | null
required

Quoted price, decimal string (e.g. "0.53"). null if the order row does not carry a quoted price — the order is still live; re-fetch it from GET /execution/orders rather than treating this as zero.

quotedCostRaw
string | null
required

Quoted cost, 6-decimal atomic USDC. null under the same conditions as quotedPriceRaw.

quotedSharesRaw
string | null
required

Quoted shares, 6-decimal atomic. null under the same conditions as quotedPriceRaw.