Forsee Trading API

Introduction

The Forsee Trading API is a REST API for the platform’s crypto UP/DOWN parimutuel markets. Each market runs in repeating rounds; you bet on whether the price will go UP or DOWN by the round’s end. Odds are derived from the pool split, with a 3% platform fee applied to winnings.

All responses are JSON and share a consistent envelope:

{ "success": true,  "data": { /* ... */ } }
{ "success": false, "error": "human-readable message" }

Access: the API is in a limited rollout. API keys are currently issued to approved accounts only — see Authentication.

Authentication

Every request authenticates with an API key sent in the X-API-Key header. Create and manage keys in your dashboard at /api-keys. The secret (pk_live_…) is shown once at creation — store it securely; it is never displayed again.

curl https://api.forsee.market/v1/markets \
  -H "X-API-Key: pk_live_your_key_here"

Each key is scoped. A request is rejected with 403 if the key lacks the scope an endpoint requires:

Rate limits

Limits are enforced per key, per account and per IP using a sliding 60-second window. Read endpoints are generous; write endpoints are stricter.

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds). When you exceed a limit you get 429 with a Retry-After header — back off and retry after that delay.

Errors

Errors use standard HTTP status codes and the { success: false, error } envelope.

Markets

A market is identified by <CRYPTO>_<TIMEFRAME>, e.g. BTC_FIVE_MINUTES. Timeframes: ONE_MINUTE, FIVE_MINUTES, FIFTEEN_MINUTES, FOUR_HOURS, ONE_DAY.

List all active markets with their current round, pool sizes and live odds.

curl https://api.forsee.market/v1/markets -H "X-API-Key: pk_live_…"

{
  "success": true,
  "data": [
    {
      "id": "BTC_FIVE_MINUTES",
      "crypto": "BTC",
      "timeFrame": "FIVE_MINUTES",
      "poolUp": 4097.0,
      "poolDown": 4050.0,
      "totalPool": 8147.0,
      "oddsUp": 1.9349,
      "oddsDown": 1.9512,
      "percentUp": 50.3,
      "percentDown": 49.7,
      "minBet": 1.0,
      "maxBet": 10000.0,
      "currentRound": {
        "id": "a1b2c3…",
        "roundNumber": 18423,
        "startTime": "2026-06-27T20:10:00.000Z",
        "lockTime":  "2026-06-27T20:14:40.000Z",
        "endTime":   "2026-06-27T20:15:00.000Z",
        "timeRemaining": 184,
        "timeToLock": 164000,
        "openPrice": 67120.5,
        "currentPrice": 67128.2,
        "status": "LIVE",
        "totalBets": 312,
        "totalVolume": 8147.0
      }
    }
  ]
}

Fetch a single market by id. Same shape as one element of the list above.

curl https://api.forsee.market/v1/markets/BTC_FIVE_MINUTES -H "X-API-Key: pk_live_…"

Prices

Current price per asset. Returns the open price of each asset’s latest live round (field source: "round_open") with a timestamp so you can judge its age. For true real-time ticks, use the realtime feed (see Realtime).

curl https://api.forsee.market/v1/prices -H "X-API-Key: pk_live_…"

{
  "success": true,
  "data": [
    { "crypto": "BTC", "price": 67120.5, "source": "round_open", "timestamp": "2026-06-27T20:10:00.000Z" },
    { "crypto": "ETH", "price": 3284.1,  "source": "round_open", "timestamp": "2026-06-27T20:10:00.000Z" }
  ]
}

Positions

Your positions — one entry per bet. Defaults to currently-open positions.

curl "https://api.forsee.market/v1/positions?status=active&limit=50" -H "X-API-Key: pk_live_…"

{
  "success": true,
  "data": [
    {
      "id": "0a1b…",
      "marketId": "BTC_FIVE_MINUTES",
      "prediction": "UP",
      "amount": 25.0,
      "oddsAtBet": 1.95,
      "potentialPayout": 47.31,
      "status": "ACTIVE",
      "result": null,
      "placedAt": "2026-06-27T20:11:02.000Z",
      "round": { "roundNumber": 18423, "status": "LIVE", "endTime": "2026-06-27T20:15:00.000Z" }
    }
  ]
}

Orders

Place a bet on the current live round of a market. The bet locks immediately and settles automatically when the round ends.

Send an Idempotency-Key header so a network retry never double-bets (see Idempotency). Bets are not accepted within the final 20 seconds before lock.

curl -X POST https://api.forsee.market/v1/orders \
  -H "X-API-Key: pk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "marketId": "BTC_FIVE_MINUTES", "prediction": "UP", "amount": 25, "expectedPercent": 50 }'

Response (201 Created):

{
  "success": true,
  "data": {
    "bet": {
      "id": "0a1b…",
      "marketId": "BTC_FIVE_MINUTES",
      "prediction": "UP",
      "amount": 25.0,
      "oddsAtBet": 1.95,
      "entryPercent": 51.2,
      "potentialPayout": 47.31,
      "status": "ACTIVE",
      "betHash": "9f2e…",
      "placedAt": "2026-06-27T20:11:02.000Z"
    },
    "newBalance": 975.0,
    "limitOrdersFilled": null
  }
}

List your recent orders (most recent first).

curl "https://api.forsee.market/v1/orders?limit=50" -H "X-API-Key: pk_live_…"

Idempotency

POST /orders accepts an Idempotency-Key header (any unique string — a UUID is ideal). The first request with a given key places the bet; any retry with the same key replays the original response instead of placing a second bet. The response of a replay carries X-Idempotent-Replay: true. Keys are remembered for 10 minutes.

Always set an idempotency key on order placement so a timeout or dropped connection can be safely retried.

Realtime

A WebSocket feed for live price ticks, round transitions and your fills is on the roadmap. Until it ships, poll GET /markets and GET /prices (cached ~2s server-side, so polling every 1–2 seconds is fine and cheap).