Fora
DocsGitHub

REST API

Base URL: https://api.fora.co

The API has three layers:

  1. Public read endpoints — markets, trades, prices. No auth.
  2. Transaction-build endpoints — return an unsigned Solana transaction for the client to sign and submit. Privy JWT required.
  3. Tinybird data proxy — historical OHLCV, price series, leaderboards. Public.

For real-time order book and trade streams, see the WebSocket at wss://fire.fora.co (separate reference, in progress).

Authentication

Transaction-build endpoints (everything under /tx/build/*) and admin endpoints (resolve, airdrop, user settings) require a Privy JWT in the Authorization header:

Authorization: Bearer <privy-id-token>

You get the token by signing in via Privy — the same auth flow that powers fora.co. The Fora app ID is cm9ld05e2008wji0mmils1a2y.

Public read endpoints

Markets

Method Path Returns
GET /markets List all markets (filterable)
GET /markets/{ticker} Single market detail
GET /markets/{ticker}/status Lifecycle state + winning outcome
GET /markets/{ticker}/twap Current TWAP for Vibe markets
GET /markets/{ticker}/twap-series TWAP history
GET /markets/events List events (groups of related markets)
GET /markets/events/{event_ticker} Event detail
GET /orderbook/{ticker} Current YES + NO order books
GET /orders/{ticker}/{trader} Open orders for a trader on a market

Trades

Method Path Returns
GET /trades Recent trades (filterable by market, time range)

Search & discovery

Method Path Returns
GET /search Full-text search across markets and events
GET /category/{category} Markets by category
GET /recommend/{user_id} Personalized market recommendations

Health

Method Path Returns
GET /health "OK" if alive
GET /airdrop/collateral_mint Returns the configured USDC mint pubkey

Transaction-build endpoints

All require Privy JWT. All return an unsigned base64-encoded Solana transaction the client signs and submits to the network.

Method Path Builds
POST /tx/build/swap Cross-market swap (YES → NO or vice versa)
POST /tx/build/order Limit or market order on a Manifest book
POST /tx/build/claim_seat Claim a Manifest seat on a YES or NO book
POST /tx/build/deposit Deposit collateral to a market
POST /tx/build/cancel_order Cancel an open order
POST /tx/build/create-market Create a new prediction market
POST /tx/create-usdc-ata Create the user's USDC associated token account

Admin endpoints

Authority-only. Privy JWT must belong to an account with the corresponding role.

Method Path Action
POST /markets/resolve Resolve a market (manual mechanism)
POST /markets/{ticker}/resolve-and-close Resolve + close in one call
GET /airdrop Devnet/localnet USDC airdrop
GET /users List all users
GET /user/{id}/settings Per-user settings

Historical data (Tinybird proxy)

Method Path Returns
GET /data/{pipe_name} Generic Tinybird pipe proxy
GET /fora/price-series Fora price series (params below)
GET /fora/ohlcv Fora OHLCV candles
GET /kalshi/price-series Mirrored Kalshi price series
GET /kalshi/ohlcv Mirrored Kalshi OHLCV

Required query parameters

The Tinybird-backed endpoints take specific parameter names that don't match what earlier docs claimed:

  • market or market_ticker — the market ticker (string). Not ticker.
  • window_minutes — TWAP/aggregation window in minutes. Not interval.
  • start_ms / end_ms — time bounds in Unix milliseconds. Not hours.
  • slot_min / slot_max — slot bounds for /trades.

Example:

curl "https://api.fora.co/fora/ohlcv?market=KXMARMAD-26-DUKE&window_minutes=60&start_ms=1714521600000&end_ms=1714608000000"

Response envelope

All Tinybird-backed endpoints return:

{
  "success": true,
  "data": [ ... ],
  "meta": { "total": 42, "page": 1, "limit": 100, "has_more": false },
  "query": { "market": "KXMARMAD-26-DUKE", "window_minutes": 60, ... }
}

The data array contents depend on the pipe.

Other

Method Path Action
POST /users/sync Sync user state from Privy
POST /markets/metadata Submit market metadata
POST /onramp/session Start a fiat → USDC onramp session
POST /auth/telegram/callback Telegram OAuth callback
GET /auth/telegram/status Check Telegram auth status
POST /chat/send Send a chat message (publishes to Kafka, broadcasts via WS)
POST /events Track a frontend analytics event
GET /notifications List user notifications
POST /notifications/read Mark a notification read

Source

The Axum router lives at api/src/main.rs; handlers at api/src/handlers.rs. When in doubt, the source is canonical.