Skip to main content
GET
Get a quote (smart route)

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.

Path Parameters

venueMarketOutcomeId
string
required

Query Parameters

mode
enum<string>
Available options:
live,
paper
chainBalances
string
slipCapBps
number
Required range: x >= 0
maxSpend
number
Required range: x > 0
sellShares
number
Required range: x > 0
compareVenues
enum<string>
Available options:
true,
false
allowedVenues
Available options:
kalshi,
polymarket,
limitless,
predict,
pred,
tiprun,
myriad,
hyperliquid,
novig,
prophetx,
betdex,
lighter
side
enum<string>
Available options:
buy,
sell
deepEstimate
enum<string>
Available options:
true,
false
signingAddress
string
Required string length: 42
fundingAddresses

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})$
appFeeBips
number
Required range: 0 <= x <= 10000Must be a multiple of 1
appFeeBipsByVenue
string

JSON object venue→bips, e.g. {"polymarket":20,"hyperliquid":10}. Per-venue app fee in basis points, 0..10000, for the legs filled on that venue. Overrides appFeeBips on the venues it names; 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
string

JSON object venue→bips, e.g. {"polymarket":20,"hyperliquid":10}. Per-venue referral fee in basis points, 0..10000, for the legs filled on that venue. Overrides referrerFeeBips on the venues it names; referrerFeeBips still applies to venues the map omits and 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

Response

200

quoteId
string
required

Pass to POST /execution/fill to trade this quote.

venueMarketOutcomeId
string
required

The outcome requested.

venueMarketId
string
required

Market of that outcome.

estimatedCostRaw
string
required

Price × shares before fees (proceeds on a sell). USD in 6-decimal atomic units, as an integer string (1000000 = $1.00).

expiresAt
string
required

ISO-8601. After this the quote cannot be filled.

refreshAt
string
required

ISO-8601, earlier than expiresAt: fetch a new quote from here on, though this one stays fillable until expiresAt.

status
enum<string>
required

ok when the quote can be filled; anything else means it cannot (see error). insufficient_balance: not enough funds. insufficient_position: not enough shares to sell (see positionAvailability). insufficient_depth / no_orderbooks / no_bids_above_min_price: not enough liquidity. min_order_size_violated / insufficient_input_amount: the amount is too small. infeasible, checker_rejected, solver_error, invalid_input, engine_unavailable: no valid route could be built.

Available options:
ok,
infeasible,
checker_rejected,
solver_error,
invalid_input,
no_orderbooks,
insufficient_input_amount,
engine_unavailable,
min_order_size_violated,
insufficient_balance,
insufficient_position,
insufficient_depth,
no_bids_above_min_price
fills
object[]
required

Where the trade executes, one entry per venue market.

totalFilled
number
required

Total shares bought (or sold), as a float.

rawExecCost
number
required

Price × shares across all fills, before fees (proceeds on a sell). USD, as a float.

solveTimeMs
number
required

Time to compute the route, in milliseconds.

verifyTimeMs
number
required

Time to verify the route, in milliseconds.

matchedMarkets
object[]
required

The same market on other venues. Empty on sells.

quoteRefreshNotBefore
string<date-time>

Earliest time to request a new quote (rate-limited venues only).

quoteFailure
object

A venue that could not be priced live; the quote excludes it.

error
string

Readable reason when status is not ok.

venueSoloQuotes
object[]

With compareVenues=true: the same trade priced on each venue alone, for comparison.

allocations
object[]

How the trade is funded, per source and venue.

bridgeSteps
object[]

Cross-chain transfers needed.

feeBreakdown
object

Cost of the trade, line by line.

appFee
object | null

App fee settings frozen at quote time, for reconciliation. null when the app charges no fee. For display use feeBreakdown.appFee.

referral
object | null

The referral this quote pays; absent or null without a referrer.

slippage
object

Price impact of the route.

optima
object

Best values each objective could reach on its own, for comparison.

warnings
object[]

Venues left out of the route or flagged, without blocking the quote.

custodyWarnings
object[]

Self-custody quotes only: the quote is valid but the fill from this wallet would be refused. Absent on managed quotes.

message
string

Informational note, e.g. on redemption.

settlementPlan
object

Sell quotes on resolved markets only: winning shares are redeemed for their payout instead of sold.

estimatedPayout
number

Payout if the outcome wins, after settlement fees. USD, as a float.

totalCostIncFees
number

All-in cost: feeBreakdown.totalCost + app fee + user-paid referral fee + any funding fee. USD, as a float.

estimatedNetProceeds
number

Sell only: what the sell returns after every fee charged at fill — gross proceeds minus venue, builder, app, and user-paid referral fees. USD, as a float.

estimatedProfit
number

estimatedPayout minus cost. USD, as a float.

returnPct
number

Profit as a percentage of cost (25 = 25%).

positionAvailability
object

Sell quotes only: the user's sellable shares when the quote was built, on the venues the request allows. Returned on ok sell quotes too; on insufficient_position it says how much can be sold. A snapshot, not a reservation: the fill re-checks the live venue balance.

sizeStepRaw
string

Limit-order size step on this venue, in 6-decimal share units (10000 = 0.01 share). Only on a single-venue quote (allowedVenues of one). Absent means any 1-unit size.

minSizeRaw
string

Smallest limit-order size on this venue/market, in 6-decimal share units. Only on a single-venue quote. Absent means no venue minimum is known.

legBounds
object[]