{ "openapi": "3.0.3", "info": { "title": "FairSeal API", "description": "Verifiable Entropy Network — provably fair random number generation via VDF (Verifiable Delay Function) and Merkle-anchored proofs.", "version": "0.2.0", "contact": { "name": "FairSeal", "url": "https://verify.fairseal.io" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://api.fairseal.io", "description": "Production" } ], "paths": { "/": { "get": { "summary": "Service Info", "description": "Landing page with service status, links, and VDF engine info.", "operationId": "getServiceInfo", "tags": [ "System" ], "responses": { "200": { "description": "Service information", "content": { "application/json": { "schema": { "type": "object", "properties": { "service": { "type": "string", "example": "FairSeal" }, "description": { "type": "string" }, "version": { "type": "string", "example": "0.2.0" }, "status": { "type": "string", "example": "operational" }, "links": { "type": "object", "properties": { "verify": { "type": "string" }, "whitepaper": { "type": "string" }, "api_docs": { "type": "string" }, "health": { "type": "string" }, "stats": { "type": "string" }, "recent": { "type": "string" }, "docs": { "type": "string" } } }, "database": { "type": "string", "enum": [ "connected", "disconnected" ] }, "vdf_engine": { "type": "object", "properties": { "status": { "type": "string" }, "epoch": { "type": "object" }, "computation_time": { "type": "string" } } }, "uptime": { "type": "number" } } } } } } } } }, "/health": { "get": { "summary": "Health Check", "description": "Returns service health status including database connectivity and VDF status.", "operationId": "getHealth", "tags": [ "System" ], "responses": { "200": { "description": "Health status", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "uptime": { "type": "number", "example": 3600 }, "database": { "type": "string", "enum": [ "connected", "disconnected" ] }, "vdf": { "type": "string", "example": "active" } } } } } } } } }, "/api/v1/entropy": { "get": { "summary": "Get Raw Entropy", "description": "Returns raw entropy from the latest resolved VDF epoch. Useful for external systems needing verifiable randomness.", "operationId": "getEntropy", "tags": [ "Entropy" ], "responses": { "200": { "description": "Entropy data from latest epoch", "content": { "application/json": { "schema": { "type": "object", "properties": { "entropy": { "type": "string", "description": "Raw entropy hex string" }, "entropy_hash": { "type": "string", "description": "SHA-256 hash of entropy" }, "source": { "type": "string", "example": "vdf_epoch" }, "epoch": { "type": "integer" }, "timestamp": { "type": "integer", "description": "Unix timestamp" }, "veo_class": { "type": "string", "example": "VEO-1A" }, "verify_url": { "type": "string" } } }, "example": { "entropy": "a1b2c3d4e5f6...", "entropy_hash": "sha256hex...", "source": "vdf_epoch", "epoch": 42, "timestamp": 1720000000, "veo_class": "VEO-1A", "verify_url": "/api/v1/verify/abc123" } } } }, "202": { "description": "No entropy available yet, waiting for next epoch", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "pending" }, "message": { "type": "string" }, "epoch": { "type": "integer" } } } } } } } } }, "/api/v1/games": { "get": { "summary": "Game Catalog", "description": "Lists all available games with their bet types, house edges, and endpoints.", "operationId": "getGameCatalog", "tags": [ "Games" ], "responses": { "200": { "description": "Available games", "content": { "application/json": { "schema": { "type": "object", "properties": { "games": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "bet_types": { "type": "array", "items": { "type": "string" } }, "house_edge": { "type": "string" }, "endpoint": { "type": "string" } } } }, "raw_rng": { "type": "object", "properties": { "description": { "type": "string" }, "endpoint": { "type": "string" } } } } } } } } } } }, "/api/v1/games/dice/bet": { "post": { "summary": "Place a Dice Bet", "description": "Place a bet on a two-dice game. Result resolves after the next VDF epoch (~5s).", "operationId": "placeDiceBet", "tags": [ "Games" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "bet_type" ], "properties": { "bet_type": { "type": "string", "enum": [ "exact", "over7", "under7", "odd", "even" ], "description": "Type of dice bet" }, "amount": { "type": "number", "default": 1.0, "description": "Bet amount" }, "target": { "type": "integer", "description": "Target number (for exact bet type)" }, "player_id": { "type": "string", "default": "anonymous" }, "player_seed": { "type": "string", "description": "Optional client-provided seed for fairness verification" }, "operator_key": { "type": "string", "default": "fairseal-house" } } }, "example": { "bet_type": "over7", "amount": 10, "player_id": "player_123" } } } }, "responses": { "202": { "description": "Bet accepted, pending resolution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BetAccepted" }, "example": { "accepted": true, "bet_id": "a1b2c3d4e5f6", "game_id": "g_abc123", "resolves_at_epoch": 43, "message": "Dice bet accepted. Result after next VDF epoch (~5s)." } } } }, "400": { "description": "Invalid bet type or parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "valid_bet_types": { "type": "array", "items": { "type": "string" } }, "example": { "type": "object" } } } } } } } } }, "/api/v1/games/sicbo/bet": { "post": { "summary": "Place a Sic Bo Bet", "description": "Place a bet on a three-dice Sic Bo (骰寶) game. All outcomes are provably fair via VDF.", "operationId": "placeSicBoBet", "tags": [ "Games" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "bet_type" ], "properties": { "bet_type": { "type": "string", "enum": [ "big", "small", "odd", "even", "total", "single", "double", "triple", "anyTriple", "combo" ], "description": "Type of Sic Bo bet" }, "amount": { "type": "number", "default": 1.0, "description": "Bet amount" }, "target": { "type": "integer", "description": "Target value (for total/single/double/triple bets)" }, "combo": { "type": "array", "items": { "type": "integer" }, "description": "Dice combination (for combo bet type)" }, "player_id": { "type": "string", "default": "anonymous" }, "player_seed": { "type": "string", "description": "Optional client-provided seed for fairness verification" }, "operator_key": { "type": "string", "default": "fairseal-house" } } }, "example": { "bet_type": "big", "amount": 10, "player_id": "player_123" } } } }, "responses": { "202": { "description": "Bet accepted, pending resolution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BetAccepted" }, "example": { "accepted": true, "bet_id": "a1b2c3d4e5f6", "game_id": "g_abc123", "resolves_at_epoch": 43, "message": "Sic Bo bet accepted. Result after next VDF epoch (~5s)." } } } }, "400": { "description": "Invalid bet type or parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "valid_bet_types": { "type": "array", "items": { "type": "string" } }, "example": { "type": "object" } } } } } } } } }, "/api/v1/rng/generate": { "post": { "summary": "Generate Raw RNG", "description": "Request raw verifiable random number generation without a game context. Poll the returned poll_url for results.", "operationId": "generateRNG", "tags": [ "Entropy" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "client_seed": { "type": "string", "description": "Optional client-provided seed" } } }, "example": { "client_seed": "my-custom-seed-123" } } } }, "responses": { "202": { "description": "RNG request accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "boolean" }, "request_id": { "type": "string" }, "game_id": { "type": "string" }, "resolves_at_epoch": { "type": "integer" }, "poll_url": { "type": "string", "description": "URL to poll for results" } } } } } } } } }, "/api/v1/games/{gameId}": { "get": { "summary": "Get Game Result", "description": "Retrieve the result of a specific game by ID. Returns pending status if not yet resolved.", "operationId": "getGameResult", "tags": [ "Games" ], "parameters": [ { "name": "gameId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Game ID (hex string)" } ], "responses": { "200": { "description": "Game resolved", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "resolved" }, "result": { "type": "object", "description": "Game result with proof data" }, "replay": { "type": "array", "items": { "type": "object" }, "description": "Step-by-step replay of the VDF computation" } } } } } }, "202": { "description": "Game pending resolution", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "pending" }, "message": { "type": "string" } } } } } } } } }, "/api/v1/verify/{gameId}": { "get": { "summary": "Verify a Game", "description": "Verify the fairness of a completed game. Returns proof data and replay steps for independent verification.", "operationId": "verifyGame", "tags": [ "Verification" ], "parameters": [ { "name": "gameId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Game ID to verify" } ], "responses": { "200": { "description": "Game verified", "content": { "application/json": { "schema": { "type": "object", "properties": { "game_id": { "type": "string" }, "verified": { "type": "boolean", "example": true }, "proof": { "type": "object", "description": "VDF proof data, including the on-chain anchor transaction.", "properties": { "anchorTx": { "type": "string", "nullable": true, "description": "Transaction hash of the Merkle-root anchor on the anchor chain (currently Base mainnet, chainId 8453). Canonical field — use this instead of the deprecated polygonTx." }, "anchorChain": { "type": "string", "example": "base", "description": "Name of the chain the batch Merkle root is anchored on." }, "anchorChainId": { "type": "integer", "example": 8453, "description": "EIP-155 chain ID of the anchor chain." }, "polygonTx": { "type": "string", "nullable": true, "deprecated": true, "description": "DEPRECATED legacy alias of anchorTx (kept for backward compatibility; same value). Despite the historical name, anchoring happens on Base mainnet, not Polygon. Use anchorTx." } } }, "replay_steps": { "type": "array", "items": { "type": "object" } } } } } } }, "404": { "description": "Game not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Game not found" }, "game_id": { "type": "string" } } } } } } } } }, "/api/v1/stats": { "get": { "summary": "Engine Stats", "description": "Returns VDF engine statistics including total games, epoch info, and performance metrics.", "operationId": "getStats", "tags": [ "System" ], "responses": { "200": { "description": "Engine statistics", "content": { "application/json": { "schema": { "type": "object", "properties": { "epoch": { "type": "object", "description": "Current epoch information" } }, "additionalProperties": true } } } } } } }, "/api/v1/recent": { "get": { "summary": "Recent Games", "description": "Returns the 20 most recent games.", "operationId": "getRecentGames", "tags": [ "Games" ], "responses": { "200": { "description": "List of recent games", "content": { "application/json": { "schema": { "type": "object", "properties": { "games": { "type": "array", "items": { "type": "object" } } } } } } } } } } }, "components": { "schemas": { "BetAccepted": { "type": "object", "properties": { "accepted": { "type": "boolean", "example": true }, "bet_id": { "type": "string" }, "game_id": { "type": "string" }, "resolves_at_epoch": { "type": "integer" }, "message": { "type": "string" } } } } }, "tags": [ { "name": "System", "description": "Health, stats, and service info" }, { "name": "Games", "description": "Game catalog, betting, and results" }, { "name": "Entropy", "description": "Raw entropy and RNG generation" }, { "name": "Verification", "description": "Provably fair game verification" } ] }