# Agg.market — Prediction Market Aggregator

> Agg.market - white-label prediction market aggregation

## Documentation

- [Introduction](https://agg.jamdesk.app/introduction.md): AGG unifies prediction market liquidity, funding, routing, and market data into one integration
- [Setup Guide](https://agg.jamdesk.app/api/setup.md): Wire up AGG for your app — client setup, provider stack, auth, and WebSocket
- [Packages](https://agg.jamdesk.app/packages/overview.md): Four npm packages — pick the layer that fits your app
- [Components Overview](https://agg.jamdesk.app/components/overview.md): Pre-built UI components for prediction market data
- [Customize UI](https://agg.jamdesk.app/components/customization.md): Theme AGG UI components with CSS variables, next/font, labels, formatting, and component slots
- [Connect Button](https://agg.jamdesk.app/components/auth/connect-button.md): Interactive preview for the @agg-build/auth ConnectButton surface
- [Event List](https://agg.jamdesk.app/components/events/event-list.md): Interactive preview for the @agg-build/ui EventList surface
- [Market Details](https://agg.jamdesk.app/components/events/market-details.md): Interactive preview for AGG market detail surfaces
- [Place Order](https://agg.jamdesk.app/components/trading/place-order.md): Interactive previews for the @agg-build/ui PlaceOrder trading surface
- [Settlement](https://agg.jamdesk.app/components/trading/settlement.md): Interactive preview for the @agg-build/ui Settlement surface
- [Home Page](https://agg.jamdesk.app/components/pages/home-page.md): Interactive preview for the @agg-build/ui HomePage surface
- [Event Market Page](https://agg.jamdesk.app/components/pages/event-market-page.md): Interactive preview for the @agg-build/ui EventMarketPage surface
- [API Overview](https://agg.jamdesk.app/api/overview.md): AGG REST API — authentication, users, markets, orderbooks, charts, and execution
- [WebSocket Protocol](https://agg.jamdesk.app/api/websocket.md): Stream live orderbooks, trades, arbitrage returns, heartbeats, and user events over WebSocket
- [Authentication](https://agg.jamdesk.app/recipes/authentication.md): Sign users in with SIWE, SIWS (Solana), Google, Twitter, Apple, or Email magic link
- [Token Refresh](https://agg.jamdesk.app/recipes/token-refresh.md): Renew user sessions with refreshAccessToken()
- [Account Linking](https://agg.jamdesk.app/recipes/account-linking.md): Link additional auth providers to an already signed-in user
- [Bot Protection](https://agg.jamdesk.app/recipes/bot-protection.md): Shield any user action with Cloudflare Turnstile challenges and multi-layer rate limiting
- [Server API Keys](https://agg.jamdesk.app/recipes/server-api-keys.md): Authenticate server-to-server calls with x-app-api-key and optionally lock your app to key-only access
- [Trusted Proxy](https://agg.jamdesk.app/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://agg.jamdesk.app/recipes/venue-geo-availability.md): Which venues a user can fill on from their country, and how to detect it before you take their money
- [Partner External ID Linking](https://agg.jamdesk.app/recipes/external-id-linking.md): Link an authenticated AGG user to your app's internal user ID with an HMAC assertion
- [Avatar Upload](https://agg.jamdesk.app/recipes/avatar-upload.md): Upload and set a user avatar with presigned S3 URLs
- [Managed Balance Refills](https://agg.jamdesk.app/recipes/managed-balance-refills.md): Keep a user's managed USDC balance above a target-chain minimum after trading
- [Paper Trading](https://agg.jamdesk.app/recipes/paper-trading-dev-mode.md): Offer simulated trading with live market data for staging, QA, or user-facing paper portfolios
- [Manage Paper Trading Accounts](https://agg.jamdesk.app/recipes/paper-trading-accounts.md): Create, seed, reset, trade, and inspect paper accounts from your backend
- [Funding & Withdrawals](https://agg.jamdesk.app/recipes/deposits.md): Use the Execution API for deposit addresses, balances, sync, and withdrawals
- [Limit Orders](https://agg.jamdesk.app/recipes/limit-orders.md): Place, monitor, and cancel venue-specific limit orders through the Execution API
- [Builder Codes](https://agg.jamdesk.app/recipes/builder-codes.md): Attribute the orders your app sends to a venue back to your own account
- [Webhooks](https://agg.jamdesk.app/recipes/webhooks/overview.md): Receive real-time event notifications at your own HTTPS endpoints
- [Managing Webhook Endpoints](https://agg.jamdesk.app/recipes/webhooks/managing-endpoints.md): Create and manage webhook endpoints from the admin dashboard
- [Verifying Webhook Signatures](https://agg.jamdesk.app/recipes/webhooks/verifying-signatures.md): Verify that webhook deliveries are authentic and untampered, in any framework
- [Webhook Event Reference](https://agg.jamdesk.app/recipes/webhooks/event-reference.md): Full payload schemas for every webhook event type
- [Matched Clusters](https://agg.jamdesk.app/recipes/matched-clusters.md): How AGG links the same event across venues, and which id to use as your cross-venue join key
- [Look up markets by venue identifier](https://agg.jamdesk.app/recipes/external-identifier-lookup.md): Resolve a Kalshi ticker or Polymarket token_id to the full cross-venue cluster.
- [Building Market Views](https://agg.jamdesk.app/recipes/building-market-views.md): How to use venue-events, venue-markets, and orderbook endpoints together to build prediction market UIs
- [Comparing Venue Prices](https://agg.jamdesk.app/recipes/comparing-venue-prices.md): Fetch matched events, walk every matched market, and pull midpoints in one batch with the SDK
- [Canonical Market Key (aggKey)](https://agg.jamdesk.app/recipes/agg-key.md): Fetch every venue's row for the same contract with one deterministic key
- [Building a Sports Market Detail Page](https://agg.jamdesk.app/recipes/sports-market-detail.md): Compose the discovery, orderbook, and chart endpoints into a cross-venue game detail page
- [Settlement Key Differences](https://agg.jamdesk.app/recipes/settlement-key-differences.md): Surface how each venue settles a matched market — resolution source, timing, and edge cases — on the event detail
- [Live Crypto Markets](https://agg.jamdesk.app/recipes/live-crypto-markets.md): Discover recurring crypto windows and poll fresh reference prices for partner apps
- [News Feed](https://agg.jamdesk.app/api/discovery/news-feed.md): Integrate market-aware news feeds into partner discovery and market detail experiences
- [Correlated Markets](https://agg.jamdesk.app/api/discovery/correlated-markets.md): Public Discovery API for finding markets connected by generated real-world outcome signals
- [Correlated Markets SDK recipe](https://agg.jamdesk.app/recipes/correlated-markets.md): End-to-end SDK walkthrough for resolving markets and rendering related events with @agg-build/sdk
- [Real-Time Orderbook](https://agg.jamdesk.app/recipes/websocket-orderbook.md): Stream a live aggregated orderbook with the SDK, hooks, or UI components
- [Real-Time Charts](https://agg.jamdesk.app/recipes/websocket-charts.md): Bootstrap TradingView-style bars by outcome id and keep the view live
- [Real-Time Arbitrage](https://agg.jamdesk.app/recipes/websocket-arb.md): Stream live cross-venue arbitrage returns with the SDK and React hooks
- [User Notifications](https://agg.jamdesk.app/recipes/websocket-notifications.md): Receive authenticated order and balance events over WebSocket
- [Changelog](https://agg.jamdesk.app/changelog.md): What shipped across the AGG platform and the @agg-build packages.

## API Reference

- [Verify SIWE/SIWS signature](https://agg.jamdesk.app/api-reference/authentication/verify-siwe-siws-signature.md): Verifies a signed SIWE/SIWS message and returns an access + refresh token pair directly.
- [Start authentication](https://agg.jamdesk.app/api-reference/authentication/start-authentication.md): Initiates an auth flow. Required fields depend on the provider: google — send redirectUrl, returns a redirect (OAuth URL) twitter — send redirectUrl, returns a…
- [Exchange auth code for tokens](https://agg.jamdesk.app/api-reference/authentication/exchange-auth-code-for-tokens.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://agg.jamdesk.app/api-reference/authentication/refresh-access-token.md): Issues a new access + refresh token pair given a valid refresh token.
- [Sign out](https://agg.jamdesk.app/api-reference/authentication/sign-out.md): Revokes all tokens for the user by bumping their tokenVersion.
- [Fetch Turnstile site key](https://agg.jamdesk.app/api-reference/bot-protection/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.
- [Verify Turnstile token](https://agg.jamdesk.app/api-reference/bot-protection/verify-turnstile-token.md): Verifies a Cloudflare Turnstile token against the app's linked widget.
- [Get current user](https://agg.jamdesk.app/api-reference/users/get-current-user.md): Returns the authenticated user's profile.
- [Update username](https://agg.jamdesk.app/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.
- [Link partner external user ID (HMAC-verified)](https://agg.jamdesk.app/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://agg.jamdesk.app/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.
- [Disconnect auth provider](https://agg.jamdesk.app/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).
- [Start account linking](https://agg.jamdesk.app/api-reference/users/start-account-linking.md): Initiates an account-link flow. Authenticated-only.
- [Confirm account linking](https://agg.jamdesk.app/api-reference/users/confirm-account-linking.md): Exchanges the short-lived linkconfirmtoken (handed to the partner app by the link callback redirect) for an actual Account row attached to the current user's…
- [Get balances](https://agg.jamdesk.app/api-reference/users/get-balances.md): Returns per-chain token balances and per-venue position balances for the authenticated user.
- [Get user positions](https://agg.jamdesk.app/api-reference/users/get-user-positions.md): Returns open positions grouped by matched market with per-venue breakdown and current pricing.
- [Get user orders](https://agg.jamdesk.app/api-reference/users/get-user-orders.md): Returns paginated orders for the authenticated user with venue market details.
- [Get user activity feed](https://agg.jamdesk.app/api-reference/users/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.
- [Get deposit addresses](https://agg.jamdesk.app/api-reference/users/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.
- [Initiate KYC](https://agg.jamdesk.app/api-reference/users/initiate-kyc.md): Starts the KYC process for a venue. Returns a KYC URL to redirect the user to. After completion, the user is redirected back to the provided redirectUri.
- [Get execution status](https://agg.jamdesk.app/api-reference/execution/get-execution-status.md): Returns quote-scoped execution progress, DAG step state, and terminal order leg results.
- [List managed balance refill policies](https://agg.jamdesk.app/api-reference/execution/list-managed-balance-refill-policies.md): List managed balance refill policies
- [Create a managed balance refill policy](https://agg.jamdesk.app/api-reference/execution/create-a-managed-balance-refill-policy.md): Create a managed balance refill policy
- [Update or pause a managed balance refill policy](https://agg.jamdesk.app/api-reference/execution/update-or-pause-a-managed-balance-refill-policy.md): Update or pause a managed balance refill policy
- [List recent managed balance refill attempts](https://agg.jamdesk.app/api-reference/execution/list-recent-managed-balance-refill-attempts.md): List recent managed balance refill attempts
- [Execute quote](https://agg.jamdesk.app/api-reference/execution/execute-quote.md): Accepts a previously quoted smart-route quote and returns pending order IDs for the submitted fill execution.
- [Place limit order](https://agg.jamdesk.app/api-reference/execution/place-limit-order.md): Places a venue-specific limit order. Funds or shares are reserved while the order is open and fills are reconciled asynchronously.
- [Cancel an order](https://agg.jamdesk.app/api-reference/execution/cancel-an-order.md): Cancels a queued managed order or an active open limit order. Terminal orders cannot be cancelled.
- [Withdraw funds](https://agg.jamdesk.app/api-reference/execution/withdraw-funds.md): Withdraws funds to an external address and returns submitted transfer details.
- [Preview a withdrawal](https://agg.jamdesk.app/api-reference/execution/preview-a-withdrawal.md): Returns real fee + receive estimates for a withdrawal without creating one. Optional — /execution/withdraw does not require a prior preview.
- [Quote withdrawable amount](https://agg.jamdesk.app/api-reference/execution/quote-withdrawable-amount.md): Returns the maximum deliverable amount for a token and destination chain without creating a withdrawal.
- [Get withdrawal status](https://agg.jamdesk.app/api-reference/execution/get-withdrawal-status.md): Returns the current persisted state of a withdrawal — used as a fallback when the WS lifecycle channel has missed events.
- [Redeem winnings for resolved positions](https://agg.jamdesk.app/api-reference/execution/redeem-winnings-for-resolved-positions.md): Converts a user's winning prediction-market positions to USDC.
- [List paper trading accounts](https://agg.jamdesk.app/api-reference/execution/list-paper-trading-accounts.md): List paper trading accounts
- [Create a paper trading account](https://agg.jamdesk.app/api-reference/execution/create-a-paper-trading-account.md): Create a paper trading account
- [Get a paper trading account](https://agg.jamdesk.app/api-reference/execution/get-a-paper-trading-account.md): Get a paper trading account
- [Set a paper trading account cash balance](https://agg.jamdesk.app/api-reference/execution/set-a-paper-trading-account-cash-balance.md): Set a paper trading account cash balance
- [Reset a paper trading account](https://agg.jamdesk.app/api-reference/execution/reset-a-paper-trading-account.md): Reset a paper trading account
- [List paper trading orders](https://agg.jamdesk.app/api-reference/execution/list-paper-trading-orders.md): List paper trading orders
- [Place a paper trading order](https://agg.jamdesk.app/api-reference/execution/place-a-paper-trading-order.md): Place a paper trading order
- [List paper trading positions](https://agg.jamdesk.app/api-reference/execution/list-paper-trading-positions.md): List paper trading positions
- [Get a paper trading portfolio](https://agg.jamdesk.app/api-reference/execution/get-a-paper-trading-portfolio.md): Get a paper trading portfolio
- [Search events or markets](https://agg.jamdesk.app/api-reference/search/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.
- [List venue events](https://agg.jamdesk.app/api-reference/discovery/list-venue-events.md): Returns paginated venue events with optional filters for venue, status, category, and search.
- [Get Venue Event](https://agg.jamdesk.app/api-reference/discovery/get-venue-event.md): Returns a single venue event. By default the response includes an embedded venueMarkets array.
- [List venue markets](https://agg.jamdesk.app/api-reference/discovery/list-venue-markets.md): Returns paginated venue markets with optional filters for venue, status, category, and date range.
- [Look up venue market outcomes by external identifier](https://agg.jamdesk.app/api-reference/discovery/look-up-venue-market-outcomes-by-external-identifier.md): Resolves venue-side outcome keys (e.g. Polymarket tokenid) to AGG outcomes, including matchedVenueMarketOutcomes counterpart references across venues.
- [List categories](https://agg.jamdesk.app/api-reference/discovery/list-categories.md): Returns categories filtered by parentId. Omit parentId for top-level categories.
- [Correlated Markets status and coverage](https://agg.jamdesk.app/api-reference/discovery/correlated-markets-status-and-coverage.md): Public app-tier Discovery endpoint that reports Correlated Markets signal, embedding, and background worker coverage.
- [Get correlated market signals for a market](https://agg.jamdesk.app/api-reference/discovery/get-correlated-market-signals-for-a-market.md): Public app-tier Discovery endpoint that returns generated Yes/No signals explaining which real-world states become more or less likely if a market resolves.
- [Find correlated markets by semantic similarity](https://agg.jamdesk.app/api-reference/discovery/find-correlated-markets-by-semantic-similarity.md): Public app-tier Discovery endpoint. Given a natural language query, finds markets whose generated market signals overlap with the query via vector similarity.
- [Find events connected via shared market signals](https://agg.jamdesk.app/api-reference/discovery/find-events-connected-via-shared-market-signals.md): Public app-tier Discovery endpoint that returns related events connected to a source market through generated market signals.
- [Get ripple effect of a market resolving (by internal ID)](https://agg.jamdesk.app/api-reference/discovery/get-ripple-effect-of-a-market-resolving-by-internal-id.md): Public app-tier Discovery endpoint that returns expand or hedge candidates for an already-known AGG venueMarketId.
- [Resolve a market by venue ID, slug, or text and return cascade](https://agg.jamdesk.app/api-reference/discovery/resolve-a-market-by-venue-id-slug-or-text-and-return-cascade.md): Public app-tier Discovery endpoint. Accepts any identifier the user has: venue+externalId, slug, conditionId, or fuzzy text search.
- [List recurring crypto window markets](https://agg.jamdesk.app/api-reference/discovery/list-recurring-crypto-window-markets.md): Returns deterministic crypto window markets grouped by asset, window duration, and derived window start across supported venues.
- [Get live crypto reference prices](https://agg.jamdesk.app/api-reference/discovery/get-live-crypto-reference-prices.md): Returns fresh reference prices for recurring crypto market targets.
- [Get news articles for markets with market impact summaries](https://agg.jamdesk.app/api-reference/discovery/get-news-articles-for-markets-with-market-impact-summaries.md): Get news articles for markets with market impact summaries
- [Article-centric news feed for a category - latest articles with linked markets and live prices](https://agg.jamdesk.app/api-reference/discovery/article-centric-news-feed-for-a-category-latest-articles-with-linked-markets-and-live-prices.md): Article-centric news feed for a category - latest articles with linked markets and live prices
- [Market-centric news feed - markets grouped with their news timeline](https://agg.jamdesk.app/api-reference/discovery/market-centric-news-feed-markets-grouped-with-their-news-timeline.md): Market-centric news feed - markets grouped with their news timeline
- [List available news feeds with IDs and item counts](https://agg.jamdesk.app/api-reference/discovery/list-available-news-feeds-with-ids-and-item-counts.md): List available news feeds with IDs and item counts
- [Get live orderbooks for multiple markets](https://agg.jamdesk.app/api-reference/orderbook/get-live-orderbooks-for-multiple-markets.md): Returns live per-venue orderbooks for the explicit venueMarketIds requested.
- [Get live orderbook for a single outcome](https://agg.jamdesk.app/api-reference/orderbook/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://agg.jamdesk.app/api-reference/orderbook/get-live-midpoints-for-multiple-markets.md): Returns live orderbook midpoints for the requested venue market IDs.
- [Compute order route](https://agg.jamdesk.app/api-reference/orderbook/compute-order-route.md): Computes a fill quote across available venues for a specific venue market outcome and returns the suggested fills.
- [Get chart bars](https://agg.jamdesk.app/api-reference/charts/get-chart-bars.md): Returns OHLCV bars for a single venue market.
- [Get crypto purchase quotes](https://agg.jamdesk.app/api-reference/ramp/get-crypto-purchase-quotes.md): Get crypto purchase quotes
- [Create a ramp widget session for checkout](https://agg.jamdesk.app/api-reference/ramp/create-a-ramp-widget-session-for-checkout.md): Create a ramp widget session for checkout
- [List users](https://agg.jamdesk.app/api-reference/app-management/list-users.md): List users
- [Get user](https://agg.jamdesk.app/api-reference/app-management/get-user.md): Get user
- [Get analytics](https://agg.jamdesk.app/api-reference/app-management/get-analytics.md): Get analytics
- [Rotate webhook signing secret](https://agg.jamdesk.app/api-reference/app-management/rotate-webhook-signing-secret.md): Rotate webhook signing secret
- [Replay failed deliveries](https://agg.jamdesk.app/api-reference/app-management/replay-failed-deliveries.md): Replay failed deliveries
- [List users affected by market resolution](https://agg.jamdesk.app/api-reference/app-management/list-users-affected-by-market-resolution.md): List users affected by market resolution
- [Get the per-app UI config (disabled venues + categories)](https://agg.jamdesk.app/api-reference/app-management/get-the-per-app-ui-config-disabled-venues-categories.md): Get the per-app UI config (disabled venues + categories)
- [Get the per-venue blocked-country lists (ISO 3166-1 alpha-2)](https://agg.jamdesk.app/api-reference/app-management/get-the-per-venue-blocked-country-lists-iso-3166-1-alpha-2.md): Get the per-venue blocked-country lists (ISO 3166-1 alpha-2)
- [Get a temporary Alchemy JWT token for RPC connections](https://agg.jamdesk.app/api-reference/app-management/get-a-temporary-alchemy-jwt-token-for-rpc-connections.md): Get a temporary Alchemy JWT token for RPC connections
- [Recompile a fingerprint to ImportedTheme + warnings](https://agg.jamdesk.app/api-reference/app-management/recompile-a-fingerprint-to-importedtheme-warnings.md): Pure compute. Used by the studio after a user edits a fingerprint field, to refresh warnings/fixes/fit without re-extracting.

## WebSocket API

- [Orderbook](https://agg.jamdesk.app/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. Sequencing: seq increments between consecutive messages for a given market. If you receive a seq that is not your expected next value, request a new snapshot via resnapshot.
- [Trades](https://agg.jamdesk.app/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://agg.jamdesk.app/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. Connect-time auth: Pass ?token=eyJ... as a query param alongside appId.
- [User events](https://agg.jamdesk.app/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 DAG steps and terminal fill / failure status across all venues.
- [Arb](https://agg.jamdesk.app/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://agg.jamdesk.app/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.