Start here

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

OptionFunds held inWho signsYou implementPick it whenGuide
Managed quote + fillThe user's managed balancePEQuote, show price, fill, poll statusYou want the best price across venues and a simple flow. The default.Quickstart: REST
Direct orderThe user's managed balancePEOne call with your externalId, then pollYour backend already knows the venue and amount, and you want idempotent server calls.Direct order execution
Limit orderThe user's managed balance (reserved while open)PEPlace, poll until open, cancelYou want price control on one venue and can wait for a fill.Limit orders
Self-custodyThe user's own EVM walletThe user's walletQuote and fill with signingAddress, then a loop that signs each requestUsers 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 venuePEProvision the account, then deposit and withdraw per venueYou 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.

SurfaceWhat it isGuide
PrivyPE signs the user's Privy wallets. The user is not present to sign.Privy wallet provider
Papermode=paper on the quote and the fill, plus a separate admin API.Paper trading
OnrampA fiat purchase into a wallet address. Not a deposit address.Onramp
RefillsKeep a managed USDC balance above a minimum on one chain after a trade.Managed balance refills
Kalshi venue keysThe 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

SetupHow it works
Browser onlyYour app signs users in and calls PE with x-app-id and the user's token. Add allowed origins.
Browser plus backendUsers 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 kitDrop 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.

On this page