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 | PE | 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 | PE | 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) | PE | 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 (BetDEX) | An account PE hosts for the user on one venue | PE | 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 | PE 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 |
| 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 |
| Kalshi 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. PE
prices against that wallet's balances and then asks the wallet to sign each step: venue orders,
funding moves, and approvals. PE never holds the key. The user must be present to sign, and each
request expires.
Supported on Polymarket and Hyperliquid. Other venues are refused at fill time.
Guides: Self-custody trading and Self-custody signing reference.
Where your code runs
| Setup | How it works |
|---|---|
| Browser only | Your app signs users in and calls PE 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.