# Agg.market — Prediction Market Aggregator

> White-label prediction market aggregator API: sign users in, quote the best price across venues, execute trades, and track them to a final status. Start with Quickstart: REST.

> ## Agent Instructions
> To integrate AGG, start with Quickstart: REST (https://docs.agg.market/quickstart/rest), then Order lifecycle & statuses (https://docs.agg.market/concepts/order-lifecycle).
> Track every trade until it reaches a terminal status. Before retrying a failed or timed-out call, read Errors, retries & idempotency (https://docs.agg.market/concepts/errors).
> The API reference is generated from https://docs.agg.market/openapi/openapi.json.

- [Overview](https://docs.agg.market/introduction.md): How a trade works in AGG, from sign-in to withdrawal, and where to start
- [Quickstart: trading bot / agent](https://docs.agg.market/quickstart/agent.md): One headless TypeScript process that signs in with its own key, quotes, fills, and tracks a trade
- [Quickstart: REST](https://docs.agg.market/quickstart/rest.md): From zero to a filled order with curl: sign in, fund, find a market, quote, fill, and track
- [Quickstart: React](https://docs.agg.market/quickstart/react.md): Wire the AGG client, provider, sign-in, and a first trade into a React app
- [Choose your integration](https://docs.agg.market/integration-options.md): Managed quote and fill, direct orders, limit orders, self-custody, and hosted venue accounts compared
- [Base URL, app IDs & API keys](https://docs.agg.market/environments.md): The API base URL, where your app ID and server API key come from, and which headers go on each call
- [Authentication & sessions](https://docs.agg.market/concepts/authentication.md): How users sign in, what tokens you get back, and how to keep a session alive
- [Identifiers](https://docs.agg.market/concepts/ids.md): Choose the correct identifiers for discovery, trading, charts, and durable cross-venue references.
- [Markets, outcomes & matching](https://docs.agg.market/concepts/markets.md): Events, markets, and outcomes, and the id you pass to a quote. Cross-venue ids are defined on Ids.
- [Quotes & smart routing](https://docs.agg.market/concepts/quotes.md): What a quote contains, when it can be filled, how long it lasts, and where fees and warnings show up
- [Execution](https://docs.agg.market/concepts/execution.md): The fill request body, why the response is always pending, and the checks that can still refuse a quote
- [Order lifecycle & statuses](https://docs.agg.market/concepts/order-lifecycle.md): Every order status, which ones are final, and how to track a trade to a final state
- [Market resolution & voids](https://docs.agg.market/concepts/market-resolution.md): How a market settles, how to read a split or refunded outcome, and what happens to positions and open orders
- [Fees](https://docs.agg.market/concepts/fees.md): Every fee on a trade or withdrawal, its unit, when it is charged, and where to read it
- [Funding & withdrawals](https://docs.agg.market/concepts/funding.md): Deposit addresses, balances, and withdrawals tracked to a final state, for managed accounts
- [Accounts & wallets](https://docs.agg.market/concepts/accounts-and-wallets.md): How a user's sign-in identity, managed wallet, self-custody wallets, and venue accounts relate, and which address to pass where
- [Errors, retries & idempotency](https://docs.agg.market/concepts/errors.md): Error shapes, HTTP statuses, quote and fill error codes, and which calls are safe to retry
- [Sign-in providers](https://docs.agg.market/recipes/authentication.md): SIWS, Google, X, Apple, and email SDK calls, the React auth UI, and React Native token storage.
- [Account Linking](https://docs.agg.market/recipes/account-linking.md): Link additional auth providers to an already signed-in user
- [Partner External ID Linking](https://docs.agg.market/recipes/external-id-linking.md): Link an authenticated AGG user to your app's internal user ID with an HMAC assertion
- [Avatar Upload](https://docs.agg.market/recipes/avatar-upload.md): Upload and set a user avatar with presigned S3 URLs
- [Privy Wallet Provider](https://docs.agg.market/recipes/privy-wallet-provider.md): Use your existing Privy wallets for authentication and trade execution in AGG.
- [KYC](https://docs.agg.market/recipes/kyc.md): Check shared KYC for the managed Solana wallet, then start a venue flow when a fill requires it.
- [Venue keys](https://docs.agg.market/recipes/venue-keys.md): Store the user's Kalshi API key, which every Kalshi trade uses, then read whether it is connected.
- [Direct Order Execution](https://docs.agg.market/recipes/direct-order-execution.md): Place one market order on a venue you name. externalId is required, and retrying a timeout with the same value is safe.
- [Limit Orders](https://docs.agg.market/recipes/limit-orders.md): Place, poll, and cancel one venue's limit order. Self-custody cancel signatures are on the signing page.
- [Claim winnings](https://docs.agg.market/recipes/claim-winnings.md): Find settled positions that need a claim, call POST /execution/redeem, and track the result
- [Self-Custody Trading](https://docs.agg.market/recipes/self-custody.md): Let users fund and sign trades with their own wallet instead of a managed balance
- [Self-Custody Signing Reference](https://docs.agg.market/recipes/self-custody-signing.md): Signature request types, a complete signer, how many prompts a user sees, and the raw signing loop
- [Paper Trading](https://docs.agg.market/recipes/paper-trading.md): Simulated trading against live market data, for user-facing paper portfolios, testing, and QA.
- [Managed Balance Refills](https://docs.agg.market/recipes/managed-balance-refills.md): Keep a user's managed USDC balance above a target-chain minimum after trading
- [Referrals](https://docs.agg.market/recipes/referrals.md): Who pays a referral fee, and how to sign an app-paid payout after the fill is already terminal.
- [Hosted venue accounts](https://docs.agg.market/recipes/hosted-venue-accounts.md): Provision a hosted BetDEX account, fund it with Solana USDC, and track withdrawals.
- [Onramp](https://docs.agg.market/recipes/onramp.md): Quote a fiat-to-crypto purchase and open the provider checkout for a supported wallet.
- [Builder Codes](https://docs.agg.market/recipes/builder-codes.md): Attribute the orders your app sends to a venue back to your own account
- [Venues](https://docs.agg.market/venues/overview.md): Every venue AGG lists, whether it can be traded, which account it trades from, and what it settles in.
- [Kalshi](https://docs.agg.market/venues/kalshi.md): How AGG trades Kalshi: the user's own Kalshi account and API key, cash held at Kalshi, and no on-chain step.
- [Market-data API](https://docs.agg.market/api/market-data.md): Choose bootstrap, chart history, search mode, or the book id for a market-data read.
- [Matched Clusters](https://docs.agg.market/recipes/matched-clusters.md): Where matched-cluster fields live on the event, market, and outcome.
- [aggKey](https://docs.agg.market/recipes/agg-key.md): Optional fetch filter for rows whose key converges. Which id to store is on the Ids page.
- [Settlement Key Differences](https://docs.agg.market/recipes/settlement-key-differences.md): Surface how each venue settles a matched market — resolution source, timing, and edge cases — on the event detail
- [Building Market Views](https://docs.agg.market/recipes/building-market-views.md): List events, open one with bootstrap, then markets, the orderbook socket, and a quote.
- [Comparing Venue Prices](https://docs.agg.market/recipes/comparing-venue-prices.md): Fetch matched events, walk matched markets, and read midpoints. The client batches 75 ids.
- [Building a Sports Market Detail Page](https://docs.agg.market/recipes/sports-market-detail.md): Compose the discovery, orderbook, and chart endpoints into a cross-venue game detail page
- [Hyperliquid Deployers](https://docs.agg.market/recipes/hyperliquid-deployers.md): Why one Hyperliquid market can be listed twice, how to tell the listings apart, and which book you are actually reading
- [Live Crypto Markets](https://docs.agg.market/recipes/live-crypto-markets.md): Discover recurring crypto windows, live depth, and fresh reference prices for partner apps
- [News Feed](https://docs.agg.market/recipes/news-feed.md): Integrate market-aware news feeds into partner discovery and market detail experiences
- [Correlated Markets](https://docs.agg.market/recipes/correlated-markets.md): Find markets connected to another market by generated real-world outcome signals
- [Bot Protection](https://docs.agg.market/recipes/bot-protection.md): Shield any user action with Cloudflare Turnstile challenges and multi-layer rate limiting
- [Trusted Proxy](https://docs.agg.market/recipes/partner-trusted-proxy.md): Forward end-user IPs to AGG for accurate per-user geo enforcement when proxying through your backend
- [Venue Geo Availability](https://docs.agg.market/recipes/venue-geo-availability.md): Check regional trading restrictions and quote warnings before asking a user to confirm a trade.
- [WebSocket Protocol](https://docs.agg.market/api/websocket.md): Stream live orderbooks, trades, arbitrage returns, heartbeats, and user events over WebSocket
- [Real-Time Orderbook](https://docs.agg.market/recipes/websocket-orderbook.md): Stream a live aggregated orderbook with the SDK, hooks, or UI components
- [Real-Time Charts](https://docs.agg.market/recipes/websocket-charts.md): Load immutable chart history from the manifest, then the unfinished tail from chart bars
- [Real-Time Arbitrage](https://docs.agg.market/recipes/websocket-arb.md): Stream live cross-venue arbitrage returns with the SDK and React hooks
- [User Notifications](https://docs.agg.market/recipes/websocket-notifications.md): Reconnect an authenticated WebSocket and seed balances, positions, and orders from REST
- [Webhooks](https://docs.agg.market/recipes/webhooks/overview.md): Receive real-time event notifications at your own HTTPS endpoints
- [Verifying Webhook Signatures](https://docs.agg.market/recipes/webhooks/verifying-signatures.md): Verify that webhook deliveries are authentic and untampered
- [Webhook Event Reference](https://docs.agg.market/recipes/webhooks/event-reference.md): Full payload schemas for every webhook event type
- [Partner admin](https://docs.agg.market/recipes/partner-admin.md): Read your app's users, balances, positions, orders, deposits, withdrawals, and analytics from your backend.
- [Portfolio](https://docs.agg.market/recipes/portfolio.md): Read the signed-in user's activity feed and the app leaderboard. Positions and orders are on Order lifecycle.
- [Packages](https://docs.agg.market/packages/overview.md): Four npm packages — pick the layer that fits your app
- [Components Overview](https://docs.agg.market/components/overview.md): Pre-built UI components for prediction market data
- [Customize UI](https://docs.agg.market/components/customization.md): Theme AGG UI components with CSS variables, next/font, labels, formatting, and component slots
- [Leaderboard Page](https://docs.agg.market/components/pages/leaderboard-page.md): Interactive preview for the @agg-build/ui LeaderboardPage surface
- [Changelog](https://docs.agg.market/changelog.md): What shipped across the AGG platform and the @agg-build packages.
- [SDK reference](https://docs.agg.market/sdk/reference.md): Every public @agg-build/sdk method, the HTTP operation it calls, and its API reference page
- [Start authentication](https://docs.agg.market/api-reference/authentication/start-authentication.md): Initiates an auth flow. Required fields depend on the provider:
- [Verify sign-in](https://docs.agg.market/api-reference/authentication/verify-sign-in.md): Proves identity and returns an access + refresh token pair directly. The body is a union on `kind`:
- [Complete redirect sign-in](https://docs.agg.market/api-reference/authentication/complete-redirect-sign-in.md): Exchanges a one-time auth code for an access + refresh token pair. Auth codes are returned by OAuth/magic-link callback redirects.
- [Refresh access token](https://docs.agg.market/api-reference/authentication/refresh-access-token.md): Issues a new access + refresh token pair given a valid refresh token.
- [Sign out](https://docs.agg.market/api-reference/authentication/sign-out.md): Revokes all tokens for the user and invalidates existing sessions.
- [Fetch Turnstile site key](https://docs.agg.market/api-reference/authentication/fetch-turnstile-site-key.md): Returns the Cloudflare Turnstile site key registered for the app so clients can render the Turnstile widget anywhere in their UI. `siteKey` is `null` when no widget is linked to the app.
- [Verify Turnstile token](https://docs.agg.market/api-reference/authentication/verify-turnstile-token.md): Verifies a Cloudflare Turnstile token against the app's linked widget. Intended to be called from **your backend**, not the browser — API keys are secrets and must never ship to the client. Both `x-app-id` and `x-app-api-key` are required; the server rejects the request with `401` if `x-app-id` does…
- [Get the first useful event view](https://docs.agg.market/api-reference/markets/get-the-first-useful-event-view.md): Event display data and the first bounded market slice share one cluster resolution. Further market pages, histories and personalized execution load independently.
- [Search events or markets](https://docs.agg.market/api-reference/markets/search-events-or-markets.md): Hybrid search (trigram + FTS + vector) across events or markets. Returns results ranked by relevance. Use listing endpoints for filtered discovery. The embedded `venueMarkets` on each event result are a top-N preview only; for the full market list use GET /venue-markets?venueEventId=.
- [List venue events](https://docs.agg.market/api-reference/markets/list-venue-events.md): Returns paginated venue events with optional filters for venue, status, category, and search. DEPRECATION: the per-item `description` field is deprecated and will be removed from list responses — fetch the full event (including `description`) via GET /venue-events/:id. The embedded `venueMarkets` on…
- [Get Venue Event](https://docs.agg.market/api-reference/markets/get-venue-event.md): Returns a single venue event. The response may include an embedded `venueMarkets` array. That array is deprecated — fetch the event's markets from GET /venue-markets?venueEventId=.  `marketCount` and the rolled-up `volume` cover the event's whole matched cluster by default. `marketCount` is the numb…
- [List venue markets](https://docs.agg.market/api-reference/markets/list-venue-markets.md): Returns paginated venue markets with optional filters for venue, status, category, and date range. When `venueEventId` is set, the response covers that event's ENTIRE matched cluster by default — every venue's markets for the same real-world event, with matched siblings folded into their anchor row…
- [Look up venue market outcomes by external identifier](https://docs.agg.market/api-reference/markets/look-up-venue-market-outcomes-by-external-identifier.md): Resolves venue-side outcome keys (e.g. Polymarket token_id) to AGG outcomes, including `matchedVenueMarketOutcomes` counterpart references across venues. The referenced markets are returned alongside `data` as `matchedVenueMarkets[]` — the same shape /venue-markets nests on each market — so a trade…
- [List categories](https://docs.agg.market/api-reference/markets/list-categories.md): Returns categories filtered by parentId. Omit parentId for top-level categories.
- [Get the per-app UI config (disabled venues + categories)](https://docs.agg.market/api-reference/markets/get-the-per-app-ui-config-disabled-venues-+-categories.md): Returns the signed-in app's public UI config: venues and category presets the app has turned off, whether early access is on, the enabled auth providers, and the app's trading mode. Authenticate with x-app-id. This does not include secrets.
- [List recurring crypto window markets](https://docs.agg.market/api-reference/markets/list-recurring-crypto-window-markets.md): Returns deterministic crypto window markets grouped by asset, window duration, and derived window start across supported venues. Scope is limited to 5 minute, 15 minute, 1 hour, and 1 day recurring crypto markets.
- [Get bounded outcome snapshots](https://docs.agg.market/api-reference/market-data/get-bounded-outcome-snapshots.md): Returns up to 100 outcome snapshots in request order. Missing or inaccessible outcomes are null. Engine failures return 503, not empty success.
- [Get live orderbooks for multiple markets](https://docs.agg.market/api-reference/market-data/get-live-orderbooks-for-multiple-markets.md): Returns live per-venue orderbooks for the explicit venueMarketIds requested. `venueMarketIds` accepts either a comma-separated string (`?venueMarketIds=a,b,c`) or repeated params (`?venueMarketIds=a&venueMarketIds=b`). Use /orderbooks/outcomes for batches keyed by venue market outcome IDs.
- [Get live orderbook for a single outcome](https://docs.agg.market/api-reference/market-data/get-live-orderbook-for-a-single-outcome.md): Returns the live single-venue orderbook for a specific venue market outcome, including the sticky tick and midpoint provenance (`markSource`).
- [Get live midpoints for multiple markets](https://docs.agg.market/api-reference/market-data/get-live-midpoints-for-multiple-markets.md): Returns live orderbook midpoints for the requested venue market IDs. `venueMarketIds` accepts either a comma-separated string (`?venueMarketIds=a,b,c`) or repeated params (`?venueMarketIds=a&venueMarketIds=b`). Midpoint represents the Yes-side price (0-1). Direct GET callers should keep batches smal…
- [Get versioned chart history references](https://docs.agg.market/api-reference/market-data/get-versioned-chart-history-references.md): Returns at most eight authorized CDN chunks, effective resolution, finalization boundary and delivery state. Fetch the unfinished tail with /charts/bars.
- [Get chart bars](https://docs.agg.market/api-reference/market-data/get-chart-bars.md): Returns OHLCV bars for a single venue market.
- [Get live crypto reference prices](https://docs.agg.market/api-reference/market-data/get-live-crypto-reference-prices.md): Returns fresh reference prices for recurring crypto market targets. Responses are never older than 1 second; concurrent requests are deduplicated across API instances.
- [Get live sports scores](https://docs.agg.market/api-reference/market-data/get-live-sports-scores.md): Returns normalized live score state for supported sports events. Event IDs are resolved through AGG's matched-event relationship to the Polymarket event used by the score provider. Unmatched, unsupported, and provider-unavailable events are listed in missingEventIds.
- [Get a quote (smart route)](https://docs.agg.market/api-reference/trading/get-a-quote-smart-route.md): Computes a fill quote across available venues for a specific venue market outcome and returns the suggested fills. When a user JWT is supplied the quote is scoped to the user's wallet balances and may be executed; without a JWT the response is a preview-only quote. ProphetX prices are computed from…
- [Execute quote](https://docs.agg.market/api-reference/trading/execute-quote.md): Accepts a previously quoted smart-route quote and returns pending order IDs for the submitted fill execution.
- [Submit signatures for a pending self-custody fill](https://docs.agg.market/api-reference/trading/submit-signatures-for-a-pending-self-custody-fill.md): Accepts client-produced signatures for a self-custodial fill. POST /execution/fill never returns the payloads to sign directly — signature requests are produced asynchronously, after the fill response is sent. Poll GET /execution/status for `pendingSignatures` instead, sign each payload, then submit…
- [Get execution status](https://docs.agg.market/api-reference/trading/get-execution-status.md): Returns quote-scoped execution progress, execution-plan step state, and terminal order leg results.
- [Place an order directly](https://docs.agg.market/api-reference/trading/place-an-order-directly.md): Places a market order on a single named venue without a prior quote. The route is priced and funded server-side and always produces exactly one order. `externalId` is required and unique within your app — two different users of the same app cannot share one — so retrying a timed-out request with the…
- [Place limit order](https://docs.agg.market/api-reference/trading/place-limit-order.md): Places a venue-specific limit order. Managed orders reserve funds or shares. Self-custody buys can fund across supported chains using the existing client-signature flow; poll quoteId until the order is open or terminal. Fills are reconciled asynchronously.
- [Cancel an order](https://docs.agg.market/api-reference/trading/cancel-an-order.md): Send `orderId` to cancel an agg order. Send `venue`, `venueOrderId`, `signerAddress` and `cancelSignature` to cancel a Polymarket or Hyperliquid limit order that one of your linked self-custody wallets placed outside AGG. `signerAddress` must be a wallet linked to this user and must be the wallet th…
- [Redeem winnings for resolved positions](https://docs.agg.market/api-reference/trading/redeem-winnings-for-resolved-positions.md): Claims a user's settled positions as USDC: winning shares, and split payouts such as a Polymarket 50/50. EVM venue redemptions need no user wallet prompt and complete asynchronously; listen for redeem_event on the WebSocket. Venues that settle on their own need no redeem call, and their positions re…
- [Get the per-venue blocked-country lists (ISO 3166-1 alpha-2)](https://docs.agg.market/api-reference/trading/get-the-per-venue-blocked-country-lists-iso-3166-1-alpha-2.md): Returns each venue's trading country policy. blockedCountries is where the venue cannot be traded. When allowedCountries is present the venue can be traded only from those countries, and an empty blockedCountries list is not 'unrestricted'. Authenticate with x-app-id. Quote and fill responses also c…
- [Get user orders](https://docs.agg.market/api-reference/portfolio/get-user-orders.md): Returns paginated orders for the authenticated user with venue market details. Filter with `status`, `orderType`, `orderId`, `quoteId`, `externalId` and `venueMarketIds` (comma-separated or repeated).
- [Get balances](https://docs.agg.market/api-reference/portfolio/get-balances.md): Returns per-chain token balances and per-venue position balances for the authenticated user. Pass `custody=self` for the wallets linked to this account (and their Polymarket deposit and legacy wallets) instead of the managed server wallet; each chain row then carries `address` and `custodyKind`. Pos…
- [Get user positions](https://docs.agg.market/api-reference/portfolio/get-user-positions.md): Returns open positions grouped by matched market with per-venue breakdown and current pricing.
- [Get user activity feed](https://docs.agg.market/api-reference/portfolio/get-user-activity-feed.md): Returns a unified, timestamp-ordered feed of the authenticated user's trades, withdrawals, standalone bridges, deposits, and low-level wallet operations. Cursor-based pagination.
- [Trader leaderboard](https://docs.agg.market/api-reference/portfolio/trader-leaderboard.md): Users of this app ranked by realizedPnl (default) or volume over an inclusive UTC day range; omit from/to for all time. rank is exact within the top 100 and null beyond. Identity fields follow the app's leaderboardIdentity setting. Pass exactly one of userId, externalId, username or walletAddress to…
- [Trader leaderboard series](https://docs.agg.market/api-reference/portfolio/trader-leaderboard-series.md): Leaderboard stats per UTC day — orders, volume, spent, realizedPnl, wins, losses and winRate, plus running cumulativeRealizedPnl and cumulativeWinRate and range totals — oldest first, ready to chart in one call. Pass at most one of userId, externalId, username or walletAddress (username and walletAd…
- [Get deposit addresses](https://docs.agg.market/api-reference/funding/get-deposit-addresses.md): Returns the user's deposit addresses (EVM + Solana) and supported chains/tokens. Returns 202 while addresses are being prepared -- poll until 200. Returns 409 when the user's Privy wallet does not grant Agg's authorization key signing rights; the message says how to fix the wallet's signers.
- [Quote withdrawable amount](https://docs.agg.market/api-reference/funding/quote-withdrawable-amount.md): Returns the maximum deliverable amount for a token and destination chain without creating a withdrawal.
- [Preview a withdrawal](https://docs.agg.market/api-reference/funding/preview-a-withdrawal.md): Returns real fee + receive estimates for a withdrawal without creating one. Optional — /execution/withdraw does not require a prior preview.
- [Withdraw funds](https://docs.agg.market/api-reference/funding/withdraw-funds.md): Withdraws funds through the normal transfer/bridge planner. An optional requestId UUID makes exact-amount requests replayable: the same owner/key and parameters return the original lifecycle without dispatching twice; changed parameters return 409. Do not combine requestId with max. Continue polling…
- [Get withdrawal status](https://docs.agg.market/api-reference/funding/get-withdrawal-status.md): Returns the current persisted state of a withdrawal — used as a fallback when the WS lifecycle channel has missed events.
- [List managed balance refill policies](https://docs.agg.market/api-reference/funding/list-managed-balance-refill-policies.md): Lists the signed-in user's managed balance refill policies. Authenticate with x-app-id and a user JWT. Amounts are 6-decimal USD integer strings. Policy status is enabled or paused.
- [Create a managed balance refill policy](https://docs.agg.market/api-reference/funding/create-a-managed-balance-refill-policy.md): Creates one refill policy for the signed-in user. Required: targetChainId, minimumRaw, and refillAmountRaw (6-decimal USD integer strings). Optional: targetTokenSymbol (USDC), dailyCapRaw, and maxFeeRaw. Authenticate with x-app-id and a user JWT.
- [Update or pause a managed balance refill policy](https://docs.agg.market/api-reference/funding/update-or-pause-a-managed-balance-refill-policy.md): Updates one policy's thresholds or sets status to enabled or paused. Authenticate with x-app-id and a user JWT. Amounts are 6-decimal USD integer strings.
- [List recent managed balance refill attempts](https://docs.agg.market/api-reference/funding/list-recent-managed-balance-refill-attempts.md): Lists recent attempts for one policy. Attempt status is reserved, executing, completed, or failed. Authenticate with x-app-id and a user JWT.
- [Get crypto purchase quotes](https://docs.agg.market/api-reference/funding/get-crypto-purchase-quotes.md): Quotes a fiat-to-crypto purchase. Send sourceAmount as a decimal string in sourceCurrencyCode units, destinationCurrencyCode, and an optional paymentMethodType. Authenticate with x-app-id only. This is not a deposit address and does not take a user JWT.
- [Create a ramp widget session for checkout](https://docs.agg.market/api-reference/funding/create-a-ramp-widget-session-for-checkout.md): Opens a checkout widget. Send the quote amount and currencies plus serviceProvider and walletAddress, and an optional redirectUrl. The response includes id, token, and widgetUrl. Authenticate with x-app-id only. This is not GET /execution/deposit-addresses.
- [Get current user](https://docs.agg.market/api-reference/users/get-current-user.md): Returns the authenticated user's profile.
- [Update username](https://docs.agg.market/api-reference/users/update-username.md): Updates the current user's username. Must be 3-30 characters. Letters, numbers, and `_ - .` allowed; must start and end with a letter or number. Returns 409 if the username is already taken.
- [Link partner external user ID (HMAC-verified)](https://docs.agg.market/api-reference/users/link-partner-external-user-id-hmac-verified.md): Verifies a partner-signed external user ID assertion and stores the linked external ID on the current user.
- [Get avatar upload URL](https://docs.agg.market/api-reference/users/get-avatar-upload-url.md): Returns a presigned S3 URL for the user to upload their avatar. Allowed types: JPEG, PNG, GIF, WebP. Max size: 5 MB. After upload, the image is automatically processed to WebP and served via CDN.
- [Disconnect auth provider](https://docs.agg.market/api-reference/users/disconnect-auth-provider.md): Removes a linked auth provider from the current user's identity. Cannot disconnect the last remaining provider (would lock the user out). When several accounts share a provider — the normal case for linked wallets — pass `?providerAccountId=` to name the one to remove; omitting it is a 400 rather th…
- [Start account linking](https://docs.agg.market/api-reference/users/start-account-linking.md): Initiates an account-link flow. Authenticated-only. For OAuth providers returns a provider redirect URL and sets an HttpOnly proof cookie that is required at callback time. The same-browser guarantee plus a mode discriminator on the state JWT prevents a phished link URL from attaching a victim's ide…
- [Confirm account linking](https://docs.agg.market/api-reference/users/confirm-account-linking.md): Finalizes an account link. Body is a union on `kind`: the `token` branch (default when `kind` is omitted, for backward compatibility with existing OAuth/email callers) exchanges the short-lived `link_confirm_token` (handed to the partner app by the link callback redirect) for an actual Account row a…
- [Get shared KYC status](https://docs.agg.market/api-reference/users/get-shared-kyc-status.md): Checks the clearinghouse verification record for the authenticated user's managed Solana wallet. Shared by Novig and ProphetX; Kalshi v2 does not require KYC.
- [Initiate KYC](https://docs.agg.market/api-reference/users/initiate-kyc.md): Starts shared clearinghouse KYC for Novig or ProphetX. Already-verified wallets return verified without a new session or signature. Kalshi v2 returns not_applicable. The backend callback redirects to redirectUri after checking authoritative status.
- [Upsert a venue API key](https://docs.agg.market/api-reference/users/upsert-a-venue-api-key.md): Stores (or replaces) the authenticated user's encrypted venue credentials.
- [List venue keys](https://docs.agg.market/api-reference/users/list-venue-keys.md): Lists the authenticated user's stored venue key summaries, optionally filtered to specific venues.
- [Delete a venue key](https://docs.agg.market/api-reference/users/delete-a-venue-key.md): Deletes the authenticated user's stored key for a venue.
- [Get venue key connection status](https://docs.agg.market/api-reference/users/get-venue-key-connection-status.md): Returns whether the authenticated user has a validated, connected key for a venue.
- [Get hosted venue deposit address](https://docs.agg.market/api-reference/hosted-venue-accounts/get-hosted-venue-deposit-address.md): Returns the authenticated user's provider-verified Solana USDC deposit address. It never returns the provider wallet ID or credentials. The capability is independently gated from trading and may be unavailable even when orders are enabled.
- [Withdraw hosted venue funds](https://docs.agg.market/api-reference/hosted-venue-accounts/withdraw-hosted-venue-funds.md): Submits one explicit-amount Solana USDC withdrawal under a caller-owned idempotency key. Agg durably records the exact request before dispatch. An ambiguous provider result is retained for manual review and is never automatically replayed.
- [Get hosted venue withdrawal](https://docs.agg.market/api-reference/hosted-venue-accounts/get-hosted-venue-withdrawal.md): Returns Agg's persisted state for one owned hosted withdrawal. This read never submits or retries a provider request and does not infer finality from an uncorrelated balance or ledger entry.
- [Get hosted venue account activity](https://docs.agg.market/api-reference/hosted-venue-accounts/get-hosted-venue-account-activity.md): Returns one owned USDC ledger page with signed exact 18-decimal amounts and native activity codes. This is observed account activity, not order-fill accounting, a spendable balance, or proof that a particular withdrawal completed. No wallet is created and no funds move. Sandbox entries are simulated…
- [Get hosted venue account](https://docs.agg.market/api-reference/hosted-venue-accounts/get-hosted-venue-account.md): Returns the current user's hosted venue status and balance. Does not create a wallet. Provider identities and credentials are never returned.
- [Provision hosted venue account](https://docs.agg.market/api-reference/hosted-venue-accounts/provision-hosted-venue-account.md): Explicitly requests a hosted account for live execution mode. Reuses the user's durable provisioning intent; a pending response never authorizes duplicate upstream creation. No private key is requested.
- [Get news articles for markets with market impact summaries](https://docs.agg.market/api-reference/news/get-news-articles-for-markets-with-market-impact-summaries.md): Returns articles for up to 10 venueMarketIds or venueEventIds, or for customQuery. Optional tbs time bound and limit (1 to 5). Authenticate with x-app-id only. Start here when you already know the market.
- [Article-centric news feed for a category - latest articles with linked markets and live prices](https://docs.agg.market/api-reference/news/article-centric-news-feed-for-a-category--latest-articles-with-linked-markets-and-live-prices.md): Pages articles for one category id from GET /news-feed. Query cursor, since, before, and limit (1 to 50). Authenticate with x-app-id only.
- [Market-centric news feed - markets grouped with their news timeline](https://docs.agg.market/api-reference/news/market-centric-news-feed--markets-grouped-with-their-news-timeline.md): Pages markets in one category, each with its article timeline. Query cursor, since, before, and limit (1 to 50). Authenticate with x-app-id only. category is a feed id from GET /news-feed.
- [List available news feeds with IDs and item counts](https://docs.agg.market/api-reference/news/list-available-news-feeds-with-ids-and-item-counts.md): Lists feed ids, names, and item counts. Use a feed id as the category path parameter on the article and market feeds. Authenticate with x-app-id only.
- [Get correlated market signals for a market](https://docs.agg.market/api-reference/correlated-markets/get-correlated-market-signals-for-a-market.md): Returns the generated Yes/No signals for a market: the real-world outcomes that become more or less likely if this market resolves.
- [Find correlated markets by semantic similarity](https://docs.agg.market/api-reference/correlated-markets/find-correlated-markets-by-semantic-similarity.md): Finds markets related to a plain-language query by matching it against each market's generated signals.
- [Find events connected via shared market signals](https://docs.agg.market/api-reference/correlated-markets/find-events-connected-via-shared-market-signals.md): Returns events connected to a source market because they share generated market signals.
- [Get ripple effect of a market resolving (by market ID)](https://docs.agg.market/api-reference/correlated-markets/get-ripple-effect-of-a-market-resolving-by-market-id.md): Returns markets that move with this one if it resolves (`mode=expand`) or offset it (`mode=hedge`). Takes an AGG `venueMarketId`; use the resolve endpoint when you only have a venue id, slug or text.
- [Resolve a market by venue ID, slug, or text and return cascade](https://docs.agg.market/api-reference/correlated-markets/resolve-a-market-by-venue-id-slug-or-text-and-return-cascade.md): Finds a market from whatever identifier you have (venue + externalId, slug, conditionId, or free text) and returns its correlated-market candidates. Returns 202 while the candidates are still being generated; retry shortly.
- [Rotate webhook signing secret](https://docs.agg.market/api-reference/webhooks/rotate-webhook-signing-secret.md): Issues a new signing secret for this endpoint. The secret is returned once and cannot be read back later. Authenticate with x-app-api-key only. Send an empty JSON body.
- [Replay failed deliveries](https://docs.agg.market/api-reference/webhooks/replay-failed-deliveries.md): Re-queues failed deliveries for this endpoint. Authenticate with x-app-api-key only. Send an empty JSON body. The response is { success }.
- [List users](https://docs.agg.market/api-reference/partner-admin/list-users.md): Lists users of this app. Filter with search and paginate with limit (1 to 100) and cursor. Authenticate with an app-scoped x-app-api-key.
- [Get user](https://docs.agg.market/api-reference/partner-admin/get-user.md): Returns the profile of one user in this app. Authenticate with an app-scoped x-app-api-key.
- [Get user balances](https://docs.agg.market/api-reference/partner-admin/get-user-balances.md): Reads one user's balances. Authenticate with x-app-api-key only. A read key can read any user of your app.
- [Get user positions](https://docs.agg.market/api-reference/partner-admin/get-user-positions.md): Open and closed positions for one user of your app. Filter with `venueEventId`, `venueMarketId` and `status`. Positions are reported per venue leg and marked at the user's average entry price — this endpoint does not consult an orderbook, so it returns no live mark or unrealized PnL. Authenticate wi…
- [Get user orders](https://docs.agg.market/api-reference/partner-admin/get-user-orders.md): Order history for one user of your app, newest first. Filter with `status`, `orderId`, `quoteId` and `venueMarketIds` (comma-separated or repeated); legs of one multi-venue trade share a `quoteId`. Authenticate with an `x-app-api-key` of either scope: a `read` key can read any user of your app, so t…
- [List orders across your app](https://docs.agg.market/api-reference/partner-admin/list-orders-across-your-app.md): Every order placed by any user of your app, as a changes feed: ordered by last update, oldest first. Page until `hasMore` is false, then store `nextCursor` and pass it as `cursor` on your next run to receive only orders created or changed since. `nextCursor` is returned on every response, including…
- [Get user deposits](https://docs.agg.market/api-reference/partner-admin/get-user-deposits.md): Reads one user's deposits. amountRaw is an integer string in the token's decimals. Page with limit and cursor. Authenticate with x-app-api-key only.
- [Get user withdrawals](https://docs.agg.market/api-reference/partner-admin/get-user-withdrawals.md): Reads one user's withdrawals. amountRaw is an integer string in the token's decimals. Page with limit and cursor. Authenticate with x-app-api-key only.
- [Get analytics](https://docs.agg.market/api-reference/partner-admin/get-analytics.md): Returns user and order totals, current cash and position values, and cumulative fees for this app. usersLast7Days, usersLast30Days, ordersLast7Days, and ordersLast30Days cover the named rolling windows. Authenticate with an app-scoped x-app-api-key.
- [List users affected by market resolution](https://docs.agg.market/api-reference/partner-admin/list-users-affected-by-market-resolution.md): Lists users of this app who hold the venue market. Set includeEmails=true to include email. Paginate with limit and cursor. Authenticate with an app-scoped x-app-api-key.
- [Create a paper trading account](https://docs.agg.market/api-reference/paper-trading/create-a-paper-trading-account.md): Creates a simulated account for this app. Authenticate with x-app-api-key only. This is the admin path. Users paper-trade by sending mode=paper on the quote and the fill, not on this route. Optional name, externalId, and a starting balance as initialBalanceRaw (integer string) or initialBalance (dis…
- [List paper trading accounts](https://docs.agg.market/api-reference/paper-trading/list-paper-trading-accounts.md): Lists this app's paper accounts. Authenticate with x-app-api-key only. Filter with externalId. Page with limit and cursor.
- [Get a paper trading account](https://docs.agg.market/api-reference/paper-trading/get-a-paper-trading-account.md): Returns one paper account. Authenticate with x-app-api-key only.
- [Set a paper trading account cash balance](https://docs.agg.market/api-reference/paper-trading/set-a-paper-trading-account-cash-balance.md): Sets the account's cash balance. Send balanceRaw (integer string) or balance (display number), and an optional reason. Authenticate with x-app-api-key only.
- [Reset a paper trading account](https://docs.agg.market/api-reference/paper-trading/reset-a-paper-trading-account.md): Resets the account and sets a new cash balance. Send balanceRaw (integer string) or balance (display number), and an optional reason. Authenticate with x-app-api-key only.
- [Place a paper trading order](https://docs.agg.market/api-reference/paper-trading/place-a-paper-trading-order.md): Places a simulated order on venueMarketOutcomeId. Buy with spendRaw or spend; sell with shares. clientOrderId is stored for traceability and is not an idempotency key. Authenticate with x-app-api-key only. This is not POST /execution/orders.
- [List paper trading orders](https://docs.agg.market/api-reference/paper-trading/list-paper-trading-orders.md): Lists paper orders for the account. Authenticate with x-app-api-key only. Page with limit and cursor. clientOrderId is stored for traceability and is not an idempotency key.
- [List paper trading positions](https://docs.agg.market/api-reference/paper-trading/list-paper-trading-positions.md): Lists paper positions for the account. Authenticate with x-app-api-key only. Page with limit and cursor. Once a market has settled, use winner rather than markPrice.
- [Get a paper trading portfolio](https://docs.agg.market/api-reference/paper-trading/get-a-paper-trading-portfolio.md): Returns cash, equity, and positions for one paper account. Authenticate with x-app-api-key only.
- [Orderbook](https://docs.agg.market/api-reference/websockets/orderbook.md): Subscribe to aggregated orderbook updates for canonical markets. Receive an initial snapshot, then incremental deltas with sequencing and checksums. Client maintains a local book by applying deltas. Request a resnapshot if your local state drifts.
- [Trades](https://docs.agg.market/api-reference/websockets/trades.md): Subscribe to public trade feed for outcomes. No user auth required. Uses { action: "subscribe", channel: "trades", outcomeIds } message format. Shares the 500-subscription limit with orderbook subscriptions.
- [Auth](https://docs.agg.market/api-reference/websockets/auth.md): Authenticate mid-session to receive user-specific events. Send your JWT token (same as REST API) to upgrade from app-level to user-level auth. Supports re-authentication for token refresh or user switch.
- [User events](https://docs.agg.market/api-reference/websockets/userevents.md): User-specific events (requires user-level auth via authenticate action or token query param). Streams order confirmations, balance updates, and a venue-agnostic order lifecycle event (`order_event`) covering execution-plan steps and terminal fill / failure status across all venues.
- [Arb](https://docs.agg.market/api-reference/websockets/arb.md): Subscribe to per-market arb-return updates. Send `{ action: "subscribe", channel: "arb", marketIds: string[] }`. The server echos subscribed marketIds in the `subscribed` reply. No initial snapshot — updates arrive as `arb_market_update` messages when the engine detects a change.
- [Arb-feed](https://docs.agg.market/api-reference/websockets/arb-feed.md): Subscribe to the full arb-return broadcast feed. Send `{ action: "subscribe", channel: "arb-feed" }` (no ids required). Receives batched `arb_feed_batch` messages for all markets whenever the engine publishes arb updates.

## OpenAPI Specs

- [openapi](/openapi/openapi.json)

## AsyncAPI Specs

- [asyncapi](/openapi/asyncapi.json)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.