Get a quote (smart route)
x-app-id<token>Your application ID. Required on app-tier and user-tier routes. Omitted on routes that authenticate with x-app-api-key only.
venueMarketOutcomeId*stringmode?string"live""paper"chainBalances?stringslipCapBps?number0 <= valuemaxSpend?number0 <= valuecompareVenues?string"true""false"allowedVenues?array<>|side?string"buy""sell"deepEstimate?string"true""false"signingAddress?string42 <= length <= 42fundingAddresses?array<>|appFeeBips?number10 <= value <= 10000appFeeBipsByVenue?stringJSON 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?stringJSON 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?stringReferral: 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.
42 <= length <= 42referrerFeeBips?numberReferral fee in basis points of the routed notional, 1..10000. sufwan-local-test takes no share of it. With referralPayer "user" it is reserved from maxSpend next to the app fee; with "app" the user pays nothing.
11 <= value <= 10000referralPayer?stringWho funds the referral. Default "user".
"user""app"referralPayerAddress?stringRequired 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).
42 <= length <= 42referralPayoutChainId?numberOptional, 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.
11 <= valuereferralActivationSponsorAddress?stringOptional, 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).
42 <= length <= 42200
application/json- response
quoteRefreshNotBefore?stringEarliest time to request a new quote (rate-limited venues only).
date-timequoteFailure?A venue that could not be priced live; the quote excludes it.
quoteId*stringPass to POST /execution/fill to trade this quote.
venueMarketOutcomeId*stringThe outcome requested.
venueMarketId*stringMarket of that outcome.
estimatedCostRaw*stringPrice × shares before fees (proceeds on a sell). USD in 6-decimal atomic units, as an integer string (1000000 = $1.00).
expiresAt*stringISO-8601. After this the quote cannot be filled.
refreshAt*stringISO-8601, earlier than expiresAt: fetch a new quote from here on, though this one stays fillable until expiresAt.
status*stringok 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.
"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*array<>Where the trade executes, one entry per venue market.
totalFilled*numberTotal shares bought (or sold), as a float.
rawExecCost*numberPrice × shares across all fills, before fees (proceeds on a sell). USD, as a float.
solveTimeMs*numberTime to compute the route, in milliseconds.
verifyTimeMs*numberTime to verify the route, in milliseconds.
matchedMarkets*array<>The same market on other venues. Empty on sells.
error?stringReadable reason when status is not ok.
venueSoloQuotes?array<>With compareVenues=true: the same trade priced on each venue alone, for comparison.
allocations?array<>How the trade is funded, per source and venue.
bridgeSteps?array<>Cross-chain transfers needed.
feeBreakdown?Cost of the trade, line by line.
appFee?App fee settings frozen at quote time, for reconciliation. null when the app charges no fee. For display use feeBreakdown.appFee.
referral?The referral this quote pays; absent or null without a referrer.
slippage?Price impact of the route.
optima?Best values each objective could reach on its own, for comparison.
warnings?array<>Venues left out of the route or flagged, without blocking the quote.
custodyWarnings?array<>Self-custody quotes only: the quote is valid but the fill from this wallet would be refused. Absent on managed quotes.
message?stringInformational note, e.g. on redemption.
settlementPlan?Sell quotes on resolved markets only: winning shares are redeemed for their payout instead of sold.
estimatedPayout?numberPayout if the outcome wins, after settlement fees. USD, as a float.
totalCostIncFees?numberAll-in cost: feeBreakdown.totalCost + app fee + user-paid referral fee + any funding fee. USD, as a float.
estimatedNetProceeds?numberSell 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?numberestimatedPayout minus cost. USD, as a float.
returnPct?numberProfit as a percentage of cost (25 = 25%).
positionAvailability?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?stringLimit-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?stringSmallest 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?array<>curl -X GET 'https://api.t.sufwankhalid.com/orderbook/string/route'{ "quoteId": "k2r8v5n1x7c4m9t3b6q0w2za", "venueMarketOutcomeId": "cmf3q8z1k00a2mw0l7xg4v9rt", "venueMarketId": "cmf3q8yzt009xmw0lh2c5d8kn", "estimatedCostRaw": "25000000", "expiresAt": "2026-09-29T15:04:30.000Z", "refreshAt": "2026-09-29T15:04:20.000Z", "status": "ok", "fills": [ { "venue": "polymarket", "venueMarketId": "cmf3q8z0a009zmw0l3w8n6jbd", "venueMarketOutcomeId": "cmf3q8z2m00a4mw0lr5t1k7yc", "chain": "137", "avgPrice": 0.51, "yesPrice": 0.51, "noPrice": 0.5, "fills": [ { "price": 0.51, "size": 30, "fill": 30 } ], "venueQty": 30, "venueFee": 0 }, { "venue": "limitless", "venueMarketId": "cmf3q8z0x00a0mw0lc1v7q3mf", "venueMarketOutcomeId": "cmf3q8z3p00a6mw0l9e4h2sxa", "chain": "8453", "avgPrice": 0.535, "yesPrice": 0.535, "noPrice": 0.475, "fills": [ { "price": 0.535, "size": 18, "fill": 18 } ], "venueQty": 18, "venueFee": 0.05 } ], "totalFilled": 48, "rawExecCost": 24.93, "solveTimeMs": 42, "verifyTimeMs": 6, "matchedMarkets": [ { "venue": "polymarket", "venueMarketId": "cmf3q8z0a009zmw0l3w8n6jbd" }, { "venue": "limitless", "venueMarketId": "cmf3q8z0x00a0mw0lc1v7q3mf" } ], "allocations": [ { "sourceChainId": "137", "venue": "polymarket", "amount": 15.3 }, { "sourceChainId": "8453", "venue": "limitless", "amount": 9.68 } ], "bridgeSteps": [], "feeBreakdown": { "rawExecCost": 24.93, "venueFees": 0.05, "bridgeFees": 0, "executionGas": 0.02, "totalCost": 25 }, "appFee": null, "referral": null, "slippage": { "vwap": 0.5194, "refMidpoint": 0.515, "slippage": 0.0044, "slippageBps": 85 }, "warnings": [], "estimatedPayout": 48, "totalCostIncFees": 25, "estimatedProfit": 23, "returnPct": 92}