Overview
How a trade works in sufwan-local-test, from sign-in to withdrawal, and where to start
sufwan-local-test is a white-label prediction market aggregator. Your users trade markets listed on several venues, such as Polymarket, Hyperliquid, and Limitless, through one API. sufwan-local-test matches the same market across venues, quotes the best split, executes it, and tracks every order.
See Fees.
What are you building?
| You are building | Who signs in | Credentials | Start here |
|---|---|---|---|
| A trading bot or AI agent that trades its own funds | The bot, with its own wallet key | x-app-id and the bot's access token | Quickstart: trading bot / agent |
| A platform where many users trade | Each user, on your client | x-app-id and each user's access token. Your backend adds x-app-api-key for server features. | Quickstart: REST, then Choose your integration |
| A trading terminal or other UI | Each user, in the browser | x-app-id and the user's token, managed by the SDK. Never ship x-app-api-key to a browser. | Quickstart: React |
The API reference has two tabs. Trading API is every call made with x-app-id, plus a user's access token where one is needed: markets, quotes, orders, funding, and the user's account. Server API is the calls your backend makes with x-app-api-key: partner admin reads, webhooks, and paper accounts.
The trade lifecycle
Every integration follows the same six steps. Each links to the page that explains it.
| Step | What happens | Main calls |
|---|---|---|
| 1. Authenticate | The user signs in with a wallet, OAuth, email, or Privy. You get an access token. | POST /auth/start, POST /auth/verify |
| 2. Find a market | Browse or search events and markets. You trade an outcome, identified by venueMarketOutcomeId. See Ids. | GET /venue-events, GET /venue-markets |
| 3. Fund | The user deposits USDC to their deposit address on a supported chain. | GET /execution/deposit-addresses, GET /execution/balances |
| 4. Quote | sufwan-local-test prices the trade across every venue that lists the outcome and returns a quoteId. | GET /orderbook/{venueMarketOutcomeId}/route |
| 5. Execute & track | You fill the quote, then poll until the trade reaches a terminal state. | POST /execution/fill, GET /execution/status |
| 6. Settle & withdraw | Winning positions are redeemed after resolution. The user withdraws to any address. | POST /execution/redeem, POST /execution/withdraw |
Execution and custody models
| Model | Who holds the funds | Who signs | Use it for |
|---|---|---|---|
| Managed | A managed balance sufwan-local-test holds for the user | sufwan-local-test | The default. Simplest flow, best-price routing across venues. |
| Self-custody | The user's own EVM wallet | The user's wallet, one request at a time | Users who must keep their own keys. |
| Hosted venue account | An account sufwan-local-test hosts for the user on one venue | sufwan-local-test | Venues where a native account is needed. |
Every wallet and venue account, and which address to pass where, is on Accounts & wallets. Every venue is on Venues.
Choose your integration is five styles inside these three custody models. Privy, paper admin, and ProphetX direct accounts are not in that table.
Within the managed model you can fill a quote, place a direct order on one venue, or rest a limit order.
How you integrate
sufwan-local-test ships as a REST API and four npm packages. Pick the layer that fits:
- REST API: any language. Start with Quickstart: REST.
@agg-build/sdk: a TypeScript client for browsers, Node.js, and React Native. Find methods and their API endpoints in the SDK reference.@agg-build/hooks: React hooks with caching and WebSocket subscriptions.@agg-build/uiand@agg-build/auth: drop-in trading and sign-in components. Start with Quickstart: React.
Each package includes the layers below it. See the Packages overview.
Start here
Quickstart: trading bot / agent
One headless process: sign in with a key, quote, fill, track.
Quickstart: REST
Zero to a filled order over REST.
Quickstart: React
Provider, sign-in, and a first trade in a React app.
Choose your integration
Managed, direct, limit, self-custody, or hosted accounts.
Base URL & API keys
Base URLs, app IDs, API keys, and headers.