# Predict API Documentation

## Instructions for AI Agents

- For clean Markdown of any page, append `.md` to the page URL
- For section-specific indexes, append `/llms.txt` to any section URL
- For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.staging.trypredict.com/_mcp/server

## Docs

- [Predict Public API](https://docs.staging.trypredict.com/welcome/overview/introduction.md): Explore Predict's public REST and realtime APIs for catalog discovery, accounts, outcome market data, activity, performance, and order queue position.
- [Make your first Predict API request](https://docs.staging.trypredict.com/welcome/overview/quick-start.md): Make your first unauthenticated Predict REST request, filter active events, follow cursor pagination, and discover account, outcome, and realtime APIs.
- [Predict API catalog hierarchy](https://docs.staging.trypredict.com/guides/guides/catalog-hierarchy.md): Learn how Predict organizes sports market data across topics, categories, series, events, participants, questions, and tradable Hyperliquid outcome records.
- [Predict realtime API](https://docs.staging.trypredict.com/guides/guides/realtime.md): Subscribe to public Predict account, outcome, and order queue snapshots and live updates over one anonymous WebSocket connection.
- [Trading with Predict and Hyperliquid](https://docs.staging.trypredict.com/guides/guides/trading.md): Connect Predict catalog outcomes to Hyperliquid trading with the TypeScript client, signed orders, probability pricing, and minimum USDC notional rules.
- [How Predict and Hyperliquid work together](https://docs.staging.trypredict.com/guides/direct-trading/architecture.md): Understand which API owns catalog metadata, market data, order entry, balances, fills, settlement, and real-time streams when trading Predict outcomes.
- [Predict and Hyperliquid market identifiers](https://docs.staging.trypredict.com/guides/direct-trading/market-identifiers.md): Map Predict hl_id and outcome side values to Hyperliquid market-data coins, balance token names, and exchange asset IDs for accurate HIP-4 trading workflows.
- [Trading market data](https://docs.staging.trypredict.com/guides/direct-trading/market-data.md): Use Predict for normalized outcome prices, trades, statistics, holders, and charts, then use Hyperliquid when you need full books, venue mids, candles, or raw account state.
- [Orders and executions](https://docs.staging.trypredict.com/guides/direct-trading/orders.md): Place, batch, modify, cancel, inspect, and reconcile signed HIP-4 outcome orders through the Predict trading API with client IDs, dead-man switches, and per-item error handling.
- [Portfolio, balances, and fills](https://docs.staging.trypredict.com/guides/direct-trading/portfolio-and-fills.md): Build Predict outcome positions from Hyperliquid spot balances and reconcile open orders, fills, fees, limits, ledger updates, builders, and subaccounts.
- [Outcome-token conversions](https://docs.staging.trypredict.com/guides/direct-trading/outcome-conversions.md): Learn how to split, merge, and negate Predict outcome tokens through the Predict trading API's signed userOutcome actions for standalone and mutually exclusive markets.
- [Signing, agent wallets, and builder fees](https://docs.staging.trypredict.com/guides/direct-trading/signing-and-agents.md): Understand Hyperliquid agent wallets, nonces, subaccount signing, action expiry, builder approvals, and private-key handling for Predict outcome trading.
- [Hyperliquid real-time trading and account streams](https://docs.staging.trypredict.com/guides/direct-trading/websockets.md): Stream direct Hyperliquid HIP-4 books, trades, candles, orders, fills, balances, ledger updates, and notifications with resilient reconnect recovery.
- [Limits, errors, and production recovery](https://docs.staging.trypredict.com/guides/direct-trading/reliability-and-limits.md): Handle Hyperliquid rate limits, bounded history, order errors, reconnects, idempotency, and operational differences from REST-first prediction exchanges.

## API Docs

- Predict REST API > Account [Get account](https://docs.staging.trypredict.com/api-reference/account/get-account.md)
- Predict REST API > Account [Get account by username](https://docs.staging.trypredict.com/api-reference/account/get-account-by-username.md)
- Predict REST API > Account [List account positions](https://docs.staging.trypredict.com/api-reference/account/list-account-positions.md)
- Predict REST API > Account [List account orders](https://docs.staging.trypredict.com/api-reference/account/list-account-orders.md)
- Predict REST API > Account [List account trades](https://docs.staging.trypredict.com/api-reference/account/list-account-trades.md)
- Predict REST API > Account [List account activity](https://docs.staging.trypredict.com/api-reference/account/list-account-activity.md)
- Predict REST API > Account [List account cashflows](https://docs.staging.trypredict.com/api-reference/account/list-account-cashflows.md)
- Predict REST API > Account [Get account stats](https://docs.staging.trypredict.com/api-reference/account/get-account-stats.md)
- Predict REST API > Account [Get account PnL](https://docs.staging.trypredict.com/api-reference/account/get-account-pnl.md)
- Predict REST API > Account [Get account volume](https://docs.staging.trypredict.com/api-reference/account/get-account-volume.md)
- Predict REST API > Account [Get account fees](https://docs.staging.trypredict.com/api-reference/account/get-account-fees.md)
- Predict REST API > Event [List events](https://docs.staging.trypredict.com/api-reference/event/list-events.md)
- Predict REST API > Event [Get event](https://docs.staging.trypredict.com/api-reference/event/get-event.md)
- Predict REST API > Outcome [List outcomes](https://docs.staging.trypredict.com/api-reference/outcome/list-outcomes.md)
- Predict REST API > Outcome [Get outcome](https://docs.staging.trypredict.com/api-reference/outcome/get-outcome.md)
- Predict REST API > Outcome [Get outcome price](https://docs.staging.trypredict.com/api-reference/outcome/get-outcome-price.md)
- Predict REST API > Outcome [Get outcome stats](https://docs.staging.trypredict.com/api-reference/outcome/get-outcome-stats.md)
- Predict REST API > Outcome [Get outcome timeseries](https://docs.staging.trypredict.com/api-reference/outcome/get-outcome-timeseries.md)
- Predict REST API > Outcome [List outcome trades](https://docs.staging.trypredict.com/api-reference/outcome/list-outcome-trades.md)
- Predict REST API > Outcome [Get outcome holders](https://docs.staging.trypredict.com/api-reference/outcome/get-outcome-holders.md)
- Predict REST API > Order [Get order queue positions](https://docs.staging.trypredict.com/api-reference/order/get-order-queue-positions.md)
- Predict REST API > Trading [Place orders](https://docs.staging.trypredict.com/api-reference/trading/trading-service-place-order.md)
- Predict REST API > Trading [Cancel orders](https://docs.staging.trypredict.com/api-reference/trading/trading-service-cancel-orders.md)
- Predict REST API > Trading [Cancel orders by client ID](https://docs.staging.trypredict.com/api-reference/trading/trading-service-cancel-orders-by-cloid.md)
- Predict REST API > Trading [Modify orders](https://docs.staging.trypredict.com/api-reference/trading/trading-service-modify-order.md)
- Predict REST API > Trading [Schedule cancel all](https://docs.staging.trypredict.com/api-reference/trading/trading-service-schedule-cancel.md)
- Predict REST API > Trading [Split a position](https://docs.staging.trypredict.com/api-reference/trading/trading-service-split-position.md)
- Predict REST API > Trading [Merge a position](https://docs.staging.trypredict.com/api-reference/trading/trading-service-merge-position.md)
- Predict REST API > Trading [Merge a question](https://docs.staging.trypredict.com/api-reference/trading/trading-service-merge-question.md)
- Predict REST API > Trading [Negate a position](https://docs.staging.trypredict.com/api-reference/trading/trading-service-negate-position.md)
- Predict REST API > Topic [List topics](https://docs.staging.trypredict.com/api-reference/topic/list-topics.md)
- Predict REST API > Topic [Get topic](https://docs.staging.trypredict.com/api-reference/topic/get-topic.md)
- Predict REST API > Category [List categories](https://docs.staging.trypredict.com/api-reference/category/list-categories.md)
- Predict REST API > Category [Get category](https://docs.staging.trypredict.com/api-reference/category/get-category.md)
- Predict REST API > Series [List series](https://docs.staging.trypredict.com/api-reference/series/list-series.md)
- Predict REST API > Series [Get series](https://docs.staging.trypredict.com/api-reference/series/get-series.md)
- Predict REST API > Participants [List participants](https://docs.staging.trypredict.com/api-reference/participants/list-participants.md)
- Predict REST API > Participants [Get participant](https://docs.staging.trypredict.com/api-reference/participants/get-participant.md)
- Predict REST API > Providers [List providers](https://docs.staging.trypredict.com/api-reference/providers/list-providers.md)
- Predict REST API > Health [Health Service Get Health](https://docs.staging.trypredict.com/api-reference/health/health-service-get-health.md)
- Predict REST API > Outcomes [Outcome Service List Outcome BB Os](https://docs.staging.trypredict.com/api-reference/outcomes/outcome-service-list-outcome-bb-os.md)
- Predict REST API > Outcomes [Outcome Service Get Outcome BBO](https://docs.staging.trypredict.com/api-reference/outcomes/outcome-service-get-outcome-bbo.md)
- Predict REST API > Outcomes [Outcome Service Get Outcome Book](https://docs.staging.trypredict.com/api-reference/outcomes/outcome-service-get-outcome-book.md)
- Predict REST API > Templates [Template Service List Templates](https://docs.staging.trypredict.com/api-reference/templates/template-service-list-templates.md)
- Predict Realtime API > Realtime [Realtime](https://docs.staging.trypredict.com/api-reference/predict-realtime-api/realtime/realtime.md)
- Trading reads > Market Data [Get exchange status](https://docs.staging.trypredict.com/api-reference/trading-reads/market-data/get-exchange-status.md)
- Trading reads > Market Data [Get mid prices](https://docs.staging.trypredict.com/api-reference/trading-reads/market-data/get-mid-prices.md)
- Trading reads > Market Data [Get order book](https://docs.staging.trypredict.com/api-reference/trading-reads/market-data/get-order-book.md)
- Trading reads > Market Data [Get recent trades](https://docs.staging.trypredict.com/api-reference/trading-reads/market-data/get-recent-trades.md)
- Trading reads > Market Data [Get candles](https://docs.staging.trypredict.com/api-reference/trading-reads/market-data/get-candles.md)
- Trading reads > Orders [Get open orders](https://docs.staging.trypredict.com/api-reference/trading-reads/orders/get-open-orders.md)
- Trading reads > Orders [Get detailed open orders](https://docs.staging.trypredict.com/api-reference/trading-reads/orders/get-detailed-open-orders.md)
- Trading reads > Orders [Get order status](https://docs.staging.trypredict.com/api-reference/trading-reads/orders/get-order-status.md)
- Trading reads > Orders [Get historical orders](https://docs.staging.trypredict.com/api-reference/trading-reads/orders/get-historical-orders.md)
- Trading reads > Portfolio [Get fills](https://docs.staging.trypredict.com/api-reference/trading-reads/portfolio/get-fills.md)
- Trading reads > Portfolio [Get fills by time](https://docs.staging.trypredict.com/api-reference/trading-reads/portfolio/get-fills-by-time.md)
- Trading reads > Portfolio [Get balances](https://docs.staging.trypredict.com/api-reference/trading-reads/portfolio/get-balances.md)
- Trading reads > Portfolio [Get fee schedule](https://docs.staging.trypredict.com/api-reference/trading-reads/portfolio/get-fee-schedule.md)
- Trading reads > Portfolio [Get rate limit](https://docs.staging.trypredict.com/api-reference/trading-reads/portfolio/get-rate-limit.md)
- Trading reads > Portfolio [Get subaccounts](https://docs.staging.trypredict.com/api-reference/trading-reads/portfolio/get-subaccounts.md)
- Trading reads > Portfolio [Get account role](https://docs.staging.trypredict.com/api-reference/trading-reads/portfolio/get-account-role.md)
- Trading reads > Portfolio [Get ledger updates](https://docs.staging.trypredict.com/api-reference/trading-reads/portfolio/get-ledger-updates.md)
- Trading reads > Portfolio [Get approved builders](https://docs.staging.trypredict.com/api-reference/trading-reads/portfolio/get-approved-builders.md)
- Trading reads > Portfolio [Get maximum builder fee](https://docs.staging.trypredict.com/api-reference/trading-reads/portfolio/get-maximum-builder-fee.md)
- Signed actions > Authorization [Approve agent wallet](https://docs.staging.trypredict.com/api-reference/signed-actions/authorization/approve-agent.md)
- Signed actions > Authorization [Approve builder fee](https://docs.staging.trypredict.com/api-reference/signed-actions/authorization/approve-builder-fee.md)
- Signed actions > Transfers [Transfer USDC class](https://docs.staging.trypredict.com/api-reference/signed-actions/transfers/transfer-usdc-class.md)
- Signed actions > Transfers [Send spot token](https://docs.staging.trypredict.com/api-reference/signed-actions/transfers/send-spot-token.md)
- Signed actions > Transfers [Send asset](https://docs.staging.trypredict.com/api-reference/signed-actions/transfers/send-asset.md)
- Signed actions > Transfers [Withdraw USDC](https://docs.staging.trypredict.com/api-reference/signed-actions/transfers/withdraw-usdc.md)
- WebSocket API [WebSocket Connection](https://docs.staging.trypredict.com/api-reference/web-socket-api/websocket-connection.md)
- WebSocket API [Connection Keep-Alive](https://docs.staging.trypredict.com/api-reference/web-socket-api/keep-alive.md)
- WebSocket API [Orderbook Updates](https://docs.staging.trypredict.com/api-reference/web-socket-api/order-book.md)
- WebSocket API [Best Bid and Offer](https://docs.staging.trypredict.com/api-reference/web-socket-api/best-bid-offer.md)
- WebSocket API [Mid Prices](https://docs.staging.trypredict.com/api-reference/web-socket-api/mid-prices.md)
- WebSocket API [Public Trades](https://docs.staging.trypredict.com/api-reference/web-socket-api/public-trades.md)
- WebSocket API [Candles](https://docs.staging.trypredict.com/api-reference/web-socket-api/candles.md)
- WebSocket API [User Fills](https://docs.staging.trypredict.com/api-reference/web-socket-api/user-fills.md)
- WebSocket API [Balances](https://docs.staging.trypredict.com/api-reference/web-socket-api/balances.md)
- WebSocket API [Open Orders](https://docs.staging.trypredict.com/api-reference/web-socket-api/open-orders.md)
- WebSocket API [Order Updates](https://docs.staging.trypredict.com/api-reference/web-socket-api/order-updates.md)
- WebSocket API [Ledger Updates](https://docs.staging.trypredict.com/api-reference/web-socket-api/ledger-updates.md)
- WebSocket API [Notifications](https://docs.staging.trypredict.com/api-reference/web-socket-api/notifications.md)
- WebSocket API [WebSocket POST Requests](https://docs.staging.trypredict.com/api-reference/web-socket-api/post-requests.md)

## OpenAPI Specification

The raw OpenAPI 3.1 specification for this API is available at:
- [OpenAPI JSON](https://docs.staging.trypredict.com/openapi.json)
- [OpenAPI YAML](https://docs.staging.trypredict.com/openapi.yaml)


## AsyncAPI Specification

The raw AsyncAPI 2.6.0 specification for the WebSocket channels is available at:
- [AsyncAPI JSON](https://docs.staging.trypredict.com/asyncapi.json)
- [AsyncAPI YAML](https://docs.staging.trypredict.com/asyncapi.yaml)