Choose your integration
Managed quote and fill, direct orders, limit orders, self-custody, and hosted venue accounts compared
Every option trades the same markets. They differ in who holds the funds, who signs, and what you build.
At a glance
| Option | Funds held in | Who signs | You implement | Pick it when | Guide |
|---|---|---|---|---|---|
| Managed quote + fill | The user's managed balance | sufwantest | Quote, show price, fill, poll status | You want the best price across venues and a simple flow. The default. | Quickstart: REST |
| Direct order | The user's managed balance | sufwantest | One call with your externalId, then poll | Your backend already knows the venue and amount, and you want idempotent server calls. | Direct order execution |
| Limit order | The user's managed balance (reserved while open) | sufwantest | Place, poll until open, cancel | You want price control on one venue and can wait for a fill. | Limit orders |
| Self-custody | The user's own EVM wallet | The user's wallet | Quote and fill with signingAddress, then a loop that signs each request | Users must keep their own keys. Needs a client that can sign. | Self-custody trading |
| Hosted venue account | An account sufwantest hosts for the user on one venue (BetDEX) | sufwantest | Provision the account, then deposit and withdraw per venue | You need that venue's native account. | Hosted venue accounts |
Only managed quote and fill accept mode=paper on the order itself. Direct orders reject it.
Other surfaces
These are not rows in the table above.
| Surface | What it is | Guide |
|---|---|---|
| Privy | sufwantest signs the user's Privy wallets. The user is not present to sign. | Privy wallet provider |
| Paper | mode=paper on the quote and the fill, plus a separate admin API. | Paper trading |
| ProphetX direct accounts | The user's own ProphetX account. A cancelled market refunds there. | Market resolution |
| Onramp | A fiat purchase into a wallet address. Not a deposit address. | Onramp |
| Refills | Keep a managed USDC balance above a minimum on one chain after a trade. | Managed balance refills |
| KYC | Shared KYC for ProphetX and the same check on other venues that ask for it. | KYC |
| Venue keys | The user's own Kalshi API key. Every Kalshi trade uses it. See Kalshi. | Venue keys |
Managed quote + fill
GET /orderbook/{venueMarketOutcomeId}/route with the user's token returns a quoteId that may
split across venues. POST /execution/fill executes it. You show the quote's price and fees before
the user confirms. Quotes last about 45 seconds.
Start with Quickstart: REST. Concepts: Quotes & smart routing, Execution.
Direct order
POST /execution/orders places a market order on one venue you name. There is no quote step, and it
never splits. externalId is required, so a timed-out request can be retried without trading twice.
maxSpend caps the all-in cost. Live only.
Guide: Direct order execution.
Limit order
POST /execution/limit-orders rests an order at your price on one venue, with a time in force
(GTC, GTD, FOK, FAK, IOC, ALO; venues support subsets). Funds or shares are reserved
while it is open. Track it with GET /execution/orders?orderId=; open is not final.
Guide: Limit orders.
Self-custody
The user links an EVM wallet to their account. Quotes and fills name it as signingAddress. sufwantest
prices against that wallet's balances and then asks the wallet to sign each step: venue orders,
funding moves, and approvals. sufwantest never holds the key. The user must be present to sign, and each
request expires.
Supported on Polymarket, Hyperliquid, and Kalshi (with the user's own Kalshi API key; see Venue keys). Other venues are refused at fill time.
Guides: Self-custody trading and Self-custody signing reference.
Hosted venue account
For BetDEX, sufwantest can host a venue account for the user. You provision it, read its balance, get a Solana USDC deposit address for it, and withdraw from it. See Hosted venue accounts. The provision call is Provision hosted venue account.
Where your code runs
| Setup | How it works |
|---|---|
| Browser only | Your app signs users in and calls sufwantest with x-app-id and the user's token. Add allowed origins. |
| Browser plus backend | Users sign in on the client. Your backend calls trading routes with x-app-id and that user's access token. Send x-app-api-key only for the header set in Base URL, app IDs & API keys. It does not replace x-app-id. |
| UI kit | Drop in @agg-build/ui components; they call the same API. See Quickstart: React. |
Server-only features, such as per-trade appFeeBips, referral fees, and skipQuote on direct
orders, need x-app-api-key.