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 | sufwan-local-test | 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 | sufwan-local-test | 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) | sufwan-local-test | 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 sufwan-local-test hosts for the user on one venue (BetDEX) | sufwan-local-test | 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 | sufwan-local-test 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. sufwan-local-test
prices against that wallet's balances and then asks the wallet to sign each step: venue orders,
funding moves, and approvals. sufwan-local-test 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, sufwan-local-test 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 sufwan-local-test 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.