# Forsee Trading API

> REST API for Forsee crypto UP/DOWN prediction markets. Markets run in repeating
> rounds; you bet UP or DOWN on whether the asset price will be higher or lower at
> the round's end. Odds derive from the pool split with a 3% fee applied to
> winnings. Authentication is a single header (X-API-Key) — far simpler than
> wallet-signed APIs. This file is the complete machine-readable reference.

- Base URL: https://api.forsee.market/v1  (legacy path also works: https://forsee.market/api/v1)
- OpenAPI spec: https://api.forsee.market/openapi.json
- Human docs: https://api.forsee.market
- Get an API key: https://forsee.market/api-keys

## Authentication

Send your key in the `X-API-Key` header on every request. Create keys in the
dashboard; the secret (`pk_live_…`) is shown once at creation.

Scopes (a request is rejected with 403 if the key lacks the required scope):
- `markets:read`    — read markets and prices (any account)
- `positions:read`  — read your positions and orders (any account)
- `orders:write`    — place orders / bets (Silver account or higher)
- `orders:cancel`   — cancel limit orders (Silver account or higher)

Active-key limit by account tier: Bronze 1, Silver 2, Gold 3, Platinum 4, VIP 5.

## Rate limits

Sliding 60-second windows: 120 read req/min and 30 write req/min per key, 240/min
per account, 300/min per IP. Every response includes X-RateLimit-Limit,
X-RateLimit-Remaining and X-RateLimit-Reset. Exceeding a limit returns 429 with a
Retry-After header — back off and retry after that delay.

## Errors

JSON envelope: `{ "success": false, "error": "message" }`. Status codes:
400 bad params · 401 missing/invalid key · 403 disabled/expired/missing scope or
tier too low · 404 not found · 409 odds moved (odds_changed) or duplicate
idempotency request · 429 rate limited · 503 trading temporarily disabled.

## Market identifiers

A market id is `<CRYPTO>_<TIMEFRAME>`, e.g. `BTC_FIVE_MINUTES`.
Crypto: BTC ETH SOL BNB XRP GOLD SILVER EURUSD GBPUSD USDJPY AUDUSD USDCAD HYPE TON.
Timeframes: ONE_MINUTE FIVE_MINUTES FIFTEEN_MINUTES FOUR_HOURS ONE_DAY.

## Endpoints

### GET /markets — list active markets (scope: markets:read)
Returns every active market with its current round, pools and live odds.

### GET /markets/{id} — single market (scope: markets:read)
`{id}` = e.g. BTC_FIVE_MINUTES.

### GET /prices — current price per asset (scope: markets:read)
Returns the latest price per crypto (current round open price) with a timestamp.

### GET /positions — your positions (scope: positions:read)
Query: `status`=active|all (default active), `limit`=1..200 (default 100).

### GET /orders — your recent orders (scope: positions:read)
Query: `limit`=1..200 (default 50).

### POST /orders — place an order/bet (scope: orders:write, Silver+)
Body (JSON):
- `marketId` (string, required) — e.g. BTC_FIVE_MINUTES
- `prediction` (string, required) — "UP" or "DOWN"
- `amount` (number, required) — stake in USD, within the market minBet/maxBet and your tier limits
- `expectedPercent` (number, optional) — slippage guard; if the live value moved >15 points the order is rejected with 409 odds_changed
- `clientSeed` (string, optional) — mixed into the provably-fair bet hash

Headers: set `Idempotency-Key` (a UUID) so a network retry never double-bets;
a repeat with the same key replays the original result. Bets are rejected within
the final 20 seconds before the round locks. Returns 201 with the created bet,
your new balance, and any limit-order fills.

## Examples

### Read markets

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

Python:
```python
import requests
r = requests.get("https://api.forsee.market/v1/markets", headers={"X-API-Key": "pk_live_…"})
print(r.json()["data"])
```

JavaScript (Node 18+):
```javascript
const res = await fetch("https://api.forsee.market/v1/markets", { headers: { "X-API-Key": "pk_live_…" } });
const { data } = await res.json();
console.log(data);
```

PHP:
```php
<?php
$ch = curl_init("https://api.forsee.market/v1/markets");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: pk_live_…"]);
echo curl_exec($ch);
curl_close($ch);
```

### Place an order

cURL:
```bash
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}'
```

Python:
```python
import requests, uuid
r = requests.post(
    "https://api.forsee.market/v1/orders",
    headers={"X-API-Key": "pk_live_…", "Idempotency-Key": str(uuid.uuid4())},
    json={"marketId": "BTC_FIVE_MINUTES", "prediction": "UP", "amount": 25, "expectedPercent": 50},
)
print(r.status_code, r.json())
```

JavaScript (Node 18+):
```javascript
const res = await fetch("https://api.forsee.market/v1/orders", {
  method: "POST",
  headers: {
    "X-API-Key": "pk_live_…",
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({ marketId: "BTC_FIVE_MINUTES", prediction: "UP", amount: 25, expectedPercent: 50 }),
});
console.log(res.status, await res.json());
```

PHP:
```php
<?php
$ch = curl_init("https://api.forsee.market/v1/orders");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: pk_live_…",
    "Content-Type: application/json",
    "Idempotency-Key: " . bin2hex(random_bytes(16)),
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "marketId" => "BTC_FIVE_MINUTES", "prediction" => "UP", "amount" => 25, "expectedPercent" => 50,
  ]),
]);
echo curl_exec($ch);
curl_close($ch);
```

## Notes for building a bot

- Parimutuel model: odds = totalPool / sidePool, settled payout = amount * oddsAtBet * (1 - 0.03).
- A round must be LIVE and more than ~20s from lockTime to accept a bet; use currentRound.timeToLock.
- Bets settle automatically after the round ends; poll GET /positions or GET /orders for results.
- Always set Idempotency-Key on POST /orders and honor 429 Retry-After.