{ "openapi": "3.1.0", "info": { "title": "River Markets API", "description": "# Getting Started\n\n\nRiver Markets provides users with a unified prime brokerage interface for prediction markets, including\n- Liquidity aggregation\n- Order routing\n- Market and data search\n\nThis API guide will help you get up and running quickly.\n\n## Concepts\n\n### River IDs\n\nEvery market across all exchanges is assigned a unique **River ID** - a unified identifier that works across our entire platform. This allows you to:\n\n- Reference the same market consistently regardless of which exchange it trades on\n- Place orders using a single identifier format\n- Track positions and fills across exchanges with one ID\n\nWhen searching for markets, the API returns both the exchange-native identifier (e.g., Kalshi ticker, Polymarket slug) and the River ID. Use the River ID when placing orders.\n\n### Subaccounts\n\n**Subaccounts** let you organize your trading activity into separate containers. Each subaccount:\n\n- Has its own set of exchange credentials\n- Maintains separate positions and order history\n- Can represent different strategies, clients, or portfolios\n\nThis is useful for:\n- **Fund managers**: Segregate client portfolios\n- **Traders**: Separate strategies (e.g., momentum vs. mean reversion)\n- **Teams**: Give team members isolated trading environments\n\n## 1. Create an Account\n\nSign up at [app.rivermarkets.com](https://app.rivermarkets.com) to create your account.\n\n## 2. Generate an API Key\n\n1. Log in to your dashboard\n2. Navigate to **Settings \u2192 API Keys**\n3. Click **Create API Key**\n4. Copy and securely store your key - it will only be shown once\n\n## 3. Install required packages\n\n```python\npip install requests\n```\n\n## 4. Make Your First Request\n\nTest your API key by searching for markets.\n\nWe support ticker (kalshi ticker, polymarket condition_id/slug, river_id) and fuzzy search ('bitcoin', 'fed rates').\n\n> **Using the SDK?** `rivermarkets` (Python) \n> handle request signing for you \u2014 pass your `KEY_ID` and `PRIVATE_KEY` to the\n> client constructor and forget about the rest of this section. The raw example\n> below is for anyone integrating without an SDK.\n\n```python\nimport base64, hashlib, time\nfrom urllib.parse import urlsplit, urlencode, parse_qsl, quote\nfrom nacl.signing import SigningKey\nimport requests\n\nKEY_ID = \"\"\nPRIVATE_KEY_B64 = \"\"\nBASE_URL = \"https://api.rivermarkets.com/v1\"\n\nsigning_key = SigningKey(base64.b64decode(PRIVATE_KEY_B64))\n\n\ndef sign(method: str, url: str, body: bytes = b\"\") -> dict:\n parts = urlsplit(url)\n # quote_via=quote encodes spaces as %20 to match RFC 3986 / the server.\n sorted_q = urlencode(sorted(parse_qsl(parts.query, keep_blank_values=True)), quote_via=quote)\n ts = str(int(time.time()))\n canonical = \"\\n\".join([\n method.upper(), parts.path, sorted_q, ts, hashlib.sha256(body).hexdigest(),\n ]).encode()\n sig = signing_key.sign(canonical).signature\n return {\n \"X-River-Key-Id\": KEY_ID,\n \"X-River-Timestamp\": ts,\n \"X-River-Signature\": base64.b64encode(sig).decode(),\n }\n\n\nurl = f\"{BASE_URL}/markets/search?q=shutdown&exchange=POLYMARKET\"\nresponse = requests.get(url, headers=sign(\"GET\", url))\nfor market in response.json()[\"results\"]:\n print(f\"River ID: {market['river_id']}, Ticker: {market['slug']}\")\n```\n\n## 5. Set Up a Subaccount\n\nRiver allows users to setup subaccounts - which allow them to manage different trading strategies or client portfolios.\n\nThese can be added through the UI by going to Settings -> Subaccounts\nor programatically.\n\n### Video Walkthrough\n\nWatch this tutorial to see how to create a subaccount, add a Polymarket account, and place your first trade:\n\n
\n\n### Programmatic Setup \n\n```python\n# Create a subaccount\nresponse = requests.post(\n f\"{BASE_URL}/subaccounts\",\n headers=headers,\n json={\"name\": \"My Trading Account\"}\n)\nsubaccount = response.json()\nsubaccount_id = subaccount[\"id\"]\n```\n\n## 6. Add Exchange Credentials\n\nExchange credentials can also be added via UI under Settings -> Subaccounts,\nor programatically as shown below.\n\nFor best results, we recommend\n- Polymarket : create an account using email (not a wallet) and get your wallet and PK directly from Polymarket under [Settings -> Export Private Key](https://polymarket.com/settings)\n- Kalshi : create a secret/key pair with Read/Write access under [Settings -> Account & security -> API keys](https://kalshi.com/account/profile)\n\n```python\n# Add Polymarket credentials\nresponse = requests.post(\n f\"{BASE_URL}/credentials\",\n headers=headers,\n json={\n \"subaccount_id\": subaccount_id,\n \"exchange\": \"polymarket\",\n \"wallet_address\": \"your_polymarket_wallet_address\",\n \"private_key\": \"your_polymarket_private_key\"\n }\n)\n# Add Kalshi credentials\nresponse = requests.post(\n f\"{BASE_URL}/credentials\",\n headers=headers,\n json={\n \"subaccount_id\": subaccount_id,\n \"exchange\": \"kalshi\",\n \"api_key\": \"your_kalshi_api_key\",\n \"api_secret\": \"your_kalshi_secret\"\n }\n)\n```\n\nWe use asymmetric encryption so your credentials are not transferred between services or stored in plain text.\nWe delete your credentials when you delete a subaccount. \n\n## 7. Place Your First Order\n\nUse the River ID from your market search to place an order.\n\n```python\n# Place a limit order (buy 10 contracts at $0.50)\nresponse = requests.post(\n f\"{BASE_URL}/orders\",\n headers=headers,\n json={\n \"subaccount_id\": subaccount_id,\n \"river_id\": 4552150, # From market search\n \"order_type\": \"LIMIT\", # LIMIT or MARKET\n \"time_in_force\": \"GTC\", # FOK, GTC, GTD, or IOC\n \"buy_flag\": True, # True=buy, False=sell\n \"price\": 0.50, # Limit price (0-1)\n \"qty\": 10, # Number of contracts\n }\n)\norder = response.json()\nprint(f\"Order placed: {order['river_order_id']}\")\n```\n\n## 8. Check Order Status\n\nMonitor your order's progress by fetching its current state.\n\n```python\n# Get order status\norder_id = order['river_order_id']\nresponse = requests.get(\n f\"{BASE_URL}/orders/{order_id}\",\n headers=headers\n)\norder_status = response.json()\nprint(f\"Status: {order_status['status']}, Filled: {order_status['traded_qty']}/{order_status['qty']}\")\n```\n\nPossible order statuses:\n- `pending_submission` - Order received, awaiting processing\n- `resting` - Order live on the exchange (may include partially-filled live orders)\n- `filled` - Terminal: order fully executed\n- `partially_filled` - Terminal: order cancelled with some quantity filled\n- `cancelled` - Terminal: order cancelled with no fills\n- `rejected` - Order rejected (see `reject_reason`)\n\n## 9. Cancel an Order\n\nCancel a resting order before it's fully filled.\n\n```python\n# Cancel an order\norder_id = order['river_order_id']\nresponse = requests.delete(\n f\"{BASE_URL}/orders/{order_id}\",\n headers=headers\n)\nif response.status_code == 200:\n print(\"Order cancelled successfully\")\n```\n\nNote: Only orders with status `pending_submission` or `resting` can be cancelled (`partially_filled` is terminal).\n\n## Supported Exchanges\n\n| Exchange | Markets | Status |\n|----------|---------|--------|\n| Kalshi | US regulated prediction markets | Available |\n| Polymarket | Crypto prediction markets | Available |\n| Polymarket US | US regulated prediction markets | Available |\n| Novig | US regulated prediction markets | Coming soon |\n| Rothera | US regulated prediction markets | Future integration |\n\n## Rate Limits\n\n- **Standard**: 10 requests/second\n- **Premium**: Contact support for higher limits\n\n\n\n## Authentication\n\nAll endpoints require authentication via one of:\n- **Bearer Token**: `Authorization: Bearer ` (for web clients)\n- **Signed Request** (programmatic access): three headers per REST request, or\n three query params on the WebSocket handshake.\n\n> **Using the SDK?** `rivermarkets` (Python) \n> sign every REST request and WS handshake for you. You only need the raw\n> recipes below if you're integrating without an SDK.\n\n### REST signing\n\nSend three headers on every request:\n- `X-River-Key-Id`: UUID of your API key\n- `X-River-Timestamp`: current unix seconds (must be within 30s of server time)\n- `X-River-Signature`: base64 Ed25519 signature over the canonical request\n\nThe REST canonical string is LF-joined:\n```\nMETHOD\\nPATH\\nSORTED_QUERY\\nTIMESTAMP\\nSHA256(body) hex\n```\n\n```python\nimport base64, hashlib, time\nfrom urllib.parse import urlsplit, urlencode, parse_qsl, quote\nfrom nacl.signing import SigningKey\n\nsigning_key = SigningKey(base64.b64decode(PRIVATE_KEY_B64))\n\ndef sign(method: str, url: str, body: bytes = b\"\") -> dict:\n parts = urlsplit(url)\n # quote_via=quote encodes spaces as %20 to match RFC 3986 / the server.\n sorted_q = urlencode(sorted(parse_qsl(parts.query, keep_blank_values=True)), quote_via=quote)\n ts = str(int(time.time()))\n canonical = \"\\n\".join([\n method.upper(), parts.path, sorted_q, ts, hashlib.sha256(body).hexdigest(),\n ]).encode()\n sig = signing_key.sign(canonical).signature\n return {\n \"X-River-Key-Id\": KEY_ID,\n \"X-River-Timestamp\": ts,\n \"X-River-Signature\": base64.b64encode(sig).decode(),\n }\n```\n\n### WebSocket signing\n\nBrowsers can't set custom headers on the WS upgrade, so the same three values\nmove to query params: `?key_id=&ts=&sig=`. The WS canonical string omits the\nbody hash and uses the literal `\"WS\"` as the method:\n```\nWS\\nPATH\\nSORTED_QUERY (excluding key_id/ts/sig)\\nTIMESTAMP\n```\n\n```python\nimport asyncio, base64, time\nfrom urllib.parse import urlencode, quote\nimport websockets\nfrom nacl.signing import SigningKey\n\nsigning_key = SigningKey(base64.b64decode(PRIVATE_KEY_B64))\n\n\ndef sign_ws(path: str, extra_params: dict | None = None) -> str:\n \"\"\"Return a fully-formed wss:// URL with signing query params appended.\"\"\"\n params = dict(extra_params or {})\n sorted_q = urlencode(sorted(params.items()), quote_via=quote)\n ts = str(int(time.time()))\n canonical = \"\\n\".join([\"WS\", path, sorted_q, ts]).encode()\n sig = base64.b64encode(signing_key.sign(canonical).signature).decode()\n params.update({\"key_id\": KEY_ID, \"ts\": ts, \"sig\": sig})\n return f\"wss://api.rivermarkets.com{path}?{urlencode(params)}\"\n\n\nasync def stream_orders(subaccount_id: str):\n url = sign_ws(\"/v1/ws/orders\", {\"subaccount_id\": subaccount_id})\n async with websockets.connect(url) as ws:\n async for frame in ws:\n print(frame)\n\n\nasyncio.run(stream_orders(\"411b3f8c-85f9-41c9-90b7-3ff6d74efc4f\"))\n```\n\n### Security notes\n\n- Your private key never traverses the wire. Generate a keypair at\n `Settings \u2192 API Keys`; the private key is shown once.\n- Same signature cannot be submitted twice within 60 seconds (replay protection).\n On network retries, re-sign with a fresh timestamp.\n- Timestamps must be within 30s of server time. Sync your clock via NTP.\n\n\n---\n\n\n\n# Order Types Documentation\n\nComplete guide to all order types available in the River Markets trading platform.\n\n---\n\n## Basic Order Types\n\n### Market Order\nExecutes immediately at the best available price.\n- **Use case**: When you need immediate execution and price is less important\n- **Example**: Market buy 100 contracts \u2192 fills at current best ask price\n\n### Limit Order\nRests on the order book at a specified price.\n- **Use case**: When you want price control and can wait for execution\n- **Example**: Limit buy 100 @ $0.65 \u2192 only fills at $0.65 or better\n\n---\n\n## Conditional Order Types\n\nConditional orders are **not placed immediately**. They activate (\"trigger\") when specific conditions are met.\n\n### 1. Stop Orders (STOP)\n\n**Stop orders trigger when price moves AGAINST your desired direction.** Used primarily for **stop losses** (exit protection) or **breakout entries**.\n\n#### Stop Market\n- **Triggers**: When market trades at or through your stop price\n- **Executes**: As a market order (immediate fill at best available price)\n- **Example**:\n ```\n You're LONG at $0.70, want to exit if price falls to $0.60\n \u2192 Stop Market SELL @ $0.60\n \u2192 Triggers when price \u2264 $0.60\n \u2192 Sends market sell order \u2192 fills immediately\n ```\n\n#### Stop Limit\n- **Triggers**: When market trades at or through your stop price\n- **Executes**: As a limit order at your specified limit price\n- **Example**:\n ```\n You're LONG at $0.70, want to exit around $0.60 but not worse than $0.59\n \u2192 Stop Limit SELL @ $0.60, Limit $0.59\n \u2192 Triggers when price \u2264 $0.60\n \u2192 Sends limit sell order @ $0.59 \u2192 waits for fill at $0.59 or better\n ```\n- **Risk**: May not fill if price moves too fast through your limit\n\n**Directional Logic:**\n- **BUY stop**: Triggers at or **above** stop price (breakout entry or short exit)\n- **SELL stop**: Triggers at or **below** stop price (stop loss or long exit)\n\n---\n\n### 2. Reverse Stop Orders (REVERSE_STOP)\n\n**Reverse stop orders trigger when price moves IN your desired direction.** Used exclusively for **take profit** scenarios.\n\n**Key Concept**: A \"reverse stop\" is called \"reverse\" because it triggers in the OPPOSITE direction of a normal stop order.\n\n#### Reverse Stop Market (TP Market)\n- **Triggers**: When market trades at or through your target price (OPPOSITE direction from normal stop)\n- **Executes**: As a market order\n- **Example**:\n ```\n You're LONG at $0.60, want to take profit if price rises to $0.80\n \u2192 TP Market (Reverse Stop Market) SELL @ $0.80\n \u2192 Normal stop would trigger BELOW, but reverse stop triggers ABOVE\n \u2192 Triggers when price \u2265 $0.80\n \u2192 Sends market sell order \u2192 fills immediately\n ```\n\n**Directional Logic (REVERSED from normal stop):**\n- **BUY reverse stop**: Triggers at or **below** target (opposite of normal buy stop)\n- **SELL reverse stop**: Triggers at or **above** target (opposite of normal sell stop)\n\n**Why \"reverse\"?**\n- Normal **SELL stop** @ $0.60 triggers when price \u2264 $0.60 (price falling)\n- **SELL reverse stop** @ $0.80 triggers when price \u2265 $0.80 (price rising)\n- The trigger direction is reversed!\n\n#### Reverse Stop Limit (TP Limit)\n- **Triggers**: When market trades at or through your target price\n- **Executes**: As a limit order at your specified limit price\n- **Example**:\n ```\n You're LONG at $0.60, want to take profit around $0.80 but not worse than $0.79\n \u2192 TP Limit (Reverse Stop Limit) SELL @ $0.80, Limit $0.79\n \u2192 Triggers when price \u2265 $0.80\n \u2192 Sends limit sell order @ $0.79 \u2192 waits for fill at $0.79 or better\n ```\n\n---\n\n### 3. Take Profit Orders (TP)\n\n**Parent-child orders**: Automatically triggers a child order when a parent order **fills**.\n\n#### TP Market\n- **Triggers**: When parent order is **fully filled**\n- **Executes**: Immediately places the child order (can be another TP/SL or direct order)\n- **Example**:\n ```\n Place limit buy 100 @ $0.60 WITH TP Market @ $0.80\n \u2192 When buy fills \u2192 immediately activates TP Market SELL @ $0.80\n \u2192 That TP Market is a reverse stop that triggers when price \u2265 $0.80\n ```\n\n#### TP Limit\n- **Triggers**: When parent order is **fully filled**\n- **Executes**: Activates TP Limit order (reverse stop limit)\n- **Example**:\n ```\n Place limit buy 100 @ $0.60 WITH TP Limit @ $0.80 (limit $0.79)\n \u2192 When buy fills \u2192 activates TP Limit SELL\n \u2192 Triggers when price \u2265 $0.80 \u2192 sends limit sell @ $0.79\n ```\n\n---\n\n### 4. Stop Loss Orders (SL)\n\n**Parent-child orders**: Automatically triggers a child order when a parent order **fills**.\n\n#### SL Market\n- **Triggers**: When parent order is **fully filled**\n- **Executes**: Immediately places the child order (can be another SL/TP or direct order)\n- **Example**:\n ```\n Place limit buy 100 @ $0.60 WITH SL Market @ $0.55\n \u2192 When buy fills \u2192 immediately activates SL Market SELL @ $0.55\n \u2192 That SL Market is a stop order that triggers when price \u2264 $0.55\n ```\n\n#### SL Limit\n- **Triggers**: When parent order is **fully filled**\n- **Executes**: Activates SL Limit order (stop limit)\n- **Example**:\n ```\n Place limit buy 100 @ $0.60 WITH SL Limit @ $0.55 (limit $0.54)\n \u2192 When buy fills \u2192 activates SL Limit SELL\n \u2192 Triggers when price \u2264 $0.55 \u2192 sends limit sell @ $0.54\n ```\n\n---\n\n## Order Type Comparison\n\n| Type | Trigger Condition | Execution | Primary Use Case |\n|------|------------------|-----------|------------------|\n| **Market** | None (immediate) | Immediate at best price | Need immediate fill |\n| **Limit** | None (rests) | At limit price or better | Want price control |\n| **Stop Market** | Price moves AGAINST you | Market order (immediate) | Stop loss, breakout entry |\n| **Stop Limit** | Price moves AGAINST you | Limit order (may not fill) | Stop loss with price protection |\n| **TP Market** | Parent fills + price moves FOR you | Market order via reverse stop | Take profit with immediate exit |\n| **TP Limit** | Parent fills + price moves FOR you | Limit order via reverse stop | Take profit with price control |\n| **SL Market** | Parent fills + price moves AGAINST you | Market order via stop | Stop loss from entry |\n| **SL Limit** | Parent fills + price moves AGAINST you | Limit order via stop | Stop loss with price floor |\n\n---\n\n## Key Concepts\n\n### Stop vs Reverse Stop\n- **Stop**: Triggers when price moves AGAINST you (exit losses, enter breakouts)\n- **Reverse Stop**: Triggers when price moves FOR you (take profits)\n\n### Parent-Child Orders\n- **TP/SL orders** are \"meta-orders\" that activate child orders when a parent fills\n- The child order itself is usually a stop or reverse stop order\n- This creates a two-step process: Parent fill \u2192 Child activation \u2192 Price trigger \u2192 Execution\n\n### Trigger Direction Summary\n| Order Side | Stop (Loss/Breakout) | Reverse Stop (Profit) |\n|------------|---------------------|----------------------|\n| **BUY** | Triggers \u2265 stop price | Triggers \u2264 target price |\n| **SELL** | Triggers \u2264 stop price | Triggers \u2265 target price |\n\n---\n\n## Examples\n\n### Complete Trading Scenario\n```\n1. Place limit BUY 100 @ $0.60\n WITH TP Market @ $0.80 (reverse stop)\n AND SL Market @ $0.55 (normal stop)\n\n2. Buy fills at $0.60\n \u2192 TP Market SELL @ $0.80 activated (reverse stop)\n \u2192 SL Market SELL @ $0.55 activated (normal stop)\n\n3a. If price rises to $0.80:\n \u2192 TP triggers (price \u2265 $0.80) \u2192 market sell executes\n \u2192 SL cancelled automatically\n\n3b. If price falls to $0.55:\n \u2192 SL triggers (price \u2264 $0.55) \u2192 market sell executes\n \u2192 TP cancelled automatically\n```\n\n### Breakout Entry with Protection\n```\nPrice is at $0.70, resistance at $0.75, support at $0.65\n\n1. Place Stop Market BUY @ $0.76 (breakout entry)\n \u2192 Triggers when price \u2265 $0.76 (breaks resistance)\n \u2192 Market buy executes\n\n2. Add SL Market @ $0.74 to the stop order\n \u2192 When breakout buy fills \u2192 SL activates\n \u2192 Protects if breakout fails\n```\n\n", "contact": { "name": "River Markets", "url": "https://rivermarkets.com/" }, "license": { "name": "Proprietary" }, "version": "1.0.0" }, "paths": { "/v1/complex-orders": { "get": { "tags": [ "complex-orders" ], "summary": "List Complex Orders", "description": "List complex orders (conditional and iceberg) with optional filters.\n\nReturns a dict keyed by complex order type (`conditional_orders`,\n`iceberg_orders`). Use `complex_order_type` to restrict to one type.", "operationId": "list_complex_orders_v1_complex_orders_get", "parameters": [ { "name": "complex_order_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by complex order type: CONDITIONAL, TWAP, ICEBERG, PEG.", "title": "Complex Order Type" }, "description": "Filter by complex order type: CONDITIONAL, TWAP, ICEBERG, PEG." }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Filter by status name. Interpreted per complex_order_type (ConditionalOrderStatus for CONDITIONAL, IcebergOrderStatus for ICEBERG, PegOrderStatus for PEG). Unknown names for the active type are ignored.", "title": "Status" }, "description": "Filter by status name. Interpreted per complex_order_type (ConditionalOrderStatus for CONDITIONAL, IcebergOrderStatus for ICEBERG, PegOrderStatus for PEG). Unknown names for the active type are ignored." }, { "name": "river_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Filter by instrument ID", "title": "River Id" }, "description": "Filter by instrument ID" }, { "name": "generic_asset_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Filter by generic asset basket ID", "title": "Generic Asset Id" }, "description": "Filter by generic asset basket ID" }, { "name": "subaccount_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Filter to a specific subaccount", "title": "Subaccount Id" }, "description": "Filter to a specific subaccount" }, { "name": "complex_order_ids", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string", "format": "uuid" } }, { "type": "null" } ], "description": "Filter by complex order IDs", "title": "Complex Order Ids" }, "description": "Filter by complex order IDs" }, { "name": "parent_river_order_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Filter by parent order ID", "title": "Parent River Order Id" }, "description": "Filter by parent order ID" }, { "name": "unparented_only", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, only return conditional orders with no parent_river_order_id (standalone stops). Ignored for non-conditional types.", "default": false, "title": "Unparented Only" }, "description": "When true, only return conditional orders with no parent_river_order_id (standalone stops). Ignored for non-conditional types." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Results per page (max 1000)", "default": 100, "title": "Limit" }, "description": "Results per page (max 1000)" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Pagination offset", "default": 0, "title": "Offset" }, "description": "Pagination offset" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplexOrderListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "complex-orders" ], "summary": "Create Complex Order", "description": "Create a new complex order (conditional or iceberg).\n\nProvide exactly one of `conditional_order_params` (TP/SL/STOP) or\n`iceberg_order_params`. The body shape determines the complex_order_type.\n\nReturns 202 Accepted with the persisted complex order in PENDING status,\nenqueued for activation by the appropriate consumer service.", "operationId": "create_complex_order_v1_complex_orders_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplexOrderCreateRequest" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplexOrderCreateResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/complex-orders/cancel-all": { "post": { "tags": [ "complex-orders" ], "summary": "Cancel All Complex Orders", "description": "Cancel all cancellable complex orders (conditional and iceberg) for a subaccount.\n\nReturns the list of complex_order_ids that were submitted for cancellation.", "operationId": "cancel_all_complex_orders_v1_complex_orders_cancel_all_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelAllComplexOrdersRequest" } } }, "required": true }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelComplexOrderResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/complex-orders/{complex_order_id}": { "get": { "tags": [ "complex-orders" ], "summary": "Get Complex Order", "description": "Get a single complex order by ID (conditional or iceberg).", "operationId": "get_complex_order_v1_complex_orders__complex_order_id__get", "parameters": [ { "name": "complex_order_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Complex Order Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplexOrderResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "complex-orders" ], "summary": "Cancel Complex Order", "description": "Cancel a single complex order (conditional or iceberg).\n\nReturns 202 Accepted. Cancellation is processed asynchronously by the\nappropriate consumer service.", "operationId": "cancel_complex_order_v1_complex_orders__complex_order_id__delete", "parameters": [ { "name": "complex_order_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Complex Order Id" } } ], "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelComplexOrderResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/fair-values": { "get": { "tags": [ "fair-values" ], "summary": "List Fair Values", "description": "List the caller's fair values, optionally scoped to one subaccount and/or one instrument.", "operationId": "list_fair_values_v1_fair_values_get", "parameters": [ { "name": "subaccount_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Restrict to a single subaccount", "title": "Subaccount Id" }, "description": "Restrict to a single subaccount" }, { "name": "river_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Restrict to a single instrument", "title": "River Id" }, "description": "Restrict to a single instrument" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FairValueListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "fair-values" ], "summary": "Set Fair Value", "description": "Set the fair value for an instrument on a subaccount (insert-or-overwrite).", "operationId": "set_fair_value_v1_fair_values_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FairValueUpsert" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FairValueResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/fair-values/{subaccount_id}/{river_id}": { "delete": { "tags": [ "fair-values" ], "summary": "Delete Fair Value", "description": "Clear the fair value for an instrument on a subaccount.", "operationId": "delete_fair_value_v1_fair_values__subaccount_id___river_id__delete", "parameters": [ { "name": "subaccount_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Subaccount Id" } }, { "name": "river_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "River Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/fills": { "get": { "tags": [ "fills" ], "summary": "Get Fills", "description": "Fetch fills/trades for the user's subaccounts.\n\nReturns fills grouped by subaccount, filterable by instrument and time range.", "operationId": "get_fills_v1_fills_get", "parameters": [ { "name": "subaccount_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subaccount Id" } }, { "name": "river_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "River Id" } }, { "name": "start_time", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Start Time" } }, { "name": "end_time", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "End Time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 100, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserFillListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/generic-assets": { "get": { "tags": [ "generic-assets" ], "summary": "List Generic Assets", "description": "List generic assets visible to the caller (their own + platform-curated approved).\n\nSorted by resolves_at (soonest first), then name.", "operationId": "list_generic_assets_v1_generic_assets_get", "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Filter by category. Repeat to filter to multiple categories.", "title": "Category" }, "description": "Filter by category. Repeat to filter to multiple categories." }, { "name": "subcategory", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by subcategory", "title": "Subcategory" }, "description": "Filter by subcategory" }, { "name": "owner", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "'me' for own baskets only, 'platform' for public only", "title": "Owner" }, "description": "'me' for own baskets only, 'platform' for public only" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericAssetListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "generic-assets" ], "summary": "Create Generic Asset", "description": "Create a new user-owned generic asset (basket).", "operationId": "create_generic_asset_v1_generic_assets_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericAssetCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericAssetDetailResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/generic-assets/{generic_asset_id}": { "get": { "tags": [ "generic-assets" ], "summary": "Get Generic Asset", "description": "Fetch a single generic asset (own or public-approved) with its resolved member markets.", "operationId": "get_generic_asset_v1_generic_assets__generic_asset_id__get", "parameters": [ { "name": "generic_asset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Generic Asset Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericAssetDetailResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "generic-assets" ], "summary": "Update Generic Asset", "description": "Update a user-owned generic asset's name or description. Platform-curated assets cannot be edited via this route.", "operationId": "update_generic_asset_v1_generic_assets__generic_asset_id__patch", "parameters": [ { "name": "generic_asset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Generic Asset Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericAssetUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericAssetResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "generic-assets" ], "summary": "Delete Generic Asset", "description": "Delete a user-owned generic asset (cascades to members).", "operationId": "delete_generic_asset_v1_generic_assets__generic_asset_id__delete", "parameters": [ { "name": "generic_asset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Generic Asset Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/generic-assets/{generic_asset_id}/members": { "post": { "tags": [ "generic-assets" ], "summary": "Add Generic Asset Members", "description": "Add river_ids to a user-owned generic asset.", "operationId": "add_generic_asset_members_v1_generic_assets__generic_asset_id__members_post", "parameters": [ { "name": "generic_asset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Generic Asset Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericAssetMemberAdd" } } } }, "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "generic-assets" ], "summary": "Remove Generic Asset Members", "description": "Remove river_ids from a user-owned generic asset.", "operationId": "remove_generic_asset_members_v1_generic_assets__generic_asset_id__members_delete", "parameters": [ { "name": "generic_asset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Generic Asset Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericAssetMemberRemove" } } } }, "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/balance/exchange": { "get": { "tags": [ "balance" ], "summary": "Get Exchange Balance", "description": "Return live exchange balances (Kalshi, Polymarket) for a non-custodial subaccount.", "operationId": "get_exchange_balance_v1_balance_exchange_get", "parameters": [ { "name": "subaccount_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Non-custodial subaccount to fetch exchange balances for", "title": "Subaccount Id" }, "description": "Non-custodial subaccount to fetch exchange balances for" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExchangeBalanceResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/markets/search": { "get": { "tags": [ "markets" ], "summary": "Search Markets", "description": "Search and browse markets across all exchanges.\n\nSupports:\n- Exact match on ticker, condition_id, slug, river_id\n- Full-text search on name, description, tags\n- Browse by filters (no query required)\n- Results ranked by relevance\n\nWe default to active markets in the view so things are faster", "operationId": "search_markets_v1_markets_search_get", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "description": "Search query", "title": "Q" }, "description": "Search query" }, { "name": "exchange_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by exchange name (KALSHI, POLYMARKET)", "title": "Exchange Name" }, "description": "Filter by exchange name (KALSHI, POLYMARKET)" }, { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Filter by canonical category. Repeat the param to filter to multiple categories (Sports, Crypto, Politics, Finance, Entertainment, Science & Tech, Weather, World Affairs, Health, Social, Other).", "title": "Category" }, "description": "Filter by canonical category. Repeat the param to filter to multiple categories (Sports, Crypto, Politics, Finance, Entertainment, Science & Tech, Weather, World Affairs, Health, Social, Other)." }, { "name": "subcategory", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by subcategory (e.g. Basketball, Football)", "title": "Subcategory" }, "description": "Filter by subcategory (e.g. Basketball, Football)" }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/InstrumentStatus" }, { "type": "null" } ], "description": "Filter by instrument status", "title": "Status" }, "description": "Filter by instrument status" }, { "name": "expiration_date_start", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Start of expiration date range (inclusive, ISO 8601)", "title": "Expiration Date Start" }, "description": "Start of expiration date range (inclusive, ISO 8601)" }, { "name": "expiration_date_end", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "End of expiration date range (exclusive, ISO 8601)", "title": "Expiration Date End" }, "description": "End of expiration date range (exclusive, ISO 8601)" }, { "name": "start_datetime_after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter to markets with start_datetime >= this (ISO 8601)", "title": "Start Datetime After" }, "description": "Filter to markets with start_datetime >= this (ISO 8601)" }, { "name": "start_datetime_before", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Filter to markets with start_datetime < this (ISO 8601)", "title": "Start Datetime Before" }, "description": "Filter to markets with start_datetime < this (ISO 8601)" }, { "name": "event_ticker", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by event_ticker (exact match)", "title": "Event Ticker" }, "description": "Filter by event_ticker (exact match)" }, { "name": "last_price_min", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": 0.0 }, { "type": "null" } ], "description": "Filter to markets with last_price >= this value (0.0\u20131.0 YES probability).", "title": "Last Price Min" }, "description": "Filter to markets with last_price >= this value (0.0\u20131.0 YES probability)." }, { "name": "last_price_max", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": 0.0 }, { "type": "null" } ], "description": "Filter to markets with last_price <= this value (0.0\u20131.0 YES probability).", "title": "Last Price Max" }, "description": "Filter to markets with last_price <= this value (0.0\u20131.0 YES probability)." }, { "name": "volume_min", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "Filter to events whose total summed volume >= this value.", "title": "Volume Min" }, "description": "Filter to events whose total summed volume >= this value." }, { "name": "sort_by", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sort mode for event-based pagination: trending, volume, newest, ending-soon, start-time, price", "title": "Sort By" }, "description": "Sort mode for event-based pagination: trending, volume, newest, ending-soon, start-time, price" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Maximum number of results", "default": 20, "title": "Limit" }, "description": "Maximum number of results" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Offset for pagination", "default": 0, "title": "Offset" }, "description": "Offset for pagination" }, { "name": "event_limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 2000, "minimum": 1 }, { "type": "null" } ], "description": "Paginate by events instead of markets. Up to 200 by default; values above that require start_datetime_after or start_datetime_before.", "title": "Event Limit" }, "description": "Paginate by events instead of markets. Up to 200 by default; values above that require start_datetime_after or start_datetime_before." }, { "name": "event_offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "Event offset for event-based pagination", "title": "Event Offset" }, "description": "Event offset for event-based pagination" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketSearchResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/markets/lookup": { "get": { "tags": [ "markets" ], "summary": "Lookup Markets", "description": "Batch lookup markets by river_ids.", "operationId": "lookup_markets_v1_markets_lookup_get", "parameters": [ { "name": "river_ids", "in": "query", "required": true, "schema": { "type": "string", "description": "Comma-separated list of river IDs", "title": "River Ids" }, "description": "Comma-separated list of river IDs" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketLookupResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/markets/match": { "get": { "tags": [ "markets" ], "summary": "Match Market", "description": "Exact match a single market by Kalshi ticker or Polymarket slug. Supply exactly one.", "operationId": "match_market_v1_markets_match_get", "parameters": [ { "name": "ticker", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Exact Kalshi ticker (e.g. KXNBA-26-DET)", "title": "Ticker" }, "description": "Exact Kalshi ticker (e.g. KXNBA-26-DET)" }, { "name": "slug", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Exact Polymarket slug (e.g. will-the-denver-nuggets-win-the-2026-nba-finals)", "title": "Slug" }, "description": "Exact Polymarket slug (e.g. will-the-denver-nuggets-win-the-2026-nba-finals)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketSearchResult" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/markets/match/batch": { "post": { "tags": [ "markets" ], "summary": "Match Markets Batch", "description": "Batch-resolve many markets by exact Kalshi ticker and/or Polymarket slug in one request.\n\nThe single-market ``/match`` endpoint costs one round-trip per identifier, so resolving\nthousands of mappings serially is slow. This endpoint takes lists of tickers and/or slugs\n(send them together in one call) and returns a full market row \u2014 including ``river_id``,\n``ticker``, ``slug`` and ``exchange_name`` \u2014 for every identifier that matched. Identifiers\nwith no match come back in ``unmatched_tickers`` / ``unmatched_slugs``.", "operationId": "match_markets_batch_v1_markets_match_batch_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketMatchBatchRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketMatchBatchResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/orderbooks/generic-asset/{generic_asset_id}": { "get": { "tags": [ "orderbooks" ], "summary": "Get Generic Asset Orderbook", "description": "Get merged orderbook for a generic asset (basket).\n\nFetches orderbooks for all member instruments and merges them by summing\nquantity at each price level. Touch mechanism ensures subscriptions are active.", "operationId": "get_generic_asset_orderbook_v1_orderbooks_generic_asset__generic_asset_id__get", "parameters": [ { "name": "generic_asset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Generic Asset Id" } }, { "name": "levels", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 10, "minimum": 1, "description": "Number of price levels to return", "default": 10, "title": "Levels" }, "description": "Number of price levels to return" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderbookResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/orderbooks/{river_id}": { "get": { "tags": [ "orderbooks" ], "summary": "Get Orderbook", "description": "Get orderbook for a river_id.", "operationId": "get_orderbook_v1_orderbooks__river_id__get", "parameters": [ { "name": "river_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "River Id" } }, { "name": "levels", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 10, "minimum": 1, "description": "Number of price levels to return", "default": 10, "title": "Levels" }, "description": "Number of price levels to return" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderbookResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/orders": { "post": { "tags": [ "orders" ], "summary": "Create Order", "description": "Place a new order.\n\nSubmits an order for asynchronous processing. The order is persisted immediately\nand queued for execution on the target exchange.\n\nSee [Orders](https://docs.rivermarkets.com/concepts/orders) and [Order Types](https://docs.rivermarkets.com/concepts/order-types) for more information.\n\n**Asset Selection:**\nProvide exactly one of `river_id` (standard instrument) or `generic_asset_id` (user-defined basket).\nGeneric asset orders only support `MARKET` order type \u2014 the system automatically routes\nIOC limit orders to each underlying instrument at optimal prices.\n\n**Response:**\nReturns `202 Accepted` with the order_id and associated complex_orders ids (TP/SL).\nPoll `GET /v1/orders/{order_id}` or use webhooks to track execution.", "operationId": "create_order_v1_orders_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCreate" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCreateResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "orders" ], "summary": "List Orders", "description": "List orders with optional filters.\n\nReturns a paginated list of orders across all accessible subaccounts, ordered by `created_at` descending.\n\n**Filters:**\nAll filters are optional and can be combined. If no `subaccount_id` is specified,\nreturns orders from all subaccounts the user has access to.\n\n**Order Statuses:**\n- `PENDING_SUBMISSION`: Order received, awaiting exchange submission.\n- `PROCESSING`: Being processed by the order consumer.\n- `RESTING`: Live on the exchange order book (may include partially-filled live orders).\n- `EXECUTED`: Terminal \u2014 fully filled.\n- `PARTIALLY_FILLED`: Terminal \u2014 cancelled with some quantity filled.\n- `CANCELLED`: Terminal \u2014 cancelled with no fills.\n- `REJECTED`: Rejected by exchange (see order details for reason).\n\n**Aggregated Fields:**\nEach order includes `traded_qty`, `average_price`, and `fees_paid` computed from fills.", "operationId": "list_orders_v1_orders_get", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by order status. Accepts a single OrderStatus name (e.g. 'RESTING') or the meta-value 'ACTIVE' which resolves to RESTING.", "title": "Status" }, "description": "Filter by order status. Accepts a single OrderStatus name (e.g. 'RESTING') or the meta-value 'ACTIVE' which resolves to RESTING." }, { "name": "river_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Filter by instrument ID", "title": "River Id" }, "description": "Filter by instrument ID" }, { "name": "generic_asset_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Filter by generic asset ID", "title": "Generic Asset Id" }, "description": "Filter by generic asset ID" }, { "name": "subaccount_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Filter to a specific subaccount", "title": "Subaccount Id" }, "description": "Filter to a specific subaccount" }, { "name": "parent_iceberg_order_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Filter to child tranches of a specific iceberg parent.", "title": "Parent Iceberg Order Id" }, "description": "Filter to child tranches of a specific iceberg parent." }, { "name": "parent_peg_order_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Filter to child tranches of a specific peg parent.", "title": "Parent Peg Order Id" }, "description": "Filter to child tranches of a specific peg parent." }, { "name": "parent_smart_taker_order_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Filter to IOC children of a specific smart-taker parent.", "title": "Parent Smart Taker Order Id" }, "description": "Filter to IOC children of a specific smart-taker parent." }, { "name": "buy_flag", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Filter by direction: true=buys, false=sells", "title": "Buy Flag" }, "description": "Filter by direction: true=buys, false=sells" }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-text search across the order's market: ticker/slug, the human-readable question (event title, market name, outcome) via full-text + substring match, plus the order's river_id / order id / generic asset id. Applied server-side over all matching orders, not just the current page.", "title": "Search" }, "description": "Free-text search across the order's market: ticker/slug, the human-readable question (event title, market name, outcome) via full-text + substring match, plus the order's river_id / order id / generic asset id. Applied server-side over all matching orders, not just the current page." }, { "name": "show_tp_sl_active", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, complex_order_ids only includes attached TP/SL orders with status PENDING or ACTIVE.", "default": false, "title": "Show Tp Sl Active" }, "description": "When true, complex_order_ids only includes attached TP/SL orders with status PENDING or ACTIVE." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Results per page (max 1000)", "default": 100, "title": "Limit" }, "description": "Results per page (max 1000)" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Pagination offset", "default": 0, "title": "Offset" }, "description": "Pagination offset" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/orders/{order_id}": { "get": { "tags": [ "orders" ], "summary": "Get Order", "description": "Get a single order by ID with its fills.\n\nReturns complete order details including execution history.\n\n**Use Cases:**\n- Track order progress and execution quality\n- Reconcile fills for accounting\n- Debug rejected or partially filled orders", "operationId": "get_order_v1_orders__order_id__get", "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Order Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderDetailResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "orders" ], "summary": "Cancel Order", "description": "Cancel an existing order.\n\nRequest cancellation of an order.\nReturns 202 Accepted with order state - cancellation is processed asynchronously.", "operationId": "cancel_order_v1_orders__order_id__delete", "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Order Id" } } ], "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelOrderResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "orders" ], "summary": "Edit Order", "description": "Edit (amend) a resting simple limit order.\n\nOnly `qty` and `price` are editable. `qty` is the new TOTAL quantity (not remaining).\nThe order must be RESTING, a simple order (no iceberg/peg parent), a single-instrument\nLIMIT order. Returns 202 Accepted; final status is delivered via the orders WS.", "operationId": "edit_order_v1_orders__order_id__patch", "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Order Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderEditRequest" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderEditResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/orders/{order_id}/queue-position": { "get": { "tags": [ "orders" ], "summary": "Get Order Queue Position", "description": "Get the best (minimum) queue position across all exchange orders backing this river order.\n\nCurrently supported only for Kalshi-backed orders.", "operationId": "get_order_queue_position_v1_orders__order_id__queue_position_get", "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Order Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderQueuePositionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/orders/cancel-all": { "post": { "tags": [ "orders" ], "summary": "Cancel All Orders", "description": "Cancel all open orders for a subaccount.\n\nIf `river_ids` is set, only orders on those instruments are cancelled;\nit must be omitted/null or non-empty. Cancellation is processed\nasynchronously by the order consumer.", "operationId": "cancel_all_orders_v1_orders_cancel_all_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelAllRequest" } } }, "required": true }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelOrderResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/positions": { "get": { "tags": [ "positions" ], "summary": "Get Positions", "description": "Fetch positions for user's subaccounts.\n\nPositions are computed from cumulative fills, with avg buy/sell prices,\nfees, and fill count. Returns positions grouped by subaccount.\nBy default, only positions in open markets are returned.", "operationId": "get_positions_v1_positions_get", "parameters": [ { "name": "subaccount_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Filter by specific subaccount", "title": "Subaccount Id" }, "description": "Filter by specific subaccount" }, { "name": "river_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Filter by instrument", "title": "River Id" }, "description": "Filter by instrument" }, { "name": "include_closed", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include positions in closed markets", "default": false, "title": "Include Closed" }, "description": "Include positions in closed markets" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserPositionListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/prices/{river_id}/volume": { "get": { "tags": [ "prices" ], "summary": "Get Volume", "description": "Traded volume over a recent window, summed from our captured trade prints\n(all exchanges write to `trade_prints`). 1 contract traded = $1 of volume.\nSummed from the raw hypertable rather than the OHLC continuous aggregates\nso the most recent minutes are always included.", "operationId": "get_volume_v1_prices__river_id__volume_get", "parameters": [ { "name": "river_id", "in": "path", "required": true, "schema": { "type": "integer", "description": "River market ID", "title": "River Id" }, "description": "River market ID" }, { "name": "window", "in": "query", "required": false, "schema": { "enum": [ "15m", "1h", "24h" ], "type": "string", "description": "Lookback window", "default": "1h", "title": "Window" }, "description": "Lookback window" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolumeResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/prices/volume": { "get": { "tags": [ "prices" ], "summary": "Get Volume Batch", "description": "Batch variant of the windowed-volume endpoint for grid views (multibook):\none grouped scan of `trade_prints` instead of a request per market.\nMarkets with no prints in the window come back with volume 0.", "operationId": "get_volume_batch_v1_prices_volume_get", "parameters": [ { "name": "river_ids", "in": "query", "required": true, "schema": { "type": "string", "description": "Comma-separated list of river IDs", "title": "River Ids" }, "description": "Comma-separated list of river IDs" }, { "name": "window", "in": "query", "required": false, "schema": { "enum": [ "15m", "1h", "24h" ], "type": "string", "description": "Lookback window", "default": "1h", "title": "Window" }, "description": "Lookback window" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchVolumeResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/prices/{river_id}": { "get": { "tags": [ "prices" ], "summary": "Get Prices", "description": "Get price data for a market.\nReturns either candlestick OHLC data or simple price history based on the `type` parameter.\nThe endpoint automatically determines the exchange and fetches data accordingly.\n\n- **Kalshi**: Returns real OHLC candlestick data with volume\n- **Polymarket**: Returns price history (candlesticks will have synthetic OHLC where all values equal the price)\n\nAll prices are normalized to 0-1 range.", "operationId": "get_prices_v1_prices__river_id__get", "parameters": [ { "name": "river_id", "in": "path", "required": true, "schema": { "type": "integer", "description": "River market ID", "title": "River Id" }, "description": "River market ID" }, { "name": "type", "in": "query", "required": false, "schema": { "enum": [ "candlesticks", "history" ], "type": "string", "description": "Response type", "default": "candlesticks", "title": "Type" }, "description": "Response type" }, { "name": "interval", "in": "query", "required": false, "schema": { "enum": [ "1d", "1w", "1m", "max" ], "type": "string", "description": "Time range", "default": "1d", "title": "Interval" }, "description": "Time range" }, { "name": "fidelity", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 120, "minimum": 1, "description": "Minutes per data point (for Polymarket history)", "default": 60, "title": "Fidelity" }, "description": "Minutes per data point (for Polymarket history)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/subaccounts": { "get": { "tags": [ "subaccounts" ], "summary": "List Subaccounts", "description": "Enumerate all trading subaccounts accessible to the user.\n\nReturns list of accounts with identifiers and metadata.", "operationId": "list_subaccounts_v1_subaccounts_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/SubaccountResponse" }, "type": "array", "title": "Response List Subaccounts V1 Subaccounts Get" } } } } } }, "post": { "tags": [ "subaccounts" ], "summary": "Create Subaccount", "description": "Create a new trading subaccount for the authenticated user.", "operationId": "create_subaccount_v1_subaccounts_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubaccountCreate" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubaccountResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/subaccounts/{subaccount_id}": { "get": { "tags": [ "subaccounts" ], "summary": "Get Subaccount", "description": "Fetch configuration and metadata for a specific subaccount.\n\nReturns account configuration, limits, and descriptive metadata.", "operationId": "get_subaccount_v1_subaccounts__subaccount_id__get", "parameters": [ { "name": "subaccount_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Subaccount Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubaccountResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "subaccounts" ], "summary": "Update Subaccount", "description": "Update an existing subaccount.", "operationId": "update_subaccount_v1_subaccounts__subaccount_id__patch", "parameters": [ { "name": "subaccount_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Subaccount Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubaccountUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubaccountResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "subaccounts" ], "summary": "Delete Subaccount", "description": "Delete a subaccount. Custodial subaccounts cannot be deleted.\n\nThis is a soft delete: the row is marked is_active = false so the audit trail\n(orders, fills, ledger entries) stays intact. The user never sees it again.", "operationId": "delete_subaccount_v1_subaccounts__subaccount_id__delete", "parameters": [ { "name": "subaccount_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Subaccount Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/tradeprints": { "get": { "tags": [ "tradeprints" ], "summary": "Get Tradeprints", "description": "Return the most recent trades for one or more markets, sourced directly from\nthe exchanges. Markets are fetched concurrently with a small semaphore\n(`MAX_CONCURRENT_FETCHES`) so a long input list never fans out into a\nthundering herd, and the result list preserves the input order. A failure\non any single market becomes a `not_found` row with a message \u2014 the call as\na whole does not 500.\n\nPer-market lookup paths:\n - Kalshi: `GET /markets/trades?ticker=...&limit=...`\n - Polymarket: `GET https://data-api.polymarket.com/trades?market=&limit=...`\n (both YES and NO legs are fetched and the NO leg is flipped into YES-price terms)\n\nTrades are sorted newest-first within each market. Prices are normalised to 0-1.\n\nUse this together with the `/v1/ws/tradeprints` WebSocket: hit this endpoint to\nbackfill the tape on page load, then dedup live WS events by `exchange_trade_id`.", "operationId": "get_tradeprints_v1_tradeprints_get", "parameters": [ { "name": "river_ids", "in": "query", "required": true, "schema": { "type": "array", "items": { "type": "integer" }, "description": "River market IDs (repeat the param for each)", "title": "River Ids" }, "description": "River market IDs (repeat the param for each)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Max trades returned per market", "default": 50, "title": "Limit" }, "description": "Max trades returned per market" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TradeprintsBulkResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/watchlists": { "get": { "tags": [ "watchlists" ], "summary": "List Watchlists", "description": "List the caller's watchlists (optionally scoped to one subaccount), newest first.", "operationId": "list_watchlists_v1_watchlists_get", "parameters": [ { "name": "subaccount_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Restrict to a single owning subaccount", "title": "Subaccount Id" }, "description": "Restrict to a single owning subaccount" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchlistListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "watchlists" ], "summary": "Create Watchlist", "description": "Create a new watchlist, optionally seeded with an ordered set of river_ids.", "operationId": "create_watchlist_v1_watchlists_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchlistCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchlistDetailResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/watchlists/{watchlist_id}": { "get": { "tags": [ "watchlists" ], "summary": "Get Watchlist", "description": "Fetch a single watchlist with its ordered member markets.", "operationId": "get_watchlist_v1_watchlists__watchlist_id__get", "parameters": [ { "name": "watchlist_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Watchlist Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchlistDetailResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "watchlists" ], "summary": "Update Watchlist", "description": "Rename a watchlist or edit its description.", "operationId": "update_watchlist_v1_watchlists__watchlist_id__patch", "parameters": [ { "name": "watchlist_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Watchlist Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchlistUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchlistDetailResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "watchlists" ], "summary": "Delete Watchlist", "description": "Delete a watchlist (cascades to its members).", "operationId": "delete_watchlist_v1_watchlists__watchlist_id__delete", "parameters": [ { "name": "watchlist_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Watchlist Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/watchlists/{watchlist_id}/members": { "post": { "tags": [ "watchlists" ], "summary": "Add Watchlist Members", "description": "Append river_ids to the end of a watchlist.", "operationId": "add_watchlist_members_v1_watchlists__watchlist_id__members_post", "parameters": [ { "name": "watchlist_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Watchlist Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchlistMemberAdd" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchlistDetailResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "watchlists" ], "summary": "Remove Watchlist Members", "description": "Remove river_ids from a watchlist. Remaining members keep their relative order.", "operationId": "remove_watchlist_members_v1_watchlists__watchlist_id__members_delete", "parameters": [ { "name": "watchlist_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Watchlist Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchlistMemberAdd" } } } }, "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/watchlists/{watchlist_id}/members/order": { "put": { "tags": [ "watchlists" ], "summary": "Reorder Watchlist Members", "description": "Reorder a watchlist. The body is the full ordered river_id list; the server\nrewrites each member's position to match. Unknown river_ids are ignored;\nmembers omitted from the list are pushed to the end in their prior order.", "operationId": "reorder_watchlist_members_v1_watchlists__watchlist_id__members_order_put", "parameters": [ { "name": "watchlist_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Watchlist Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchlistMemberReorder" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchlistDetailResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "AccountType": { "type": "string", "enum": [ "custodial", "non_custodial" ], "title": "AccountType", "description": "Type of trading subaccount." }, "BatchVolumeEntry": { "properties": { "river_id": { "type": "integer", "title": "River Id" }, "volume": { "type": "number", "title": "Volume" } }, "type": "object", "required": [ "river_id", "volume" ], "title": "BatchVolumeEntry" }, "BatchVolumeResponse": { "properties": { "window": { "type": "string", "enum": [ "15m", "1h", "24h" ], "title": "Window" }, "volumes": { "items": { "$ref": "#/components/schemas/BatchVolumeEntry" }, "type": "array", "title": "Volumes" }, "as_of": { "type": "integer", "title": "As Of" } }, "type": "object", "required": [ "window", "volumes", "as_of" ], "title": "BatchVolumeResponse", "description": "Windowed traded volume for a batch of markets (multibook grids)." }, "CancelAllComplexOrdersRequest": { "properties": { "subaccount_id": { "type": "string", "format": "uuid", "title": "Subaccount Id", "description": "Subaccount to cancel all complex orders for" }, "river_ids": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "River Ids", "description": "If set, only cancel cancellable complex orders for these instruments. Must be either omitted/null or a non-empty list." } }, "type": "object", "required": [ "subaccount_id" ], "title": "CancelAllComplexOrdersRequest", "description": "Request body for cancelling all complex orders for a subaccount." }, "CancelAllRequest": { "properties": { "subaccount_id": { "type": "string", "format": "uuid", "title": "Subaccount Id" }, "river_ids": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "River Ids", "description": "If set, only cancel open orders for these instruments; otherwise cancel all open orders on the subaccount. Must be either omitted/null or a non-empty list." } }, "type": "object", "required": [ "subaccount_id" ], "title": "CancelAllRequest", "description": "Request body for cancelling all orders for a subaccount." }, "CancelComplexOrderResponse": { "properties": { "cancelled_complex_order_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "title": "Cancelled Complex Order Ids", "description": "List of cancelled complex order identifiers" }, "failed_cancelled_complex_order_ids": { "additionalProperties": { "type": "string" }, "propertyNames": { "format": "uuid" }, "type": "object", "title": "Failed Cancelled Complex Order Ids", "description": "Dictionary of failed to cancel complex order identifiers and reasons" } }, "type": "object", "required": [ "cancelled_complex_order_ids", "failed_cancelled_complex_order_ids" ], "title": "CancelComplexOrderResponse", "description": "Schema for cancel order response What is returned when user cancels an order/ orders." }, "CancelOrderResponse": { "properties": { "cancelled_river_order_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "title": "Cancelled River Order Ids", "description": "List of cancelled river order identifiers" }, "failed_cancelled_reasons": { "additionalProperties": { "type": "string" }, "propertyNames": { "format": "uuid" }, "type": "object", "title": "Failed Cancelled Reasons", "description": "Dictionary of failed to cancel river order identifiers and reasons" } }, "type": "object", "required": [ "cancelled_river_order_ids", "failed_cancelled_reasons" ], "title": "CancelOrderResponse", "description": "Schema for cancel order response" }, "ComplexOrderCreateRequest": { "properties": { "subaccount_id": { "type": "string", "format": "uuid", "title": "Subaccount Id", "description": "Subaccount to create the order under" }, "river_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "River Id", "description": "Instrument ID. Mutually exclusive with generic_asset_id." }, "generic_asset_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Generic Asset Id", "description": "Generic asset basket ID. Mutually exclusive with river_id." }, "conditional_order_params": { "anyOf": [ { "$ref": "#/components/schemas/ConditionalOrderCreate" }, { "type": "null" } ], "description": "Conditional order parameters (TP/SL/STOP)" }, "iceberg_order_params": { "anyOf": [ { "$ref": "#/components/schemas/IcebergOrderParams" }, { "type": "null" } ], "description": "Iceberg order parameters" }, "peg_order_params": { "anyOf": [ { "$ref": "#/components/schemas/PegOrderParams" }, { "type": "null" } ], "description": "Peg order parameters" }, "smart_taker_order_params": { "anyOf": [ { "$ref": "#/components/schemas/SmartTakerOrderParams" }, { "type": "null" } ], "description": "Smart-taker order parameters" } }, "type": "object", "required": [ "subaccount_id" ], "title": "ComplexOrderCreateRequest", "description": "Request body for creating a complex order.\n\nProvide exactly one of `conditional_order_params` (TP/SL/STOP) or\n`iceberg_order_params` (iceberg). The active param block determines the\ncomplex_order_type." }, "ComplexOrderCreateResponse": { "properties": { "complex_order_id": { "type": "string", "format": "uuid", "title": "Complex Order Id", "description": "Unique complex order identifier" } }, "type": "object", "required": [ "complex_order_id" ], "title": "ComplexOrderCreateResponse", "description": "Schema for a complex order response (unified across all complex order types)." }, "ComplexOrderListResponse": { "properties": { "complex_orders": { "additionalProperties": { "items": { "$ref": "#/components/schemas/ComplexOrderResponse" }, "type": "array" }, "type": "object", "title": "Complex Orders", "description": "List of complex orders matching the query" }, "count": { "type": "integer", "title": "Count", "description": "Total count of matching complex orders (for pagination)" } }, "type": "object", "required": [ "complex_orders", "count" ], "title": "ComplexOrderListResponse", "description": "Schema for list of complex orders (all types)." }, "ComplexOrderResponse": { "properties": { "complex_order_id": { "type": "string", "format": "uuid", "title": "Complex Order Id", "description": "Unique complex order identifier" }, "complex_order_type": { "type": "string", "title": "Complex Order Type", "description": "Complex order type: CONDITIONAL, TWAP, etc." }, "complex_order_subtype": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Complex Order Subtype", "description": "Complex order subtype: TP, SL, STOP, etc." }, "subaccount_id": { "type": "string", "format": "uuid", "title": "Subaccount Id", "description": "Subaccount the order belongs to" }, "river_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "River Id", "description": "Instrument ID" }, "generic_asset_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Generic Asset Id", "description": "Generic asset basket ID" }, "status": { "type": "string", "title": "Status", "description": "Order status (interpretation depends on complex_order_type)" }, "created_at": { "type": "string", "title": "Created At", "description": "Creation timestamp (UTC)" }, "updated_at": { "type": "string", "title": "Updated At", "description": "Last update timestamp (UTC)" }, "conditional_order": { "anyOf": [ { "$ref": "#/components/schemas/ConditionalOrderResponse" }, { "type": "null" } ], "description": "Conditional order detail" }, "iceberg_order": { "anyOf": [ { "$ref": "#/components/schemas/IcebergOrderResponse" }, { "type": "null" } ], "description": "Iceberg order detail" }, "peg_order": { "anyOf": [ { "$ref": "#/components/schemas/PegOrderResponse" }, { "type": "null" } ], "description": "Peg order detail" }, "smart_taker_order": { "anyOf": [ { "$ref": "#/components/schemas/SmartTakerOrderResponse" }, { "type": "null" } ], "description": "Smart-taker order detail" } }, "type": "object", "required": [ "complex_order_id", "complex_order_type", "subaccount_id", "status", "created_at", "updated_at" ], "title": "ComplexOrderResponse", "description": "Schema for a complex order response (unified across all complex order types)." }, "ConditionalOrderCreate": { "properties": { "conditional_order_type": { "type": "string", "enum": [ "TP", "SL", "STOP", "REVERSE_STOP" ], "description": "Type of conditional order: TP (take profit), SL (stop loss), or STOP" }, "stop_order_price": { "anyOf": [ { "type": "number", "exclusiveMaximum": 1.0, "exclusiveMinimum": 0.0 }, { "type": "null" } ], "title": "Stop Order Price", "description": "Activation price for STOP conditional orders. This is the price at which the conditional order triggers and places the trigger_order." }, "trigger_order": { "$ref": "#/components/schemas/TriggerOrder", "description": "The order that gets placed when the conditional order activates. For TP/SL this happens after the parent order fills; for STOP this happens when stop_order_price is reached." }, "parent_river_order_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Parent River Order Id", "description": "Parent order ID (required for TP and SL)" }, "parent_complex_order_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Parent Complex Order Id", "description": "Parent complex order ID (for chaining)" } }, "type": "object", "required": [ "conditional_order_type", "trigger_order" ], "title": "ConditionalOrderCreate", "description": "Schema for a conditional order (take profit or stop loss) attached to a parent order." }, "ConditionalOrderResponse": { "properties": { "parent_river_order_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Parent River Order Id", "description": "Parent order ID that this conditional is attached to (for TP/SL)" }, "parent_complex_order_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Parent Complex Order Id", "description": "Parent complex order ID that this conditional is attached to (for chaining)" }, "conditional_order_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conditional Order Type", "description": "Type of conditional order: TP (take profit), SL (stop loss), or STOP" }, "stop_order_price": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Stop Order Price", "description": "Activation price for STOP conditional orders. The price at which the conditional triggers and places the trigger order." }, "trigger_stop_order_price": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Trigger Stop Order Price", "description": "Stop/reverse-stop price for the triggered order (SL or TP MARKET)" }, "trigger_order_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trigger Order Type", "description": "Order type of the triggered order: LIMIT or MARKET" }, "trigger_order_qty": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Trigger Order Qty", "description": "Quantity of the triggered order" }, "trigger_order_limit_price": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Trigger Order Limit Price", "description": "Limit price of the triggered order (if LIMIT)" }, "trigger_order_buy_flag": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Trigger Order Buy Flag", "description": "Direction of the triggered order: true=buy, false=sell" }, "trigger_river_order_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Trigger River Order Id", "description": "River order ID of the triggered order (set once activated)" }, "trigger_complex_order_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Trigger Complex Order Id", "description": "Complex order ID of the triggered order (set once activated)" } }, "type": "object", "title": "ConditionalOrderResponse", "description": "Response for a conditional order. Contains both the condition definition and the trigger order\nthat gets placed when the condition is met.\n\nFor TP/SL: the parent order fills \u2192 the conditional activates \u2192 the trigger order is placed.\nFor STOP/REVERSE_STOP: stop_order_price is reached \u2192 the trigger order is placed." }, "ConditionalOrderType": { "type": "integer", "enum": [ 1, 2, 3, 4 ], "title": "ConditionalOrderType" }, "ExchangeBalance": { "properties": { "exchange_id": { "type": "integer", "title": "Exchange Id" }, "exchange_name": { "type": "string", "title": "Exchange Name" }, "balance": { "anyOf": [ { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Balance" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" } }, "type": "object", "required": [ "exchange_id", "exchange_name" ], "title": "ExchangeBalance" }, "ExchangeBalanceResponse": { "properties": { "subaccount_id": { "type": "string", "format": "uuid", "title": "Subaccount Id" }, "balances": { "items": { "$ref": "#/components/schemas/ExchangeBalance" }, "type": "array", "title": "Balances" } }, "type": "object", "required": [ "subaccount_id", "balances" ], "title": "ExchangeBalanceResponse" }, "FairValueListResponse": { "properties": { "fair_values": { "items": { "$ref": "#/components/schemas/FairValueResponse" }, "type": "array", "title": "Fair Values" } }, "type": "object", "required": [ "fair_values" ], "title": "FairValueListResponse" }, "FairValueResponse": { "properties": { "subaccount_id": { "type": "string", "format": "uuid", "title": "Subaccount Id" }, "river_id": { "type": "integer", "title": "River Id" }, "fair_value": { "type": "number", "title": "Fair Value" }, "updated_at": { "type": "string", "title": "Updated At" } }, "type": "object", "required": [ "subaccount_id", "river_id", "fair_value", "updated_at" ], "title": "FairValueResponse", "description": "A user-set fair value for one instrument on one subaccount." }, "FairValueUpsert": { "properties": { "subaccount_id": { "type": "string", "format": "uuid", "title": "Subaccount Id" }, "river_id": { "type": "integer", "title": "River Id" }, "fair_value": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "Fair Value", "description": "Probability in [0, 1]" } }, "type": "object", "required": [ "subaccount_id", "river_id", "fair_value" ], "title": "FairValueUpsert", "description": "Request schema for setting a fair value (insert-or-overwrite)." }, "FillResponse": { "properties": { "river_id": { "type": "integer", "title": "River Id" }, "client_order_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Order Id" }, "exchange_order_id": { "type": "string", "title": "Exchange Order Id" }, "exchange_trade_id": { "type": "string", "title": "Exchange Trade Id" }, "exchange_timestamp": { "type": "string", "title": "Exchange Timestamp", "description": "Execution timestamp from exchange (UTC)" }, "price": { "type": "number", "title": "Price" }, "qty": { "type": "number", "title": "Qty" }, "fee": { "type": "number", "title": "Fee" }, "buy_flag": { "type": "boolean", "title": "Buy Flag" }, "is_maker": { "type": "boolean", "title": "Is Maker" }, "counterparty_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Counterparty Address" }, "counterparty_exchange_order_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Counterparty Exchange Order Id" } }, "type": "object", "required": [ "river_id", "exchange_order_id", "exchange_trade_id", "exchange_timestamp", "price", "qty", "fee", "buy_flag", "is_maker" ], "title": "FillResponse", "description": "Schema for fill response." }, "GenericAssetCreate": { "properties": { "subaccount_id": { "type": "string", "format": "uuid", "title": "Subaccount Id" }, "name": { "type": "string", "maxLength": 255, "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "river_ids": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "River Ids" } }, "type": "object", "required": [ "subaccount_id", "name" ], "title": "GenericAssetCreate", "description": "Request schema for creating a new user-owned generic asset (basket)." }, "GenericAssetDetailResponse": { "properties": { "generic_asset_id": { "type": "string", "format": "uuid", "title": "Generic Asset Id" }, "owner_subaccount_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Owner Subaccount Id" }, "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" }, "subcategory": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subcategory" }, "resolves_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Resolves At" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "members": { "items": { "$ref": "#/components/schemas/MarketSearchResult" }, "type": "array", "title": "Members" }, "inserted_at": { "type": "string", "title": "Inserted At", "description": "Creation timestamp (UTC)" } }, "type": "object", "required": [ "generic_asset_id", "name", "members", "inserted_at" ], "title": "GenericAssetDetailResponse", "description": "Response schema for a generic asset with its resolved members (detail view)." }, "GenericAssetListResponse": { "properties": { "assets": { "items": { "$ref": "#/components/schemas/GenericAssetResponse" }, "type": "array", "title": "Assets" } }, "type": "object", "required": [ "assets" ], "title": "GenericAssetListResponse" }, "GenericAssetMemberAdd": { "properties": { "river_ids": { "items": { "type": "integer" }, "type": "array", "minItems": 1, "title": "River Ids" } }, "type": "object", "required": [ "river_ids" ], "title": "GenericAssetMemberAdd", "description": "Request schema for adding members to a user-owned generic asset." }, "GenericAssetMemberRemove": { "properties": { "river_ids": { "items": { "type": "integer" }, "type": "array", "minItems": 1, "title": "River Ids" } }, "type": "object", "required": [ "river_ids" ], "title": "GenericAssetMemberRemove", "description": "Request schema for removing members from a user-owned generic asset." }, "GenericAssetResponse": { "properties": { "generic_asset_id": { "type": "string", "title": "Generic Asset Id" }, "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" }, "subcategory": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subcategory" }, "resolves_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Resolves At" }, "owner_subaccount_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner Subaccount Id" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "river_ids": { "items": { "type": "integer" }, "type": "array", "title": "River Ids" }, "inserted_at": { "type": "string", "title": "Inserted At", "description": "Creation timestamp (UTC)" } }, "type": "object", "required": [ "generic_asset_id", "name", "river_ids", "inserted_at" ], "title": "GenericAssetResponse", "description": "A tradeable generic asset (platform-curated or user-owned) with its member river_ids." }, "GenericAssetUpdate": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" } }, "type": "object", "title": "GenericAssetUpdate", "description": "Request schema for updating a user-owned generic asset." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "IcebergOrderParams": { "properties": { "buy_flag": { "type": "boolean", "title": "Buy Flag", "description": "Direction: true=buy, false=sell" }, "total_qty": { "type": "number", "exclusiveMinimum": 0.0, "title": "Total Qty", "description": "Total iceberg quantity (across all tranches)" }, "displayed_qty": { "type": "number", "exclusiveMinimum": 0.0, "title": "Displayed Qty", "description": "Tranche size \u2014 quantity shown to the market at any moment" }, "limit_price": { "type": "number", "exclusiveMaximum": 1.0, "exclusiveMinimum": 0.0, "title": "Limit Price", "description": "Static limit price for every tranche (between 0 and 1)" }, "post_only": { "type": "boolean", "title": "Post Only", "description": "If true, every tranche is posted as post-only (maker-only)", "default": false }, "cancel_order_on_pause": { "type": "boolean", "title": "Cancel Order On Pause", "description": "Kalshi only: if true, resting tranches are cancelled by the exchange when it enters a trading pause. Ignored on other venues.", "default": true }, "reload_delay_s": { "anyOf": [ { "type": "integer", "maximum": 3600.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Reload Delay S", "description": "Optional delay between a tranche fully filling and the next one being placed, in seconds. NULL or 0 = place next tranche immediately." }, "expiry_ts_utc": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expiry Ts Utc", "description": "Optional expiry timestamp in UTC (ISO 8601). When set, every tranche is submitted to the venue as GTD with this expiry; venue-side expiry of a tranche cascades to cancel the parent iceberg." } }, "type": "object", "required": [ "buy_flag", "total_qty", "displayed_qty", "limit_price" ], "title": "IcebergOrderParams", "description": "Parameters for creating an iceberg complex order.\n\nAn iceberg's `total_qty` is split into sequential `displayed_qty` tranches\nposted at the same `limit_price`. When a tranche fully fills, the next is\nplaced automatically until the total is exhausted or the iceberg is cancelled." }, "IcebergOrderResponse": { "properties": { "buy_flag": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Buy Flag", "description": "Direction" }, "total_qty": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Qty", "description": "Total iceberg quantity" }, "displayed_qty": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Displayed Qty", "description": "Tranche size" }, "limit_price": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Limit Price", "description": "Static limit price for every tranche" }, "post_only": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Post Only", "description": "Whether tranches are posted as post-only" }, "cancel_order_on_pause": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Cancel Order On Pause", "description": "Kalshi only: whether the exchange cancels resting tranches during a trading pause" }, "reload_delay_s": { "anyOf": [ { "type": "integer", "maximum": 3600.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Reload Delay S", "description": "Inter-tranche reload delay in seconds, if set. NULL or 0 = place next tranche immediately." }, "executed_qty": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Executed Qty", "description": "Sum of fully-executed child tranches' qty" }, "remaining_qty": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Remaining Qty", "description": "total_qty - executed_qty" }, "expiry_ts_utc": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expiry Ts Utc", "description": "Expiry timestamp in UTC, if set. Tranches are submitted as GTD with this expiry." }, "reject_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reject Reason", "description": "Reason for rejection, if any" } }, "type": "object", "title": "IcebergOrderResponse", "description": "Iceberg-specific runtime detail returned alongside a ComplexOrderResponse.\n\nSourced from `view_iceberg_orders` so it includes derived fields\n(executed_qty, remaining_qty)." }, "InstrumentStatus": { "type": "string", "enum": [ "active", "closed", "inactive" ], "title": "InstrumentStatus", "description": "Instrument status derived in instruments table from exchange-specific fields.\n\nKalshi: maps from kalshi_markets.status\n - 'active' -> ACTIVE\n - everything else (closed, determined, finalized, settled, amended, inactive, initialized) -> CLOSED\n\nPolymarket: maps from polymarket_markets.closed and polymarket_markets.active booleans\n - closed=true -> CLOSED\n - active=true (and not closed) -> ACTIVE\n - else (active=false, closed=false) -> INACTIVE" }, "MarketLookupResponse": { "properties": { "results": { "items": { "$ref": "#/components/schemas/MarketSearchResult" }, "type": "array", "title": "Results" } }, "type": "object", "required": [ "results" ], "title": "MarketLookupResponse", "description": "Schema for batch market lookup response." }, "MarketMatchBatchRequest": { "properties": { "tickers": { "items": { "type": "string" }, "type": "array", "title": "Tickers", "description": "Exact Kalshi tickers to resolve (e.g. KXNBA-26-DET)." }, "slugs": { "items": { "type": "string" }, "type": "array", "title": "Slugs", "description": "Exact Polymarket / Polymarket-US slugs to resolve (e.g. will-the-denver-nuggets-win-the-2026-nba-finals)." } }, "type": "object", "title": "MarketMatchBatchRequest", "description": "Batch exact-match request: resolve many Kalshi tickers / Polymarket slugs at once." }, "MarketMatchBatchResponse": { "properties": { "results": { "items": { "$ref": "#/components/schemas/MarketSearchResult" }, "type": "array", "title": "Results" }, "unmatched_tickers": { "items": { "type": "string" }, "type": "array", "title": "Unmatched Tickers" }, "unmatched_slugs": { "items": { "type": "string" }, "type": "array", "title": "Unmatched Slugs" } }, "type": "object", "required": [ "results" ], "title": "MarketMatchBatchResponse", "description": "Batch exact-match response.\n\n``results`` holds a full market row (with ``river_id``, ``ticker``, ``slug`` and\n``exchange_name``) for every identifier that matched. Identifiers with no match are\nechoed back in ``unmatched_tickers`` / ``unmatched_slugs`` so callers can tell the\ndifference between \"not found\" and a lookup they forgot to send." }, "MarketSearchResponse": { "properties": { "query": { "type": "string", "title": "Query" }, "results": { "items": { "$ref": "#/components/schemas/MarketSearchResult" }, "type": "array", "title": "Results" }, "total": { "type": "integer", "title": "Total" }, "total_events": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Events" } }, "type": "object", "required": [ "query", "results", "total" ], "title": "MarketSearchResponse", "description": "Schema for market search response." }, "MarketSearchResult": { "properties": { "river_id": { "type": "integer", "title": "River Id" }, "exchange_value": { "type": "integer", "title": "Exchange Value" }, "exchange_name": { "type": "string", "title": "Exchange Name" }, "ticker": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ticker" }, "token_id_yes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token Id Yes" }, "token_id_no": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Token Id No" }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Slug" }, "tick_size_price": { "type": "number", "title": "Tick Size Price" }, "tick_size_qty": { "type": "number", "title": "Tick Size Qty" }, "tick_structure": { "type": "string", "title": "Tick Structure", "default": "uniform" }, "minimum_order_size": { "type": "number", "title": "Minimum Order Size" }, "expiration_datetime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expiration Datetime", "description": "Market expiration datetime (UTC)" }, "start_datetime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Start Datetime", "description": "Game/event start datetime (UTC). Populated for sports; null otherwise." }, "neg_risk": { "type": "boolean", "title": "Neg Risk" }, "neg_risk_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Neg Risk Id" }, "condition_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Condition Id" }, "name": { "type": "string", "title": "Name" }, "subtitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subtitle" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "status": { "$ref": "#/components/schemas/InstrumentStatus" }, "category": { "type": "string", "title": "Category", "default": "Other" }, "subcategory": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subcategory" }, "rank": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Rank" }, "event_ticker": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Event Ticker" }, "event_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Event Title" }, "volume": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Volume" }, "volume_24h": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Volume 24H" }, "series_ticker": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Series Ticker" }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Image" }, "last_price": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Last Price", "description": "Most recent YES price normalized to 0.0\u20131.0 (probability). Kalshi cents / 100; Polymarket already 0.0\u20131.0. NULL when no trade has been observed." }, "primary_entity_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Primary Entity Name", "description": "Resolved display name of the canonical structured-target entity (player, team, competitor, \u2026) referenced by the market. NULL for markets without a structured target. Kalshi only \u2014 Polymarket has no equivalent concept." } }, "type": "object", "required": [ "river_id", "exchange_value", "exchange_name", "tick_size_price", "tick_size_qty", "minimum_order_size", "neg_risk", "name", "status" ], "title": "MarketSearchResult", "description": "Schema for a single market search result." }, "OrderCreate": { "properties": { "order_type": { "type": "string", "enum": [ "LIMIT", "MARKET", "RFQ_TAKER" ], "description": "Order type: 'LIMIT' or 'MARKET'" }, "time_in_force": { "type": "string", "enum": [ "FOK", "GTC", "GTD", "IOC" ], "description": "Time in force: 'FOK', 'GTC', 'GTD', or 'IOC'" }, "qty": { "type": "number", "exclusiveMinimum": 0.0, "title": "Qty", "description": "Order quantity (number of contracts)" }, "price": { "anyOf": [ { "type": "number", "exclusiveMaximum": 1.0, "exclusiveMinimum": 0.0 }, { "type": "null" } ], "title": "Price", "description": "Limit price between 0 and 1. Required for LIMIT orders." }, "buy_flag": { "type": "boolean", "title": "Buy Flag", "description": "Order direction: true=buy, false=sell" }, "post_only": { "type": "boolean", "title": "Post Only", "description": "If true, the order is rejected instead of taking liquidity. Only valid for LIMIT orders with a resting time in force (GTC or GTD).", "default": false }, "cancel_order_on_pause": { "type": "boolean", "title": "Cancel Order On Pause", "description": "Kalshi only: if true, the resting order is cancelled by the exchange when it enters a trading pause. Ignored on other venues.", "default": true }, "river_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "River Id", "description": "Instrument ID. Mutually exclusive with generic_asset_id." }, "generic_asset_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Generic Asset Id", "description": "Generic asset basket UUID. Mutually exclusive with river_id." }, "subaccount_id": { "type": "string", "format": "uuid", "title": "Subaccount Id", "description": "Subaccount to place the order under" }, "expiry_ts_utc": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expiry Ts Utc", "description": "Expiry timestamp in UTC(ISO 8601). Required for GTD orders. i.e '2023-11-07T05:31:56Z'" }, "conditional_orders_params": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ConditionalOrderCreate" }, "type": "array" }, { "type": "null" } ], "title": "Conditional Orders Params", "description": "Optional list of conditional orders (TP/SL) to attach to this order." } }, "type": "object", "required": [ "order_type", "time_in_force", "qty", "buy_flag", "subaccount_id" ], "title": "OrderCreate", "description": "Schema for creating a new order." }, "OrderCreateResponse": { "properties": { "river_order_id": { "type": "string", "format": "uuid", "title": "River Order Id", "description": "Unique order identifier" }, "complex_orders": { "additionalProperties": { "items": { "type": "string", "format": "uuid" }, "type": "array" }, "type": "object", "title": "Complex Orders", "description": "List of complex river orders id" } }, "type": "object", "required": [ "river_order_id", "complex_orders" ], "title": "OrderCreateResponse", "description": "Schema for order create response." }, "OrderDetailResponse": { "properties": { "river_order_id": { "type": "string", "format": "uuid", "title": "River Order Id", "description": "Unique order identifier" }, "order_type": { "type": "string", "title": "Order Type", "description": "Order type: LIMIT or MARKET" }, "time_in_force": { "type": "string", "title": "Time In Force", "description": "Time in force: FOK, GTC, GTD, or IOC" }, "qty": { "type": "number", "title": "Qty", "description": "Original order quantity" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Price", "description": "Limit price (null for market orders)" }, "buy_flag": { "type": "boolean", "title": "Buy Flag", "description": "Order direction: true=buy, false=sell" }, "post_only": { "type": "boolean", "title": "Post Only", "description": "Whether the order is post-only (maker-only)", "default": false }, "cancel_order_on_pause": { "type": "boolean", "title": "Cancel Order On Pause", "description": "Kalshi only: whether the exchange cancels the resting order during a trading pause", "default": true }, "status": { "type": "string", "title": "Status", "description": "Order status. Live: PENDING_SUBMISSION, PROCESSING, RESTING. Terminal: EXECUTED, PARTIALLY_FILLED (cancelled with some fills), CANCELLED, REJECTED." }, "river_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "River Id", "description": "Instrument ID" }, "generic_asset_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Generic Asset Id", "description": "Generic asset basket UUID" }, "subaccount_id": { "type": "string", "format": "uuid", "title": "Subaccount Id", "description": "Subaccount the order belongs to" }, "expiry_ts_utc": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expiry Ts Utc", "description": "Expiry timestamp in UTC for GTD orders" }, "created_at": { "type": "string", "title": "Created At", "description": "Order creation timestamp (UTC)" }, "updated_at": { "type": "string", "title": "Updated At", "description": "Last update timestamp (UTC)" }, "traded_qty": { "type": "number", "title": "Traded Qty", "description": "Total quantity filled", "default": 0.0 }, "average_price": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Average Price", "description": "Volume-weighted average fill price" }, "fees_paid": { "type": "number", "title": "Fees Paid", "description": "Total fees paid across all fills", "default": 0.0 }, "complex_order_ids": { "additionalProperties": { "items": { "type": "string", "format": "uuid" }, "type": "array" }, "type": "object", "title": "Complex Order Ids", "description": "List of complex river orders id" }, "reject_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reject Reason", "description": "Reason for rejection (if status is REJECTED)" }, "parent_iceberg_order_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Parent Iceberg Order Id", "description": "If this order is a tranche of an iceberg parent, the parent's id; otherwise null." }, "parent_peg_order_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Parent Peg Order Id", "description": "If this order is the resting child of a peg parent, the parent's id; otherwise null." }, "parent_smart_taker_order_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Parent Smart Taker Order Id", "description": "If this order is an IOC child of a smart-taker parent, the parent's id; otherwise null." }, "fills": { "items": { "$ref": "#/components/schemas/OrderFillResponse" }, "type": "array", "title": "Fills", "description": "List of executions (fills) for this order", "default": [] } }, "type": "object", "required": [ "river_order_id", "order_type", "time_in_force", "qty", "buy_flag", "status", "subaccount_id", "created_at", "updated_at", "complex_order_ids" ], "title": "OrderDetailResponse", "description": "Schema for order detail response including fills." }, "OrderEditRequest": { "properties": { "qty": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "null" } ], "title": "Qty", "description": "New total order quantity" }, "price": { "anyOf": [ { "type": "number", "exclusiveMaximum": 1.0, "exclusiveMinimum": 0.0 }, { "type": "null" } ], "title": "Price", "description": "New limit price (between 0 and 1)" } }, "type": "object", "title": "OrderEditRequest", "description": "Schema for editing (amending) an existing simple limit order.\n\n`qty` is the TOTAL order quantity (not remaining) \u2014 matches Kalshi's amend semantics.\nAt least one of `qty` or `price` must be provided." }, "OrderEditResponse": { "properties": { "river_order_id": { "type": "string", "format": "uuid", "title": "River Order Id", "description": "Unique order identifier" }, "status": { "type": "string", "title": "Status", "description": "Always PENDING_AMEND. Final status (RESTING on success, REJECTED on failure) is delivered via the orders WS." } }, "type": "object", "required": [ "river_order_id", "status" ], "title": "OrderEditResponse", "description": "Schema for order edit response." }, "OrderFillResponse": { "properties": { "river_id": { "type": "integer", "title": "River Id", "description": "Instrument ID" }, "exchange_order_id": { "type": "string", "title": "Exchange Order Id", "description": "Exchange-assigned order ID" }, "exchange_trade_id": { "type": "string", "title": "Exchange Trade Id", "description": "Exchange-assigned trade/fill ID" }, "exchange_timestamp": { "type": "string", "title": "Exchange Timestamp", "description": "Execution timestamp from exchange (UTC)" }, "price": { "type": "number", "title": "Price", "description": "Execution price" }, "qty": { "type": "number", "title": "Qty", "description": "Filled quantity" }, "fee": { "type": "number", "title": "Fee", "description": "Fee charged by the exchange for this fill" }, "buy_flag": { "type": "boolean", "title": "Buy Flag", "description": "Fill direction: true=buy, false=sell" }, "is_maker": { "type": "boolean", "title": "Is Maker", "description": "Whether this fill provided liquidity (maker) or took it (taker)" } }, "type": "object", "required": [ "river_id", "exchange_order_id", "exchange_trade_id", "exchange_timestamp", "price", "qty", "fee", "buy_flag", "is_maker" ], "title": "OrderFillResponse", "description": "Schema for a single fill on an order." }, "OrderListResponse": { "properties": { "orders": { "items": { "$ref": "#/components/schemas/OrderResponse" }, "type": "array", "title": "Orders", "description": "List of orders matching the query" }, "count": { "type": "integer", "title": "Count", "description": "Total count of matching orders (for pagination)" } }, "type": "object", "required": [ "orders", "count" ], "title": "OrderListResponse", "description": "Schema for list of orders." }, "OrderQueuePositionResponse": { "properties": { "river_order_id": { "type": "string", "format": "uuid", "title": "River Order Id", "description": "River order identifier" }, "exchange_order_id": { "type": "string", "title": "Exchange Order Id", "description": "Exchange order ID with the best (minimum) queue priority" }, "queue_position": { "type": "number", "title": "Queue Position", "description": "Number of preceding shares in the queue ahead of this order (lower is better priority)" } }, "type": "object", "required": [ "river_order_id", "exchange_order_id", "queue_position" ], "title": "OrderQueuePositionResponse", "description": "Schema for the queue-position response of an order." }, "OrderResponse": { "properties": { "river_order_id": { "type": "string", "format": "uuid", "title": "River Order Id", "description": "Unique order identifier" }, "order_type": { "type": "string", "title": "Order Type", "description": "Order type: LIMIT or MARKET" }, "time_in_force": { "type": "string", "title": "Time In Force", "description": "Time in force: FOK, GTC, GTD, or IOC" }, "qty": { "type": "number", "title": "Qty", "description": "Original order quantity" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Price", "description": "Limit price (null for market orders)" }, "buy_flag": { "type": "boolean", "title": "Buy Flag", "description": "Order direction: true=buy, false=sell" }, "post_only": { "type": "boolean", "title": "Post Only", "description": "Whether the order is post-only (maker-only)", "default": false }, "cancel_order_on_pause": { "type": "boolean", "title": "Cancel Order On Pause", "description": "Kalshi only: whether the exchange cancels the resting order during a trading pause", "default": true }, "status": { "type": "string", "title": "Status", "description": "Order status. Live: PENDING_SUBMISSION, PROCESSING, RESTING. Terminal: EXECUTED, PARTIALLY_FILLED (cancelled with some fills), CANCELLED, REJECTED." }, "river_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "River Id", "description": "Instrument ID" }, "generic_asset_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Generic Asset Id", "description": "Generic asset basket UUID" }, "subaccount_id": { "type": "string", "format": "uuid", "title": "Subaccount Id", "description": "Subaccount the order belongs to" }, "expiry_ts_utc": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expiry Ts Utc", "description": "Expiry timestamp in UTC for GTD orders" }, "created_at": { "type": "string", "title": "Created At", "description": "Order creation timestamp (UTC)" }, "updated_at": { "type": "string", "title": "Updated At", "description": "Last update timestamp (UTC)" }, "traded_qty": { "type": "number", "title": "Traded Qty", "description": "Total quantity filled", "default": 0.0 }, "average_price": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Average Price", "description": "Volume-weighted average fill price" }, "fees_paid": { "type": "number", "title": "Fees Paid", "description": "Total fees paid across all fills", "default": 0.0 }, "complex_order_ids": { "additionalProperties": { "items": { "type": "string", "format": "uuid" }, "type": "array" }, "type": "object", "title": "Complex Order Ids", "description": "List of complex river orders id" }, "reject_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reject Reason", "description": "Reason for rejection (if status is REJECTED)" }, "parent_iceberg_order_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Parent Iceberg Order Id", "description": "If this order is a tranche of an iceberg parent, the parent's id; otherwise null." }, "parent_peg_order_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Parent Peg Order Id", "description": "If this order is the resting child of a peg parent, the parent's id; otherwise null." }, "parent_smart_taker_order_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Parent Smart Taker Order Id", "description": "If this order is an IOC child of a smart-taker parent, the parent's id; otherwise null." } }, "type": "object", "required": [ "river_order_id", "order_type", "time_in_force", "qty", "buy_flag", "status", "subaccount_id", "created_at", "updated_at", "complex_order_ids" ], "title": "OrderResponse", "description": "Schema for order response, when user request information about an order." }, "OrderTimeInForce": { "type": "integer", "enum": [ 1, 2, 3, 4 ], "title": "OrderTimeInForce", "description": "Time-in-force setting. Can be FOK (Fill or kill), GTC (Good till cancelled) or GTD (Good till date)." }, "OrderType": { "type": "integer", "enum": [ 1, 2, 3 ], "title": "OrderType" }, "OrderbookData": { "properties": { "river_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "River Id" }, "generic_asset_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Generic Asset Id" }, "bids": { "items": { "$ref": "#/components/schemas/PriceLevelResponse" }, "type": "array", "title": "Bids" }, "asks": { "items": { "$ref": "#/components/schemas/PriceLevelResponse" }, "type": "array", "title": "Asks" }, "best_bid_price": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Best Bid Price" }, "best_ask_price": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Best Ask Price" }, "exchange_timestamp": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Exchange Timestamp", "description": "Exchange orderbook timestamp (UTC)" } }, "type": "object", "required": [ "bids", "asks" ], "title": "OrderbookData" }, "OrderbookResponse": { "properties": { "status": { "$ref": "#/components/schemas/OrderbookStatus" }, "orderbook": { "anyOf": [ { "$ref": "#/components/schemas/OrderbookData" }, { "type": "null" } ] }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message" } }, "type": "object", "required": [ "status" ], "title": "OrderbookResponse" }, "OrderbookStatus": { "type": "string", "enum": [ "ok", "pending", "not_found" ], "title": "OrderbookStatus" }, "PegOrderParams": { "properties": { "buy_flag": { "type": "boolean", "title": "Buy Flag", "description": "Direction: true=buy, false=sell" }, "total_qty": { "type": "number", "exclusiveMinimum": 0.0, "title": "Total Qty", "description": "Total peg quantity" }, "min_price": { "anyOf": [ { "type": "number", "exclusiveMaximum": 1.0, "exclusiveMinimum": 0.0 }, { "type": "null" } ], "title": "Min Price", "description": "Price floor \u2014 the child never rests below this (between 0 and 1)" }, "max_price": { "anyOf": [ { "type": "number", "exclusiveMaximum": 1.0, "exclusiveMinimum": 0.0 }, { "type": "null" } ], "title": "Max Price", "description": "Price ceiling \u2014 the child never rests above this (between 0 and 1)" }, "post_only": { "type": "boolean", "title": "Post Only", "description": "If true, the resting child order is posted as post-only; a repeg that would cross the book cancels the peg instead of taking liquidity", "default": false }, "expiry_ts_utc": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expiry Ts Utc", "description": "Optional expiry timestamp in UTC (ISO 8601). When set, the resting child is submitted to the venue as GTD with this expiry; venue-side expiry cancels the peg (caught by the periodic reconciliation sweep)." }, "peg_min_stay_time_s": { "anyOf": [ { "type": "integer", "maximum": 3600.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Peg Min Stay Time S", "description": "Optional repeg gate. When set, a price-driven repeg is suppressed until the resting child has been on the book for at least this many seconds (measured from send time). Expiry-driven cancels are unaffected." }, "max_qty_level": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "null" } ], "title": "Max Qty Level", "description": "Penny-jump threshold (contracts). If the level the peg would join holds more than this many contracts, rest one tick tighter instead (if not crossing the book and not already quoting the level). Unset to disable." } }, "type": "object", "required": [ "buy_flag", "total_qty" ], "title": "PegOrderParams", "description": "Parameters for creating a peg complex order.\n\nA peg's child limit order rests on the venue at the current best bid (for buys)\nor best ask (for sells), clamped to the absolute band [min_price, max_price]:\nthe child never rests below min_price or above max_price. Both bounds are\noptional \u2014 an unset min floors at 0, an unset max ceils at 1. The peg worker\nrepegs the child as the top of book moves." }, "PegOrderResponse": { "properties": { "buy_flag": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Buy Flag", "description": "Direction" }, "total_qty": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Qty", "description": "Total peg quantity" }, "min_price": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Min Price", "description": "Price floor \u2014 the child never rests below this" }, "max_price": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Max Price", "description": "Price ceiling \u2014 the child never rests above this" }, "post_only": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Post Only", "description": "Whether the resting child order is post-only" }, "executed_qty": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Executed Qty", "description": "Sum of filled child qty" }, "remaining_qty": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Remaining Qty", "description": "total_qty - executed_qty" }, "expiry_ts_utc": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expiry Ts Utc", "description": "Expiry timestamp in UTC, if set. The child is submitted as GTD with this expiry." }, "peg_min_stay_time_s": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Peg Min Stay Time S", "description": "Minimum seconds a resting child must stay on the book before a price-driven repeg is allowed, if set." }, "max_qty_level": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Max Qty Level", "description": "Penny-jump threshold (contracts): levels larger than this are stepped past, one tick inside the spread." }, "reject_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reject Reason", "description": "Reason for rejection, if any" } }, "type": "object", "title": "PegOrderResponse", "description": "Peg-specific runtime detail returned alongside a ComplexOrderResponse.\n\nSourced from `view_peg_orders` so it includes derived fields\n(executed_qty, remaining_qty)." }, "PositionResponse": { "properties": { "river_id": { "type": "integer", "title": "River Id" }, "position": { "type": "number", "title": "Position" }, "avg_buy_price": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Avg Buy Price" }, "avg_sell_price": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Avg Sell Price" }, "total_fees": { "type": "number", "title": "Total Fees" }, "total_qty_bought": { "type": "number", "title": "Total Qty Bought" }, "total_qty_sold": { "type": "number", "title": "Total Qty Sold" }, "fill_count": { "type": "integer", "title": "Fill Count" }, "first_fill_at": { "type": "string", "title": "First Fill At" }, "last_fill_at": { "type": "string", "title": "Last Fill At" }, "exchange_name": { "type": "string", "title": "Exchange Name" }, "exchange_ticker": { "type": "string", "title": "Exchange Ticker" } }, "type": "object", "required": [ "river_id", "position", "total_fees", "total_qty_bought", "total_qty_sold", "fill_count", "first_fill_at", "last_fill_at", "exchange_name", "exchange_ticker" ], "title": "PositionResponse", "description": "Schema for a position (computed from cumulative fills)." }, "PriceCandlestick": { "properties": { "timestamp": { "type": "integer", "title": "Timestamp" }, "open": { "type": "number", "title": "Open" }, "high": { "type": "number", "title": "High" }, "low": { "type": "number", "title": "Low" }, "close": { "type": "number", "title": "Close" }, "volume": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Volume" } }, "type": "object", "required": [ "timestamp", "open", "high", "low", "close" ], "title": "PriceCandlestick", "description": "Candlestick format for all exchanges." }, "PriceLevelResponse": { "properties": { "price": { "type": "number", "title": "Price" }, "qty": { "type": "number", "title": "Qty" }, "breakdown": { "additionalProperties": { "type": "number" }, "type": "object", "title": "Breakdown" } }, "type": "object", "required": [ "price", "qty" ], "title": "PriceLevelResponse" }, "PricePoint": { "properties": { "timestamp": { "type": "integer", "title": "Timestamp" }, "price": { "type": "number", "title": "Price" } }, "type": "object", "required": [ "timestamp", "price" ], "title": "PricePoint", "description": "Simple price point for history type." }, "PriceResponse": { "properties": { "river_id": { "type": "integer", "title": "River Id" }, "exchange": { "type": "string", "title": "Exchange" }, "type": { "type": "string", "enum": [ "candlesticks", "history" ], "title": "Type" }, "has_ohlc": { "type": "boolean", "title": "Has Ohlc", "default": false }, "candlesticks": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PriceCandlestick" }, "type": "array" }, { "type": "null" } ], "title": "Candlesticks" }, "history": { "anyOf": [ { "items": { "$ref": "#/components/schemas/PricePoint" }, "type": "array" }, { "type": "null" } ], "title": "History" } }, "type": "object", "required": [ "river_id", "exchange", "type" ], "title": "PriceResponse", "description": "Response for price queries." }, "SmartTakerOrderParams": { "properties": { "buy_flag": { "type": "boolean", "title": "Buy Flag", "description": "Direction: true=buy, false=sell" }, "total_qty": { "type": "number", "exclusiveMinimum": 0.0, "title": "Total Qty", "description": "Total quantity to acquire/offload across all IOC clips" }, "limit_price": { "type": "number", "exclusiveMaximum": 1.0, "exclusiveMinimum": 0.0, "title": "Limit Price", "description": "Worst price the taker will accept \u2014 max for buy, min for sell (between 0 and 1)" }, "min_qty": { "type": "number", "exclusiveMinimum": 0.0, "title": "Min Qty", "description": "Book-depth trigger gate: only fire when at least this much acceptable liquidity sits within limit_price on the opposite side. A depth floor, not a per-clip fill floor \u2014 it may exceed total_qty (e.g. 'take my 100 only when >=500 is resting') and an IOC may fill less if liquidity vanishes mid-flight." }, "expiry_ts_utc": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expiry Ts Utc", "description": "Optional expiry timestamp in UTC (ISO 8601). Once it passes, the order stops firing and is torn down by the periodic reconciliation sweep." } }, "type": "object", "required": [ "buy_flag", "total_qty", "limit_price", "min_qty" ], "title": "SmartTakerOrderParams", "description": "Parameters for creating a smart-taker complex order.\n\nA smart-taker rests nothing on the book. It watches the opposite side and\nfires an IOC sweep (at `limit_price`, for the full remaining qty) whenever at\nleast `min_qty` of acceptable liquidity (price within `limit_price`) is\nresting on the book \u2014 amortising taker fee/spread and refusing to cross into\na thin book." }, "SmartTakerOrderResponse": { "properties": { "buy_flag": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Buy Flag", "description": "Direction" }, "total_qty": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Total Qty", "description": "Total quantity across all IOC clips" }, "limit_price": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Limit Price", "description": "Worst price the taker will accept" }, "min_qty": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Min Qty", "description": "Book-depth trigger gate (min acceptable liquidity resting before firing)" }, "executed_qty": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Executed Qty", "description": "Sum of filled child qty" }, "remaining_qty": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Remaining Qty", "description": "total_qty - executed_qty" }, "expiry_ts_utc": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expiry Ts Utc", "description": "Expiry timestamp in UTC, if set." }, "reject_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reject Reason", "description": "Reason for rejection, if any" } }, "type": "object", "title": "SmartTakerOrderResponse", "description": "Smart-taker-specific runtime detail returned alongside a ComplexOrderResponse.\n\nSourced from `view_smart_taker_orders` so it includes derived fields\n(executed_qty, remaining_qty)." }, "SubaccountCreate": { "properties": { "name": { "type": "string", "maxLength": 100, "title": "Name" }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "title": "Description" }, "account_type": { "$ref": "#/components/schemas/AccountType", "default": "non_custodial" } }, "type": "object", "required": [ "name" ], "title": "SubaccountCreate", "description": "Schema for creating a new subaccount." }, "SubaccountResponse": { "properties": { "subaccount_id": { "type": "string", "format": "uuid", "title": "Subaccount Id" }, "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "account_type": { "$ref": "#/components/schemas/AccountType" }, "is_active": { "type": "boolean", "title": "Is Active" }, "inserted_at": { "type": "string", "title": "Inserted At" } }, "type": "object", "required": [ "subaccount_id", "name", "account_type", "is_active", "inserted_at" ], "title": "SubaccountResponse", "description": "Schema for subaccount response." }, "SubaccountUpdate": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Name" }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "title": "Description" } }, "type": "object", "title": "SubaccountUpdate", "description": "Schema for updating a subaccount." }, "TradeprintEvent": { "properties": { "exchange_timestamp": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Exchange Timestamp", "description": "Exchange-reported trade timestamp (UTC)" }, "price": { "type": "number", "title": "Price" }, "qty": { "type": "number", "title": "Qty" }, "aggressor_buy_flag": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Aggressor Buy Flag" }, "exchange_trade_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Exchange Trade Id", "description": "Exchange-assigned trade id. Used by clients to dedup overlap between REST backfill and WS live stream." } }, "type": "object", "required": [ "price", "qty" ], "title": "TradeprintEvent", "description": "A single trade print.\n\n`aggressor_buy_flag` is true when the aggressing (taker) side bought \u2014\ni.e. the trade hit an ask. The frontend renders side color and \"Buy/Sell\"\nfrom this flag." }, "TradeprintsBulkResponse": { "properties": { "results": { "items": { "$ref": "#/components/schemas/TradeprintsResponse" }, "type": "array", "title": "Results" } }, "type": "object", "title": "TradeprintsBulkResponse", "description": "Response for `GET /v1/tradeprints?river_ids=...`.\n\n`results` preserves the order of the requested `river_ids`. Partial failures\nare surfaced per-row (status `not_found`) with a `message` \u2014 a bad river_id\nor upstream error never aborts the whole call." }, "TradeprintsResponse": { "properties": { "status": { "$ref": "#/components/schemas/TradeprintsStatus" }, "river_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "River Id" }, "trades": { "items": { "$ref": "#/components/schemas/TradeprintEvent" }, "type": "array", "title": "Trades" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message" } }, "type": "object", "required": [ "status" ], "title": "TradeprintsResponse", "description": "Per-market block of recent trades from the exchange." }, "TradeprintsStatus": { "type": "string", "enum": [ "ok", "pending", "not_found" ], "title": "TradeprintsStatus" }, "TriggerOrder": { "properties": { "order_type": { "type": "string", "enum": [ "LIMIT", "MARKET", "RFQ_TAKER" ], "description": "Order type for the triggered order: 'LIMIT' or 'MARKET'" }, "qty": { "type": "number", "exclusiveMinimum": 0.0, "title": "Qty", "description": "Quantity (number of contracts) for the triggered order" }, "price": { "anyOf": [ { "type": "number", "exclusiveMaximum": 1.0, "exclusiveMinimum": 0.0 }, { "type": "null" } ], "title": "Price", "description": "Limit price for the triggered order (between 0 and 1). Required when order_type is LIMIT." }, "buy_flag": { "type": "boolean", "title": "Buy Flag", "description": "Direction of the triggered order: true=buy, false=sell" }, "stop_order_price": { "anyOf": [ { "type": "number", "exclusiveMaximum": 1.0, "exclusiveMinimum": 0.0 }, { "type": "null" } ], "title": "Stop Order Price", "description": "Price at which the triggered order activates as a stop or reverse stop. Required for SL (stop trigger) and TP MARKET (reverse stop trigger). For SL: triggers when price moves against you. For TP MARKET: triggers when price moves in your favor." } }, "type": "object", "required": [ "order_type", "qty", "buy_flag" ], "title": "TriggerOrder", "description": "The order that will be sent to the exchange when the conditional order's condition is met.\n\nFor TP/SL: the parent order fills \u2192 the conditional activates \u2192 this trigger order is placed.\nFor STOP/REVERSE_STOP: the stop_order_price is reached \u2192 this trigger order is placed." }, "UserFillListResponse": { "properties": { "subaccount_to_fills": { "items": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "items": { "$ref": "#/components/schemas/FillResponse" }, "type": "array" } ] }, "type": "object" }, "type": "array", "title": "Subaccount To Fills" } }, "type": "object", "required": [ "subaccount_to_fills" ], "title": "UserFillListResponse", "description": "Schema for list of fills for a user." }, "UserPositionListResponse": { "properties": { "subaccount_to_positions": { "items": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "items": { "$ref": "#/components/schemas/PositionResponse" }, "type": "array" } ] }, "type": "object" }, "type": "array", "title": "Subaccount To Positions" } }, "type": "object", "required": [ "subaccount_to_positions" ], "title": "UserPositionListResponse", "description": "Positions grouped by subaccount." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "VolumeResponse": { "properties": { "river_id": { "type": "integer", "title": "River Id" }, "window": { "type": "string", "enum": [ "15m", "1h", "24h" ], "title": "Window" }, "volume": { "type": "number", "title": "Volume" }, "as_of": { "type": "integer", "title": "As Of" } }, "type": "object", "required": [ "river_id", "window", "volume", "as_of" ], "title": "VolumeResponse", "description": "Traded volume over a recent window, summed from captured trade prints." }, "WatchlistCreate": { "properties": { "subaccount_id": { "type": "string", "format": "uuid", "title": "Subaccount Id" }, "name": { "type": "string", "maxLength": 255, "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "river_ids": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "River Ids" } }, "type": "object", "required": [ "subaccount_id", "name" ], "title": "WatchlistCreate", "description": "Request schema for creating a new watchlist." }, "WatchlistDetailResponse": { "properties": { "watchlist_id": { "type": "string", "format": "uuid", "title": "Watchlist Id" }, "owner_subaccount_id": { "type": "string", "format": "uuid", "title": "Owner Subaccount Id" }, "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "river_ids": { "items": { "type": "integer" }, "type": "array", "title": "River Ids" }, "members": { "items": { "$ref": "#/components/schemas/MarketSearchResult" }, "type": "array", "title": "Members" }, "created_at": { "type": "string", "title": "Created At", "description": "Creation timestamp (UTC)" } }, "type": "object", "required": [ "watchlist_id", "owner_subaccount_id", "name", "river_ids", "members", "created_at" ], "title": "WatchlistDetailResponse", "description": "Response schema for a watchlist with its resolved members (detail view).\n\n``members`` are ordered by ``position``; ``river_ids`` is the same ordering\nas a convenience for handing straight to the multibook handoff." }, "WatchlistListResponse": { "properties": { "watchlists": { "items": { "$ref": "#/components/schemas/WatchlistResponse" }, "type": "array", "title": "Watchlists" } }, "type": "object", "required": [ "watchlists" ], "title": "WatchlistListResponse" }, "WatchlistMemberAdd": { "properties": { "river_ids": { "items": { "type": "integer" }, "type": "array", "minItems": 1, "title": "River Ids" } }, "type": "object", "required": [ "river_ids" ], "title": "WatchlistMemberAdd", "description": "Request schema for adding members to a watchlist (appended at the end)." }, "WatchlistMemberReorder": { "properties": { "river_ids": { "items": { "type": "integer" }, "type": "array", "minItems": 1, "title": "River Ids" } }, "type": "object", "required": [ "river_ids" ], "title": "WatchlistMemberReorder", "description": "Request schema for reordering a watchlist.\n\nThe body is the full ordered list of ``river_id``s; the server rewrites\n``position`` to match. Sending the whole array avoids partial-reorder races\nand keeps it to one round-trip." }, "WatchlistResponse": { "properties": { "watchlist_id": { "type": "string", "title": "Watchlist Id" }, "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "owner_subaccount_id": { "type": "string", "title": "Owner Subaccount Id" }, "river_ids": { "items": { "type": "integer" }, "type": "array", "title": "River Ids" }, "created_at": { "type": "string", "title": "Created At" } }, "type": "object", "required": [ "watchlist_id", "name", "owner_subaccount_id", "river_ids", "created_at" ], "title": "WatchlistResponse", "description": "A watchlist summary (list view): metadata + ordered member river_ids." }, "WatchlistUpdate": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" } }, "type": "object", "title": "WatchlistUpdate", "description": "Request schema for renaming / editing a watchlist." } }, "securitySchemes": { "SignedRequestKeyId": { "type": "apiKey", "in": "header", "name": "X-River-Key-Id", "description": "UUID of your API key (from Settings \u2192 API Keys)." }, "SignedRequestTimestamp": { "type": "apiKey", "in": "header", "name": "X-River-Timestamp", "description": "Current unix seconds. Must be within 30s of server time." }, "SignedRequestSignature": { "type": "apiKey", "in": "header", "name": "X-River-Signature", "description": "Base64 Ed25519 signature over the canonical request: METHOD\\nPATH\\nSORTED_QUERY\\nTIMESTAMP\\nSHA256(body) hex. See /api-reference/authentication for the full recipe." }, "BearerAuth": { "type": "http", "scheme": "bearer", "description": "JWT bearer token for web client authentication." } } }, "tags": [ { "name": "markets", "description": "Search and discover prediction markets across Kalshi and Polymarket." }, { "name": "subaccounts", "description": "Manage trading subaccounts. Each subaccount can have its own exchange credentials and positions." }, { "name": "positions", "description": "View current portfolio positions across all connected exchanges." }, { "name": "fills", "description": "Retrieve trade execution history and fill details." }, { "name": "prices", "description": "Get historical price data and candlesticks from exchanges." }, { "name": "tradeprints", "description": "Recent trades for a market. Pairs with the /v1/ws/tradeprints WebSocket for live updates." }, { "name": "orders", "description": "Place and manage orders on prediction market exchanges." }, { "name": "complex-orders", "description": "Manage complex orders: conditional orders (take-profit and stop-loss), TWAP, and other advanced order types." } ], "servers": [ { "url": "https://api.rivermarkets.com" } ], "security": [ { "SignedRequestKeyId": [], "SignedRequestTimestamp": [], "SignedRequestSignature": [] }, { "BearerAuth": [] } ] }