Skip to main content
You’ll need:
  • An app ID. Sign in to the admin dashboard (https://admin.agg.market); your first sign-in creates an app. Copy its ID from API. See Base URL, app IDs & API keys.
  • One allowed origin on that app, for example https://app.example.com (Domains). A new app has none, and wallet sign-in is refused until you add one. The sign-in message must name it.
  • curl, jq, and Foundry’s cast (to create a test wallet and sign), or Node 18+ with @agg-build/sdk and viem for the SDK tabs.
  • A few dollars of USDC on a supported chain, or use paper mode.
Result: a filled order, polled until terminal is true.
This guide places a real order on a live venue and spends real funds. Use a small amount, or add mode=paper to trade without funds. Venues are restricted by the caller’s country; see Venue geo availability.

0. Set up

1. Sign the user in

Get a nonce, sign an EIP-4361 (SIWE) message with the wallet, and exchange it for tokens.
Full shapes on Start authentication and Verify sign-in. POST /auth/verify returns { accessToken, refreshToken, user }. Every call below sends x-app-id and Authorization: Bearer $ACCESS_TOKEN. The message format must be exact: a blank statement slot means two empty lines between the address and URI:. If sign-in fails: Access tokens are short-lived. If a later call returns 401, see Authentication & sessions.

2. Get a deposit address and fund it

Full shape on Get deposit addresses. The full 202 {ready:false} loop is on Funding. Send USDC to evmAddress on one of the chains in supportedChains (or to svmAddress on Solana). Then check the balance until availableRaw is above zero:
availableRaw is an integer string in the token’s decimals: "5000000" with 6 decimals is 5 USDC. Full shape on Get balances.

3. Find a market

List open markets and take an outcome id. You trade an outcome, not a market.
Full shape on List venue markets. See Markets, outcomes & matching and Ids for how ids and cross-venue matching work.

4. Get a quote

Send the user’s token so the quote is executable, not a preview.
Full shape on Get a quote (smart route). message is informational. Read error when status is not "ok". Fill only when status is "ok". Otherwise: The quote expires at expiresAt, about 45 seconds after it is created. Fill within that window. Details: Quotes & smart routing.

5. Execute the quote

Full shape on Execute quote. The response status is pending: accepted, not done. Poll Order lifecycle. If the call times out or returns 404, follow Errors. Do not re-quote until that page says to.

6. Track it to a final state

Poll the execution status until terminal is true, waiting pollAfterMs between calls.
Full shape on Get execution status. The final overallState is one of: filledAmountRaw is USD spent and actualSharesRaw is shares bought, both as 6-decimal integer strings. Every status and state is listed in Order lifecycle & statuses. The new position shows up in GET /execution/positions.

Test without real funds

Add mode=paper to the quote, "mode": "paper" to the fill body, and mode=paper to the status call. Skip step 2: a paper account is created for the user on first use, with a simulated PAPER_USD balance. Paper fills price against live books but never reach a venue. See Paper trading.

Next

To expand this integration, use the SDK method reference to find the client method for each API operation.

Choose your integration

Direct orders, limit orders, and self-custody.

Errors, retries & idempotency

Every error code and which calls are safe to retry.

Webhooks

Get trade and deposit events pushed to your backend.

Base URL & API keys

Configure your app and add a server API key.