{"openapi":"3.1.0","info":{"title":"Forsee Trading API","version":"1.0.0","description":"REST API for Forsee crypto UP/DOWN prediction markets. Markets run in repeating rounds; you bet UP or DOWN on the price by the round end. Odds come from the pool split with a 3% fee on winnings. Authenticate with the X-API-Key header (create keys at https://forsee.market/api-keys). The orders:write and orders:cancel scopes require a Silver account or higher.","contact":{"url":"https://api.forsee.market"}},"servers":[{"url":"https://api.forsee.market/v1","description":"Production (canonical)"},{"url":"https://forsee.market/api/v1","description":"Production (legacy path)"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"Markets","description":"Market and price data (scope: markets:read)"},{"name":"Positions","description":"Your positions and orders (scope: positions:read)"},{"name":"Orders","description":"Place orders (scope: orders:write, Silver+)"}],"paths":{"/markets":{"get":{"tags":["Markets"],"summary":"List active markets","description":"Returns all active markets with their current round, pool sizes and live odds.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Market"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/markets/{id}":{"get":{"tags":["Markets"],"summary":"Get a market by id","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"BTC_FIVE_MINUTES"},"description":"Market id in the form <CRYPTO>_<TIMEFRAME>."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Market"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/prices":{"get":{"tags":["Markets"],"summary":"Current price per asset","description":"Latest price per crypto (the current round open price). For real-time ticks use the realtime feed when available.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Price"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/positions":{"get":{"tags":["Positions"],"summary":"List your positions","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["active","all"],"default":"active"},"description":"active = open positions only; all = full history."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":100}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Position"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/orders":{"get":{"tags":["Positions"],"summary":"List your recent orders","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Position"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["Orders"],"summary":"Place an order (bet)","description":"Places a bet on the current live round of a market. Requires the orders:write scope (Silver account or higher). Send an Idempotency-Key header so a retry never double-bets. Bets are rejected within the final 20 seconds before the round locks.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","example":"7f3c1a90-1d2e-4b3a-9c8d-abc123"},"description":"Unique key (e.g. a UUID). A repeat with the same key replays the original result."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderRequest"}}}},"responses":{"201":{"description":"Order placed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/OrderResult"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"Odds moved beyond tolerance (odds_changed) or a duplicate idempotency request is in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key (pk_live_…) created at https://forsee.market/api-keys."}},"responses":{"Unauthorized":{"description":"Missing, malformed or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Key disabled/expired, missing scope, or tier too low for this scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"BadRequest":{"description":"Invalid parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit exceeded. See the Retry-After and X-RateLimit-* headers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"invalid API key"}}},"Round":{"type":"object","properties":{"id":{"type":"string"},"roundNumber":{"type":"integer"},"startTime":{"type":"string","format":"date-time"},"lockTime":{"type":"string","format":"date-time"},"endTime":{"type":"string","format":"date-time"},"timeRemaining":{"type":"integer","description":"Seconds until the round ends."},"timeToLock":{"type":"integer","description":"Milliseconds until betting locks."},"openPrice":{"type":["number","null"]},"currentPrice":{"type":["number","null"]},"status":{"type":"string","enum":["UPCOMING","LIVE","LOCKED","SETTLING","SETTLED"]},"totalBets":{"type":"integer"},"totalVolume":{"type":"number"},"result":{"type":"string","enum":["UP","DOWN","DRAW"]}}},"Market":{"type":"object","properties":{"id":{"type":"string","example":"BTC_FIVE_MINUTES"},"crypto":{"type":"string","enum":["BTC","ETH","SOL","BNB","XRP","GOLD","SILVER","EURUSD","GBPUSD","USDJPY","AUDUSD","USDCAD","HYPE","TON"]},"timeFrame":{"type":"string","enum":["ONE_MINUTE","FIVE_MINUTES","FIFTEEN_MINUTES","FOUR_HOURS","ONE_DAY"]},"poolUp":{"type":"number"},"poolDown":{"type":"number"},"totalPool":{"type":"number"},"oddsUp":{"type":"number"},"oddsDown":{"type":"number"},"percentUp":{"type":"number"},"percentDown":{"type":"number"},"minBet":{"type":"number"},"maxBet":{"type":"number"},"currentRound":{"oneOf":[{"$ref":"#/components/schemas/Round"},{"type":"null"}]}}},"Price":{"type":"object","properties":{"crypto":{"type":"string","enum":["BTC","ETH","SOL","BNB","XRP","GOLD","SILVER","EURUSD","GBPUSD","USDJPY","AUDUSD","USDCAD","HYPE","TON"]},"price":{"type":"number"},"source":{"type":"string","example":"round_open"},"timestamp":{"type":"string","format":"date-time"}}},"Position":{"type":"object","properties":{"id":{"type":"string"},"marketId":{"type":["string","null"],"example":"BTC_FIVE_MINUTES"},"crypto":{"type":["string","null"]},"timeFrame":{"type":["string","null"]},"prediction":{"type":"string","enum":["UP","DOWN"]},"amount":{"type":"number"},"oddsAtBet":{"type":"number"},"potentialPayout":{"type":"number"},"status":{"type":"string","enum":["PENDING","ACTIVE","SETTLING","SETTLED","CANCELLED","EXPIRED"]},"result":{"type":["string","null"],"enum":["WIN","LOSS","DRAW","REFUNDED","CASHOUT",null]},"payout":{"type":["number","null"]},"profit":{"type":["number","null"]},"isLimitOrder":{"type":"boolean"},"placedAt":{"type":"string","format":"date-time"},"settledAt":{"type":["string","null"],"format":"date-time"}}},"OrderRequest":{"type":"object","required":["marketId","prediction","amount"],"properties":{"marketId":{"type":"string","example":"BTC_FIVE_MINUTES"},"prediction":{"type":"string","enum":["UP","DOWN"]},"amount":{"type":"number","description":"Stake in USD. Must satisfy the market minBet/maxBet and your account tier limits.","example":25},"expectedPercent":{"type":"number","description":"Slippage guard: the percent you expect for your side. If the live value moved more than 15 points, the order is rejected with 409 odds_changed.","example":50},"clientSeed":{"type":"string","description":"Optional client seed mixed into the provably-fair bet hash."}}},"OrderResult":{"type":"object","properties":{"bet":{"type":"object","properties":{"id":{"type":"string"},"marketId":{"type":"string"},"prediction":{"type":"string","enum":["UP","DOWN"]},"amount":{"type":"number"},"oddsAtBet":{"type":"number"},"entryPercent":{"type":"number"},"potentialPayout":{"type":"number"},"status":{"type":"string"},"betHash":{"type":"string"},"placedAt":{"type":"string","format":"date-time"}}},"newBalance":{"type":"number"},"limitOrdersFilled":{"type":["object","null"]}}}}}}