Stock Predictions API

Programmatic access to 3,700+ stock prediction markets. Each market asks: will this stock outperform the S&P 500 this hour? Trade on a CLOB orderbook with limit orders, or bet into parimutuel pools.

Authentication

Read endpoints are public. Trading endpoints require a JWT obtained from POST /auth/login.

curl -X POST https://cymetica.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"…"}'

Use the returned access_token as Authorization: Bearer <token>.

Markets

List all active stock prediction markets. Returns ticker, company name, sector, exchange, logo URL, and current epoch info. Single response — no pagination.

curl https://cymetica.com/api/v1/otc/markets

{
  "markets": [
    {
      "id": "a1b2c3d4-...",
      "source_title": "Apple Inc (AAPL) vs S&P 500",
      "assets": [{
        "symbol": "AAPL",
        "name": "Apple Inc",
        "sector": "Technology",
        "exchange": "NASDAQ",
        "logo_url": "https://financialmodelingprep.com/image-stock/AAPL.png"
      }],
      "current_epoch": {
        "id": 521767,
        "total_pool": 3.08,
        "end_time": "2026-05-11T05:00:00",
        "resolved": false
      }
    }
  ],
  "total": 3742
}

Full detail for a single market including assets, current epoch, betting pool, and resolution status.

Orderbook (CLOB)

symbol is the stock ticker (e.g. AAPL). Returns aggregated bids/asks, best bid/ask, spread, last trade.

{
  "symbol": "AAPL",
  "bids": [{"price": "0.52", "size": "10.00", "orders": 1}],
  "asks": [{"price": "0.58", "size": "10.00", "orders": 1}],
  "best_bid": "0.52",
  "best_ask": "0.58",
  "spread": "0.06",
  "last_trade": "0.55",
  "sequence": 42
}

Trades (Chart + Time & Sales)

Recent fills for a symbol. Drives the price chart and Time & Sales feed. Falls back to synthetic price series derived from market maker quotes when no CLOB fills exist.

{
  "trades": [
    {"price": "0.55", "size": "5.0", "taker_side": "buy", "symbol": "AAPL", "timestamp": 1747000000.0}
  ],
  "symbol": "AAPL"
}

Place Order

Place a limit order on a stock prediction market.

curl -X POST https://cymetica.com/api/v1/otc/order \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "market_id": "a1b2c3d4-...",
    "symbol": "AAPL",
    "side": "buy",
    "price": 0.55,
    "size": 10
  }'

Cancel Order

Cancel a resting limit order. The symbol query parameter is required.

Parimutuel Betting

Place a bet into the prediction pool instead of the CLOB orderbook. Payouts are proportional to pool share.

curl -X POST https://cymetica.com/api/v1/wta/markets/{market_id}/bet \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"symbol": "AAPL", "amount": 5.0, "user_address": "0xYourWallet"}'

WebSocket

Subscribe to live orderbook and trade streams:

wss://cymetica.com/ws/wta/markets/{market_id}

Messages arrive as JSON with type field: orderbook_update, trade, epoch_resolved.

Rate Limits

Authenticated trading: 10 orders per 10 seconds per account. Public read endpoints are server-cached (30s TTL) and not individually rate-limited.

Errors

{"detail": "Authentication required"}                   // 401
{"detail": "OTC market not found or inactive"}           // 404
{"detail": "Invalid symbol for this market"}             // 400
{"detail": "No active epoch"}                            // 400
{"detail": "Order cost $X below minimum $Y"}             // 400
{"detail": "Order cost $X above maximum $Y"}             // 400
{"detail": "Rate limit: 10 orders per 10 seconds"}      // 429
{"detail": "Duplicate order (idempotency_key already used)"}  // 409
{"detail": "Order matching timed out"}                       // 504