{ "openapi": "3.0.3", "info": { "title": "AIsa API proxy", "description": "APIs for prediction markets.", "version": "0.0.1" }, "servers": [ { "url": "https://api.aisa.one/apis/v1" } ], "security": [ { "BearerAuth": [] } ], "paths": { "/polymarket/markets": { "get": { "x-aisa-pricing": { "model": "per_request", "currency": "USD", "price_usd": 0.00044, "cost_tier": "low" }, "summary": "Get Polymarket Markets", "description": "List individual Polymarket prediction markets \u2014 one binary question each \u2014 with live pricing. Use this when you need the market-implied probability of a specific outcome, or to screen markets by size and timing; filter with `slug`, `condition_ids`, `clob_token_ids`, `tag_id`, `closed`, and the `volume_num_*` / `start_date_*` / `end_date_*` ranges.\n\nReturns a top-level array of market objects. The probability signal is `outcomes` paired with `outcomePrices`, quoted against `bestBid` / `bestAsk`; `conditionId` and `clobTokenIds` are the on-chain identifiers you need to join to other Polymarket data.\n\nFor the topic that groups several related questions together, use `get_polymarket_events`. For the same kind of question on the US-regulated Kalshi exchange, use `get_kalshi_markets`.", "operationId": "get_polymarket_markets", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of markets to return.", "schema": { "type": "integer", "minimum": 0, "example": 20 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of markets to skip for offset-based pagination.", "schema": { "type": "integer", "minimum": 0, "example": 0 } }, { "name": "order", "in": "query", "required": false, "description": "Comma-separated list of fields to order by.", "schema": { "type": "string", "example": "volume" } }, { "name": "ascending", "in": "query", "required": false, "description": "Sort ascending when true.", "schema": { "type": "boolean", "example": false } }, { "name": "id", "in": "query", "required": false, "description": "Filter by one or more Polymarket market IDs.", "schema": { "type": "array", "items": { "type": "integer" }, "example": [ 540817 ] }, "style": "form", "explode": true }, { "name": "slug", "in": "query", "required": false, "description": "Filter by one or more market slugs.", "schema": { "type": "array", "items": { "type": "string" }, "example": [ "new-rhianna-album-before-gta-vi-926" ] }, "style": "form", "explode": true }, { "name": "clob_token_ids", "in": "query", "required": false, "description": "Filter by one or more CLOB token IDs.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "condition_ids", "in": "query", "required": false, "description": "Filter by one or more market condition IDs.", "schema": { "type": "array", "items": { "type": "string" }, "example": [ "0x1fad72fae204143ff1c3035e99e7c0f65ea8d5cd9bd1070987bd1a3316f772be" ] }, "style": "form", "explode": true }, { "name": "volume_num_min", "in": "query", "required": false, "description": "Minimum total volume.", "schema": { "type": "number", "example": 1000 } }, { "name": "volume_num_max", "in": "query", "required": false, "description": "Maximum total volume.", "schema": { "type": "number", "example": 1000000 } }, { "name": "start_date_min", "in": "query", "required": false, "description": "Filter markets starting after this ISO timestamp.", "schema": { "type": "string", "format": "date-time", "example": "2025-01-01T00:00:00Z" } }, { "name": "start_date_max", "in": "query", "required": false, "description": "Filter markets starting before this ISO timestamp.", "schema": { "type": "string", "format": "date-time", "example": "2026-01-01T00:00:00Z" } }, { "name": "end_date_min", "in": "query", "required": false, "description": "Filter markets ending after this ISO timestamp.", "schema": { "type": "string", "format": "date-time", "example": "2025-01-01T00:00:00Z" } }, { "name": "end_date_max", "in": "query", "required": false, "description": "Filter markets ending before this ISO timestamp.", "schema": { "type": "string", "format": "date-time", "example": "2026-01-01T00:00:00Z" } }, { "name": "tag_id", "in": "query", "required": false, "description": "Filter by tag ID.", "schema": { "type": "integer", "example": 1 } }, { "name": "closed", "in": "query", "required": false, "description": "Filter by whether the market is closed.", "schema": { "type": "boolean", "default": false, "example": false } }, { "name": "include_tag", "in": "query", "required": false, "description": "Include tag metadata when true.", "schema": { "type": "boolean", "example": true } } ], "responses": { "200": { "description": "Top-level array of Polymarket market objects", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "example": "540817" }, "question": { "type": "string", "example": "New Rihanna Album before GTA VI?" }, "slug": { "type": "string", "example": "new-rhianna-album-before-gta-vi-926" }, "conditionId": { "type": "string", "example": "0x1fad72fae204143ff1c3035e99e7c0f65ea8d5cd9bd1070987bd1a3316f772be" }, "clobTokenIds": { "description": "Polymarket CLOB token IDs. The upstream Gamma API may encode this as a JSON string.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "outcomes": { "description": "Market outcomes. The upstream Gamma API may encode this as a JSON string.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "outcomePrices": { "description": "Outcome prices. The upstream Gamma API may encode this as a JSON string.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "active": { "type": "boolean" }, "closed": { "type": "boolean" }, "liquidity": { "type": "string" }, "volume": { "type": "string" }, "volumeNum": { "type": "number" }, "bestBid": { "type": "number" }, "bestAsk": { "type": "number" }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time" }, "image": { "type": "string" }, "icon": { "type": "string" }, "description": { "type": "string" } } } } } } }, "400": { "description": "Bad Request - Invalid parameters or validation errors", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Invalid search parameter" }, "message": { "type": "string", "example": "search must be at least 2 characters long" } } }, "examples": { "search_too_short": { "summary": "Search query too short", "value": { "error": "Invalid search parameter", "message": "search must be at least 2 characters long" } }, "search_with_other_params": { "summary": "Search with other parameters", "value": { "error": "Invalid query parameters", "message": "search parameter cannot be used with other filter parameters" } }, "invalid_limit": { "summary": "Invalid limit", "value": { "error": "Invalid limit parameter", "message": "limit must be a number between 1 and 100" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Internal Server Error" }, "message": { "type": "string", "example": "Failed to fetch markets data" } } } } } } } } }, "/polymarket/events": { "get": { "x-aisa-pricing": { "model": "per_request", "currency": "USD", "price_usd": 0.00044, "cost_tier": "low" }, "summary": "Get Polymarket Events", "description": "List Polymarket events \u2014 the topic-level grouping that bundles related markets, such as an election or a season-long series. Use this to browse by subject rather than by individual question, or to find every market attached to one storyline; filter with `tag_slug`, `active`, `featured`, `archived`, `closed`, and the liquidity / volume ranges.\n\nReturns a top-level array of event objects with `title`, `ticker`, `slug`, `volume`, `volume24hr`, `liquidity`, `startDate` / `endDate`, and a nested `markets` array holding the tradable questions.\n\nWhen you already know which question you want and need its price, use `get_polymarket_markets` instead.", "operationId": "get_polymarket_events", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of events to return.", "schema": { "type": "integer", "minimum": 0, "example": 20 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of events to skip for offset-based pagination.", "schema": { "type": "integer", "minimum": 0, "example": 0 } }, { "name": "order", "in": "query", "required": false, "description": "Comma-separated list of fields to order by.", "schema": { "type": "string", "example": "volume" } }, { "name": "ascending", "in": "query", "required": false, "description": "Sort ascending when true.", "schema": { "type": "boolean", "example": false } }, { "name": "id", "in": "query", "required": false, "description": "Filter by one or more event IDs.", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true }, { "name": "slug", "in": "query", "required": false, "description": "Filter by one or more event slugs.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "tag_id", "in": "query", "required": false, "description": "Filter by tag ID.", "schema": { "type": "integer" } }, { "name": "tag_slug", "in": "query", "required": false, "description": "Filter by tag slug.", "schema": { "type": "string", "example": "sports" } }, { "name": "active", "in": "query", "required": false, "description": "Filter by active events.", "schema": { "type": "boolean" } }, { "name": "archived", "in": "query", "required": false, "description": "Filter by archived events.", "schema": { "type": "boolean" } }, { "name": "featured", "in": "query", "required": false, "description": "Filter by featured events.", "schema": { "type": "boolean" } }, { "name": "closed", "in": "query", "required": false, "description": "Filter by whether the event is closed.", "schema": { "type": "boolean" } }, { "name": "liquidity_min", "in": "query", "required": false, "description": "Minimum liquidity.", "schema": { "type": "number" } }, { "name": "liquidity_max", "in": "query", "required": false, "description": "Maximum liquidity.", "schema": { "type": "number" } }, { "name": "volume_min", "in": "query", "required": false, "description": "Minimum volume.", "schema": { "type": "number" } }, { "name": "volume_max", "in": "query", "required": false, "description": "Maximum volume.", "schema": { "type": "number" } }, { "name": "start_date_min", "in": "query", "required": false, "description": "Filter events starting after this ISO timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "start_date_max", "in": "query", "required": false, "description": "Filter events starting before this ISO timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_date_min", "in": "query", "required": false, "description": "Filter events ending after this ISO timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_date_max", "in": "query", "required": false, "description": "Filter events ending before this ISO timestamp.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Top-level array of Polymarket event objects", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "ticker": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "active": { "type": "boolean" }, "closed": { "type": "boolean" }, "archived": { "type": "boolean" }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time" }, "volume": { "type": "string" }, "volume24hr": { "type": "number" }, "liquidity": { "type": "number" }, "image": { "type": "string" }, "icon": { "type": "string" }, "markets": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } } }, "400": { "description": "Bad Request - Invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Invalid status parameter" }, "message": { "type": "string", "example": "status must be 'open' or 'closed'" } } }, "examples": { "invalid_status": { "summary": "Invalid status", "value": { "error": "Invalid status parameter", "message": "status must be 'open' or 'closed'" } }, "invalid_limit": { "summary": "Invalid limit", "value": { "error": "Invalid limit parameter", "message": "limit must be a number between 1 and 100" } }, "invalid_offset": { "summary": "Invalid offset", "value": { "error": "Invalid offset parameter", "message": "offset must be a non-negative number" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Internal Server Error" }, "message": { "type": "string", "example": "Failed to fetch events data" } } } } } } } } }, "/polymarket/activity": { "get": { "x-aisa-pricing": { "model": "per_request", "currency": "USD", "price_usd": 0.012, "cost_tier": "med" }, "summary": "Get Polymarket Wallet Activity", "description": "Get one wallet's on-chain Polymarket activity \u2014 a per-address lookup, not a market-wide trade feed. The `user` parameter is required. Use it to reconstruct what a specific trader did \u2014 position splits, merges and redemptions, with size, price, and the transaction that settled them; narrow further with `market_slug`, `condition_id`, and the `start_time` / `end_time` Unix-second range.\n\nReturns `activities[]` with `side` (`MERGE` / `SPLIT` / `REDEEM`), `market_slug`, `condition_id`, `shares`, `price`, `timestamp`, and `tx_hash`, plus a `pagination` object whose key you pass back as `pagination_key`.\n\nFor market-wide prices rather than one wallet's history, use `get_polymarket_markets`.", "operationId": "get_polymarket_activity", "parameters": [ { "name": "user", "in": "query", "required": true, "description": "Wallet address or user identifier. Required by the runtime route.", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "example": "0x7c3db723f1d4d8cb9c550095203b686cb11e5c6b" } }, { "name": "start_time", "in": "query", "required": false, "description": "Filter activity from this Unix timestamp in seconds (inclusive)", "schema": { "type": "integer", "example": 1640995200 } }, { "name": "end_time", "in": "query", "required": false, "description": "Filter activity until this Unix timestamp in seconds (inclusive)", "schema": { "type": "integer", "example": 1672531200 } }, { "name": "market_slug", "in": "query", "required": false, "description": "Filter activity by market slug", "schema": { "type": "string", "example": "bitcoin-up-or-down-july-25-8pm-et" } }, { "name": "condition_id", "in": "query", "required": false, "description": "Filter activity by condition ID", "schema": { "type": "string", "example": "0x4567b275e6b667a6217f5cb4f06a797d3a1eaf1d0281fb5bc8c75e2046ae7e57" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of activities to return (1-1000)", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100, "example": 50 } }, { "name": "pagination_key", "in": "query", "required": false, "description": "Base64-encoded cursor for efficient pagination. Returned in the previous response's pagination object.", "schema": { "type": "string", "example": "eyJibG9ja190aW1lc3RhbXAiOiIyMDI1LTAxLTE5VDEyOjAwOjAwLjAwMFoiLCJzaWRlIjoiU1BMSVQiLCJ0eF9oYXNoIjoiMHgxMjM0NTY3ODkwYWJjZGVmIiwibG9nX2luZGV4IjoxMCwidG90YWwiOjE5ODkwMTc3Nn0=" } } ], "responses": { "200": { "description": "Activity response with pagination", "content": { "application/json": { "schema": { "type": "object", "properties": { "activities": { "type": "array", "items": { "type": "object", "properties": { "token_id": { "type": "string", "example": "" }, "side": { "type": "string", "enum": [ "MERGE", "SPLIT", "REDEEM" ], "example": "REDEEM" }, "market_slug": { "type": "string", "example": "will-the-doj-charge-boeing" }, "condition_id": { "type": "string", "example": "0x92e4b1b8e0621fab0537486e7d527322569d7a8fd394b3098ff4bb1d6e1c0bbd" }, "shares": { "type": "number", "example": 187722726, "description": "Raw number of shares (from the blockchain)" }, "shares_normalized": { "type": "number", "example": 187.722726, "description": "Number of shares normalized (raw divided by 1000000)" }, "price": { "type": "number", "example": 1 }, "block_number": { "type": "integer", "description": "Block number where the activity occurred", "example": 123456789 }, "log_index": { "type": "integer", "description": "Log index of the activity event in the block", "example": 42 }, "tx_hash": { "type": "string", "example": "0x028baff23a90c10728606781d15077098ee93c991ea204aa52a0bd2869187574" }, "title": { "type": "string", "example": "Will the DOJ charge Boeing?" }, "timestamp": { "type": "integer", "description": "Unix timestamp in seconds when the activity occurred", "example": 1721263049 }, "order_hash": { "type": "string", "example": "" }, "user": { "type": "string", "description": "User wallet address", "example": "0xfd9c3e7f8c56eb4186372f343c873cce154b3873" } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "example": 50 }, "count": { "type": "integer", "description": "Total number of activities matching the filters", "example": 1250 }, "has_more": { "type": "boolean", "description": "Whether there are more activities available", "example": true }, "pagination_key": { "type": "string", "description": "Base64-encoded cursor for the next page. Only present when there are more results.", "example": "eyJibG9ja190aW1lc3RhbXAiOiIyMDI1LTAxLTE5VDEyOjAwOjAwLjAwMFoiLCJzaWRlIjoiU1BMSVQiLCJ0eF9oYXNoIjoiMHgxMjM0NTY3ODkwYWJjZGVmIiwibG9nX2luZGV4IjoxMCwidG90YWwiOjE5ODkwMTc3Nn0=" } } } } } } } }, "400": { "description": "Bad Request - Invalid parameters or validation errors", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Missing required parameter" }, "message": { "type": "string", "example": "user parameter is required" } } }, "examples": { "invalid_start_time": { "summary": "Invalid start_time parameter", "value": { "error": "Invalid start_time parameter", "message": "start_time must be a valid Unix timestamp" } }, "invalid_end_time": { "summary": "Invalid end_time parameter", "value": { "error": "Invalid end_time parameter", "message": "end_time must be a valid Unix timestamp" } }, "invalid_time_range": { "summary": "Invalid time range", "value": { "error": "Invalid time range", "message": "start_time must be less than end_time" } }, "invalid_limit": { "summary": "Invalid limit", "value": { "error": "Invalid limit parameter", "message": "limit must be a number between 1 and 1000" } }, "invalid_pagination_key": { "summary": "Invalid pagination key", "value": { "error": "Invalid pagination key", "message": "pagination_key is invalid or corrupted" } }, "invalid_filter_combination": { "summary": "Invalid filter combination", "value": { "error": "Invalid filter combination", "message": "Only one of market_slug or condition_id can be provided" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Internal Server Error" }, "message": { "type": "string", "example": "Failed to fetch activity data" } } } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "AISA API Key", "description": "Your AIsa API key as a Bearer token." } } } }