{"openapi":"3.1.0","info":{"title":"Marketry Paper Trading API","version":"0.1.0","description":"REST API for programmatic paper trading on Marketry. Primary docs: /lab. SDK: @marketry/sdk.","license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"}},"servers":[{"url":"https://localhost:3000","description":"API server"}],"tags":[{"name":"System"},{"name":"Markets"},{"name":"Trading"},{"name":"Portfolio"},{"name":"Accounts"},{"name":"Platform"}],"paths":{"/api/health":{"get":{"tags":["System"],"summary":"Health check","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/api/openapi":{"get":{"tags":["System"],"summary":"OpenAPI specification (this document)","responses":{"200":{"description":"OpenAPI 3.1 JSON","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/markets":{"get":{"tags":["Markets"],"summary":"List markets","parameters":[{"name":"status","in":"query","schema":{"type":"string","default":"active"}},{"name":"sector","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"array","items":{"type":"object"}}}}}}}},"/api/markets/{id}":{"get":{"tags":["Markets"],"summary":"Market detail","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/markets/signals":{"get":{"tags":["Markets"],"summary":"Enriched strategy signals","security":[{"bearerAuth":[]}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketSignalList"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/orderbook/{marketId}":{"get":{"tags":["Markets"],"summary":"Order book","parameters":[{"name":"marketId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/orders":{"get":{"tags":["Trading"],"summary":"List orders","security":[{"bearerAuth":[]}],"parameters":[{"name":"marketId","in":"query","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderList"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Trading"],"summary":"Place order","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrderInput"}}}},"responses":{"200":{"description":"Order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/orders/{id}":{"delete":{"tags":["Trading"],"summary":"Cancel order","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/portfolio":{"get":{"tags":["Portfolio"],"summary":"Portfolio summary","security":[{"bearerAuth":[]}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Portfolio"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/positions":{"get":{"tags":["Portfolio"],"summary":"Positions snapshot","security":[{"bearerAuth":[]}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/accounts/sub":{"get":{"tags":["Accounts"],"summary":"List sub-accounts","security":[{"bearerAuth":[]}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Accounts"],"summary":"Create sub-account + API key","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSubAccountInput"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/accounts/sub/{id}/keys":{"post":{"tags":["Accounts"],"summary":"Create API key for sub-account","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyInput"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/accounts/keys/{keyId}":{"delete":{"tags":["Accounts"],"summary":"Revoke API key","security":[{"bearerAuth":[]}],"parameters":[{"name":"keyId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/leaderboard":{"get":{"tags":["Platform"],"summary":"Ranked traders by portfolio value","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeaderboardList"}}}}}}},"/api/trades/recent":{"get":{"tags":["Platform"],"summary":"Recent platform trades","responses":{"200":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RecentTrade"}}}}}}}},"/api/activity":{"get":{"tags":["Platform"],"summary":"Platform pulse + activity feed","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivitySnapshot"}}}}}}},"/api/stream":{"get":{"tags":["Platform"],"summary":"SSE market pulse stream (2s interval)","parameters":[{"name":"marketId","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"text/event-stream","content":{"text/event-stream":{"schema":{"type":"string"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Sub-account API key (`mkt_live_…`)"},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Alternative to Bearer token"}},"schemas":{"CreateOrderInput":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"marketId":{"type":"string","minLength":1},"outcome":{"type":"string","enum":["yes","no"]},"side":{"default":"buy","type":"string","enum":["buy","sell"]},"orderType":{"default":"limit","type":"string","enum":["limit","market"]},"timeInForce":{"default":"GTC","type":"string","enum":["GTC","IOC","FOK"]},"price":{"type":"number","minimum":0.01,"maximum":0.99},"quantity":{"type":"integer","minimum":1,"maximum":500},"notional":{"type":"number","minimum":1,"maximum":5000},"maxPrice":{"type":"number","minimum":0.01,"maximum":0.99},"slippage":{"type":"number","minimum":0,"maximum":0.25}},"required":["marketId","outcome","side","orderType","timeInForce"],"additionalProperties":false},"CreateSubAccountInput":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"displayName":{"type":"string","minLength":2,"maxLength":24},"permissions":{"type":"array","items":{"type":"string","enum":["view","trade","master","reconcile"]}}},"required":["displayName"],"additionalProperties":false},"CreateApiKeyInput":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40},"permissions":{"minItems":1,"type":"array","items":{"type":"string","enum":["view","trade","master","reconcile"]}}},"required":["name","permissions"],"additionalProperties":false},"ErrorResponse":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error"],"additionalProperties":false},"HealthResponse":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"status":{"type":"string"},"version":{"type":"string"},"database":{"type":"string"},"timestamp":{"type":"string"},"complianceMode":{"type":"string"},"emailConfigured":{"type":"boolean"}},"required":["status"],"additionalProperties":false},"MarketSignal":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"marketId":{"type":"string"},"title":{"type":"string"},"probability":{"type":"number"},"volume":{"type":"number"},"companySlug":{"type":"string"},"companyImpact":{"type":"number"},"snapshotDelta":{"type":"number"},"neighborSignal":{"anyOf":[{"type":"number"},{"type":"null"}]},"sector":{"type":"string"},"category":{"type":"string"},"daysToEnd":{"type":"number"},"volumeDelta":{"type":"number"},"sectorAvgProb":{"type":"number"},"bestYesBid":{"anyOf":[{"type":"number"},{"type":"null"}]},"bestNoBid":{"anyOf":[{"type":"number"},{"type":"null"}]},"bestYesAsk":{"anyOf":[{"type":"number"},{"type":"null"}]},"spread":{"anyOf":[{"type":"number"},{"type":"null"}]},"openInterest":{"type":"number"},"settlementSource":{"type":"string"},"relatedDrivers":{"type":"array","items":{"type":"string"}},"siblingAvgProb":{"anyOf":[{"type":"number"},{"type":"null"}]},"graphCentrality":{"type":"number"},"clusterIds":{"type":"array","items":{"type":"string"}},"clusterRiskScore":{"type":"number"},"oracleScore":{"type":"number"}},"required":["marketId","title","probability","volume","companySlug","companyImpact","snapshotDelta","neighborSignal","sector","category","daysToEnd","volumeDelta","sectorAvgProb","bestYesBid","bestNoBid","bestYesAsk","spread","openInterest","settlementSource","relatedDrivers","siblingAvgProb","graphCentrality","clusterIds","clusterRiskScore","oracleScore"],"additionalProperties":false},"MarketSignalList":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"array","items":{"type":"object","properties":{"marketId":{"type":"string"},"title":{"type":"string"},"probability":{"type":"number"},"volume":{"type":"number"},"companySlug":{"type":"string"},"companyImpact":{"type":"number"},"snapshotDelta":{"type":"number"},"neighborSignal":{"anyOf":[{"type":"number"},{"type":"null"}]},"sector":{"type":"string"},"category":{"type":"string"},"daysToEnd":{"type":"number"},"volumeDelta":{"type":"number"},"sectorAvgProb":{"type":"number"},"bestYesBid":{"anyOf":[{"type":"number"},{"type":"null"}]},"bestNoBid":{"anyOf":[{"type":"number"},{"type":"null"}]},"bestYesAsk":{"anyOf":[{"type":"number"},{"type":"null"}]},"spread":{"anyOf":[{"type":"number"},{"type":"null"}]},"openInterest":{"type":"number"},"settlementSource":{"type":"string"},"relatedDrivers":{"type":"array","items":{"type":"string"}},"siblingAvgProb":{"anyOf":[{"type":"number"},{"type":"null"}]},"graphCentrality":{"type":"number"},"clusterIds":{"type":"array","items":{"type":"string"}},"clusterRiskScore":{"type":"number"},"oracleScore":{"type":"number"}},"required":["marketId","title","probability","volume","companySlug","companyImpact","snapshotDelta","neighborSignal","sector","category","daysToEnd","volumeDelta","sectorAvgProb","bestYesBid","bestNoBid","bestYesAsk","spread","openInterest","settlementSource","relatedDrivers","siblingAvgProb","graphCentrality","clusterIds","clusterRiskScore","oracleScore"],"additionalProperties":false}},"Order":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"marketId":{"type":"string"},"userId":{"type":"string"},"side":{"type":"string","enum":["buy","sell"]},"outcome":{"type":"string","enum":["yes","no"]},"orderType":{"type":"string","enum":["limit","market"]},"timeInForce":{"type":"string","enum":["GTC","IOC","FOK"]},"price":{"type":"number"},"quantity":{"type":"number"},"filledQty":{"type":"number"},"status":{"type":"string","enum":["open","partial","filled","cancelled"]},"createdAt":{"type":"string"},"reservedAmount":{"type":"number"},"avgFillPrice":{"type":"number"},"filledValue":{"type":"number"}},"required":["id","marketId","side","outcome","price","quantity","filledQty","status","createdAt"],"additionalProperties":false},"OrderList":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"marketId":{"type":"string"},"userId":{"type":"string"},"side":{"type":"string","enum":["buy","sell"]},"outcome":{"type":"string","enum":["yes","no"]},"orderType":{"type":"string","enum":["limit","market"]},"timeInForce":{"type":"string","enum":["GTC","IOC","FOK"]},"price":{"type":"number"},"quantity":{"type":"number"},"filledQty":{"type":"number"},"status":{"type":"string","enum":["open","partial","filled","cancelled"]},"createdAt":{"type":"string"},"reservedAmount":{"type":"number"},"avgFillPrice":{"type":"number"},"filledValue":{"type":"number"}},"required":["id","marketId","side","outcome","price","quantity","filledQty","status","createdAt"],"additionalProperties":false}},"Portfolio":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"summary":{"type":"object","properties":{"cash":{"type":"number"},"positionsValue":{"type":"number"},"portfolioValue":{"type":"number"},"pnl":{"type":"number"},"unrealizedPnl":{"type":"number"},"openOrders":{"type":"number"},"displayName":{"type":"string"},"startingBalance":{"type":"number"},"reserved":{"type":"number"},"volume":{"type":"number"}},"required":["cash","positionsValue","portfolioValue","pnl","unrealizedPnl","openOrders","displayName","startingBalance"],"additionalProperties":false},"fleetSummary":{"anyOf":[{"type":"object","properties":{"accountCount":{"type":"number"},"subAccountCount":{"type":"number"},"master":{"type":"object","properties":{"cash":{"type":"number"},"positionsValue":{"type":"number"},"portfolioValue":{"type":"number"},"pnl":{"type":"number"},"reserved":{"type":"number"},"volume":{"type":"number"}},"required":["cash","positionsValue","portfolioValue","pnl"],"additionalProperties":false},"subAccounts":{"type":"object","properties":{"cash":{"type":"number"},"positionsValue":{"type":"number"},"portfolioValue":{"type":"number"},"pnl":{"type":"number"},"reserved":{"type":"number"},"volume":{"type":"number"}},"required":["cash","positionsValue","portfolioValue","pnl"],"additionalProperties":false},"total":{"type":"object","properties":{"cash":{"type":"number"},"positionsValue":{"type":"number"},"portfolioValue":{"type":"number"},"pnl":{"type":"number"},"reserved":{"type":"number"},"volume":{"type":"number"}},"required":["cash","positionsValue","portfolioValue","pnl"],"additionalProperties":false}},"required":["accountCount","subAccountCount","master","subAccounts","total"],"additionalProperties":false},{"type":"null"}]},"positions":{"type":"array","items":{"type":"object","properties":{"marketId":{"type":"string"},"side":{"type":"string","enum":["yes","no"]},"shares":{"type":"number"},"avgCost":{"type":"number"},"markPrice":{"type":"number"},"marketValue":{"type":"number"},"unrealizedPnl":{"type":"number"},"yesShares":{"type":"number"},"noShares":{"type":"number"},"market":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"probability":{"type":"number"},"status":{"type":"string","enum":["active","ended","resolved","halted","pending","proposed"]},"ticker":{"type":"string"},"companySlug":{"type":"string"},"resolvedOutcome":{"anyOf":[{"type":"string","enum":["yes","no","void"]},{"type":"null"}]}},"required":["title","ticker","companySlug"],"additionalProperties":false}},"required":["marketId","side","shares","avgCost","markPrice","marketValue","unrealizedPnl","market"],"additionalProperties":false}},"orders":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"marketId":{"type":"string"},"side":{"type":"string","enum":["buy","sell"]},"outcome":{"type":"string","enum":["yes","no"]},"orderType":{"type":"string","enum":["limit","market"]},"timeInForce":{"type":"string","enum":["GTC","IOC","FOK"]},"price":{"type":"number"},"quantity":{"type":"number"},"filledQty":{"type":"number"},"status":{"type":"string","enum":["open","partial","filled","cancelled"]},"createdAt":{"type":"string"},"reservedAmount":{"type":"number"},"avgFillPrice":{"type":"number"},"filledValue":{"type":"number"},"market":{"type":"object","properties":{"title":{"type":"string"},"ticker":{"type":"string"},"companySlug":{"type":"string"},"resolvedOutcome":{"anyOf":[{"type":"string","enum":["yes","no","void"]},{"type":"null"}]}},"required":["title","ticker","companySlug"],"additionalProperties":false}},"required":["id","marketId","side","outcome","price","quantity","filledQty","status","createdAt","market"],"additionalProperties":false}},"trades":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"marketId":{"type":"string"},"outcome":{"type":"string","enum":["yes","no"]},"price":{"type":"number"},"quantity":{"type":"number"},"notional":{"type":"number"},"createdAt":{"type":"string"},"market":{"type":"object","properties":{"title":{"type":"string"},"ticker":{"type":"string"},"companySlug":{"type":"string"},"resolvedOutcome":{"anyOf":[{"type":"string","enum":["yes","no","void"]},{"type":"null"}]}},"required":["title","ticker","companySlug"],"additionalProperties":false}},"required":["id","marketId","outcome","price","quantity","notional","createdAt","market"],"additionalProperties":false}},"settled":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"marketId":{"type":"string"},"outcome":{"type":"string","enum":["yes","no","void"]},"shares":{"type":"number"},"payout":{"type":"number"},"pnl":{"type":"number"},"settledAt":{"type":"string"},"market":{"type":"object","properties":{"title":{"type":"string"},"ticker":{"type":"string"},"companySlug":{"type":"string"},"resolvedOutcome":{"anyOf":[{"type":"string","enum":["yes","no","void"]},{"type":"null"}]}},"required":["title","ticker","companySlug"],"additionalProperties":false}},"required":["id","marketId","outcome","shares","payout","pnl","settledAt","market"],"additionalProperties":false}}},"required":["summary","positions","orders","trades","settled"],"additionalProperties":false},"LeaderboardEntry":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"},"rank":{"type":"number"},"cash":{"type":"number"},"positionsValue":{"type":"number"},"portfolioValue":{"type":"number"},"pnl":{"type":"number"},"openPositions":{"type":"number"},"trades":{"type":"number"},"volume":{"type":"number"},"dailyPnl":{"type":"number"},"dailyVolume":{"type":"number"},"weeklyPnl":{"type":"number"},"weeklyVolume":{"type":"number"},"role":{"type":"string","enum":["admin","founder","beta","bot"]},"roleLabel":{"type":"string"},"isBot":{"type":"boolean"}},"required":["id","displayName","rank","cash","positionsValue","portfolioValue","pnl","openPositions","trades","volume"],"additionalProperties":false},"LeaderboardList":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"},"rank":{"type":"number"},"cash":{"type":"number"},"positionsValue":{"type":"number"},"portfolioValue":{"type":"number"},"pnl":{"type":"number"},"openPositions":{"type":"number"},"trades":{"type":"number"},"volume":{"type":"number"},"dailyPnl":{"type":"number"},"dailyVolume":{"type":"number"},"weeklyPnl":{"type":"number"},"weeklyVolume":{"type":"number"},"role":{"type":"string","enum":["admin","founder","beta","bot"]},"roleLabel":{"type":"string"},"isBot":{"type":"boolean"}},"required":["id","displayName","rank","cash","positionsValue","portfolioValue","pnl","openPositions","trades","volume"],"additionalProperties":false}},"RecentTrade":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"},"ticker":{"type":"string"},"marketId":{"type":"string"},"marketTitle":{"type":"string"},"outcome":{"type":"string","enum":["yes","no"]},"price":{"type":"number"},"quantity":{"type":"number"},"createdAt":{"type":"string"}},"required":["id","displayName","ticker","marketId","marketTitle","outcome","price","quantity","createdAt"],"additionalProperties":false},"ActivitySnapshot":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"pulse":{"type":"object","properties":{"activeMarkets":{"type":"number"},"totalVolume":{"type":"number"},"traders":{"type":"number"}},"required":["activeMarkets","totalVolume","traders"],"additionalProperties":{}},"activity":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"marketId":{"type":"string"},"title":{"type":"string"},"probability":{"type":"number"},"createdAt":{"type":"string"}},"required":["type","createdAt"],"additionalProperties":{}}}},"required":["pulse","activity"],"additionalProperties":false}}}}