{ "openapi": "3.1.0", "info": { "title": "Prediction Market API", "description": "API endpoints for trading on prediction markets and querying market data, user positions, and activity via workflows.", "version": "1.0.0", "contact": { "name": "Swaps.xyz", "url": "https://swaps.xyz" } }, "servers": [ { "url": "https://api-v2.swaps.xyz", "description": "Production server" } ], "paths": { "/api/workflows/polymarket/search": { "get": { "summary": "Search Markets", "description": "Search for markets and events by query string or tags.", "operationId": "searchMarkets", "parameters": [ { "name": "q", "in": "query", "description": "Search query string. Use '*' to return all results.", "schema": { "type": "string" }, "example": "new-england-patriots" }, { "name": "tagIds", "in": "query", "description": "Array of tag IDs to filter by (can be repeated)", "schema": { "type": "array", "items": { "type": "integer" } }, "style": "form", "explode": true, "example": [ 450, 226 ] }, { "name": "page", "in": "query", "description": "Page number for pagination", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "description": "Limit results per type", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "activeOnly", "in": "query", "description": "Only return markets currently accepting orders", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Successful search response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardizedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/workflows/polymarket/getTags": { "get": { "summary": "Get Tags", "description": "Retrieve all available tags for filtering markets.", "operationId": "getTags", "parameters": [ { "name": "limit", "in": "query", "description": "Number of tags to return", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Zero-based index of first tag to return", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "slug", "in": "query", "description": "Filter by tag slug", "schema": { "type": "string" }, "example": "nfl" } ], "responses": { "200": { "description": "Array of tags", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/workflows/polymarket/getEvent": { "get": { "summary": "Get Event", "description": "Retrieve detailed information about a specific event, including all associated markets.", "operationId": "getEvent", "parameters": [ { "name": "slug", "in": "query", "required": true, "description": "Event slug identifier", "schema": { "type": "string" }, "example": "largest-company-end-of-2025" } ], "responses": { "200": { "description": "Event details with markets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/workflows/polymarket/getMarkets": { "get": { "summary": "Get Markets", "description": "Retrieve market information by CLOB token IDs, slugs, or tag ID.", "operationId": "getMarkets", "parameters": [ { "name": "clobTokenIds", "in": "query", "description": "Array of CLOB token IDs (can be repeated)", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true, "example": [ "80746058984644290629624903019922696017323803605256698757445938534814122585786" ] }, { "name": "slug", "in": "query", "description": "Market slug identifier", "schema": { "type": "string" }, "example": "fed-decreases-interest-rates-by-50-bps-after-december-2025-meeting" }, { "name": "tagId", "in": "query", "description": "Filter by tag ID", "schema": { "type": "integer" }, "example": 10 } ], "responses": { "200": { "description": "Market events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/workflows/polymarket/getMarketPrice": { "get": { "summary": "Get Market Price", "description": "Retrieve the current best price for a specific token and side (BUY or SELL).", "operationId": "getMarketPrice", "parameters": [ { "name": "clobTokenId", "in": "query", "required": true, "description": "CLOB token ID", "schema": { "type": "string" }, "example": "80746058984644290629624903019922696017323803605256698757445938534814122585786" }, { "name": "side", "in": "query", "required": true, "description": "Order side (BUY or SELL)", "schema": { "type": "string", "enum": [ "BUY", "SELL" ] }, "example": "BUY" } ], "responses": { "200": { "description": "Current market price", "content": { "application/json": { "schema": { "type": "object", "required": [ "price" ], "properties": { "price": { "type": "string", "description": "Current best price for the specified side", "example": "0.52" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/workflows/polymarket/getPriceHistory": { "get": { "summary": "Get Price History", "description": "Retrieve historical price data for a specific token over a given time interval.", "operationId": "getPriceHistory", "parameters": [ { "name": "clobTokenId", "in": "query", "required": true, "description": "CLOB token ID", "schema": { "type": "string" }, "example": "47380452228751713070322726097676074449505499789775322838989368264459427079864" }, { "name": "interval", "in": "query", "required": true, "description": "Time interval for price history", "schema": { "type": "string", "enum": [ "1hr", "1d", "1w", "1m", "max" ] }, "example": "1d" } ], "responses": { "200": { "description": "Price history data", "content": { "application/json": { "schema": { "type": "object", "required": [ "history" ], "properties": { "history": { "type": "array", "items": { "type": "object", "required": [ "t", "p" ], "properties": { "t": { "type": "integer", "description": "Unix timestamp", "example": 1735689600 }, "p": { "type": "number", "format": "float", "description": "Price at timestamp", "example": 0.52 } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/workflows/polymarket/getTrendingMarkets": { "get": { "summary": "Get Trending Markets", "description": "Retrieve trending markets sorted by 24-hour volume. Markets must have minimum $150K of 24h volume.", "operationId": "getTrendingMarkets", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of results to return", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "page", "in": "query", "description": "Page number for pagination", "schema": { "type": "integer", "minimum": 1, "default": 1 } } ], "responses": { "200": { "description": "Trending markets response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardizedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/workflows/polymarket/getCurrentPositions": { "get": { "summary": "Get Current Positions", "description": "Retrieve all current open positions for a specific user.", "operationId": "getCurrentPositions", "parameters": [ { "name": "userId", "in": "query", "required": true, "description": "User EVM EOA address", "schema": { "$ref": "#/components/schemas/Address" }, "example": "0x0797bfec6d2d4f733d461bbee8125805e9e9c892" }, { "name": "proxyWallet", "in": "query", "description": "Polymarket proxy wallet address", "schema": { "$ref": "#/components/schemas/Address" } }, { "name": "redeemable", "in": "query", "description": "Filter for redeemable positions only", "schema": { "type": "boolean", "default": false } }, { "name": "mergeable", "in": "query", "description": "Filter for mergeable positions only", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Array of current positions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Position" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/workflows/polymarket/getClosedPositions": { "get": { "summary": "Get Closed Positions", "description": "Retrieve closed positions (resolved markets) for a specific user.", "operationId": "getClosedPositions", "parameters": [ { "name": "userId", "in": "query", "required": true, "description": "User EVM EOA address", "schema": { "$ref": "#/components/schemas/Address" }, "example": "0x0797bfec6d2d4f733d461bbee8125805e9e9c892" }, { "name": "proxyWallet", "in": "query", "description": "Polymarket proxy wallet address", "schema": { "$ref": "#/components/schemas/Address" } } ], "responses": { "200": { "description": "Array of closed positions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ClosedPosition" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/workflows/polymarket/getTrades": { "get": { "summary": "Get Trades", "description": "Retrieve trade history for a specific user.", "operationId": "getTrades", "parameters": [ { "name": "userId", "in": "query", "required": true, "description": "User EVM EOA address", "schema": { "$ref": "#/components/schemas/Address" }, "example": "0x0797bfec6d2d4f733d461bbee8125805e9e9c892" }, { "name": "proxyWallet", "in": "query", "description": "Polymarket proxy wallet address", "schema": { "$ref": "#/components/schemas/Address" } } ], "responses": { "200": { "description": "Array of trades", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Trade" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/workflows/polymarket/getActivity": { "get": { "summary": "Get Activity", "description": "Retrieve comprehensive activity history for a specific user, including orders, trades, and other actions.", "operationId": "getActivity", "parameters": [ { "name": "userId", "in": "query", "required": true, "description": "User EVM EOA address", "schema": { "$ref": "#/components/schemas/Address" }, "example": "0x0797bfec6d2d4f733d461bbee8125805e9e9c892" }, { "name": "proxyWallet", "in": "query", "description": "Polymarket proxy wallet address", "schema": { "$ref": "#/components/schemas/Address" } } ], "responses": { "200": { "description": "Array of activity items", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Activity" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/workflows/polymarket/getPnL": { "get": { "summary": "Get Profit and Loss", "description": "Retrieve aggregate profit and loss information across all positions for a specific user.", "operationId": "getPnL", "parameters": [ { "name": "userId", "in": "query", "required": true, "description": "User EVM EOA address", "schema": { "$ref": "#/components/schemas/Address" }, "example": "0x0797bfec6d2d4f733d461bbee8125805e9e9c892" }, { "name": "proxyWallet", "in": "query", "description": "Polymarket proxy wallet address", "schema": { "$ref": "#/components/schemas/Address" } } ], "responses": { "200": { "description": "Profit and loss summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PnLResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/workflows/polymarket/createOrFetchPolymarketUser": { "post": { "summary": "Create or Fetch User", "description": "Creates a new Swaps account for a user or fetches an existing one based on the provided EVM address.", "operationId": "createOrFetchPolymarketUser", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrFetchPolymarketUserRequest" } } } }, "responses": { "200": { "description": "Successful response with user information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrFetchPolymarketUserResponse" } } } }, "400": { "description": "Bad request due to missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowErrorResponse" } } } } } } }, "/api/workflows/polymarket/placeOrder": { "post": { "summary": "Place Order", "description": "Places a market order (BUY or SELL) directly against the Polymarket CLOB on behalf of the user, using their pre-funded proxy wallet.\n\nThis endpoint always requires an EIP-712 `signatureByEvmEoa` produced by the user's EOA — see the [Polymarket Signing Guide](/prediction-market-reference/polymarket-signing). The endpoint submits the order synchronously and returns `{ txId, orderResponse }` so callers can poll workflow status.", "operationId": "placeOrder", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "evmEoa", "orderRequest", "expiration", "signatureByEvmEoa" ], "properties": { "evmEoa": { "$ref": "#/components/schemas/EvmAddress", "description": "User's EVM wallet address" }, "proxyWallet": { "$ref": "#/components/schemas/EvmAddress", "description": "Proxy wallet address (optional)" }, "orderRequest": { "type": "object", "required": [ "side", "tokenID", "orderType", "tickSize", "negRisk", "amount", "slippage" ], "properties": { "side": { "type": "string", "enum": [ "BUY", "SELL" ], "description": "Order side" }, "tokenID": { "type": "string", "description": "Polymarket CLOB token ID of the outcome to trade" }, "orderType": { "type": "string", "enum": [ "FOK", "FAK" ], "description": "Order type - Fill-Or-Kill (FOK) or Fill-And-Kill (FAK)" }, "tickSize": { "type": "string", "description": "Tick size from the market details (e.g., '0.01')" }, "negRisk": { "type": "boolean", "description": "Negative risk flag from the market details" }, "amount": { "type": "number", "description": "Order amount in USD (must be a positive number)" }, "slippage": { "type": "number", "description": "Slippage tolerance in basis points" } } }, "expiration": { "type": "integer", "description": "Unix timestamp (seconds) when `signatureByEvmEoa` expires. Must be in the future and ≤ 300s ahead." }, "signatureByEvmEoa": { "$ref": "#/components/schemas/Hex", "description": "EIP-712 signature by the EOA over the `PlaceOrder` typed data. See the [Polymarket Signing Guide](/prediction-market-reference/polymarket-signing)." } }, "example": { "evmEoa": "0xB9519a08267d7B259eCA6DbD8F7286B1f176A41f", "orderRequest": { "side": "BUY", "tokenID": "90234889617199443673709150877675264662915727532354468551650133547723659310093", "orderType": "FOK", "tickSize": "0.01", "negRisk": true, "amount": 5, "slippage": 100 }, "expiration": 1735689600, "signatureByEvmEoa": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890001b" } } } } }, "responses": { "200": { "description": "Order placed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "txId": { "type": "string", "description": "Box transaction ID for the order workflow" }, "orderResponse": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the order was accepted" }, "errorMsg": { "type": "string", "description": "Error message if the order failed (empty string if successful)" }, "orderID": { "type": "string", "description": "Unique Polymarket order ID" }, "transactionsHashes": { "type": "array", "items": { "type": "string" }, "description": "Array of on-chain transaction hashes produced by the order" }, "status": { "type": "string", "description": "Order status (e.g. 'matched', 'LIVE')" }, "takingAmount": { "type": "string", "description": "Amount of the counter asset taken in (USDC for BUY, outcome tokens for SELL)" }, "makingAmount": { "type": "string", "description": "Amount of the offered asset (USDC for BUY, outcome tokens for SELL)" } } } }, "example": { "txId": "0xa66c86a47f4f81caae5d767e2d8a5a7def1a191d24eba5bd49f8767297cfe2e5", "orderResponse": { "success": true, "errorMsg": "", "orderID": "0xb9826fe87ddf21261eceaf513977cb5ea1ae31ac173210857c879cef936dfa2b", "transactionsHashes": [ "0x39ac6726cf2cfb7814bdb2e04aeeea1d3bde2d1ce7e357f79a404cacb6984f35" ], "status": "matched", "takingAmount": "8.5", "makingAmount": "5" } } } } } }, "400": { "description": "Bad request due to missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key, or invalid/expired `signatureByEvmEoa`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowErrorResponse" } } } } } } }, "/api/workflows/polymarket/sellPosition": { "post": { "summary": "Sell Position", "description": "Sells an existing position in a Polymarket market. This endpoint allows users to exit their positions by selling their outcome tokens using market orders (FOK/FAK).\n\nEvery request must include `expiration` and an EIP-712 `signatureByEvmEoa` over the `SellPosition` typed data — see the [Polymarket Signing Guide](/prediction-market-reference/polymarket-signing).\n\nProceeds default to the caller's `evmEoa`. To deliver them to a different wallet or token, set `dstWalletAddress` and/or `dstToken`.", "operationId": "sellPosition", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "evmEoa", "side", "tokenID", "orderType", "tickSize", "negRisk", "amount", "expiration", "signatureByEvmEoa" ], "properties": { "evmEoa": { "$ref": "#/components/schemas/EvmAddress", "description": "EVM address (wallet address)" }, "proxyWallet": { "$ref": "#/components/schemas/EvmAddress", "description": "Proxy wallet address (optional)" }, "side": { "type": "string", "enum": [ "SELL" ], "description": "Order side - must be SELL" }, "tokenID": { "type": "string", "description": "Polymarket CLOB token ID of the position to sell" }, "orderType": { "type": "string", "enum": [ "FOK", "FAK" ], "description": "Order type - Fill-Or-Kill (FOK) or Fill-And-Kill (FAK) for market orders" }, "tickSize": { "type": "string", "description": "Tick size from the market details (e.g., '0.01')" }, "negRisk": { "type": "boolean", "description": "Negative risk flag from the market details" }, "amount": { "type": "number", "description": "Amount of tokens to sell (must be a positive number)" }, "slippage": { "type": "number", "description": "Slippage tolerance in basis points (optional, defaults to 0)" }, "dstToken": { "$ref": "#/components/schemas/PolymarketDstToken", "description": "Optional destination token. When set, sale proceeds are swapped into this token (address + chainId) before delivery." }, "dstWalletAddress": { "$ref": "#/components/schemas/EvmAddress", "description": "Optional wallet that receives the proceeds instead of the caller's `evmEoa`." }, "expiration": { "type": "integer", "description": "Unix timestamp (seconds) when `signatureByEvmEoa` expires. Must be in the future and ≤ 300s ahead." }, "signatureByEvmEoa": { "$ref": "#/components/schemas/Hex", "description": "EIP-712 signature by the EOA over the `SellPosition` typed data. See the [Polymarket Signing Guide](/prediction-market-reference/polymarket-signing)." } }, "example": { "evmEoa": "0xB9519a08267d7B259eCA6DbD8F7286B1f176A41f", "side": "SELL", "tokenID": "90234889617199443673709150877675264662915727532354468551650133547723659310093", "orderType": "FAK", "tickSize": "0.01", "negRisk": true, "amount": 2, "slippage": 100, "expiration": 1735689600, "signatureByEvmEoa": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890001b" } } } } }, "responses": { "200": { "description": "Position sold successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "txId": { "type": "string", "description": "Transaction ID" }, "orderResponse": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the sell order was successful" }, "errorMsg": { "type": "string", "description": "Error message if the order failed (empty string if successful)" }, "orderID": { "type": "string", "description": "Unique order ID" }, "transactionsHashes": { "type": "array", "items": { "type": "string" }, "description": "Array of transaction hashes" }, "status": { "type": "string", "description": "Order status (e.g., 'matched')" }, "takingAmount": { "type": "string", "description": "Amount of USDC received" }, "makingAmount": { "type": "string", "description": "Amount of tokens sold" } } } }, "example": { "txId": "0xa66c86a47f4f81caae5d767e2d8a5a7def1a191d24eba5bd49f8767297cfe2e5", "orderResponse": { "success": true, "errorMsg": "", "orderID": "0xb9826fe87ddf21261eceaf513977cb5ea1ae31ac173210857c879cef936dfa2b", "transactionsHashes": [ "0x39ac6726cf2cfb7814bdb2e04aeeea1d3bde2d1ce7e357f79a404cacb6984f35" ], "status": "matched", "takingAmount": "1.376", "makingAmount": "2" } } } } } }, "400": { "description": "Bad request due to missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowErrorResponse" } } } } } } }, "/api/workflows/polymarket/redeemPosition": { "post": { "summary": "Redeem Position", "description": "Redeems position from a resolved Polymarket market. For positions with a current value > 0, this endpoint allows users to claim their winnings from a specific market condition. For losing positions with a current value = 0, this endpoint allows users to burn their position tokens to clean up their account. \n Endpoint awaits successful execution of the redemption transaction before returning the transaction hash.\n\nEvery request must include `expiration` and an EIP-712 `signatureByEvmEoa` over the `RedeemPosition` typed data — see the [Polymarket Signing Guide](/prediction-market-reference/polymarket-signing).\n\nProceeds default to the caller's `evmEoa`. To deliver them to a different wallet or token, set `dstWalletAddress` and/or `dstToken`.", "operationId": "redeemPosition", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "evmEoa", "conditionId", "assetId", "expiration", "signatureByEvmEoa" ], "properties": { "evmEoa": { "$ref": "#/components/schemas/EvmAddress", "description": "User's EVM wallet address" }, "conditionId": { "type": "string", "description": "Polymarket condition ID for the position to redeem", "example": "0x52f13a5eaf375170189f326e58cc6d217515de1cf9e41bff17be7779ea9a295c" }, "assetId": { "type": "string", "description": "Polymarket asset ID for the asset to redeem", "example": "25851216745091725550702226389795916287148711992808817855215289655518936398397" }, "dstToken": { "$ref": "#/components/schemas/PolymarketDstToken", "description": "Optional destination token. When set, redeemed USDC.e is swapped into this token (address + chainId) before delivery." }, "dstWalletAddress": { "$ref": "#/components/schemas/EvmAddress", "description": "Optional wallet that receives the proceeds instead of the caller's `evmEoa`." }, "expiration": { "type": "integer", "description": "Unix timestamp (seconds) when `signatureByEvmEoa` expires. Must be in the future and ≤ 300s ahead." }, "signatureByEvmEoa": { "$ref": "#/components/schemas/Hex", "description": "EIP-712 signature by the EOA over the `RedeemPosition` typed data. See the [Polymarket Signing Guide](/prediction-market-reference/polymarket-signing)." } } } } } }, "responses": { "200": { "description": "Position redeemed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "txId", "txHash", "status" ], "properties": { "txId": { "type": "string", "description": "Workflow transaction ID. Track execution with `GET /workflows/getStatus`." }, "txHash": { "$ref": "#/components/schemas/Hex", "description": "Transaction hash of the redemption" }, "status": { "type": "string", "description": "Status message of the redemption" } } } } } }, "400": { "description": "Bad request due to missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowErrorResponse" } } } } } } }, "/api/workflows/polymarket/mergePositions": { "post": { "summary": "Merge Position", "description": "Merges a full set of position tokens back into collateral by burning them. Can be used to claim winnings from resolved markets or clean up positions. Endpoint awaits successful execution of the merge transaction before returning the transaction hash.", "operationId": "mergePositions", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "evmEoa", "conditionId" ], "properties": { "evmEoa": { "$ref": "#/components/schemas/EvmAddress", "description": "User's EVM wallet address" }, "conditionId": { "type": "string", "description": "Polymarket condition ID for the position to redeem", "example": "0x52f13a5eaf375170189f326e58cc6d217515de1cf9e41bff17be7779ea9a295c" } } } } } }, "responses": { "200": { "description": "Positions merged successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "txId", "txHash", "status" ], "properties": { "txId": { "type": "string", "description": "Workflow transaction ID. Track execution with `GET /workflows/getStatus`." }, "txHash": { "$ref": "#/components/schemas/Hex", "description": "Transaction hash of the redemption" }, "status": { "type": "string", "description": "Status message of the merge" } } } } } }, "400": { "description": "Bad request due to missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowErrorResponse" } } } } } } }, "/api/workflows/getStatus": { "get": { "summary": "Get Workflow Status", "description": "Retrieves the status of a workflow transaction by transaction ID.", "operationId": "getWorkflowStatus", "parameters": [ { "name": "txId", "in": "query", "description": "Transaction ID from /getAction request", "required": true, "schema": { "type": "string", "example": "0x1b121f30eeddfc1ee3eeb491c02be6c4b676b0ac0ac3e309fa25f010172c5af4" } } ], "responses": { "200": { "description": "Workflow status response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowStatusResponse" } } } }, "400": { "description": "Bad request due to missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowErrorResponse" } } } }, "404": { "description": "Workflow not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowErrorResponse" } } } } } } }, "/api/workflows/polymarket/withdraw": { "post": { "summary": "Withdraw", "description": "Withdraws the user's Polymarket proxy-wallet collateral to an arbitrary `dstWalletAddress`. Optional `dstToken` swaps the proxy collateral into a different token (and/or chain) before delivery.\n\nThis endpoint **always requires** an EIP-712 `signatureByEvmEoa` produced by the user's EOA over `{ dstToken, dstWalletAddress, expiration }` — see the [Polymarket Signing Guide](/prediction-market-reference/polymarket-signing). The signature is what authorizes funds being sent to a wallet other than the EOA.\n\nThe endpoint awaits successful execution of the withdrawal transaction before returning the transaction hash.", "operationId": "withdraw", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "evmEoa", "dstWalletAddress", "expiration", "signatureByEvmEoa" ], "properties": { "evmEoa": { "$ref": "#/components/schemas/EvmAddress", "description": "User's EVM wallet address (the signer)" }, "dstWalletAddress": { "$ref": "#/components/schemas/EvmAddress", "description": "Wallet address that receives the withdrawn funds" }, "srcTokenAddress": { "$ref": "#/components/schemas/EvmAddress", "description": "Optional source token address to withdraw from the proxy wallet. Always on Polygon, so only the address is needed. Defaults to pUSD collateral. Set to USDC.e to sweep funds stuck as USDC.e." }, "dstToken": { "$ref": "#/components/schemas/PolymarketDstToken", "description": "Optional destination token (address + chainId). When set, the source token is swapped into this token before delivery." }, "expiration": { "type": "integer", "description": "Unix timestamp (seconds) when the signature expires. Must be within the next ~300 seconds." }, "signatureByEvmEoa": { "$ref": "#/components/schemas/Hex", "description": "EIP-712 signature by the EOA over the `Withdraw` typed data." } } } } } }, "responses": { "200": { "description": "Withdrawal executed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "txId", "txHash", "status" ], "properties": { "txId": { "type": "string", "description": "Workflow transaction ID. Track execution with `GET /workflows/getStatus`." }, "txHash": { "$ref": "#/components/schemas/Hex", "description": "Transaction hash of the withdrawal" }, "status": { "type": "string", "description": "Status message of the withdrawal" } } } } } }, "400": { "description": "Bad request due to missing or invalid parameters, or an invalid/expired signature", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowErrorResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowErrorResponse" } } } } } } } }, "components": { "schemas": { "Address": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address (0x prefix + 40 hex characters)", "example": "0x1234567890123456789012345678901234567890" }, "Tag": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "Unique tag identifier" }, "label": { "type": "string", "nullable": true, "description": "Human-readable tag label" }, "slug": { "type": "string", "nullable": true, "description": "URL-friendly tag identifier" }, "forceShow": { "type": "boolean", "nullable": true, "description": "Whether to force show this tag" }, "publishedAt": { "type": "string", "nullable": true, "description": "Tag publication timestamp (format: YYYY-MM-DD HH:mm:ss.SSS+00)" }, "createdBy": { "type": "integer", "nullable": true, "description": "ID of user who created the tag" }, "updatedBy": { "type": "integer", "nullable": true, "description": "ID of user who last updated the tag" }, "createdAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Tag creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Tag last update timestamp" }, "forceHide": { "type": "boolean", "nullable": true, "description": "Whether to force hide this tag" }, "isCarousel": { "type": "boolean", "nullable": true, "description": "Whether this tag is a carousel tag" }, "requiresTranslation": { "type": "boolean", "nullable": true, "description": "Whether this tag requires translation" } } }, "Series": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "Unique series identifier" }, "ticker": { "type": [ "string", "null" ], "description": "Series ticker symbol" }, "slug": { "type": [ "string", "null" ], "description": "URL-friendly series identifier" }, "title": { "type": [ "string", "null" ], "description": "Series title" }, "seriesType": { "type": [ "string", "null" ], "description": "Type of series (e.g., 'single')" }, "recurrence": { "type": [ "string", "null" ], "description": "Recurrence pattern (e.g., 'monthly', 'weekly')" }, "image": { "type": [ "string", "null" ], "description": "Series image URL" }, "icon": { "type": [ "string", "null" ], "description": "Series icon URL" }, "active": { "type": [ "boolean", "null" ], "description": "Whether series is active" }, "closed": { "type": [ "boolean", "null" ], "description": "Whether series is closed" }, "archived": { "type": [ "boolean", "null" ], "description": "Whether series is archived" }, "featured": { "type": [ "boolean", "null" ], "description": "Whether series is featured" }, "restricted": { "type": [ "boolean", "null" ], "description": "Whether series has restrictions" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Series creation timestamp" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Series last update timestamp" }, "volume": { "type": [ "number", "null" ], "format": "float", "description": "Total series volume" }, "liquidity": { "type": [ "number", "null" ], "format": "float", "description": "Total series liquidity" }, "commentCount": { "type": [ "integer", "null" ], "description": "Number of comments on series" } } }, "Market": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "Unique market identifier" }, "question": { "type": [ "string", "null" ], "description": "Market question" }, "conditionId": { "type": [ "string", "null" ], "description": "Condition ID for the market" }, "slug": { "type": [ "string", "null" ], "description": "URL-friendly market identifier" }, "resolutionSource": { "type": [ "string", "null" ], "description": "Source for market resolution" }, "endDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Market end date" }, "liquidity": { "type": [ "string", "null" ], "description": "Market liquidity" }, "startDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Market start date" }, "description": { "type": [ "string", "null" ], "description": "Detailed market description" }, "outcomes": { "type": [ "string", "null" ], "description": "JSON string of possible outcomes" }, "outcomePrices": { "type": [ "string", "null" ], "description": "JSON string of outcome prices" }, "volume": { "type": [ "string", "null" ], "description": "Market trading volume" }, "active": { "type": [ "boolean", "null" ], "description": "Whether market is active" }, "closed": { "type": [ "boolean", "null" ], "description": "Whether market is closed" }, "marketMakerAddress": { "type": [ "string", "null" ], "description": "Market maker address" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Market creation timestamp" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Market last update timestamp" }, "new": { "type": [ "boolean", "null" ], "description": "Whether market is new" }, "featured": { "type": [ "boolean", "null" ], "description": "Whether market is featured" }, "submitted_by": { "type": [ "string", "null" ], "description": "Address of user who submitted the market" }, "archived": { "type": [ "boolean", "null" ], "description": "Whether market is archived" }, "resolvedBy": { "type": [ "string", "null" ], "description": "Address of resolver" }, "restricted": { "type": [ "boolean", "null" ], "description": "Whether market has restrictions" }, "groupItemTitle": { "type": [ "string", "null" ], "description": "Group item title" }, "groupItemThreshold": { "type": [ "string", "null" ], "description": "Group item threshold" }, "questionID": { "type": [ "string", "null" ], "description": "Question ID" }, "enableOrderBook": { "type": [ "boolean", "null" ], "description": "Whether order book is enabled" }, "orderPriceMinTickSize": { "type": [ "number", "null" ], "format": "float", "description": "Minimum tick size for orders" }, "orderMinSize": { "type": [ "number", "null" ], "format": "float", "description": "Minimum order size" }, "volumeNum": { "type": [ "number", "null" ], "format": "float", "description": "Numeric volume" }, "liquidityNum": { "type": [ "number", "null" ], "format": "float", "description": "Numeric liquidity" }, "endDateIso": { "type": [ "string", "null" ], "description": "ISO date string of end date" }, "startDateIso": { "type": [ "string", "null" ], "description": "ISO date string of start date" }, "hasReviewedDates": { "type": [ "boolean", "null" ], "description": "Whether dates have been reviewed" }, "volume24hr": { "type": [ "number", "null" ], "format": "float", "description": "24-hour trading volume" }, "volume1wk": { "type": [ "number", "null" ], "format": "float", "description": "1-week trading volume" }, "volume1mo": { "type": [ "number", "null" ], "format": "float", "description": "1-month trading volume" }, "volume1yr": { "type": [ "number", "null" ], "format": "float", "description": "1-year trading volume" }, "clobTokenIds": { "type": [ "string", "null" ], "description": "JSON string of CLOB token IDs" }, "umaBond": { "type": [ "string", "null" ], "description": "UMA bond amount" }, "umaReward": { "type": [ "string", "null" ], "description": "UMA reward amount" }, "volume24hrAmm": { "type": [ "number", "null" ], "format": "float", "description": "24-hour AMM volume" }, "volume1wkAmm": { "type": [ "number", "null" ], "format": "float", "description": "1-week AMM volume" }, "volume1moAmm": { "type": [ "number", "null" ], "format": "float", "description": "1-month AMM volume" }, "volume1yrAmm": { "type": [ "number", "null" ], "format": "float", "description": "1-year AMM volume" }, "volume24hrClob": { "type": [ "number", "null" ], "format": "float", "description": "24-hour CLOB volume" }, "volume1wkClob": { "type": [ "number", "null" ], "format": "float", "description": "1-week CLOB volume" }, "volume1moClob": { "type": [ "number", "null" ], "format": "float", "description": "1-month CLOB volume" }, "volume1yrClob": { "type": [ "number", "null" ], "format": "float", "description": "1-year CLOB volume" }, "volumeAmm": { "type": [ "number", "null" ], "format": "float", "description": "Total AMM volume" }, "volumeClob": { "type": [ "number", "null" ], "format": "float", "description": "Total CLOB volume" }, "liquidityAmm": { "type": [ "number", "null" ], "format": "float", "description": "AMM liquidity" }, "liquidityClob": { "type": [ "number", "null" ], "format": "float", "description": "CLOB liquidity" }, "acceptingOrders": { "type": [ "boolean", "null" ], "description": "Whether market is accepting orders" }, "negRisk": { "type": [ "boolean", "null" ], "description": "Whether market uses negative risk" }, "negRiskMarketID": { "type": [ "string", "null" ], "description": "Negative risk market ID" }, "negRiskRequestID": { "type": [ "string", "null" ], "description": "Negative risk request ID" }, "ready": { "type": [ "boolean", "null" ], "description": "Whether market is ready" }, "funded": { "type": [ "boolean", "null" ], "description": "Whether market is funded" }, "acceptingOrdersTimestamp": { "type": [ "string", "null" ], "format": "date-time", "description": "When market started accepting orders" }, "cyom": { "type": [ "boolean", "null" ], "description": "Create Your Own Market flag" }, "competitive": { "type": [ "number", "null" ], "format": "float", "description": "Competitiveness score" }, "pagerDutyNotificationEnabled": { "type": [ "boolean", "null" ], "description": "Whether PagerDuty notifications are enabled" }, "approved": { "type": [ "boolean", "null" ], "description": "Whether market is approved" }, "clobRewards": { "type": [ "array", "null" ], "items": { "type": "object" }, "description": "CLOB rewards" }, "rewardsMinSize": { "type": [ "number", "null" ], "format": "float", "description": "Minimum size for rewards" }, "rewardsMaxSpread": { "type": [ "number", "null" ], "format": "float", "description": "Maximum spread for rewards" }, "spread": { "type": [ "number", "null" ], "format": "float", "description": "Current spread" }, "oneDayPriceChange": { "type": [ "number", "null" ], "format": "float", "description": "1-day price change" }, "oneHourPriceChange": { "type": [ "number", "null" ], "format": "float", "description": "1-hour price change" }, "oneWeekPriceChange": { "type": [ "number", "null" ], "format": "float", "description": "1-week price change" }, "oneMonthPriceChange": { "type": [ "number", "null" ], "format": "float", "description": "1-month price change" }, "oneYearPriceChange": { "type": [ "number", "null" ], "format": "float", "description": "1-year price change" }, "lastTradePrice": { "type": [ "number", "null" ], "format": "float", "description": "Last trade price" }, "bestBid": { "type": [ "number", "null" ], "format": "float", "description": "Best bid price" }, "bestAsk": { "type": [ "number", "null" ], "format": "float", "description": "Best ask price" }, "automaticallyActive": { "type": [ "boolean", "null" ], "description": "Whether market is automatically active" }, "clearBookOnStart": { "type": [ "boolean", "null" ], "description": "Whether to clear book on start" }, "seriesColor": { "type": [ "string", "null" ], "description": "Series color" }, "showGmpSeries": { "type": [ "boolean", "null" ], "description": "Whether to show GMP series" }, "showGmpOutcome": { "type": [ "boolean", "null" ], "description": "Whether to show GMP outcome" }, "manualActivation": { "type": [ "boolean", "null" ], "description": "Whether market requires manual activation" }, "negRiskOther": { "type": [ "boolean", "null" ], "description": "Other negative risk flag" }, "umaResolutionStatuses": { "type": [ "string", "null" ], "description": "JSON string of UMA resolution statuses" }, "pendingDeployment": { "type": [ "boolean", "null" ], "description": "Whether deployment is pending" }, "deploying": { "type": [ "boolean", "null" ], "description": "Whether currently deploying" }, "rfqEnabled": { "type": [ "boolean", "null" ], "description": "Whether RFQ is enabled" }, "holdingRewardsEnabled": { "type": [ "boolean", "null" ], "description": "Whether holding rewards are enabled" }, "feesEnabled": { "type": [ "boolean", "null" ], "description": "Whether fees are enabled" }, "image": { "type": [ "string", "null" ], "description": "Market image URL" }, "icon": { "type": [ "string", "null" ], "description": "Market icon URL" } } }, "Event": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "ticker": { "type": [ "string", "null" ], "description": "Event ticker symbol" }, "slug": { "type": [ "string", "null" ], "description": "URL-friendly event identifier" }, "title": { "type": [ "string", "null" ], "description": "Event title" }, "subtitle": { "type": [ "string", "null" ], "description": "Event subtitle" }, "description": { "type": [ "string", "null" ], "description": "Event description" }, "resolutionSource": { "type": [ "string", "null" ], "description": "Source for event resolution" }, "startDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Event start date" }, "creationDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Event creation date" }, "endDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Event end date" }, "image": { "type": [ "string", "null" ], "description": "Event image URL" }, "icon": { "type": [ "string", "null" ], "description": "Event icon URL" }, "active": { "type": [ "boolean", "null" ], "description": "Whether event is active" }, "closed": { "type": [ "boolean", "null" ], "description": "Whether event is closed" }, "archived": { "type": [ "boolean", "null" ], "description": "Whether event is archived" }, "new": { "type": [ "boolean", "null" ], "description": "Whether event is new" }, "featured": { "type": [ "boolean", "null" ], "description": "Whether event is featured" }, "restricted": { "type": [ "boolean", "null" ], "description": "Whether event has restrictions" }, "volume": { "type": [ "number", "null" ], "format": "float", "description": "Total event volume" }, "volume24hr": { "type": [ "number", "null" ], "format": "float", "description": "24-hour trading volume" }, "volume1wk": { "type": [ "number", "null" ], "format": "float", "description": "1-week trading volume" }, "volume1mo": { "type": [ "number", "null" ], "format": "float", "description": "1-month trading volume" }, "volume1yr": { "type": [ "number", "null" ], "format": "float", "description": "1-year trading volume" }, "openInterest": { "type": [ "number", "null" ], "format": "float", "description": "Open interest" }, "liquidity": { "type": [ "number", "null" ], "format": "float", "description": "Total liquidity" }, "liquidityAmm": { "type": [ "number", "null" ], "format": "float", "description": "AMM liquidity" }, "liquidityClob": { "type": [ "number", "null" ], "format": "float", "description": "CLOB liquidity" }, "sortBy": { "type": [ "string", "null" ], "description": "Sorting field (e.g., 'price')" }, "category": { "type": [ "string", "null" ], "description": "Event category" }, "subcategory": { "type": [ "string", "null" ], "description": "Event subcategory" }, "isTemplate": { "type": [ "boolean", "null" ], "description": "Whether event is a template" }, "templateVariables": { "type": [ "string", "null" ], "description": "Template variables" }, "published_at": { "type": [ "string", "null" ], "description": "Publication timestamp" }, "createdBy": { "type": [ "string", "null" ], "description": "Creator identifier" }, "updatedBy": { "type": [ "string", "null" ], "description": "Last updater identifier" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Event creation timestamp" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Event last update timestamp" }, "commentsEnabled": { "type": [ "boolean", "null" ], "description": "Whether comments are enabled" }, "competitive": { "type": [ "number", "null" ], "format": "float", "description": "Competitiveness score (0-1)" }, "featuredImage": { "type": [ "string", "null" ], "description": "Featured image URL" }, "disqusThread": { "type": [ "string", "null" ], "description": "Disqus thread identifier" }, "parentEvent": { "type": [ "string", "null" ], "description": "Parent event identifier" }, "enableOrderBook": { "type": [ "boolean", "null" ], "description": "Whether order book is enabled" }, "negRisk": { "type": [ "boolean", "null" ], "description": "Whether event uses negative risk" }, "negRiskMarketID": { "type": [ "string", "null" ], "description": "Negative risk market ID" }, "negRiskFeeBips": { "type": [ "integer", "null" ], "description": "Negative risk fee in basis points" }, "commentCount": { "type": [ "integer", "null" ], "description": "Number of comments" }, "imageOptimized": { "type": [ "object", "null" ], "description": "Optimized image metadata" }, "iconOptimized": { "type": [ "object", "null" ], "description": "Optimized icon metadata" }, "featuredImageOptimized": { "type": [ "object", "null" ], "description": "Optimized featured image metadata" }, "subEvents": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Sub-event identifiers" }, "cyom": { "type": [ "boolean", "null" ], "description": "Create Your Own Market flag" }, "closedTime": { "type": [ "string", "null" ], "format": "date-time", "description": "Market close timestamp" }, "showAllOutcomes": { "type": [ "boolean", "null" ], "description": "Whether to show all outcomes" }, "showMarketImages": { "type": [ "boolean", "null" ], "description": "Whether to show market images" }, "automaticallyResolved": { "type": [ "boolean", "null" ], "description": "Whether event is automatically resolved" }, "enableNegRisk": { "type": [ "boolean", "null" ], "description": "Whether negative risk is enabled" }, "automaticallyActive": { "type": [ "boolean", "null" ], "description": "Whether event is automatically active" }, "eventDate": { "type": [ "string", "null" ], "description": "Event date" }, "startTime": { "type": [ "string", "null" ], "format": "date-time", "description": "Event start time" }, "eventWeek": { "type": [ "integer", "null" ], "description": "Event week number" }, "seriesSlug": { "type": [ "string", "null" ], "description": "Series slug identifier" }, "score": { "type": [ "string", "null" ], "description": "Event score" }, "elapsed": { "type": [ "string", "null" ], "description": "Elapsed time" }, "period": { "type": [ "string", "null" ], "description": "Event period" }, "live": { "type": [ "boolean", "null" ], "description": "Whether event is live" }, "ended": { "type": [ "boolean", "null" ], "description": "Whether event has ended" }, "finishedTimestamp": { "type": [ "string", "null" ], "format": "date-time", "description": "Event finish timestamp" }, "gmpChartMode": { "type": [ "string", "null" ], "description": "Chart mode (e.g., 'default')" }, "eventCreators": { "type": [ "array", "null" ], "items": { "type": "object" }, "description": "Event creators" }, "tweetCount": { "type": [ "integer", "null" ], "description": "Number of tweets" }, "chats": { "type": [ "array", "null" ], "items": { "type": "object" }, "description": "Associated chats" }, "featuredOrder": { "type": [ "integer", "null" ], "description": "Featured ordering position" }, "estimateValue": { "type": [ "boolean", "null" ], "description": "Whether to estimate value" }, "cantEstimate": { "type": [ "boolean", "null" ], "description": "Whether value cannot be estimated" }, "estimatedValue": { "type": [ "string", "null" ], "description": "Estimated value" }, "templates": { "type": [ "array", "null" ], "items": { "type": "object" }, "description": "Associated templates" }, "spreadsMainLine": { "type": [ "number", "null" ], "format": "float", "description": "Main line for spreads" }, "totalsMainLine": { "type": [ "number", "null" ], "format": "float", "description": "Main line for totals" }, "carouselMap": { "type": [ "string", "null" ], "description": "Carousel mapping" }, "negRiskAugmented": { "type": [ "boolean", "null" ], "description": "Whether negative risk is augmented" }, "pendingDeployment": { "type": [ "boolean", "null" ], "description": "Whether deployment is pending" }, "deploying": { "type": [ "boolean", "null" ], "description": "Whether currently deploying" }, "deployingTimestamp": { "type": [ "string", "null" ], "format": "date-time", "description": "Deployment timestamp" }, "scheduledDeploymentTimestamp": { "type": [ "string", "null" ], "format": "date-time", "description": "Scheduled deployment timestamp" }, "gameStatus": { "type": [ "string", "null" ], "description": "Game status" }, "requiresTranslation": { "type": [ "boolean", "null" ], "description": "Whether the event requires translation" }, "markets": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Market" }, "description": "Markets associated with this event" }, "series": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Series" }, "description": "Series associated with this event" }, "categories": { "type": [ "array", "null" ], "items": { "type": "object" }, "description": "Categories associated with this event" }, "collections": { "type": [ "array", "null" ], "items": { "type": "object" }, "description": "Collections associated with this event" }, "tags": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Tag" }, "description": "Tags associated with this event" } } }, "Pagination": { "type": "object", "required": [ "hasMore", "totalResults" ], "properties": { "hasMore": { "type": "boolean", "description": "Whether more results are available" }, "totalResults": { "type": "integer", "description": "Total number of results" } } }, "MarketsResponse": { "type": "object", "required": [ "events" ], "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/Event" }, "description": "Array of events with associated markets and tags" } } }, "StandardizedResponse": { "type": "object", "required": [ "events", "pagination" ], "properties": { "events": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Event" }, "description": "Array of events with associated markets and tags" }, "tags": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Tag" }, "description": "Optional array of tags (top-level)" }, "profiles": { "type": [ "array", "null" ], "items": { "type": "object" }, "description": "Optional array of user profiles (top-level)" }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "Position": { "type": "object", "required": [ "proxyWallet", "asset", "conditionId", "size", "avgPrice", "initialValue", "currentValue", "cashPnl", "percentPnl", "totalBought", "realizedPnl", "percentRealizedPnl", "curPrice", "redeemable", "mergeable", "title", "slug", "icon", "eventSlug", "outcome", "outcomeIndex", "oppositeOutcome", "oppositeAsset", "endDate", "negativeRisk" ], "properties": { "proxyWallet": { "type": "string", "description": "Proxy wallet address", "pattern": "^0x[a-fA-F0-9]{40}$", "example": "0x56687bf447db6ffa42ffe2204a05edaa20f55839" }, "asset": { "type": "string", "description": "Asset token ID" }, "conditionId": { "type": "string", "description": "Condition ID (0x-prefixed 64-hex string)", "pattern": "^0x[a-fA-F0-9]{64}$", "example": "0xdd22472e552920b8438158ea7238bfadfa4f736aa4cee91a6b86c39ead110917" }, "size": { "type": "number", "format": "float", "description": "Position size" }, "avgPrice": { "type": "number", "format": "float", "description": "Average purchase price" }, "initialValue": { "type": "number", "format": "float", "description": "Initial position value" }, "currentValue": { "type": "number", "format": "float", "description": "Current position value" }, "cashPnl": { "type": "number", "format": "float", "description": "Cash profit/loss" }, "percentPnl": { "type": "number", "format": "float", "description": "Percentage profit/loss" }, "totalBought": { "type": "number", "format": "float", "description": "Total amount bought" }, "realizedPnl": { "type": "number", "format": "float", "description": "Realized profit/loss" }, "percentRealizedPnl": { "type": "number", "format": "float", "description": "Percentage realized profit/loss" }, "curPrice": { "type": "number", "format": "float", "description": "Current price" }, "redeemable": { "type": "boolean", "description": "Whether position is redeemable" }, "mergeable": { "type": "boolean", "description": "Whether position is mergeable" }, "title": { "type": "string", "description": "Market title" }, "slug": { "type": "string", "description": "Market slug" }, "icon": { "type": "string", "description": "Market icon URL" }, "eventId": { "type": "string", "description": "Event ID (optional field)" }, "eventSlug": { "type": "string", "description": "Event slug" }, "outcome": { "type": "string", "description": "Outcome name" }, "outcomeIndex": { "type": "integer", "description": "Outcome index" }, "oppositeOutcome": { "type": "string", "description": "Opposite outcome name" }, "oppositeAsset": { "type": "string", "description": "Opposite asset token ID" }, "endDate": { "type": "string", "description": "Market end date" }, "negativeRisk": { "type": "boolean", "description": "Whether position uses negative risk" } } }, "ClosedPosition": { "type": "object", "required": [ "proxyWallet", "asset", "conditionId", "avgPrice", "totalBought", "realizedPnl", "curPrice", "timestamp", "title", "slug", "icon", "eventSlug", "outcome", "outcomeIndex", "oppositeOutcome", "oppositeAsset", "endDate" ], "properties": { "proxyWallet": { "type": "string", "description": "Proxy wallet address", "pattern": "^0x[a-fA-F0-9]{40}$", "example": "0x56687bf447db6ffa42ffe2204a05edaa20f55839" }, "asset": { "type": "string", "description": "Asset token ID" }, "conditionId": { "type": "string", "description": "Condition ID (0x-prefixed 64-hex string)", "pattern": "^0x[a-fA-F0-9]{64}$", "example": "0xdd22472e552920b8438158ea7238bfadfa4f736aa4cee91a6b86c39ead110917" }, "avgPrice": { "type": "number", "format": "float", "description": "Average purchase price" }, "totalBought": { "type": "number", "format": "float", "description": "Total amount bought" }, "realizedPnl": { "type": "number", "format": "float", "description": "Realized profit/loss" }, "curPrice": { "type": "number", "format": "float", "description": "Current price" }, "timestamp": { "type": "integer", "format": "int64", "description": "Unix timestamp" }, "title": { "type": "string", "description": "Market title" }, "slug": { "type": "string", "description": "Market slug" }, "icon": { "type": "string", "description": "Market icon URL" }, "eventSlug": { "type": "string", "description": "Event slug" }, "outcome": { "type": "string", "description": "Outcome name" }, "outcomeIndex": { "type": "integer", "description": "Outcome index" }, "oppositeOutcome": { "type": "string", "description": "Opposite outcome name" }, "oppositeAsset": { "type": "string", "description": "Opposite asset token ID" }, "endDate": { "type": "string", "description": "Market end date" } } }, "Activity": { "type": "object", "required": [ "proxyWallet", "timestamp", "conditionId", "type", "size", "usdcSize", "transactionHash", "price", "asset", "side", "outcomeIndex", "title", "slug", "icon", "eventSlug", "outcome", "name", "pseudonym", "bio", "profileImage", "profileImageOptimized" ], "properties": { "proxyWallet": { "type": "string", "description": "User Profile Address (0x-prefixed, 40 hex chars)", "pattern": "^0x[a-fA-F0-9]{40}$" }, "timestamp": { "type": "integer", "format": "int64", "description": "Unix timestamp" }, "conditionId": { "type": "string", "description": "Condition ID (0x-prefixed 64-hex string)", "pattern": "^0x[a-fA-F0-9]{64}$" }, "type": { "type": "string", "enum": [ "TRADE", "SPLIT", "MERGE", "REDEEM", "REWARD", "CONVERSION" ], "description": "Activity type" }, "size": { "type": "number", "description": "Activity size" }, "usdcSize": { "type": "number", "description": "USDC value of the activity" }, "transactionHash": { "type": "string", "description": "Transaction hash" }, "price": { "type": "number", "description": "Trade price" }, "asset": { "type": "string", "description": "Asset token ID" }, "side": { "type": "string", "enum": [ "BUY", "SELL", "" ], "description": "Order side (BUY or SELL for trades, empty for non-trade activities)" }, "outcomeIndex": { "type": "integer", "description": "Outcome index" }, "title": { "type": "string", "description": "Market title" }, "slug": { "type": "string", "description": "Market slug" }, "icon": { "type": "string", "description": "Market icon URL" }, "eventSlug": { "type": "string", "description": "Event slug" }, "outcome": { "type": "string", "description": "Outcome name" }, "name": { "type": "string", "description": "User name" }, "pseudonym": { "type": "string", "description": "User pseudonym" }, "bio": { "type": "string", "description": "User bio" }, "profileImage": { "type": "string", "description": "User profile image URL" }, "profileImageOptimized": { "type": "string", "description": "Optimized profile image URL" } } }, "Trade": { "type": "object", "required": [ "proxyWallet", "side", "asset", "conditionId", "size", "price", "timestamp", "title", "slug", "icon", "eventSlug", "outcome", "outcomeIndex", "name", "pseudonym", "bio", "profileImage", "profileImageOptimized", "transactionHash" ], "properties": { "proxyWallet": { "type": "string", "description": "User Profile Address (0x-prefixed, 40 hex chars)", "pattern": "^0x[a-fA-F0-9]{40}$" }, "side": { "type": "string", "enum": [ "BUY", "SELL" ], "description": "Order side" }, "asset": { "type": "string", "description": "Asset token ID" }, "conditionId": { "type": "string", "description": "Condition ID (0x-prefixed 64-hex string)", "pattern": "^0x[a-fA-F0-9]{64}$" }, "size": { "type": "number", "description": "Trade size" }, "price": { "type": "number", "description": "Trade price" }, "timestamp": { "type": "integer", "format": "int64", "description": "Unix timestamp" }, "title": { "type": "string", "description": "Market title" }, "slug": { "type": "string", "description": "Market slug" }, "icon": { "type": "string", "description": "Market icon URL" }, "eventSlug": { "type": "string", "description": "Event slug" }, "outcome": { "type": "string", "description": "Outcome name" }, "outcomeIndex": { "type": "integer", "description": "Outcome index" }, "name": { "type": "string", "description": "User name" }, "pseudonym": { "type": "string", "description": "User pseudonym" }, "bio": { "type": "string", "description": "User bio" }, "profileImage": { "type": "string", "description": "User profile image URL" }, "profileImageOptimized": { "type": "string", "description": "Optimized profile image URL" }, "transactionHash": { "type": "string", "description": "Transaction hash" } } }, "PnLResponse": { "type": "object", "required": [ "currentPositions", "closedPositions", "allTime" ], "properties": { "currentPositions": { "type": "number", "format": "float", "description": "Total PnL from current open positions" }, "closedPositions": { "type": "number", "format": "float", "description": "Total PnL from closed positions" }, "allTime": { "type": "number", "format": "float", "description": "All-time total PnL" } } }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "integer", "description": "Error code" }, "details": { "type": "object", "description": "Additional error details" } } }, "WorkflowErrorResponse": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "description": "Always false for error responses", "enum": [ false ], "example": false }, "error": { "type": "object", "required": [ "code", "name", "message", "title", "statusCode", "timestamp" ], "properties": { "code": { "type": "string", "description": "Error type code for programmatic handling" }, "name": { "type": "string", "description": "Error class name" }, "message": { "type": "string", "description": "Detailed error message" }, "title": { "type": "string", "description": "Short, user-friendly error title" }, "statusCode": { "type": "integer", "description": "HTTP status code" }, "details": { "type": "object", "description": "Additional error details", "additionalProperties": true }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp when the error occurred" } } } } }, "EvmAddress": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address (0x prefix + 40 hex characters)" }, "Hex": { "type": "string", "pattern": "^0x[a-fA-F0-9]*$", "description": "Hex string with 0x prefix" }, "PolyMarketWorkflowData": { "type": "object", "required": [ "userId", "orderRequest", "orderResponse" ], "properties": { "userId": { "type": "string", "description": "Polymarket user ID", "example": "0x0797bfec6d2d4f733d461bbee8125805e9e9c892" }, "orderRequest": { "$ref": "#/components/schemas/PolymarketOrderRequest" }, "orderResponse": { "oneOf": [ { "title": "Open Order", "$ref": "#/components/schemas/PolymarketOpenOrder" }, { "title": "Error Response", "type": "object", "required": [ "error", "status" ], "properties": { "error": { "type": "string", "description": "Error message" }, "status": { "type": "string", "description": "Order status" } } } ], "description": "Order response from Polymarket" }, "relayTx": { "type": [ "object", "null" ], "properties": { "txHash": { "type": "string", "description": "Transaction hash of the relay transaction" }, "status": { "type": "string", "description": "Status of the relay transaction" } }, "description": "Relay transaction details (null if not applicable)" } } }, "PolymarketOrderRequest": { "type": "object", "required": [ "side", "tokenID", "orderType", "feeRateBps", "slippage", "tickSize", "negRisk" ], "properties": { "side": { "type": "string", "enum": [ "BUY", "SELL" ], "description": "Order side" }, "tokenID": { "type": "string", "description": "Polymarket CLOB token ID", "example": "110902308091723190012269532299497167125504426554890434343419495764557291673806" }, "orderType": { "type": "string", "enum": [ "FOK", "FAK", "GTC", "GTD" ], "description": "Order type (FOK/FAK are market orders, GTC/GTD are limit orders)" }, "feeRateBps": { "type": "number", "minimum": 0, "description": "Fee rate in basis points", "example": 0 }, "slippage": { "type": "number", "description": "Slippage tolerance in basis points", "example": 100 }, "tickSize": { "type": "string", "enum": [ "0.01", "0.001", "0.0001" ], "description": "Price tick size" }, "negRisk": { "type": "boolean", "description": "Negative risk flag" }, "amount": { "type": "number", "description": "Amount for market orders (FOK/FAK)", "example": 5 }, "price": { "type": "number", "minimum": 0, "maximum": 1, "description": "Price per share (0-1) - required for limit orders, optional for market orders", "example": 0.021 }, "size": { "type": "number", "minimum": 0, "description": "Number of shares for limit orders", "example": 5 } } }, "PolymarketOpenOrder": { "type": "object", "required": [ "id", "status", "owner", "maker_address", "market", "asset_id", "side", "original_size", "size_matched", "price", "outcome", "created_at", "expiration", "order_type", "associate_trades" ], "properties": { "id": { "type": "string", "description": "Order ID", "example": "0xbd2f3c625c1f6f918a74e8645c3afee9e8f2c5adf91f178efa5e1b65f74fb489" }, "status": { "type": "string", "description": "Order status", "example": "MATCHED" }, "owner": { "type": "string", "description": "Owner ID", "example": "258f7485-b93f-52e5-2327-a53c49a299c1" }, "maker_address": { "type": "string", "description": "Maker address", "example": "0xBEDcAD563ddf52391573a016Bc5EC7A334Eec756" }, "market": { "type": "string", "description": "Market ID", "example": "0xb050c89e1e5738c79e117d28da1f057ac2f193511aab87a01b517b466c7265dc" }, "asset_id": { "type": "string", "description": "Asset ID (token ID)", "example": "110902308091723190012269532299497167125504426554890434343419495764557291673806" }, "side": { "type": "string", "enum": [ "BUY", "SELL" ], "description": "Order side" }, "original_size": { "type": "string", "description": "Original order size", "example": "5" }, "size_matched": { "type": "string", "description": "Size matched", "example": "0" }, "price": { "type": "string", "description": "Order price", "example": "0.02" }, "outcome": { "type": "string", "description": "Order outcome", "example": "No" }, "expiration": { "type": "string", "description": "Expiration timestamp", "example": "1763996360" }, "order_type": { "type": "string", "description": "Order type", "example": "GTD" }, "associate_trades": { "type": "array", "items": { "type": "string" }, "description": "Associated trade IDs" }, "created_at": { "type": "integer", "description": "Unix timestamp when order was created", "example": 1763996291 } } }, "CreateOrFetchPolymarketUserRequest": { "type": "object", "required": [ "evmEoa" ], "properties": { "evmEoa": { "$ref": "#/components/schemas/EvmAddress", "description": "EVM address (wallet address)" }, "unfreeze": { "type": "boolean", "description": "Set to `true` to unfreeze a wallet whose `proxyWalletStatus` is `temporary-frozen`." } } }, "CreateOrFetchPolymarketUserResponse": { "type": "object", "required": [ "userCredentials", "newUser", "userId" ], "properties": { "userCredentials": { "$ref": "#/components/schemas/UserCredentials", "description": "User credentials object containing wallet information" }, "newUser": { "type": "boolean", "description": "Whether this is a newly created user (true) or existing user (false)", "example": true }, "userId": { "type": "string", "description": "Polymarket user ID (EVM address)", "example": "0x0797bfec6d2d4f733d461bbee8125805e9e9c892" } } }, "PolymarketDstToken": { "type": "object", "required": [ "address", "chainId" ], "description": "Destination token used by Polymarket workflow endpoints. When provided, proceeds are swapped into this token before delivery.", "properties": { "address": { "$ref": "#/components/schemas/EvmAddress", "description": "Destination token contract address" }, "chainId": { "type": "number", "description": "Destination chain ID. See the [chain list](/resources/chain-list)." } } }, "ProxyWalletStatus": { "type": "string", "enum": [ "ready", "deploying", "permissioning", "failed-deploy", "failed-permission", "not-created", "temporary-frozen" ], "description": "Status of the proxy wallet" }, "UserCredentials": { "type": "object", "required": [ "evmEoa" ], "properties": { "evmEoa": { "$ref": "#/components/schemas/EvmAddress", "description": "The home EOA address (wallet address)" }, "proxyWallet": { "anyOf": [ { "$ref": "#/components/schemas/EvmAddress" }, { "type": "null" } ], "description": "Proxy wallet address (if available)" }, "proxyWalletStatus": { "anyOf": [ { "$ref": "#/components/schemas/ProxyWalletStatus" }, { "type": "null" } ], "description": "Status of the proxy wallet" } } }, "WorkflowStatusResponse": { "type": "object", "required": [ "txId", "status", "operation", "timestamp", "name", "data" ], "properties": { "txId": { "type": "string", "description": "Transaction ID", "example": "0x36f51092bdfb6f9793fefd9b2d27529fbf7362b48ded9acb7fa4cc7aea03aeca" }, "status": { "type": "string", "enum": [ "success", "failed", "pending" ], "description": "Workflow status", "example": "success" }, "operation": { "type": "string", "description": "Operation type", "example": "placeOrder" }, "timestamp": { "type": "integer", "description": "Unix timestamp when workflow was executed", "example": 1765593597 }, "name": { "type": "string", "description": "Workflow name", "example": "polymarket" }, "data": { "oneOf": [ { "title": "Polymarket Data", "$ref": "#/components/schemas/PolyMarketWorkflowData" }, { "title": "Generic Workflow Data", "type": "object", "additionalProperties": true } ], "description": "Workflow-specific data" } } } }, "responses": { "BadRequest": { "description": "Bad request due to missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "InternalServerError": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key for authentication. Contact Swaps.xyz to obtain an API key." } } }, "security": [ { "ApiKeyAuth": [] } ] }