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’scast(to create a test wallet and sign), or Node 18+ with@agg-build/sdkandviemfor the SDK tabs.- A few dollars of USDC on a supported chain, or use paper mode.
terminal is true.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.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
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.4. Get a quote
Send the user’s token so the quote is executable, not a preview.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
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 untilterminal is true, waiting pollAfterMs between calls.
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
Addmode=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.