{"openapi":"3.1.0","info":{"title":"Kash Public API","version":"dev","description":"Public REST API for SDKs, CLI, AI agents, and market makers.\n\nAPI-key authenticated only — keys are issued via the webapp Settings page (self-service `free` tier; higher tiers by request) or via `kash-admin api-keys issue` (admin / MM tier).\n\n## Tier-differentiated limits\n\nEvery key belongs to one of four tiers (`free`, `developer`, `enterprise`, `mm`) which determine four independent limits: daily spending cap, per-trade cap, requests per minute, and high-value confirmation threshold. See [`docs/api-tiers.md`](https://docs.kash.bot/developer-docs/rest-api/rate-limits) for the full matrix, the rationale for the caps, and how to upgrade. Most rate-limited or spending-capped error responses (`RATE_LIMIT_EXCEEDED`, `SPENDING_LIMIT_EXCEEDED`) link back to that page from their per-code documentation in `docs/api-errors/`.\n\nSee https://github.com/kashdao for source-of-truth architecture decisions.","contact":{"name":"Kash","url":"https://kash.bot"}},"servers":[{"url":"https://api.kash.bot/v1","description":"API server"}],"components":{"securitySchemes":{"XApiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Public API key, format kash_{live|test}_<32-base62>. HMAC-SHA256 with server-side pepper. Used by the SDK / CLI / agents for every authenticated route."}},"schemas":{"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","description":"URI of the per-code documentation page. RFC 7807 §3.1 defines `type` as the canonical link to human-readable docs for the problem type — every code in our catalogue has a stable page.","example":"https://docs.kash.bot/developer-docs/api-errors/API_KEY_MISSING"},"title":{"type":"string","example":"Authentication required"},"status":{"type":"integer","example":401},"code":{"type":"string","example":"API_KEY_MISSING"},"detail":{"type":"string"},"instance":{"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code"]},"ResponseMeta":{"type":"object","properties":{"requestId":{"type":"string","example":"01HQGY8K2N3X4Z5C6D7E8F9G0H"},"timestamp":{"type":"string","format":"date-time","example":"2026-04-30T12:34:56.789Z"}},"required":["requestId","timestamp"]},"WriteResponseMeta":{"allOf":[{"$ref":"#/components/schemas/ResponseMeta"},{"type":"object","properties":{"idempotent":{"type":"boolean","example":false}},"required":["idempotent"]}]},"TradeResource":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"b8c5e3d1-4a7c-4b2e-8f5d-1c9a3e7b6f8d"},"marketId":{"type":"string","format":"uuid","example":"7a6e9c0a-3f4f-4c43-b6ab-1b2f0c8e3c91"},"outcomeIndex":{"type":"integer","minimum":0,"example":0},"amount":{"type":"string","pattern":"^(?:\\d+|\\d+\\.\\d{1,6})$","description":"USDC amount as a decimal string (e.g. \"100\" or \"100.500000\"). Up to 6 decimals.","example":"100"},"side":{"type":"string","enum":["buy","sell"],"example":"buy"},"status":{"type":"string","enum":["pending_confirmation","pending","validating","executing","completed","failed","rejected"],"example":"pending"},"correlationId":{"type":"string","format":"uuid","example":"d5f3e7c2-9b8a-4c1d-8e7f-3a5b9c1d2e4f"},"clientRequestId":{"type":["string","null"],"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_\\-:.]+$","description":"Optional client-side idempotency token. Same value with same body returns the existing trade; same value with different body returns 409."},"txHash":{"type":["string","null"],"pattern":"^0x[a-fA-F0-9]{64}$","example":"0x9b3a4c1f8e7d6b5a2f9c8e1d4b7a6f3c2e5d8b9a1f4c7e3d6b5a8f2c1e9b4d7a"},"tokensOut":{"type":["string","null"],"pattern":"^\\d+$","example":"105420000000000000000"},"errorCode":{"type":["string","null"]},"errorMessage":{"type":["string","null"]},"webhookDelivery":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["none","pending","delivered","retrying","failed"]},"attempts":{"type":"integer","minimum":0},"lastAttemptedAt":{"type":["string","null"],"format":"date-time"},"lastStatusCode":{"type":["integer","null"]},"lastFailureCode":{"type":["string","null"]},"terminalFailureAt":{"type":["string","null"],"format":"date-time"}},"required":["status","attempts","lastAttemptedAt","lastStatusCode","lastFailureCode","terminalFailureAt"]},"metadata":{"type":"object","additionalProperties":{"type":"string"},"default":{}},"createdAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:56Z"},"updatedAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:57Z"}},"required":["id","marketId","outcomeIndex","amount","side","status","correlationId","clientRequestId","txHash","tokensOut","errorCode","errorMessage","webhookDelivery","createdAt","updatedAt"]},"CreateTradeBody":{"type":"object","properties":{"marketId":{"type":"string","format":"uuid","example":"7a6e9c0a-3f4f-4c43-b6ab-1b2f0c8e3c91"},"outcomeIndex":{"type":"integer","minimum":0,"example":0},"amount":{"type":"string","pattern":"^(?:\\d+|\\d+\\.\\d{1,6})$","description":"USDC amount as a decimal string (e.g. \"100\" or \"100.500000\"). Up to 6 decimals.","example":"100"},"side":{"type":"string","enum":["buy","sell"],"example":"buy"},"clientRequestId":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_\\-:.]+$","description":"Optional client-side idempotency token. Same value with same body returns the existing trade; same value with different body returns 409.","example":"cli-2026-04-30-001"},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"example":{"orderId":"order_123","strategy":"mm-v2","tenantId":"acme-corp"}}},"required":["marketId","outcomeIndex","amount","side"]},"CreateTradeCreatedResponse":{"type":"object","properties":{"trade":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"b8c5e3d1-4a7c-4b2e-8f5d-1c9a3e7b6f8d"},"marketId":{"type":"string","format":"uuid","example":"7a6e9c0a-3f4f-4c43-b6ab-1b2f0c8e3c91"},"outcomeIndex":{"type":"integer","minimum":0,"example":0},"amount":{"type":"string","pattern":"^(?:\\d+|\\d+\\.\\d{1,6})$","description":"USDC amount as a decimal string (e.g. \"100\" or \"100.500000\"). Up to 6 decimals.","example":"100"},"side":{"type":"string","enum":["buy","sell"],"example":"buy"},"status":{"type":"string","enum":["pending_confirmation","pending","validating","executing","completed","failed","rejected"],"example":"pending"},"correlationId":{"type":"string","format":"uuid","example":"d5f3e7c2-9b8a-4c1d-8e7f-3a5b9c1d2e4f"},"clientRequestId":{"type":["string","null"],"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_\\-:.]+$","description":"Optional client-side idempotency token. Same value with same body returns the existing trade; same value with different body returns 409."},"txHash":{"type":["string","null"],"pattern":"^0x[a-fA-F0-9]{64}$","example":"0x9b3a4c1f8e7d6b5a2f9c8e1d4b7a6f3c2e5d8b9a1f4c7e3d6b5a8f2c1e9b4d7a"},"tokensOut":{"type":["string","null"],"pattern":"^\\d+$","example":"105420000000000000000"},"errorCode":{"type":["string","null"]},"errorMessage":{"type":["string","null"]},"webhookDelivery":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["none","pending","delivered","retrying","failed"]},"attempts":{"type":"integer","minimum":0},"lastAttemptedAt":{"type":["string","null"],"format":"date-time"},"lastStatusCode":{"type":["integer","null"]},"lastFailureCode":{"type":["string","null"]},"terminalFailureAt":{"type":["string","null"],"format":"date-time"}},"required":["status","attempts","lastAttemptedAt","lastStatusCode","lastFailureCode","terminalFailureAt"]},"metadata":{"type":"object","additionalProperties":{"type":"string"},"default":{}},"createdAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:56Z"},"updatedAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:57Z"}},"required":["id","marketId","outcomeIndex","amount","side","status","correlationId","clientRequestId","txHash","tokensOut","errorCode","errorMessage","webhookDelivery","createdAt","updatedAt"]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"b8c5e3d1-4a7c-4b2e-8f5d-1c9a3e7b6f8d"},"marketId":{"type":"string","format":"uuid","example":"7a6e9c0a-3f4f-4c43-b6ab-1b2f0c8e3c91"},"outcomeIndex":{"type":"integer","minimum":0,"example":0},"amount":{"type":"string","pattern":"^(?:\\d+|\\d+\\.\\d{1,6})$","description":"USDC amount as a decimal string (e.g. \"100\" or \"100.500000\"). Up to 6 decimals.","example":"100"},"side":{"type":"string","enum":["buy","sell"],"example":"buy"},"status":{"type":"string","enum":["pending_confirmation","pending","validating","executing","completed","failed","rejected"],"example":"pending"},"correlationId":{"type":"string","format":"uuid","example":"d5f3e7c2-9b8a-4c1d-8e7f-3a5b9c1d2e4f"},"clientRequestId":{"type":["string","null"],"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_\\-:.]+$","description":"Optional client-side idempotency token. Same value with same body returns the existing trade; same value with different body returns 409."},"txHash":{"type":["string","null"],"pattern":"^0x[a-fA-F0-9]{64}$","example":"0x9b3a4c1f8e7d6b5a2f9c8e1d4b7a6f3c2e5d8b9a1f4c7e3d6b5a8f2c1e9b4d7a"},"tokensOut":{"type":["string","null"],"pattern":"^\\d+$","example":"105420000000000000000"},"errorCode":{"type":["string","null"]},"errorMessage":{"type":["string","null"]},"webhookDelivery":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["none","pending","delivered","retrying","failed"]},"attempts":{"type":"integer","minimum":0},"lastAttemptedAt":{"type":["string","null"],"format":"date-time"},"lastStatusCode":{"type":["integer","null"]},"lastFailureCode":{"type":["string","null"]},"terminalFailureAt":{"type":["string","null"],"format":"date-time"}},"required":["status","attempts","lastAttemptedAt","lastStatusCode","lastFailureCode","terminalFailureAt"]},"metadata":{"type":"object","additionalProperties":{"type":"string"},"default":{}},"createdAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:56Z"},"updatedAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:57Z"}},"required":["id","marketId","outcomeIndex","amount","side","status","correlationId","clientRequestId","txHash","tokensOut","errorCode","errorMessage","webhookDelivery","createdAt","updatedAt"]},"_meta":{"$ref":"#/components/schemas/WriteResponseMeta"}},"required":["trade","data","_meta"]},"CreateTradeAcceptedResponse":{"type":"object","properties":{"trade":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"b8c5e3d1-4a7c-4b2e-8f5d-1c9a3e7b6f8d"},"marketId":{"type":"string","format":"uuid","example":"7a6e9c0a-3f4f-4c43-b6ab-1b2f0c8e3c91"},"outcomeIndex":{"type":"integer","minimum":0,"example":0},"amount":{"type":"string","pattern":"^(?:\\d+|\\d+\\.\\d{1,6})$","description":"USDC amount as a decimal string (e.g. \"100\" or \"100.500000\"). Up to 6 decimals.","example":"100"},"side":{"type":"string","enum":["buy","sell"],"example":"buy"},"status":{"type":"string","enum":["pending_confirmation","pending","validating","executing","completed","failed","rejected"],"example":"pending"},"correlationId":{"type":"string","format":"uuid","example":"d5f3e7c2-9b8a-4c1d-8e7f-3a5b9c1d2e4f"},"clientRequestId":{"type":["string","null"],"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_\\-:.]+$","description":"Optional client-side idempotency token. Same value with same body returns the existing trade; same value with different body returns 409."},"txHash":{"type":["string","null"],"pattern":"^0x[a-fA-F0-9]{64}$","example":"0x9b3a4c1f8e7d6b5a2f9c8e1d4b7a6f3c2e5d8b9a1f4c7e3d6b5a8f2c1e9b4d7a"},"tokensOut":{"type":["string","null"],"pattern":"^\\d+$","example":"105420000000000000000"},"errorCode":{"type":["string","null"]},"errorMessage":{"type":["string","null"]},"webhookDelivery":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["none","pending","delivered","retrying","failed"]},"attempts":{"type":"integer","minimum":0},"lastAttemptedAt":{"type":["string","null"],"format":"date-time"},"lastStatusCode":{"type":["integer","null"]},"lastFailureCode":{"type":["string","null"]},"terminalFailureAt":{"type":["string","null"],"format":"date-time"}},"required":["status","attempts","lastAttemptedAt","lastStatusCode","lastFailureCode","terminalFailureAt"]},"metadata":{"type":"object","additionalProperties":{"type":"string"},"default":{}},"createdAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:56Z"},"updatedAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:57Z"}},"required":["id","marketId","outcomeIndex","amount","side","status","correlationId","clientRequestId","txHash","tokensOut","errorCode","errorMessage","webhookDelivery","createdAt","updatedAt"]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"b8c5e3d1-4a7c-4b2e-8f5d-1c9a3e7b6f8d"},"marketId":{"type":"string","format":"uuid","example":"7a6e9c0a-3f4f-4c43-b6ab-1b2f0c8e3c91"},"outcomeIndex":{"type":"integer","minimum":0,"example":0},"amount":{"type":"string","pattern":"^(?:\\d+|\\d+\\.\\d{1,6})$","description":"USDC amount as a decimal string (e.g. \"100\" or \"100.500000\"). Up to 6 decimals.","example":"100"},"side":{"type":"string","enum":["buy","sell"],"example":"buy"},"status":{"type":"string","enum":["pending_confirmation","pending","validating","executing","completed","failed","rejected"],"example":"pending"},"correlationId":{"type":"string","format":"uuid","example":"d5f3e7c2-9b8a-4c1d-8e7f-3a5b9c1d2e4f"},"clientRequestId":{"type":["string","null"],"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_\\-:.]+$","description":"Optional client-side idempotency token. Same value with same body returns the existing trade; same value with different body returns 409."},"txHash":{"type":["string","null"],"pattern":"^0x[a-fA-F0-9]{64}$","example":"0x9b3a4c1f8e7d6b5a2f9c8e1d4b7a6f3c2e5d8b9a1f4c7e3d6b5a8f2c1e9b4d7a"},"tokensOut":{"type":["string","null"],"pattern":"^\\d+$","example":"105420000000000000000"},"errorCode":{"type":["string","null"]},"errorMessage":{"type":["string","null"]},"webhookDelivery":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["none","pending","delivered","retrying","failed"]},"attempts":{"type":"integer","minimum":0},"lastAttemptedAt":{"type":["string","null"],"format":"date-time"},"lastStatusCode":{"type":["integer","null"]},"lastFailureCode":{"type":["string","null"]},"terminalFailureAt":{"type":["string","null"],"format":"date-time"}},"required":["status","attempts","lastAttemptedAt","lastStatusCode","lastFailureCode","terminalFailureAt"]},"metadata":{"type":"object","additionalProperties":{"type":"string"},"default":{}},"createdAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:56Z"},"updatedAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:57Z"}},"required":["id","marketId","outcomeIndex","amount","side","status","correlationId","clientRequestId","txHash","tokensOut","errorCode","errorMessage","webhookDelivery","createdAt","updatedAt"]},"confirmation":{"type":"object","properties":{"token":{"type":"string","minLength":40,"maxLength":64},"expiresAt":{"type":"string","format":"date-time"}},"required":["token","expiresAt"]},"_meta":{"$ref":"#/components/schemas/WriteResponseMeta"}},"required":["trade","data","confirmation","_meta"]},"ConfirmTradeBody":{"type":"object","properties":{"token":{"type":"string","minLength":40,"maxLength":64,"example":"kVAa4iL_xQyP8jHqM7nF2tR3wL5vY9zX1bN0gK6cE8hJqWmZ7sR"}},"required":["token"]},"ConfirmTradeResponse":{"type":"object","properties":{"trade":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"b8c5e3d1-4a7c-4b2e-8f5d-1c9a3e7b6f8d"},"marketId":{"type":"string","format":"uuid","example":"7a6e9c0a-3f4f-4c43-b6ab-1b2f0c8e3c91"},"outcomeIndex":{"type":"integer","minimum":0,"example":0},"amount":{"type":"string","pattern":"^(?:\\d+|\\d+\\.\\d{1,6})$","description":"USDC amount as a decimal string (e.g. \"100\" or \"100.500000\"). Up to 6 decimals.","example":"100"},"side":{"type":"string","enum":["buy","sell"],"example":"buy"},"status":{"type":"string","enum":["pending_confirmation","pending","validating","executing","completed","failed","rejected"],"example":"pending"},"correlationId":{"type":"string","format":"uuid","example":"d5f3e7c2-9b8a-4c1d-8e7f-3a5b9c1d2e4f"},"clientRequestId":{"type":["string","null"],"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_\\-:.]+$","description":"Optional client-side idempotency token. Same value with same body returns the existing trade; same value with different body returns 409."},"txHash":{"type":["string","null"],"pattern":"^0x[a-fA-F0-9]{64}$","example":"0x9b3a4c1f8e7d6b5a2f9c8e1d4b7a6f3c2e5d8b9a1f4c7e3d6b5a8f2c1e9b4d7a"},"tokensOut":{"type":["string","null"],"pattern":"^\\d+$","example":"105420000000000000000"},"errorCode":{"type":["string","null"]},"errorMessage":{"type":["string","null"]},"webhookDelivery":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["none","pending","delivered","retrying","failed"]},"attempts":{"type":"integer","minimum":0},"lastAttemptedAt":{"type":["string","null"],"format":"date-time"},"lastStatusCode":{"type":["integer","null"]},"lastFailureCode":{"type":["string","null"]},"terminalFailureAt":{"type":["string","null"],"format":"date-time"}},"required":["status","attempts","lastAttemptedAt","lastStatusCode","lastFailureCode","terminalFailureAt"]},"metadata":{"type":"object","additionalProperties":{"type":"string"},"default":{}},"createdAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:56Z"},"updatedAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:57Z"}},"required":["id","marketId","outcomeIndex","amount","side","status","correlationId","clientRequestId","txHash","tokensOut","errorCode","errorMessage","webhookDelivery","createdAt","updatedAt"]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"b8c5e3d1-4a7c-4b2e-8f5d-1c9a3e7b6f8d"},"marketId":{"type":"string","format":"uuid","example":"7a6e9c0a-3f4f-4c43-b6ab-1b2f0c8e3c91"},"outcomeIndex":{"type":"integer","minimum":0,"example":0},"amount":{"type":"string","pattern":"^(?:\\d+|\\d+\\.\\d{1,6})$","description":"USDC amount as a decimal string (e.g. \"100\" or \"100.500000\"). Up to 6 decimals.","example":"100"},"side":{"type":"string","enum":["buy","sell"],"example":"buy"},"status":{"type":"string","enum":["pending_confirmation","pending","validating","executing","completed","failed","rejected"],"example":"pending"},"correlationId":{"type":"string","format":"uuid","example":"d5f3e7c2-9b8a-4c1d-8e7f-3a5b9c1d2e4f"},"clientRequestId":{"type":["string","null"],"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_\\-:.]+$","description":"Optional client-side idempotency token. Same value with same body returns the existing trade; same value with different body returns 409."},"txHash":{"type":["string","null"],"pattern":"^0x[a-fA-F0-9]{64}$","example":"0x9b3a4c1f8e7d6b5a2f9c8e1d4b7a6f3c2e5d8b9a1f4c7e3d6b5a8f2c1e9b4d7a"},"tokensOut":{"type":["string","null"],"pattern":"^\\d+$","example":"105420000000000000000"},"errorCode":{"type":["string","null"]},"errorMessage":{"type":["string","null"]},"webhookDelivery":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["none","pending","delivered","retrying","failed"]},"attempts":{"type":"integer","minimum":0},"lastAttemptedAt":{"type":["string","null"],"format":"date-time"},"lastStatusCode":{"type":["integer","null"]},"lastFailureCode":{"type":["string","null"]},"terminalFailureAt":{"type":["string","null"],"format":"date-time"}},"required":["status","attempts","lastAttemptedAt","lastStatusCode","lastFailureCode","terminalFailureAt"]},"metadata":{"type":"object","additionalProperties":{"type":"string"},"default":{}},"createdAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:56Z"},"updatedAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:57Z"}},"required":["id","marketId","outcomeIndex","amount","side","status","correlationId","clientRequestId","txHash","tokensOut","errorCode","errorMessage","webhookDelivery","createdAt","updatedAt"]},"_meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["trade","data","_meta"]},"ListTradesResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"b8c5e3d1-4a7c-4b2e-8f5d-1c9a3e7b6f8d"},"marketId":{"type":"string","format":"uuid","example":"7a6e9c0a-3f4f-4c43-b6ab-1b2f0c8e3c91"},"outcomeIndex":{"type":"integer","minimum":0,"example":0},"amount":{"type":"string","pattern":"^(?:\\d+|\\d+\\.\\d{1,6})$","description":"USDC amount as a decimal string (e.g. \"100\" or \"100.500000\"). Up to 6 decimals.","example":"100"},"side":{"type":"string","enum":["buy","sell"],"example":"buy"},"status":{"type":"string","enum":["pending_confirmation","pending","validating","executing","completed","failed","rejected"],"example":"pending"},"correlationId":{"type":"string","format":"uuid","example":"d5f3e7c2-9b8a-4c1d-8e7f-3a5b9c1d2e4f"},"clientRequestId":{"type":["string","null"],"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_\\-:.]+$","description":"Optional client-side idempotency token. Same value with same body returns the existing trade; same value with different body returns 409."},"txHash":{"type":["string","null"],"pattern":"^0x[a-fA-F0-9]{64}$","example":"0x9b3a4c1f8e7d6b5a2f9c8e1d4b7a6f3c2e5d8b9a1f4c7e3d6b5a8f2c1e9b4d7a"},"tokensOut":{"type":["string","null"],"pattern":"^\\d+$","example":"105420000000000000000"},"errorCode":{"type":["string","null"]},"errorMessage":{"type":["string","null"]},"webhookDelivery":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["none","pending","delivered","retrying","failed"]},"attempts":{"type":"integer","minimum":0},"lastAttemptedAt":{"type":["string","null"],"format":"date-time"},"lastStatusCode":{"type":["integer","null"]},"lastFailureCode":{"type":["string","null"]},"terminalFailureAt":{"type":["string","null"],"format":"date-time"}},"required":["status","attempts","lastAttemptedAt","lastStatusCode","lastFailureCode","terminalFailureAt"]},"metadata":{"type":"object","additionalProperties":{"type":"string"},"default":{}},"createdAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:56Z"},"updatedAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:57Z"}},"required":["id","marketId","outcomeIndex","amount","side","status","correlationId","clientRequestId","txHash","tokensOut","errorCode","errorMessage","webhookDelivery","createdAt","updatedAt"]}},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"hasMore":{"type":"boolean"},"limit":{"type":"integer","exclusiveMinimum":0}},"required":["cursor","hasMore","limit"]},"_meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["data","pagination","_meta"]},"GetTradeResponse":{"type":"object","properties":{"trade":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"b8c5e3d1-4a7c-4b2e-8f5d-1c9a3e7b6f8d"},"marketId":{"type":"string","format":"uuid","example":"7a6e9c0a-3f4f-4c43-b6ab-1b2f0c8e3c91"},"outcomeIndex":{"type":"integer","minimum":0,"example":0},"amount":{"type":"string","pattern":"^(?:\\d+|\\d+\\.\\d{1,6})$","description":"USDC amount as a decimal string (e.g. \"100\" or \"100.500000\"). Up to 6 decimals.","example":"100"},"side":{"type":"string","enum":["buy","sell"],"example":"buy"},"status":{"type":"string","enum":["pending_confirmation","pending","validating","executing","completed","failed","rejected"],"example":"pending"},"correlationId":{"type":"string","format":"uuid","example":"d5f3e7c2-9b8a-4c1d-8e7f-3a5b9c1d2e4f"},"clientRequestId":{"type":["string","null"],"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_\\-:.]+$","description":"Optional client-side idempotency token. Same value with same body returns the existing trade; same value with different body returns 409."},"txHash":{"type":["string","null"],"pattern":"^0x[a-fA-F0-9]{64}$","example":"0x9b3a4c1f8e7d6b5a2f9c8e1d4b7a6f3c2e5d8b9a1f4c7e3d6b5a8f2c1e9b4d7a"},"tokensOut":{"type":["string","null"],"pattern":"^\\d+$","example":"105420000000000000000"},"errorCode":{"type":["string","null"]},"errorMessage":{"type":["string","null"]},"webhookDelivery":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["none","pending","delivered","retrying","failed"]},"attempts":{"type":"integer","minimum":0},"lastAttemptedAt":{"type":["string","null"],"format":"date-time"},"lastStatusCode":{"type":["integer","null"]},"lastFailureCode":{"type":["string","null"]},"terminalFailureAt":{"type":["string","null"],"format":"date-time"}},"required":["status","attempts","lastAttemptedAt","lastStatusCode","lastFailureCode","terminalFailureAt"]},"metadata":{"type":"object","additionalProperties":{"type":"string"},"default":{}},"createdAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:56Z"},"updatedAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:57Z"}},"required":["id","marketId","outcomeIndex","amount","side","status","correlationId","clientRequestId","txHash","tokensOut","errorCode","errorMessage","webhookDelivery","createdAt","updatedAt"]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"b8c5e3d1-4a7c-4b2e-8f5d-1c9a3e7b6f8d"},"marketId":{"type":"string","format":"uuid","example":"7a6e9c0a-3f4f-4c43-b6ab-1b2f0c8e3c91"},"outcomeIndex":{"type":"integer","minimum":0,"example":0},"amount":{"type":"string","pattern":"^(?:\\d+|\\d+\\.\\d{1,6})$","description":"USDC amount as a decimal string (e.g. \"100\" or \"100.500000\"). Up to 6 decimals.","example":"100"},"side":{"type":"string","enum":["buy","sell"],"example":"buy"},"status":{"type":"string","enum":["pending_confirmation","pending","validating","executing","completed","failed","rejected"],"example":"pending"},"correlationId":{"type":"string","format":"uuid","example":"d5f3e7c2-9b8a-4c1d-8e7f-3a5b9c1d2e4f"},"clientRequestId":{"type":["string","null"],"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_\\-:.]+$","description":"Optional client-side idempotency token. Same value with same body returns the existing trade; same value with different body returns 409."},"txHash":{"type":["string","null"],"pattern":"^0x[a-fA-F0-9]{64}$","example":"0x9b3a4c1f8e7d6b5a2f9c8e1d4b7a6f3c2e5d8b9a1f4c7e3d6b5a8f2c1e9b4d7a"},"tokensOut":{"type":["string","null"],"pattern":"^\\d+$","example":"105420000000000000000"},"errorCode":{"type":["string","null"]},"errorMessage":{"type":["string","null"]},"webhookDelivery":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["none","pending","delivered","retrying","failed"]},"attempts":{"type":"integer","minimum":0},"lastAttemptedAt":{"type":["string","null"],"format":"date-time"},"lastStatusCode":{"type":["integer","null"]},"lastFailureCode":{"type":["string","null"]},"terminalFailureAt":{"type":["string","null"],"format":"date-time"}},"required":["status","attempts","lastAttemptedAt","lastStatusCode","lastFailureCode","terminalFailureAt"]},"metadata":{"type":"object","additionalProperties":{"type":"string"},"default":{}},"createdAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:56Z"},"updatedAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:57Z"}},"required":["id","marketId","outcomeIndex","amount","side","status","correlationId","clientRequestId","txHash","tokensOut","errorCode","errorMessage","webhookDelivery","createdAt","updatedAt"]},"_meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["trade","data","_meta"]},"TraceEventData":{"type":"object","properties":{"tradeId":{"type":"string","format":"uuid"},"marketId":{"type":"string","format":"uuid"},"outcomeIndex":{"type":"integer","minimum":0},"side":{"type":"string","enum":["buy","sell"]},"amount":{"type":"string"},"chainId":{"type":"integer","exclusiveMinimum":0},"txHash":{"type":"string"},"tokensOut":{"type":"string"},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"reason":{"type":"string"}},"additionalProperties":false},"TraceEvent":{"type":"object","properties":{"type":{"type":"string","minLength":1,"example":"com.kash.trade.executed.v1"},"occurredAt":{"type":"string","format":"date-time","example":"2026-05-02T12:00:03.000Z"},"sequenceNumber":{"type":"integer","minimum":0},"data":{"$ref":"#/components/schemas/TraceEventData"}},"required":["type","occurredAt","sequenceNumber","data"]},"TraceResource":{"type":"object","properties":{"correlationId":{"type":"string","format":"uuid"},"events":{"type":"array","items":{"$ref":"#/components/schemas/TraceEvent"}}},"required":["correlationId","events"]},"GetTraceResponse":{"type":"object","properties":{"trace":{"$ref":"#/components/schemas/TraceResource"},"data":{"$ref":"#/components/schemas/TraceResource"},"_meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["trace","data","_meta"]},"MarketResource":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"contractAddress":{"type":"string"},"chainId":{"type":"integer","exclusiveMinimum":0},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"status":{"type":["string","null"],"enum":["UNSEEDED","ACTIVE","RESOLVED"]},"outcomeCount":{"type":"integer","exclusiveMinimum":0},"outcomes":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":0},"label":{"type":"string"},"probability":{"type":"number","minimum":0,"maximum":1}},"required":["index","label","probability"]}},"imageUrl":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":["string","null"],"format":"date-time"},"resolvedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","contractAddress","chainId","title","description","status","outcomeCount","outcomes","imageUrl","createdAt","expiresAt","resolvedAt"]},"ListMarketsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"contractAddress":{"type":"string"},"chainId":{"type":"integer","exclusiveMinimum":0},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"status":{"type":["string","null"],"enum":["UNSEEDED","ACTIVE","RESOLVED"]},"outcomeCount":{"type":"integer","exclusiveMinimum":0},"outcomes":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":0},"label":{"type":"string"},"probability":{"type":"number","minimum":0,"maximum":1}},"required":["index","label","probability"]}},"imageUrl":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":["string","null"],"format":"date-time"},"resolvedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","contractAddress","chainId","title","description","status","outcomeCount","outcomes","imageUrl","createdAt","expiresAt","resolvedAt"]}},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"hasMore":{"type":"boolean"},"limit":{"type":"integer","exclusiveMinimum":0}},"required":["cursor","hasMore","limit"]},"_meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["data","pagination","_meta"]},"GetMarketResponse":{"type":"object","properties":{"market":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"contractAddress":{"type":"string"},"chainId":{"type":"integer","exclusiveMinimum":0},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"status":{"type":["string","null"],"enum":["UNSEEDED","ACTIVE","RESOLVED"]},"outcomeCount":{"type":"integer","exclusiveMinimum":0},"outcomes":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":0},"label":{"type":"string"},"probability":{"type":"number","minimum":0,"maximum":1}},"required":["index","label","probability"]}},"imageUrl":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":["string","null"],"format":"date-time"},"resolvedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","contractAddress","chainId","title","description","status","outcomeCount","outcomes","imageUrl","createdAt","expiresAt","resolvedAt"]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"contractAddress":{"type":"string"},"chainId":{"type":"integer","exclusiveMinimum":0},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"status":{"type":["string","null"],"enum":["UNSEEDED","ACTIVE","RESOLVED"]},"outcomeCount":{"type":"integer","exclusiveMinimum":0},"outcomes":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":0},"label":{"type":"string"},"probability":{"type":"number","minimum":0,"maximum":1}},"required":["index","label","probability"]}},"imageUrl":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":["string","null"],"format":"date-time"},"resolvedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","contractAddress","chainId","title","description","status","outcomeCount","outcomes","imageUrl","createdAt","expiresAt","resolvedAt"]},"_meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["market","data","_meta"]},"PredictionResource":{"type":"object","properties":{"id":{"type":"string"},"marketId":{"type":"string","format":"uuid"},"outcomeIndex":{"type":"integer","minimum":0},"side":{"type":"string","enum":["buy","sell"]},"usdcIn":{"type":["string","null"]},"usdcOut":{"type":["string","null"]},"tokensIn":{"type":["string","null"]},"tokensOut":{"type":["string","null"]},"price":{"type":"string"},"probability":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"blockNumber":{"type":"string"},"transactionHash":{"type":"string"},"logIndex":{"type":"integer","minimum":0}},"required":["id","marketId","outcomeIndex","side","usdcIn","usdcOut","tokensIn","tokensOut","price","probability","timestamp","blockNumber","transactionHash","logIndex"]},"ListPredictionsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"marketId":{"type":"string","format":"uuid"},"outcomeIndex":{"type":"integer","minimum":0},"side":{"type":"string","enum":["buy","sell"]},"usdcIn":{"type":["string","null"]},"usdcOut":{"type":["string","null"]},"tokensIn":{"type":["string","null"]},"tokensOut":{"type":["string","null"]},"price":{"type":"string"},"probability":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"blockNumber":{"type":"string"},"transactionHash":{"type":"string"},"logIndex":{"type":"integer","minimum":0}},"required":["id","marketId","outcomeIndex","side","usdcIn","usdcOut","tokensIn","tokensOut","price","probability","timestamp","blockNumber","transactionHash","logIndex"]}},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"hasMore":{"type":"boolean"},"limit":{"type":"integer","exclusiveMinimum":0}},"required":["cursor","hasMore","limit"]},"_meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["data","pagination","_meta"]},"PositionResource":{"type":"object","properties":{"marketId":{"type":"string","format":"uuid"},"outcomeIndex":{"type":"integer","minimum":0},"shares":{"type":"string","pattern":"^\\d+$"},"costBasisAtomic":{"type":"string","pattern":"^\\d+$"},"tradeCount":{"type":"integer","minimum":0},"firstTradeAt":{"type":"string","format":"date-time"},"lastTradeAt":{"type":"string","format":"date-time"}},"required":["marketId","outcomeIndex","shares","costBasisAtomic","tradeCount","firstTradeAt","lastTradeAt"]},"PositionsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"marketId":{"type":"string","format":"uuid"},"outcomeIndex":{"type":"integer","minimum":0},"shares":{"type":"string","pattern":"^\\d+$"},"costBasisAtomic":{"type":"string","pattern":"^\\d+$"},"tradeCount":{"type":"integer","minimum":0},"firstTradeAt":{"type":"string","format":"date-time"},"lastTradeAt":{"type":"string","format":"date-time"}},"required":["marketId","outcomeIndex","shares","costBasisAtomic","tradeCount","firstTradeAt","lastTradeAt"]}},"_meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["data","_meta"]},"PortfolioSummaryResponse":{"type":"object","properties":{"portfolio":{"type":"object","properties":{"smartAccountAddress":{"type":"string"},"activePositions":{"type":"integer","minimum":0},"totalCostBasisAtomic":{"type":"string","pattern":"^\\d+$"}},"required":["smartAccountAddress","activePositions","totalCostBasisAtomic"]},"data":{"type":"object","properties":{"smartAccountAddress":{"type":"string"},"activePositions":{"type":"integer","minimum":0},"totalCostBasisAtomic":{"type":"string","pattern":"^\\d+$"}},"required":["smartAccountAddress","activePositions","totalCostBasisAtomic"]},"_meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["portfolio","data","_meta"]},"AccountUsage":{"type":"object","properties":{"apiKeyId":{"type":"string","format":"uuid"},"generatedAt":{"type":"string","format":"date-time"},"trades":{"type":"object","properties":{"24h":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"completed":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"successRate":{"type":["number","null"],"minimum":0,"maximum":1},"latencyMs":{"type":"object","properties":{"p50":{"type":["integer","null"]},"p99":{"type":["integer","null"]}},"required":["p50","p99"]}},"required":["total","completed","failed","successRate","latencyMs"]},"7d":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"completed":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"successRate":{"type":["number","null"],"minimum":0,"maximum":1}},"required":["total","completed","failed","successRate"]},"30d":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"completed":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"successRate":{"type":["number","null"],"minimum":0,"maximum":1}},"required":["total","completed","failed","successRate"]}},"required":["24h","7d","30d"]},"webhooks":{"type":"object","properties":{"7d":{"type":"object","properties":{"emitted":{"type":"integer","minimum":0},"delivered":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"successRate":{"type":["number","null"],"minimum":0,"maximum":1}},"required":["emitted","delivered","failed","successRate"]}},"required":["7d"]},"auth":{"type":"object","properties":{"24h":{"type":"object","properties":{"failures":{"type":"integer","minimum":0},"rateLimitRejections":{"type":"integer","minimum":0}},"required":["failures","rateLimitRejections"]}},"required":["24h"]}},"required":["apiKeyId","generatedAt","trades","webhooks","auth"]},"AccountUsageResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"apiKeyId":{"type":"string","format":"uuid"},"generatedAt":{"type":"string","format":"date-time"},"trades":{"type":"object","properties":{"24h":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"completed":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"successRate":{"type":["number","null"],"minimum":0,"maximum":1},"latencyMs":{"type":"object","properties":{"p50":{"type":["integer","null"]},"p99":{"type":["integer","null"]}},"required":["p50","p99"]}},"required":["total","completed","failed","successRate","latencyMs"]},"7d":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"completed":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"successRate":{"type":["number","null"],"minimum":0,"maximum":1}},"required":["total","completed","failed","successRate"]},"30d":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"completed":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"successRate":{"type":["number","null"],"minimum":0,"maximum":1}},"required":["total","completed","failed","successRate"]}},"required":["24h","7d","30d"]},"webhooks":{"type":"object","properties":{"7d":{"type":"object","properties":{"emitted":{"type":"integer","minimum":0},"delivered":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"successRate":{"type":["number","null"],"minimum":0,"maximum":1}},"required":["emitted","delivered","failed","successRate"]}},"required":["7d"]},"auth":{"type":"object","properties":{"24h":{"type":"object","properties":{"failures":{"type":"integer","minimum":0},"rateLimitRejections":{"type":"integer","minimum":0}},"required":["failures","rateLimitRejections"]}},"required":["24h"]}},"required":["apiKeyId","generatedAt","trades","webhooks","auth"]},"_meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["data","_meta"]},"WebhookEventResource":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"eventType":{"type":"string"},"tradeRequestId":{"type":["string","null"],"format":"uuid"},"emittedAt":{"type":"string","format":"date-time"},"outboxEmittedAt":{"type":["string","null"],"format":"date-time"},"replayCount":{"type":"integer","minimum":0},"status":{"type":"string","enum":["none","pending","delivered","retrying","failed"]},"delivery":{"type":"object","properties":{"attempts":{"type":"integer","minimum":0},"lastAttemptedAt":{"type":["string","null"],"format":"date-time"},"lastDeliveredAt":{"type":["string","null"],"format":"date-time"},"lastStatusCode":{"type":["integer","null"]},"lastFailureCode":{"type":["string","null"]},"lastErrorMessage":{"type":["string","null"]},"terminalFailureAt":{"type":["string","null"],"format":"date-time"}},"required":["attempts","lastAttemptedAt","lastDeliveredAt","lastStatusCode","lastFailureCode","lastErrorMessage","terminalFailureAt"]}},"required":["id","eventType","tradeRequestId","emittedAt","outboxEmittedAt","replayCount","status","delivery"]},"ListWebhookEventsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"eventType":{"type":"string"},"tradeRequestId":{"type":["string","null"],"format":"uuid"},"emittedAt":{"type":"string","format":"date-time"},"outboxEmittedAt":{"type":["string","null"],"format":"date-time"},"replayCount":{"type":"integer","minimum":0},"status":{"type":"string","enum":["none","pending","delivered","retrying","failed"]},"delivery":{"type":"object","properties":{"attempts":{"type":"integer","minimum":0},"lastAttemptedAt":{"type":["string","null"],"format":"date-time"},"lastDeliveredAt":{"type":["string","null"],"format":"date-time"},"lastStatusCode":{"type":["integer","null"]},"lastFailureCode":{"type":["string","null"]},"lastErrorMessage":{"type":["string","null"]},"terminalFailureAt":{"type":["string","null"],"format":"date-time"}},"required":["attempts","lastAttemptedAt","lastDeliveredAt","lastStatusCode","lastFailureCode","lastErrorMessage","terminalFailureAt"]}},"required":["id","eventType","tradeRequestId","emittedAt","outboxEmittedAt","replayCount","status","delivery"]}},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"hasMore":{"type":"boolean"},"limit":{"type":"integer","exclusiveMinimum":0}},"required":["cursor","hasMore","limit"]},"_meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["data","pagination","_meta"]},"RedeliverWebhookResponse":{"type":"object","properties":{"event":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"eventType":{"type":"string"},"apiKeyId":{"type":"string","format":"uuid"},"tradeRequestId":{"type":["string","null"],"format":"uuid"},"emittedAt":{"type":"string","format":"date-time"},"lastDeliveredAt":{"type":["string","null"],"format":"date-time"},"deliveryAttempts":{"type":"integer","minimum":0}},"required":["id","eventType","apiKeyId","tradeRequestId","emittedAt","lastDeliveredAt","deliveryAttempts"]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"eventType":{"type":"string"},"apiKeyId":{"type":"string","format":"uuid"},"tradeRequestId":{"type":["string","null"],"format":"uuid"},"emittedAt":{"type":"string","format":"date-time"},"lastDeliveredAt":{"type":["string","null"],"format":"date-time"},"deliveryAttempts":{"type":"integer","minimum":0}},"required":["id","eventType","apiKeyId","tradeRequestId","emittedAt","lastDeliveredAt","deliveryAttempts"]},"_meta":{"allOf":[{"$ref":"#/components/schemas/ResponseMeta"},{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}]}},"required":["event","data","_meta"]},"RotateWebhookSecretResponse":{"type":"object","properties":{"webhookSecret":{"type":"object","properties":{"secret":{"type":"string"},"rotatedAt":{"type":"string","format":"date-time"},"previousRetainedUntil":{"type":"string","format":"date-time"}},"required":["secret","rotatedAt","previousRetainedUntil"]},"data":{"type":"object","properties":{"secret":{"type":"string"},"rotatedAt":{"type":"string","format":"date-time"},"previousRetainedUntil":{"type":"string","format":"date-time"}},"required":["secret","rotatedAt","previousRetainedUntil"]},"_meta":{"allOf":[{"$ref":"#/components/schemas/ResponseMeta"},{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}]}},"required":["webhookSecret","data","_meta"]},"TradeWebhookCommon":{"type":"object","properties":{"tradeId":{"type":"string","format":"uuid","example":"b8c5e3d1-4a7c-4b2e-8f5d-1c9a3e7b6f8d"},"marketId":{"type":"string","format":"uuid","example":"7a6e9c0a-3f4f-4c43-b6ab-1b2f0c8e3c91"},"outcomeIndex":{"type":"integer","minimum":0,"example":0},"amount":{"type":"string","pattern":"^\\d+(\\.\\d{1,6})?$","example":"100"},"side":{"type":"string","enum":["buy","sell"],"example":"buy"},"metadata":{"type":"object","additionalProperties":{"type":"string"},"example":{"strategy":"momentum-v2","cohort":"beta"}}},"required":["tradeId","marketId","outcomeIndex","amount","side","metadata"]},"TradeConfirmationRequiredPayload":{"allOf":[{"$ref":"#/components/schemas/TradeWebhookCommon"},{"type":"object","properties":{"status":{"type":"string","enum":["pending_confirmation"]},"confirmationExpiresAt":{"type":"string","format":"date-time"}},"required":["status","confirmationExpiresAt"]}]},"TradeConfirmationRequiredEnvelope":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["trade.confirmation-required"]},"apiVersion":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/TradeConfirmationRequiredPayload"}},"required":["id","type","apiVersion","createdAt","data"]},"TradeCompletedPayload":{"allOf":[{"$ref":"#/components/schemas/TradeWebhookCommon"},{"type":"object","properties":{"status":{"type":"string","enum":["completed"]},"txHash":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$","example":"0x9b3a4c1f8e7d6b5a2f9c8e1d4b7a6f3c2e5d8b9a1f4c7e3d6b5a8f2c1e9b4d7a"},"tokensOut":{"type":"string","pattern":"^\\d+$","example":"105420000000000000000"}},"required":["status","txHash","tokensOut"]}]},"TradeCompletedEnvelope":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["trade.completed"]},"apiVersion":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/TradeCompletedPayload"}},"required":["id","type","apiVersion","createdAt","data"]},"TradeFailedPayload":{"allOf":[{"$ref":"#/components/schemas/TradeWebhookCommon"},{"type":"object","properties":{"status":{"type":"string","enum":["failed"]},"errorCode":{"type":"string","minLength":1},"errorMessage":{"type":"string","minLength":1}},"required":["status","errorCode","errorMessage"]}]},"TradeFailedEnvelope":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["trade.failed"]},"apiVersion":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/TradeFailedPayload"}},"required":["id","type","apiVersion","createdAt","data"]},"TradeRejectedPayload":{"allOf":[{"$ref":"#/components/schemas/TradeWebhookCommon"},{"type":"object","properties":{"status":{"type":"string","enum":["rejected"]},"errorCode":{"type":"string","minLength":1},"errorMessage":{"type":"string","minLength":1}},"required":["status","errorCode","errorMessage"]}]},"TradeRejectedEnvelope":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["trade.rejected"]},"apiVersion":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/TradeRejectedPayload"}},"required":["id","type","apiVersion","createdAt","data"]}},"parameters":{}},"paths":{"/v1/health":{"get":{"summary":"Liveness probe","description":"Returns 200 with a small JSON body when the process is up. No auth.","responses":{"200":{"description":"Service is up.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"version":{"type":"string"},"uptime_seconds":{"type":"integer"},"timestamp":{"type":"string","format":"date-time"}},"required":["status","version","uptime_seconds","timestamp"]}}}}}}},"/v1/ready":{"get":{"summary":"Readiness probe","description":"Returns 200 when every downstream dependency (Postgres, Redis, Supabase PostgREST, HMAC pepper) is reachable; 503 with a per-dependency status object otherwise. No auth. Use this for orchestrator readiness gates and external monitors. For plain liveness without dep checks, use `/v1/health`.","responses":{"200":{"description":"All downstream dependencies are healthy.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ready"]},"checks":{"type":"object","additionalProperties":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded","fail"]},"latencyMs":{"type":"integer"},"detail":{"type":"string"}},"required":["status"]}},"timestamp":{"type":"string","format":"date-time"}},"required":["status","checks","timestamp"]}}}},"503":{"description":"One or more downstream dependencies are unavailable.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["not_ready"]},"checks":{"type":"object","additionalProperties":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded","fail"]},"latencyMs":{"type":"integer"},"detail":{"type":"string"}},"required":["status"]}},"timestamp":{"type":"string","format":"date-time"}},"required":["status","checks","timestamp"]}}}}}}},"/v1/openapi.json":{"get":{"summary":"OpenAPI 3.1 specification","description":"The contract of record for this API (per AD-15). Live, generated from Zod.","responses":{"200":{"description":"OpenAPI 3.1 document.","content":{"application/json":{"schema":{}}}}}}},"/v1/trades":{"post":{"summary":"Create a trade request","description":"Creates a new trade request. For high-value trades (≥ `api_keys.high_value_trade_threshold_usdc`) returns 202 Accepted with a one-time confirmation token; otherwise returns 201 Created and the trade enters the risk-engine pipeline immediately. Honors the `Idempotency-Key` HTTP header and the body-level `clientRequestId`. Subject to the per-key spending caps (`per_trade_limit_usdc`, `daily_spend_limit_usdc`) and rate limit set by the key's tier — see [docs/api-tiers.md](https://docs.kash.bot/developer-docs/rest-api/rate-limits) for the matrix and upgrade paths.","security":[{"XApiKey":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"marketId":{"type":"string","format":"uuid","example":"7a6e9c0a-3f4f-4c43-b6ab-1b2f0c8e3c91"},"outcomeIndex":{"type":"integer","minimum":0,"example":0},"amount":{"type":"string","pattern":"^(?:\\d+|\\d+\\.\\d{1,6})$","description":"USDC amount as a decimal string (e.g. \"100\" or \"100.500000\"). Up to 6 decimals.","example":"100"},"side":{"type":"string","enum":["buy","sell"],"example":"buy"},"clientRequestId":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_\\-:.]+$","description":"Optional client-side idempotency token. Same value with same body returns the existing trade; same value with different body returns 409.","example":"cli-2026-04-30-001"},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"example":{"orderId":"order_123","strategy":"mm-v2","tenantId":"acme-corp"}}},"required":["marketId","outcomeIndex","amount","side"]}}}},"responses":{"201":{"description":"Trade accepted into the pipeline.","content":{"application/json":{"schema":{"type":"object","properties":{"trade":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"b8c5e3d1-4a7c-4b2e-8f5d-1c9a3e7b6f8d"},"marketId":{"type":"string","format":"uuid","example":"7a6e9c0a-3f4f-4c43-b6ab-1b2f0c8e3c91"},"outcomeIndex":{"type":"integer","minimum":0,"example":0},"amount":{"type":"string","pattern":"^(?:\\d+|\\d+\\.\\d{1,6})$","description":"USDC amount as a decimal string (e.g. \"100\" or \"100.500000\"). Up to 6 decimals.","example":"100"},"side":{"type":"string","enum":["buy","sell"],"example":"buy"},"status":{"type":"string","enum":["pending_confirmation","pending","validating","executing","completed","failed","rejected"],"example":"pending"},"correlationId":{"type":"string","format":"uuid","example":"d5f3e7c2-9b8a-4c1d-8e7f-3a5b9c1d2e4f"},"clientRequestId":{"type":["string","null"],"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_\\-:.]+$","description":"Optional client-side idempotency token. Same value with same body returns the existing trade; same value with different body returns 409."},"txHash":{"type":["string","null"],"pattern":"^0x[a-fA-F0-9]{64}$","example":"0x9b3a4c1f8e7d6b5a2f9c8e1d4b7a6f3c2e5d8b9a1f4c7e3d6b5a8f2c1e9b4d7a"},"tokensOut":{"type":["string","null"],"pattern":"^\\d+$","example":"105420000000000000000"},"errorCode":{"type":["string","null"]},"errorMessage":{"type":["string","null"]},"webhookDelivery":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["none","pending","delivered","retrying","failed"]},"attempts":{"type":"integer","minimum":0},"lastAttemptedAt":{"type":["string","null"],"format":"date-time"},"lastStatusCode":{"type":["integer","null"]},"lastFailureCode":{"type":["string","null"]},"terminalFailureAt":{"type":["string","null"],"format":"date-time"}},"required":["status","attempts","lastAttemptedAt","lastStatusCode","lastFailureCode","terminalFailureAt"]},"metadata":{"type":"object","additionalProperties":{"type":"string"},"default":{}},"createdAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:56Z"},"updatedAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:57Z"}},"required":["id","marketId","outcomeIndex","amount","side","status","correlationId","clientRequestId","txHash","tokensOut","errorCode","errorMessage","webhookDelivery","createdAt","updatedAt"]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"b8c5e3d1-4a7c-4b2e-8f5d-1c9a3e7b6f8d"},"marketId":{"type":"string","format":"uuid","example":"7a6e9c0a-3f4f-4c43-b6ab-1b2f0c8e3c91"},"outcomeIndex":{"type":"integer","minimum":0,"example":0},"amount":{"type":"string","pattern":"^(?:\\d+|\\d+\\.\\d{1,6})$","description":"USDC amount as a decimal string (e.g. \"100\" or \"100.500000\"). Up to 6 decimals.","example":"100"},"side":{"type":"string","enum":["buy","sell"],"example":"buy"},"status":{"type":"string","enum":["pending_confirmation","pending","validating","executing","completed","failed","rejected"],"example":"pending"},"correlationId":{"type":"string","format":"uuid","example":"d5f3e7c2-9b8a-4c1d-8e7f-3a5b9c1d2e4f"},"clientRequestId":{"type":["string","null"],"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_\\-:.]+$","description":"Optional client-side idempotency token. Same value with same body returns the existing trade; same value with different body returns 409."},"txHash":{"type":["string","null"],"pattern":"^0x[a-fA-F0-9]{64}$","example":"0x9b3a4c1f8e7d6b5a2f9c8e1d4b7a6f3c2e5d8b9a1f4c7e3d6b5a8f2c1e9b4d7a"},"tokensOut":{"type":["string","null"],"pattern":"^\\d+$","example":"105420000000000000000"},"errorCode":{"type":["string","null"]},"errorMessage":{"type":["string","null"]},"webhookDelivery":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["none","pending","delivered","retrying","failed"]},"attempts":{"type":"integer","minimum":0},"lastAttemptedAt":{"type":["string","null"],"format":"date-time"},"lastStatusCode":{"type":["integer","null"]},"lastFailureCode":{"type":["string","null"]},"terminalFailureAt":{"type":["string","null"],"format":"date-time"}},"required":["status","attempts","lastAttemptedAt","lastStatusCode","lastFailureCode","terminalFailureAt"]},"metadata":{"type":"object","additionalProperties":{"type":"string"},"default":{}},"createdAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:56Z"},"updatedAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:57Z"}},"required":["id","marketId","outcomeIndex","amount","side","status","correlationId","clientRequestId","txHash","tokensOut","errorCode","errorMessage","webhookDelivery","createdAt","updatedAt"]},"_meta":{"$ref":"#/components/schemas/WriteResponseMeta"}},"required":["trade","data","_meta"]}}}},"202":{"description":"High-value trade waiting on confirmation (AD-10).","content":{"application/json":{"schema":{"type":"object","properties":{"trade":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"b8c5e3d1-4a7c-4b2e-8f5d-1c9a3e7b6f8d"},"marketId":{"type":"string","format":"uuid","example":"7a6e9c0a-3f4f-4c43-b6ab-1b2f0c8e3c91"},"outcomeIndex":{"type":"integer","minimum":0,"example":0},"amount":{"type":"string","pattern":"^(?:\\d+|\\d+\\.\\d{1,6})$","description":"USDC amount as a decimal string (e.g. \"100\" or \"100.500000\"). Up to 6 decimals.","example":"100"},"side":{"type":"string","enum":["buy","sell"],"example":"buy"},"status":{"type":"string","enum":["pending_confirmation","pending","validating","executing","completed","failed","rejected"],"example":"pending"},"correlationId":{"type":"string","format":"uuid","example":"d5f3e7c2-9b8a-4c1d-8e7f-3a5b9c1d2e4f"},"clientRequestId":{"type":["string","null"],"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_\\-:.]+$","description":"Optional client-side idempotency token. Same value with same body returns the existing trade; same value with different body returns 409."},"txHash":{"type":["string","null"],"pattern":"^0x[a-fA-F0-9]{64}$","example":"0x9b3a4c1f8e7d6b5a2f9c8e1d4b7a6f3c2e5d8b9a1f4c7e3d6b5a8f2c1e9b4d7a"},"tokensOut":{"type":["string","null"],"pattern":"^\\d+$","example":"105420000000000000000"},"errorCode":{"type":["string","null"]},"errorMessage":{"type":["string","null"]},"webhookDelivery":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["none","pending","delivered","retrying","failed"]},"attempts":{"type":"integer","minimum":0},"lastAttemptedAt":{"type":["string","null"],"format":"date-time"},"lastStatusCode":{"type":["integer","null"]},"lastFailureCode":{"type":["string","null"]},"terminalFailureAt":{"type":["string","null"],"format":"date-time"}},"required":["status","attempts","lastAttemptedAt","lastStatusCode","lastFailureCode","terminalFailureAt"]},"metadata":{"type":"object","additionalProperties":{"type":"string"},"default":{}},"createdAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:56Z"},"updatedAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:57Z"}},"required":["id","marketId","outcomeIndex","amount","side","status","correlationId","clientRequestId","txHash","tokensOut","errorCode","errorMessage","webhookDelivery","createdAt","updatedAt"]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"b8c5e3d1-4a7c-4b2e-8f5d-1c9a3e7b6f8d"},"marketId":{"type":"string","format":"uuid","example":"7a6e9c0a-3f4f-4c43-b6ab-1b2f0c8e3c91"},"outcomeIndex":{"type":"integer","minimum":0,"example":0},"amount":{"type":"string","pattern":"^(?:\\d+|\\d+\\.\\d{1,6})$","description":"USDC amount as a decimal string (e.g. \"100\" or \"100.500000\"). Up to 6 decimals.","example":"100"},"side":{"type":"string","enum":["buy","sell"],"example":"buy"},"status":{"type":"string","enum":["pending_confirmation","pending","validating","executing","completed","failed","rejected"],"example":"pending"},"correlationId":{"type":"string","format":"uuid","example":"d5f3e7c2-9b8a-4c1d-8e7f-3a5b9c1d2e4f"},"clientRequestId":{"type":["string","null"],"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_\\-:.]+$","description":"Optional client-side idempotency token. Same value with same body returns the existing trade; same value with different body returns 409."},"txHash":{"type":["string","null"],"pattern":"^0x[a-fA-F0-9]{64}$","example":"0x9b3a4c1f8e7d6b5a2f9c8e1d4b7a6f3c2e5d8b9a1f4c7e3d6b5a8f2c1e9b4d7a"},"tokensOut":{"type":["string","null"],"pattern":"^\\d+$","example":"105420000000000000000"},"errorCode":{"type":["string","null"]},"errorMessage":{"type":["string","null"]},"webhookDelivery":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["none","pending","delivered","retrying","failed"]},"attempts":{"type":"integer","minimum":0},"lastAttemptedAt":{"type":["string","null"],"format":"date-time"},"lastStatusCode":{"type":["integer","null"]},"lastFailureCode":{"type":["string","null"]},"terminalFailureAt":{"type":["string","null"],"format":"date-time"}},"required":["status","attempts","lastAttemptedAt","lastStatusCode","lastFailureCode","terminalFailureAt"]},"metadata":{"type":"object","additionalProperties":{"type":"string"},"default":{}},"createdAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:56Z"},"updatedAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:57Z"}},"required":["id","marketId","outcomeIndex","amount","side","status","correlationId","clientRequestId","txHash","tokensOut","errorCode","errorMessage","webhookDelivery","createdAt","updatedAt"]},"confirmation":{"type":"object","properties":{"token":{"type":"string","minLength":40,"maxLength":64},"expiresAt":{"type":"string","format":"date-time"}},"required":["token","expiresAt"]},"_meta":{"$ref":"#/components/schemas/WriteResponseMeta"}},"required":["trade","data","confirmation","_meta"]}}}},"400":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}},"get":{"summary":"List trades (cursor pagination)","description":"Lists the authenticated user's trades, newest first. Cursor pagination per AD-15. `status` filter accepts a comma-separated list (e.g. `pending,completed`).","security":[{"XApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"marketId","in":"query"}],"responses":{"200":{"description":"Page of trades.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"b8c5e3d1-4a7c-4b2e-8f5d-1c9a3e7b6f8d"},"marketId":{"type":"string","format":"uuid","example":"7a6e9c0a-3f4f-4c43-b6ab-1b2f0c8e3c91"},"outcomeIndex":{"type":"integer","minimum":0,"example":0},"amount":{"type":"string","pattern":"^(?:\\d+|\\d+\\.\\d{1,6})$","description":"USDC amount as a decimal string (e.g. \"100\" or \"100.500000\"). Up to 6 decimals.","example":"100"},"side":{"type":"string","enum":["buy","sell"],"example":"buy"},"status":{"type":"string","enum":["pending_confirmation","pending","validating","executing","completed","failed","rejected"],"example":"pending"},"correlationId":{"type":"string","format":"uuid","example":"d5f3e7c2-9b8a-4c1d-8e7f-3a5b9c1d2e4f"},"clientRequestId":{"type":["string","null"],"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_\\-:.]+$","description":"Optional client-side idempotency token. Same value with same body returns the existing trade; same value with different body returns 409."},"txHash":{"type":["string","null"],"pattern":"^0x[a-fA-F0-9]{64}$","example":"0x9b3a4c1f8e7d6b5a2f9c8e1d4b7a6f3c2e5d8b9a1f4c7e3d6b5a8f2c1e9b4d7a"},"tokensOut":{"type":["string","null"],"pattern":"^\\d+$","example":"105420000000000000000"},"errorCode":{"type":["string","null"]},"errorMessage":{"type":["string","null"]},"webhookDelivery":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["none","pending","delivered","retrying","failed"]},"attempts":{"type":"integer","minimum":0},"lastAttemptedAt":{"type":["string","null"],"format":"date-time"},"lastStatusCode":{"type":["integer","null"]},"lastFailureCode":{"type":["string","null"]},"terminalFailureAt":{"type":["string","null"],"format":"date-time"}},"required":["status","attempts","lastAttemptedAt","lastStatusCode","lastFailureCode","terminalFailureAt"]},"metadata":{"type":"object","additionalProperties":{"type":"string"},"default":{}},"createdAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:56Z"},"updatedAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:57Z"}},"required":["id","marketId","outcomeIndex","amount","side","status","correlationId","clientRequestId","txHash","tokensOut","errorCode","errorMessage","webhookDelivery","createdAt","updatedAt"]}},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"hasMore":{"type":"boolean"},"limit":{"type":"integer","exclusiveMinimum":0}},"required":["cursor","hasMore","limit"]},"_meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["data","pagination","_meta"]}}}},"400":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/trades/{id}/confirm":{"post":{"summary":"Confirm a high-value trade","description":"Releases a trade in `pending_confirmation` (returned via 202 from POST /v1/trades) into the executor pipeline. Single-use token; subsequent attempts return 409 CONFIRMATION_TOKEN_USED.","security":[{"XApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","minLength":40,"maxLength":64,"example":"kVAa4iL_xQyP8jHqM7nF2tR3wL5vY9zX1bN0gK6cE8hJqWmZ7sR"}},"required":["token"]}}}},"responses":{"200":{"description":"Trade released into the pipeline.","content":{"application/json":{"schema":{"type":"object","properties":{"trade":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"b8c5e3d1-4a7c-4b2e-8f5d-1c9a3e7b6f8d"},"marketId":{"type":"string","format":"uuid","example":"7a6e9c0a-3f4f-4c43-b6ab-1b2f0c8e3c91"},"outcomeIndex":{"type":"integer","minimum":0,"example":0},"amount":{"type":"string","pattern":"^(?:\\d+|\\d+\\.\\d{1,6})$","description":"USDC amount as a decimal string (e.g. \"100\" or \"100.500000\"). Up to 6 decimals.","example":"100"},"side":{"type":"string","enum":["buy","sell"],"example":"buy"},"status":{"type":"string","enum":["pending_confirmation","pending","validating","executing","completed","failed","rejected"],"example":"pending"},"correlationId":{"type":"string","format":"uuid","example":"d5f3e7c2-9b8a-4c1d-8e7f-3a5b9c1d2e4f"},"clientRequestId":{"type":["string","null"],"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_\\-:.]+$","description":"Optional client-side idempotency token. Same value with same body returns the existing trade; same value with different body returns 409."},"txHash":{"type":["string","null"],"pattern":"^0x[a-fA-F0-9]{64}$","example":"0x9b3a4c1f8e7d6b5a2f9c8e1d4b7a6f3c2e5d8b9a1f4c7e3d6b5a8f2c1e9b4d7a"},"tokensOut":{"type":["string","null"],"pattern":"^\\d+$","example":"105420000000000000000"},"errorCode":{"type":["string","null"]},"errorMessage":{"type":["string","null"]},"webhookDelivery":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["none","pending","delivered","retrying","failed"]},"attempts":{"type":"integer","minimum":0},"lastAttemptedAt":{"type":["string","null"],"format":"date-time"},"lastStatusCode":{"type":["integer","null"]},"lastFailureCode":{"type":["string","null"]},"terminalFailureAt":{"type":["string","null"],"format":"date-time"}},"required":["status","attempts","lastAttemptedAt","lastStatusCode","lastFailureCode","terminalFailureAt"]},"metadata":{"type":"object","additionalProperties":{"type":"string"},"default":{}},"createdAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:56Z"},"updatedAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:57Z"}},"required":["id","marketId","outcomeIndex","amount","side","status","correlationId","clientRequestId","txHash","tokensOut","errorCode","errorMessage","webhookDelivery","createdAt","updatedAt"]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"b8c5e3d1-4a7c-4b2e-8f5d-1c9a3e7b6f8d"},"marketId":{"type":"string","format":"uuid","example":"7a6e9c0a-3f4f-4c43-b6ab-1b2f0c8e3c91"},"outcomeIndex":{"type":"integer","minimum":0,"example":0},"amount":{"type":"string","pattern":"^(?:\\d+|\\d+\\.\\d{1,6})$","description":"USDC amount as a decimal string (e.g. \"100\" or \"100.500000\"). Up to 6 decimals.","example":"100"},"side":{"type":"string","enum":["buy","sell"],"example":"buy"},"status":{"type":"string","enum":["pending_confirmation","pending","validating","executing","completed","failed","rejected"],"example":"pending"},"correlationId":{"type":"string","format":"uuid","example":"d5f3e7c2-9b8a-4c1d-8e7f-3a5b9c1d2e4f"},"clientRequestId":{"type":["string","null"],"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_\\-:.]+$","description":"Optional client-side idempotency token. Same value with same body returns the existing trade; same value with different body returns 409."},"txHash":{"type":["string","null"],"pattern":"^0x[a-fA-F0-9]{64}$","example":"0x9b3a4c1f8e7d6b5a2f9c8e1d4b7a6f3c2e5d8b9a1f4c7e3d6b5a8f2c1e9b4d7a"},"tokensOut":{"type":["string","null"],"pattern":"^\\d+$","example":"105420000000000000000"},"errorCode":{"type":["string","null"]},"errorMessage":{"type":["string","null"]},"webhookDelivery":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["none","pending","delivered","retrying","failed"]},"attempts":{"type":"integer","minimum":0},"lastAttemptedAt":{"type":["string","null"],"format":"date-time"},"lastStatusCode":{"type":["integer","null"]},"lastFailureCode":{"type":["string","null"]},"terminalFailureAt":{"type":["string","null"],"format":"date-time"}},"required":["status","attempts","lastAttemptedAt","lastStatusCode","lastFailureCode","terminalFailureAt"]},"metadata":{"type":"object","additionalProperties":{"type":"string"},"default":{}},"createdAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:56Z"},"updatedAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:57Z"}},"required":["id","marketId","outcomeIndex","amount","side","status","correlationId","clientRequestId","txHash","tokensOut","errorCode","errorMessage","webhookDelivery","createdAt","updatedAt"]},"_meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["trade","data","_meta"]}}}},"400":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/trades/{id}":{"get":{"summary":"Get a single trade","security":[{"XApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Trade resource.","content":{"application/json":{"schema":{"type":"object","properties":{"trade":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"b8c5e3d1-4a7c-4b2e-8f5d-1c9a3e7b6f8d"},"marketId":{"type":"string","format":"uuid","example":"7a6e9c0a-3f4f-4c43-b6ab-1b2f0c8e3c91"},"outcomeIndex":{"type":"integer","minimum":0,"example":0},"amount":{"type":"string","pattern":"^(?:\\d+|\\d+\\.\\d{1,6})$","description":"USDC amount as a decimal string (e.g. \"100\" or \"100.500000\"). Up to 6 decimals.","example":"100"},"side":{"type":"string","enum":["buy","sell"],"example":"buy"},"status":{"type":"string","enum":["pending_confirmation","pending","validating","executing","completed","failed","rejected"],"example":"pending"},"correlationId":{"type":"string","format":"uuid","example":"d5f3e7c2-9b8a-4c1d-8e7f-3a5b9c1d2e4f"},"clientRequestId":{"type":["string","null"],"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_\\-:.]+$","description":"Optional client-side idempotency token. Same value with same body returns the existing trade; same value with different body returns 409."},"txHash":{"type":["string","null"],"pattern":"^0x[a-fA-F0-9]{64}$","example":"0x9b3a4c1f8e7d6b5a2f9c8e1d4b7a6f3c2e5d8b9a1f4c7e3d6b5a8f2c1e9b4d7a"},"tokensOut":{"type":["string","null"],"pattern":"^\\d+$","example":"105420000000000000000"},"errorCode":{"type":["string","null"]},"errorMessage":{"type":["string","null"]},"webhookDelivery":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["none","pending","delivered","retrying","failed"]},"attempts":{"type":"integer","minimum":0},"lastAttemptedAt":{"type":["string","null"],"format":"date-time"},"lastStatusCode":{"type":["integer","null"]},"lastFailureCode":{"type":["string","null"]},"terminalFailureAt":{"type":["string","null"],"format":"date-time"}},"required":["status","attempts","lastAttemptedAt","lastStatusCode","lastFailureCode","terminalFailureAt"]},"metadata":{"type":"object","additionalProperties":{"type":"string"},"default":{}},"createdAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:56Z"},"updatedAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:57Z"}},"required":["id","marketId","outcomeIndex","amount","side","status","correlationId","clientRequestId","txHash","tokensOut","errorCode","errorMessage","webhookDelivery","createdAt","updatedAt"]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"b8c5e3d1-4a7c-4b2e-8f5d-1c9a3e7b6f8d"},"marketId":{"type":"string","format":"uuid","example":"7a6e9c0a-3f4f-4c43-b6ab-1b2f0c8e3c91"},"outcomeIndex":{"type":"integer","minimum":0,"example":0},"amount":{"type":"string","pattern":"^(?:\\d+|\\d+\\.\\d{1,6})$","description":"USDC amount as a decimal string (e.g. \"100\" or \"100.500000\"). Up to 6 decimals.","example":"100"},"side":{"type":"string","enum":["buy","sell"],"example":"buy"},"status":{"type":"string","enum":["pending_confirmation","pending","validating","executing","completed","failed","rejected"],"example":"pending"},"correlationId":{"type":"string","format":"uuid","example":"d5f3e7c2-9b8a-4c1d-8e7f-3a5b9c1d2e4f"},"clientRequestId":{"type":["string","null"],"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_\\-:.]+$","description":"Optional client-side idempotency token. Same value with same body returns the existing trade; same value with different body returns 409."},"txHash":{"type":["string","null"],"pattern":"^0x[a-fA-F0-9]{64}$","example":"0x9b3a4c1f8e7d6b5a2f9c8e1d4b7a6f3c2e5d8b9a1f4c7e3d6b5a8f2c1e9b4d7a"},"tokensOut":{"type":["string","null"],"pattern":"^\\d+$","example":"105420000000000000000"},"errorCode":{"type":["string","null"]},"errorMessage":{"type":["string","null"]},"webhookDelivery":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["none","pending","delivered","retrying","failed"]},"attempts":{"type":"integer","minimum":0},"lastAttemptedAt":{"type":["string","null"],"format":"date-time"},"lastStatusCode":{"type":["integer","null"]},"lastFailureCode":{"type":["string","null"]},"terminalFailureAt":{"type":["string","null"],"format":"date-time"}},"required":["status","attempts","lastAttemptedAt","lastStatusCode","lastFailureCode","terminalFailureAt"]},"metadata":{"type":"object","additionalProperties":{"type":"string"},"default":{}},"createdAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:56Z"},"updatedAt":{"type":"string","format":"date-time","example":"2026-04-30T12:34:57Z"}},"required":["id","marketId","outcomeIndex","amount","side","status","correlationId","clientRequestId","txHash","tokensOut","errorCode","errorMessage","webhookDelivery","createdAt","updatedAt"]},"_meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["trade","data","_meta"]}}}},"401":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/traces/{correlationId}":{"get":{"summary":"Get the curated event timeline for a correlation id","description":"Returns the sanitized event timeline for a single trade's correlation id (intent → funding → bridge → execution → webhook delivery). Each event carries a stable, allowlisted subset of the originating event payload — raw event_data is never returned. Returns 404 (not 403) when the correlation id is unknown OR the caller does not own the underlying trade — by design, to prevent enumeration.","security":[{"XApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","example":"33333333-3333-3333-3333-333333333333"},"required":true,"name":"correlationId","in":"path"}],"responses":{"200":{"description":"Trace resource with curated event timeline.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetTraceResponse"}}}},"400":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/markets":{"get":{"summary":"List markets","description":"Lists all markets, newest first. Requires `markets:read` scope (granted by default on every tier).","security":[{"XApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["UNSEEDED","ACTIVE","RESOLVED"]},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"Page of markets.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"contractAddress":{"type":"string"},"chainId":{"type":"integer","exclusiveMinimum":0},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"status":{"type":["string","null"],"enum":["UNSEEDED","ACTIVE","RESOLVED"]},"outcomeCount":{"type":"integer","exclusiveMinimum":0},"outcomes":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":0},"label":{"type":"string"},"probability":{"type":"number","minimum":0,"maximum":1}},"required":["index","label","probability"]}},"imageUrl":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":["string","null"],"format":"date-time"},"resolvedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","contractAddress","chainId","title","description","status","outcomeCount","outcomes","imageUrl","createdAt","expiresAt","resolvedAt"]}},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"hasMore":{"type":"boolean"},"limit":{"type":"integer","exclusiveMinimum":0}},"required":["cursor","hasMore","limit"]},"_meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["data","pagination","_meta"]}}}},"400":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/markets/{id}":{"get":{"summary":"Get a single market","description":"Returns the market with its outcome list. Requires `markets:read` scope (granted by default on every tier).","security":[{"XApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Market resource.","content":{"application/json":{"schema":{"type":"object","properties":{"market":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"contractAddress":{"type":"string"},"chainId":{"type":"integer","exclusiveMinimum":0},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"status":{"type":["string","null"],"enum":["UNSEEDED","ACTIVE","RESOLVED"]},"outcomeCount":{"type":"integer","exclusiveMinimum":0},"outcomes":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":0},"label":{"type":"string"},"probability":{"type":"number","minimum":0,"maximum":1}},"required":["index","label","probability"]}},"imageUrl":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":["string","null"],"format":"date-time"},"resolvedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","contractAddress","chainId","title","description","status","outcomeCount","outcomes","imageUrl","createdAt","expiresAt","resolvedAt"]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"contractAddress":{"type":"string"},"chainId":{"type":"integer","exclusiveMinimum":0},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"status":{"type":["string","null"],"enum":["UNSEEDED","ACTIVE","RESOLVED"]},"outcomeCount":{"type":"integer","exclusiveMinimum":0},"outcomes":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":0},"label":{"type":"string"},"probability":{"type":"number","minimum":0,"maximum":1}},"required":["index","label","probability"]}},"imageUrl":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":["string","null"],"format":"date-time"},"resolvedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","contractAddress","chainId","title","description","status","outcomeCount","outcomes","imageUrl","createdAt","expiresAt","resolvedAt"]},"_meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["market","data","_meta"]}}}},"401":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/markets/{id}/predictions":{"get":{"summary":"List recent trades (predictions) against a market","description":"Returns recent trades for a market, newest first, cursor-paginated. Backs the `markets.history()` method on the protocol SDK. Requires `markets:read` scope (granted by default on every tier).","security":[{"XApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["buy","sell"]},"required":false,"name":"side","in":"query"},{"schema":{"type":["integer","null"],"minimum":0},"required":false,"name":"outcomeIndex","in":"query"}],"responses":{"200":{"description":"Page of predictions (recent trades).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"marketId":{"type":"string","format":"uuid"},"outcomeIndex":{"type":"integer","minimum":0},"side":{"type":"string","enum":["buy","sell"]},"usdcIn":{"type":["string","null"]},"usdcOut":{"type":["string","null"]},"tokensIn":{"type":["string","null"]},"tokensOut":{"type":["string","null"]},"price":{"type":"string"},"probability":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"blockNumber":{"type":"string"},"transactionHash":{"type":"string"},"logIndex":{"type":"integer","minimum":0}},"required":["id","marketId","outcomeIndex","side","usdcIn","usdcOut","tokensIn","tokensOut","price","probability","timestamp","blockNumber","transactionHash","logIndex"]}},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"hasMore":{"type":"boolean"},"limit":{"type":"integer","exclusiveMinimum":0}},"required":["cursor","hasMore","limit"]},"_meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["data","pagination","_meta"]}}}},"400":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/markets/{id}/quote":{"get":{"summary":"Quote a buy or sell against a market","description":"Returns an on-chain quote for a buy (`amount` in USDC atomic-6) or sell (`amount` in token WAD-18). All bigints come back as decimal strings — see the `units` block in the response. Requires `markets:quote` scope (granted by default on every tier). Quotes are RPC-heavy; this scope is split from `markets:read` so customers can throttle quote traffic independently.","security":[{"XApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":["integer","null"],"minimum":0},"required":false,"name":"outcomeIndex","in":"query"},{"schema":{"type":"string","enum":["buy","sell"]},"required":true,"name":"action","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$"},"required":true,"name":"amount","in":"query"}],"responses":{"200":{"description":"Quote detail + market summary + units block.","content":{"application/json":{"schema":{"type":"object","properties":{"quote":{"oneOf":[{"type":"object","properties":{"outcomeIndex":{"type":"integer","minimum":0},"reserveAfter":{"type":"string","pattern":"^\\d+$"},"c":{"type":"string","pattern":"^\\d+$"},"pAfter":{"type":"array","items":{"type":"string","pattern":"^\\d+$"}},"qAfter":{"type":"array","items":{"type":"string","pattern":"^\\d+$"}},"effectivePrice":{"type":"number"},"impliedProbability":{"type":["number","null"],"minimum":0,"maximum":1},"action":{"type":"string","enum":["buy"]},"amountIn":{"type":"string","pattern":"^\\d+$"},"tokensOut":{"type":"string","pattern":"^\\d+$"}},"required":["outcomeIndex","reserveAfter","c","pAfter","qAfter","effectivePrice","impliedProbability","action","amountIn","tokensOut"]},{"type":"object","properties":{"outcomeIndex":{"type":"integer","minimum":0},"reserveAfter":{"type":"string","pattern":"^\\d+$"},"c":{"type":"string","pattern":"^\\d+$"},"pAfter":{"type":"array","items":{"type":"string","pattern":"^\\d+$"}},"qAfter":{"type":"array","items":{"type":"string","pattern":"^\\d+$"}},"effectivePrice":{"type":"number"},"impliedProbability":{"type":["number","null"],"minimum":0,"maximum":1},"action":{"type":"string","enum":["sell"]},"tokensIn":{"type":"string","pattern":"^\\d+$"},"usdcOut":{"type":"string","pattern":"^\\d+$"},"grossRelease":{"type":"string","pattern":"^\\d+$"}},"required":["outcomeIndex","reserveAfter","c","pAfter","qAfter","effectivePrice","impliedProbability","action","tokensIn","usdcOut","grossRelease"]}]},"market":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"contractAddress":{"type":"string"},"chainId":{"type":"integer","exclusiveMinimum":0},"outcomes":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":0},"label":{"type":"string"},"probability":{"type":"number","minimum":0,"maximum":1}},"required":["index","label","probability"]}},"status":{"type":["string","null"],"enum":["UNSEEDED","ACTIVE","RESOLVED"]}},"required":["id","contractAddress","chainId","outcomes","status"]},"units":{"type":"object","properties":{"usdc":{"type":"string","enum":["atomic-6"]},"token":{"type":"string","enum":["wad-18"]}},"required":["usdc","token"]},"_meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["quote","market","units","_meta"]}}}},"400":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/portfolio":{"get":{"summary":"Get the authenticated user's portfolio summary","security":[{"XApiKey":[]}],"responses":{"200":{"description":"Portfolio summary.","content":{"application/json":{"schema":{"type":"object","properties":{"portfolio":{"type":"object","properties":{"smartAccountAddress":{"type":"string"},"activePositions":{"type":"integer","minimum":0},"totalCostBasisAtomic":{"type":"string","pattern":"^\\d+$"}},"required":["smartAccountAddress","activePositions","totalCostBasisAtomic"]},"data":{"type":"object","properties":{"smartAccountAddress":{"type":"string"},"activePositions":{"type":"integer","minimum":0},"totalCostBasisAtomic":{"type":"string","pattern":"^\\d+$"}},"required":["smartAccountAddress","activePositions","totalCostBasisAtomic"]},"_meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["portfolio","data","_meta"]}}}},"401":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/portfolio/positions":{"get":{"summary":"List the authenticated user's active positions","security":[{"XApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":false,"name":"marketId","in":"query"}],"responses":{"200":{"description":"Active positions.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"marketId":{"type":"string","format":"uuid"},"outcomeIndex":{"type":"integer","minimum":0},"shares":{"type":"string","pattern":"^\\d+$"},"costBasisAtomic":{"type":"string","pattern":"^\\d+$"},"tradeCount":{"type":"integer","minimum":0},"firstTradeAt":{"type":"string","format":"date-time"},"lastTradeAt":{"type":"string","format":"date-time"}},"required":["marketId","outcomeIndex","shares","costBasisAtomic","tradeCount","firstTradeAt","lastTradeAt"]}},"_meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["data","_meta"]}}}},"401":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/account/usage":{"get":{"summary":"Per-key usage telemetry summary (24h / 7d / 30d windows)","description":"Single-round-trip rolling-window summary the webapp Settings page renders inline. Returns trade counts and success rates per window, p50/p99 end-to-end latency, webhook delivery success, and recent auth + rate-limit signals — all derived from the calling key's own audit + trade rows. Auth: requires the `auth:manage` scope.","security":[{"XApiKey":[]}],"responses":{"200":{"description":"Per-key usage summary for the calling API key.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"apiKeyId":{"type":"string","format":"uuid"},"generatedAt":{"type":"string","format":"date-time"},"trades":{"type":"object","properties":{"24h":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"completed":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"successRate":{"type":["number","null"],"minimum":0,"maximum":1},"latencyMs":{"type":"object","properties":{"p50":{"type":["integer","null"]},"p99":{"type":["integer","null"]}},"required":["p50","p99"]}},"required":["total","completed","failed","successRate","latencyMs"]},"7d":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"completed":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"successRate":{"type":["number","null"],"minimum":0,"maximum":1}},"required":["total","completed","failed","successRate"]},"30d":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"completed":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"successRate":{"type":["number","null"],"minimum":0,"maximum":1}},"required":["total","completed","failed","successRate"]}},"required":["24h","7d","30d"]},"webhooks":{"type":"object","properties":{"7d":{"type":"object","properties":{"emitted":{"type":"integer","minimum":0},"delivered":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"successRate":{"type":["number","null"],"minimum":0,"maximum":1}},"required":["emitted","delivered","failed","successRate"]}},"required":["7d"]},"auth":{"type":"object","properties":{"24h":{"type":"object","properties":{"failures":{"type":"integer","minimum":0},"rateLimitRejections":{"type":"integer","minimum":0}},"required":["failures","rateLimitRejections"]}},"required":["24h"]}},"required":["apiKeyId","generatedAt","trades","webhooks","auth"]},"_meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["data","_meta"]}}}},"401":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/webhooks/events":{"get":{"summary":"List recent webhook deliveries for the calling key","description":"Paginated, newest-first list of webhook events scoped strictly to the calling key (api_key_id, not user_id — cross-key leaks are impossible). Each row carries the same delivery-state shape that surfaces inline on a trade resource's `webhookDelivery`. Auth: requires the `webhooks:manage` scope.","security":[{"XApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"Page of webhook events with cursor pagination.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"eventType":{"type":"string"},"tradeRequestId":{"type":["string","null"],"format":"uuid"},"emittedAt":{"type":"string","format":"date-time"},"outboxEmittedAt":{"type":["string","null"],"format":"date-time"},"replayCount":{"type":"integer","minimum":0},"status":{"type":"string","enum":["none","pending","delivered","retrying","failed"]},"delivery":{"type":"object","properties":{"attempts":{"type":"integer","minimum":0},"lastAttemptedAt":{"type":["string","null"],"format":"date-time"},"lastDeliveredAt":{"type":["string","null"],"format":"date-time"},"lastStatusCode":{"type":["integer","null"]},"lastFailureCode":{"type":["string","null"]},"lastErrorMessage":{"type":["string","null"]},"terminalFailureAt":{"type":["string","null"],"format":"date-time"}},"required":["attempts","lastAttemptedAt","lastDeliveredAt","lastStatusCode","lastFailureCode","lastErrorMessage","terminalFailureAt"]}},"required":["id","eventType","tradeRequestId","emittedAt","outboxEmittedAt","replayCount","status","delivery"]}},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"hasMore":{"type":"boolean"},"limit":{"type":"integer","exclusiveMinimum":0}},"required":["cursor","hasMore","limit"]},"_meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["data","pagination","_meta"]}}}},"401":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/webhooks/events/{eventId}/redeliver":{"post":{"summary":"Re-emit a previously-shipped webhook event","description":"Idempotent at the customer's dedupe layer: the redelivered webhook carries the same X-Kash-Event-Id as the original, so a customer who already processed the first delivery treats the replay as a no-op. Capped at 5 replays per event to bound amplification. Auth: requires the `webhooks:manage` scope.","security":[{"XApiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"eventId","in":"path"}],"responses":{"202":{"description":"Replay accepted; delivery worker drains the FIFO queue at its own cadence.","content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"eventType":{"type":"string"},"apiKeyId":{"type":"string","format":"uuid"},"tradeRequestId":{"type":["string","null"],"format":"uuid"},"emittedAt":{"type":"string","format":"date-time"},"lastDeliveredAt":{"type":["string","null"],"format":"date-time"},"deliveryAttempts":{"type":"integer","minimum":0}},"required":["id","eventType","apiKeyId","tradeRequestId","emittedAt","lastDeliveredAt","deliveryAttempts"]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"eventType":{"type":"string"},"apiKeyId":{"type":"string","format":"uuid"},"tradeRequestId":{"type":["string","null"],"format":"uuid"},"emittedAt":{"type":"string","format":"date-time"},"lastDeliveredAt":{"type":["string","null"],"format":"date-time"},"deliveryAttempts":{"type":"integer","minimum":0}},"required":["id","eventType","apiKeyId","tradeRequestId","emittedAt","lastDeliveredAt","deliveryAttempts"]},"_meta":{"allOf":[{"$ref":"#/components/schemas/ResponseMeta"},{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}]}},"required":["event","data","_meta"]}}}},"401":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/v1/auth/api-keys/me/webhook-secret/rotate":{"post":{"summary":"Rotate the webhook signing secret for the authenticating API key","description":"Self-service: the key authenticates itself; no path param. The plaintext secret is returned ONCE — capture it from this response. The previous secret is retained for the 7-day overlap window during which the worker dual-signs deliveries (`X-Kash-Signature: t=<ms>,v1=<new>,v1=<previous>`), so verifiers on either secret accept the signature. Returns 429 `WEBHOOK_SECRET_ROTATION_COOLDOWN` if called within 60s of a prior successful rotation — this protects the rollback slot against retry-storm double-rotation. Auth: requires the `webhooks:manage` scope.","security":[{"XApiKey":[]}],"responses":{"200":{"description":"Rotation complete; capture the new plaintext secret immediately.","content":{"application/json":{"schema":{"type":"object","properties":{"webhookSecret":{"type":"object","properties":{"secret":{"type":"string"},"rotatedAt":{"type":"string","format":"date-time"},"previousRetainedUntil":{"type":"string","format":"date-time"}},"required":["secret","rotatedAt","previousRetainedUntil"]},"data":{"type":"object","properties":{"secret":{"type":"string"},"rotatedAt":{"type":"string","format":"date-time"},"previousRetainedUntil":{"type":"string","format":"date-time"}},"required":["secret","rotatedAt","previousRetainedUntil"]},"_meta":{"allOf":[{"$ref":"#/components/schemas/ResponseMeta"},{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}]}},"required":["webhookSecret","data","_meta"]}}}},"401":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"RFC 7807 Problem Details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}},"webhooks":{"trade.confirmation-required":{"post":{"summary":"High-value trade is awaiting explicit confirmation","description":"Fires when POST /v1/trades returns a 202 Accepted with a confirmation token. The customer endpoint should surface to a human (or auto-approve via policy) and POST the token to /v1/trades/{id}/confirm before `confirmationExpiresAt` — otherwise the trade auto-cancels.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TradeConfirmationRequiredEnvelope"}}}},"responses":{"200":{"description":"ACK — delivery confirmed; no further attempts."},"202":{"description":"Acknowledged for async processing — also confirms delivery."},"4XX":{"description":"Permanent failure — customer endpoint rejected the payload. Delivery worker classifies as terminal and surfaces via /v1/webhooks/events. Use POST /v1/webhooks/events/{id}/redeliver after fixing the endpoint."},"5XX":{"description":"Transient failure — retried with exponential backoff up to 10 attempts over ~24h, then moved to the DLQ."}}}},"trade.completed":{"post":{"summary":"Trade reached terminal success","description":"Fires when a trade row reaches `status: 'completed'`. The on-chain transaction has been mined; `txHash` and `tokensOut` are final. No further events for this trade.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TradeCompletedEnvelope"}}}},"responses":{"200":{"description":"ACK — delivery confirmed; no further attempts."},"202":{"description":"Acknowledged for async processing — also confirms delivery."},"4XX":{"description":"Permanent failure — customer endpoint rejected the payload. Delivery worker classifies as terminal and surfaces via /v1/webhooks/events. Use POST /v1/webhooks/events/{id}/redeliver after fixing the endpoint."},"5XX":{"description":"Transient failure — retried with exponential backoff up to 10 attempts over ~24h, then moved to the DLQ."}}}},"trade.failed":{"post":{"summary":"Trade reached terminal failure (execution-time)","description":"Fires when a trade was submitted on-chain but failed during execution (RPC revert, balance race, etc.). `errorCode` is a stable token (see the per-code docs at /v1/errors); `errorMessage` is a sanitised human description. For pre-execution rejections (risk-engine declined the trade) see the separate `trade.rejected` event. No further events for this trade.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TradeFailedEnvelope"}}}},"responses":{"200":{"description":"ACK — delivery confirmed; no further attempts."},"202":{"description":"Acknowledged for async processing — also confirms delivery."},"4XX":{"description":"Permanent failure — customer endpoint rejected the payload. Delivery worker classifies as terminal and surfaces via /v1/webhooks/events. Use POST /v1/webhooks/events/{id}/redeliver after fixing the endpoint."},"5XX":{"description":"Transient failure — retried with exponential backoff up to 10 attempts over ~24h, then moved to the DLQ."}}}},"trade.rejected":{"post":{"summary":"Trade rejected before on-chain execution","description":"Fires when the risk engine declined a trade BEFORE submission (per-trade cap, daily spend cap, sanctions / KYC gate, kill switch, etc.). The trade was never broadcast, so there is no `txHash` and no `tokensOut`. `errorCode` is a stable token (see the per-code docs at /v1/errors). Distinct from `trade.failed`, which fires for execution-time failures. No further events for this trade.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TradeRejectedEnvelope"}}}},"responses":{"200":{"description":"ACK — delivery confirmed; no further attempts."},"202":{"description":"Acknowledged for async processing — also confirms delivery."},"4XX":{"description":"Permanent failure — customer endpoint rejected the payload. Delivery worker classifies as terminal and surfaces via /v1/webhooks/events. Use POST /v1/webhooks/events/{id}/redeliver after fixing the endpoint."},"5XX":{"description":"Transient failure — retried with exponential backoff up to 10 attempts over ~24h, then moved to the DLQ."}}}}}}