Skip to main content

​
Base URL

There is one environment. Orders route to the real venues, so a live fill spends real funds. Use paper trading to test without them.

​
Your app ID

Every request carries your app ID in the x-app-id header. Find it in the admin dashboard: pick your app, then open API under Develop. The same page lists your API keys.

​
Allowed origins

Your app’s allowed origins are the sites your browser code runs on. Manage them in the admin dashboard under Domains. Enter bare origins such as https://app.example.com, with no path, query, or wildcard. They are used in three places:
  • A request that sends an Origin header must match one of them, or it gets 403 Origin not allowed for this app. Server requests usually send no Origin and skip this check.
  • A SIWE or SIWS sign-in message names a domain. It must match an allowed origin, or sign-in fails with 401 and code: "unregistered_domain".
  • OAuth and magic-link redirectUrl values must be on an allowed origin.
An app with no allowed origins cannot complete wallet sign-in.

​
Headers

Each route has an auth tier. The API Reference shows it on every endpoint. Where the call comes from decides what else to send: Users sign in on the client, and your backend includes that user’s access token on trading calls. See Authentication & sessions.

​
Server API keys

Send x-app-api-key from your backend. It is always accepted and never required unless you turn on Require API key. A validated key gives your backend its own rate-limit budget and unlocks server-only options such as per-trade appFeeBips, referral fields, and skipQuote.
An API key is a secret. Never put it in browser bundles, source maps, public repositories, or logs.

​
Create a key

In the admin dashboard, pick your app, open API, and create a key. Pick a scope: The key is shown once. Store it in your secret manager right away. AGG keeps only a hash and cannot show it again. Keys look like agg_<appId>_<64 hex characters>. A key only works with its own app’s x-app-id. A key that is missing, malformed, unknown, revoked, expired, or for another app is rejected with 401 or 403. Unknown and wrong-app keys return the same "Invalid API key" message.

​
Send it

​
Require a key for every request

Turn on Require API key in the dashboard’s Settings for a server-only app. Then every request without a valid key returns 401 with "This app requires x-app-api-key for all requests.". Browser calls stop working, because they carry no key, so leave it off for any app with browser users. Only a signed-in dashboard admin can change this setting. A read_write key cannot.

​
Rotate a key

  1. Create a new key.
  2. Deploy your backend with it.
  3. Check traffic moved to it (lastUsedAt in the dashboard).
  4. Revoke the old key. Revoked and expired keys fail at once with 401.

​
Rate limits

A validated key gets its own per-key budget, by default 18,000 requests per minute, and skips browser IP limits. AGG can change a key’s budget on request. Route-specific caps still apply, see Market data API. A limited request returns 429 with a Retry-After header in seconds. See Errors, retries & idempotency.

​
Testing mode

New apps start in testing mode, with two caps: Existing users can always sign in. Past the user cap, POST /auth/verify returns 403 for new users. Past the trade cap, trading calls return 403. Both carry a readable message:
OAuth and magic-link sign-in report the user cap on the redirect URL as a message query parameter with error=testing_user_limit_reached. To lift the caps, sign the partner agreement in the admin dashboard (Go Live). It takes effect at once and cannot be undone from the dashboard. Existing users and trades are kept.

​
Route families

The API Reference groups endpoints in the order a trade flows:
  • Authentication: start sign-in, verify wallet signatures, exchange redirect codes, refresh tokens, sign out, bot protection.
  • Markets: venue events, venue markets, outcome lookup, categories, search, recurring crypto markets.
  • Market Data: orderbooks, outcome snapshots, midpoints, chart bars, live sports scores, crypto reference prices.
  • Trading: quote, execute, submit self-custody signatures, direct and limit orders, cancel, execution status, redeem, venue geo policy.
  • Portfolio: orders, positions, balances, activity, leaderboard.
  • Funding: deposit addresses, withdrawals, balance refill policies, fiat on-ramp.
  • Users: current user, profile, linked accounts, KYC, venue API keys.
  • Hosted Venue Accounts: accounts AGG hosts for the user on a venue.
  • Webhooks: create, update, test, and replay webhook endpoints.
  • Partner Admin: server-side reads across your app’s users, orders, and analytics.
  • Paper Trading: simulated accounts and orders.
  • News and Correlated Markets: market-aware articles and related markets.