{"openapi":"3.1.0","info":{"title":"Centaur Partners API","version":"1.0.0","description":"Public partner API for read-only Centaur data over REST with a companion MCP surface."},"servers":[{"url":"https://partners.centaur.io","description":"Current service base URL"}],"externalDocs":{"description":"Canonical partner documentation","url":"https://partners.centaur.io/docs"},"tags":[{"name":"System","description":"Health and service metadata endpoints."},{"name":"Discovery","description":"Read-only trader and asset directory discovery endpoints."},{"name":"Events","description":"Historical trade-event reads with source, trader, asset, and position context."},{"name":"Messages","description":"Read-only partner source-message reads."},{"name":"Positions","description":"Read-only open and valid closed position reads."},{"name":"Stats","description":"Read-only aggregate trader and asset stats."}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Partner API key issued by Centaur.","x-default":"<partner-api-key>"}},"schemas":{"EventsResponseData":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"meta":{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true},"appliedTimeRange":{"$ref":"#/components/schemas/AppliedTimeRange"}},"required":["hasMore","nextCursor","appliedTimeRange"]}},"required":["results","meta"]},"Event":{"type":"object","properties":{"id":{"type":"integer"},"eventType":{"$ref":"#/components/schemas/EventType"},"price":{"type":"number","nullable":true},"timeOfEvent":{"type":"string","format":"date-time"},"assumed":{"type":"boolean"},"retrospective":{"type":"boolean"},"autoGenerated":{"type":"boolean"},"position":{"type":"object","properties":{"id":{"type":"integer"},"direction":{"$ref":"#/components/schemas/TraderDirection"},"openAt":{"type":"string","nullable":true,"format":"date-time"},"openPrice":{"type":"number","nullable":true},"closeAt":{"type":"string","nullable":true,"format":"date-time"},"closePrice":{"type":"number","nullable":true},"returnPercentage":{"type":"number","nullable":true}},"required":["id","direction","openAt","openPrice","closeAt","closePrice","returnPercentage"]},"trader":{"$ref":"#/components/schemas/TraderSummary"},"asset":{"$ref":"#/components/schemas/AssetSummary"},"source":{"type":"object","nullable":true,"properties":{"messageId":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"text":{"type":"string","nullable":true},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/Attachment"}},"originalCreatedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["messageId","url","text","attachments","originalCreatedAt"]}},"required":["id","eventType","price","timeOfEvent","assumed","retrospective","autoGenerated","position","trader","asset","source"]},"EventType":{"type":"string","enum":["open","close","increase","decrease"]},"TraderDirection":{"type":"string","enum":["long","short"]},"TraderSummary":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"slug":{"type":"string","nullable":true},"avatarUrl":{"type":"string","nullable":true}},"required":["id","name","slug","avatarUrl"]},"AssetSummary":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"symbol":{"type":"string"},"logoUrl":{"type":"string","nullable":true}},"required":["id","name","symbol","logoUrl"]},"Attachment":{"type":"object","properties":{"type":{"type":"string"},"url":{"type":"string","format":"uri"}},"required":["type","url"]},"AppliedTimeRange":{"type":"object","properties":{"startTime":{"type":"string","nullable":true,"format":"date-time"},"endTime":{"type":"string","nullable":true,"format":"date-time"}},"required":["startTime","endTime"]},"ErrorEnvelope":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"$ref":"#/components/schemas/Error"},"requestId":{"type":"string","example":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}},"required":["success","error","requestId"]},"Error":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code.","example":"UNAUTHORIZED"},"message":{"type":"string","description":"Human-readable explanation for the failure.","example":"Unauthorized"},"details":{"nullable":true,"description":"Optional structured details for validation or input failures."}},"required":["code","message"]},"MessagesResponseData":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"meta":{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true},"appliedTimeRange":{"$ref":"#/components/schemas/AppliedTimeRange"}},"required":["hasMore","nextCursor","appliedTimeRange"]}},"required":["results","meta"]},"Message":{"type":"object","properties":{"id":{"type":"string"},"telegramChannelId":{"type":"integer"},"telegramMessageId":{"type":"integer"},"originalCreatedAt":{"type":"string","format":"date-time"},"url":{"type":"string","nullable":true},"text":{"type":"string","nullable":true},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/Attachment"}},"trader":{"$ref":"#/components/schemas/TraderSummary"}},"required":["id","telegramChannelId","telegramMessageId","originalCreatedAt","url","text","attachments","trader"]},"ClosedPositionsResponseData":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/ClosedPosition"}},"meta":{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true},"appliedTimeRange":{"$ref":"#/components/schemas/AppliedTimeRange"}},"required":["hasMore","nextCursor","appliedTimeRange"]}},"required":["results","meta"]},"ClosedPosition":{"type":"object","properties":{"id":{"type":"integer"},"direction":{"$ref":"#/components/schemas/TraderDirection"},"openAt":{"type":"string","format":"date-time"},"openPrice":{"type":"number","nullable":true},"closeAt":{"type":"string","format":"date-time"},"closePrice":{"type":"number","nullable":true},"returnPercentage":{"type":"number","nullable":true},"closeAssumed":{"type":"boolean"},"closeAutoGenerated":{"type":"boolean"},"trader":{"$ref":"#/components/schemas/TraderSummary"},"asset":{"$ref":"#/components/schemas/AssetSummary"}},"required":["id","direction","openAt","openPrice","closeAt","closePrice","returnPercentage","closeAssumed","closeAutoGenerated","trader","asset"]},"OpenPositionsResponseData":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/OpenPosition"}},"meta":{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true}},"required":["hasMore","nextCursor"]}},"required":["results","meta"]},"OpenPosition":{"type":"object","properties":{"id":{"type":"integer"},"direction":{"$ref":"#/components/schemas/TraderDirection"},"openAt":{"type":"string","format":"date-time"},"openPrice":{"type":"number","nullable":true},"currentPrice":{"type":"number","nullable":true},"currentReturnPercentage":{"type":"number","nullable":true},"priceAsOf":{"type":"string","nullable":true,"format":"date-time"},"trader":{"$ref":"#/components/schemas/TraderSummary"},"asset":{"$ref":"#/components/schemas/AssetSummary"}},"required":["id","direction","openAt","openPrice","currentPrice","currentReturnPercentage","priceAsOf","trader","asset"]},"TradersResponseData":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/TraderSummary"}},"meta":{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true}},"required":["hasMore","nextCursor"]}},"required":["results","meta"]},"AssetsResponseData":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/AssetSummary"}},"meta":{"type":"object","properties":{"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true}},"required":["hasMore","nextCursor"]}},"required":["results","meta"]},"TraderStats":{"type":"object","properties":{"subject":{"$ref":"#/components/schemas/TraderSummary"},"filtersApplied":{"type":"object","properties":{"assetIds":{"type":"array","items":{"type":"integer"}},"direction":{"allOf":[{"$ref":"#/components/schemas/TraderDirection"},{"nullable":true}]},"appliedTimeRange":{"$ref":"#/components/schemas/AppliedTimeRange"}},"required":["assetIds","direction","appliedTimeRange"]},"summary":{"type":"object","properties":{"medianReturnPercentage":{"type":"number","nullable":true},"averageReturnPercentage":{"type":"number","nullable":true},"medianHoldingPeriodMinutes":{"type":"number","nullable":true},"winRatePercentage":{"type":"number","nullable":true},"assetFocus":{"type":"array","items":{"type":"object","properties":{"asset":{"$ref":"#/components/schemas/AssetSummary"},"positionsCount":{"type":"integer"},"sharePercentage":{"type":"number"}},"required":["asset","positionsCount","sharePercentage"]}},"directionBias":{"$ref":"#/components/schemas/DirectionBias"}},"required":["medianReturnPercentage","averageReturnPercentage","medianHoldingPeriodMinutes","winRatePercentage","assetFocus","directionBias"]}},"required":["subject","filtersApplied","summary"]},"DirectionBias":{"type":"object","properties":{"label":{"type":"string","enum":["long","short","neutral"]},"longCount":{"type":"integer"},"shortCount":{"type":"integer"},"longPercentage":{"type":"number","nullable":true},"shortPercentage":{"type":"number","nullable":true}},"required":["label","longCount","shortCount","longPercentage","shortPercentage"]},"AssetStats":{"type":"object","properties":{"subject":{"$ref":"#/components/schemas/AssetSummary"},"filtersApplied":{"type":"object","properties":{"traderIds":{"type":"array","items":{"type":"integer"}},"direction":{"allOf":[{"$ref":"#/components/schemas/TraderDirection"},{"nullable":true}]},"appliedTimeRange":{"$ref":"#/components/schemas/AppliedTimeRange"}},"required":["traderIds","direction","appliedTimeRange"]},"summary":{"type":"object","properties":{"marketPositioning":{"$ref":"#/components/schemas/DirectionBias"},"topTraders":{"type":"object","properties":{"long":{"type":"array","items":{"$ref":"#/components/schemas/TraderSummary"}},"short":{"type":"array","items":{"$ref":"#/components/schemas/TraderSummary"}}},"required":["long","short"]}},"required":["marketPositioning","topTraders"]}},"required":["subject","filtersApplied","summary"]},"HealthResponseData":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]}},"required":["status"]}},"parameters":{}},"paths":{"/api/v1/events":{"get":{"tags":["Events"],"operationId":"listEvents","summary":"List trading events","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Filter to specific trader IDs."},"required":false,"description":"Filter to specific trader IDs.","name":"traderIds","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Filter to specific asset IDs."},"required":false,"description":"Filter to specific asset IDs.","name":"assetIds","in":"query"},{"schema":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}]},{"type":"array","items":{"$ref":"#/components/schemas/TraderDirection"}}],"description":"Filter to `long` and/or `short` positions."},"required":false,"description":"Filter to `long` and/or `short` positions.","name":"directions","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Inclusive ISO-8601 lower time bound."},"required":false,"description":"Inclusive ISO-8601 lower time bound.","name":"startTime","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Inclusive ISO-8601 upper time bound."},"required":false,"description":"Inclusive ISO-8601 upper time bound.","name":"endTime","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum number of rows to return."},"required":false,"description":"Maximum number of rows to return.","name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Forward pagination cursor from `meta.nextCursor`."},"required":false,"description":"Forward pagination cursor from `meta.nextCursor`.","name":"cursor","in":"query"},{"schema":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}]},{"type":"array","items":{"$ref":"#/components/schemas/EventType"}}],"description":"Filter to specific event types: `open`, `close`, `increase`, or `decrease`."},"required":false,"description":"Filter to specific event types: `open`, `close`, `increase`, or `decrease`.","name":"eventTypes","in":"query"}],"responses":{"200":{"description":"Paginated list of public trading events","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/EventsResponseData"},"requestId":{"type":"string","example":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}},"required":["success","data","requestId"]}}}},"400":{"description":"Invalid cursor or query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"code":"INVALID_CURSOR","message":"Malformed cursor"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Unauthorized"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"code":"FORBIDDEN","message":"Forbidden"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/messages":{"get":{"tags":["Messages"],"operationId":"listMessages","summary":"List source message feed","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Filter to messages from specific trader IDs."},"required":false,"description":"Filter to messages from specific trader IDs.","name":"traderIds","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Compatibility narrowing filter. Only include messages with at least one linked event on specific asset IDs."},"required":false,"description":"Compatibility narrowing filter. Only include messages with at least one linked event on specific asset IDs.","name":"assetIds","in":"query"},{"schema":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}]},{"type":"array","items":{"$ref":"#/components/schemas/TraderDirection"}}],"description":"Compatibility narrowing filter. Only include messages with at least one linked `long` and/or `short` event."},"required":false,"description":"Compatibility narrowing filter. Only include messages with at least one linked `long` and/or `short` event.","name":"directions","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Inclusive ISO-8601 lower time bound on message timestamp."},"required":false,"description":"Inclusive ISO-8601 lower time bound on message timestamp.","name":"startTime","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Inclusive ISO-8601 upper time bound on message timestamp."},"required":false,"description":"Inclusive ISO-8601 upper time bound on message timestamp.","name":"endTime","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum number of rows to return."},"required":false,"description":"Maximum number of rows to return.","name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Forward pagination cursor from `meta.nextCursor`."},"required":false,"description":"Forward pagination cursor from `meta.nextCursor`.","name":"cursor","in":"query"},{"schema":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}]},{"type":"array","items":{"$ref":"#/components/schemas/EventType"}}],"description":"Compatibility narrowing filter. Only include messages with at least one linked event of type `open`, `close`, `increase`, or `decrease`."},"required":false,"description":"Compatibility narrowing filter. Only include messages with at least one linked event of type `open`, `close`, `increase`, or `decrease`.","name":"eventTypes","in":"query"}],"responses":{"200":{"description":"Paginated list of messages","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/MessagesResponseData"},"requestId":{"type":"string","example":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}},"required":["success","data","requestId"]}}}},"400":{"description":"Invalid cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"code":"INVALID_CURSOR","message":"Malformed cursor"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Unauthorized"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"code":"FORBIDDEN","message":"Forbidden"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/positions/closed/valid":{"get":{"tags":["Positions"],"operationId":"listValidClosedPositions","summary":"List valid closed positions","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Filter to specific trader IDs."},"required":false,"description":"Filter to specific trader IDs.","name":"traderIds","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Filter to specific asset IDs."},"required":false,"description":"Filter to specific asset IDs.","name":"assetIds","in":"query"},{"schema":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}]},{"type":"array","items":{"$ref":"#/components/schemas/TraderDirection"}}],"description":"Filter to `long` and/or `short` positions."},"required":false,"description":"Filter to `long` and/or `short` positions.","name":"directions","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Inclusive ISO-8601 lower time bound."},"required":false,"description":"Inclusive ISO-8601 lower time bound.","name":"startTime","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Inclusive ISO-8601 upper time bound."},"required":false,"description":"Inclusive ISO-8601 upper time bound.","name":"endTime","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum number of rows to return."},"required":false,"description":"Maximum number of rows to return.","name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Forward pagination cursor from `meta.nextCursor`."},"required":false,"description":"Forward pagination cursor from `meta.nextCursor`.","name":"cursor","in":"query"}],"responses":{"200":{"description":"Paginated valid closed positions","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/ClosedPositionsResponseData"},"requestId":{"type":"string","example":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}},"required":["success","data","requestId"]}}}},"400":{"description":"Invalid cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"code":"INVALID_CURSOR","message":"Malformed cursor"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Unauthorized"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"code":"FORBIDDEN","message":"Forbidden"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/positions/open":{"get":{"tags":["Positions"],"operationId":"listOpenPositions","summary":"List open positions","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Filter to specific trader IDs."},"required":false,"description":"Filter to specific trader IDs.","name":"traderIds","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Filter to specific asset IDs."},"required":false,"description":"Filter to specific asset IDs.","name":"assetIds","in":"query"},{"schema":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}]},{"type":"array","items":{"$ref":"#/components/schemas/TraderDirection"}}],"description":"Filter to `long` and/or `short` positions."},"required":false,"description":"Filter to `long` and/or `short` positions.","name":"directions","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum number of rows to return."},"required":false,"description":"Maximum number of rows to return.","name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Forward pagination cursor from `meta.nextCursor`."},"required":false,"description":"Forward pagination cursor from `meta.nextCursor`.","name":"cursor","in":"query"}],"responses":{"200":{"description":"Paginated open positions","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/OpenPositionsResponseData"},"requestId":{"type":"string","example":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}},"required":["success","data","requestId"]}}}},"400":{"description":"Invalid cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"code":"INVALID_CURSOR","message":"Malformed cursor"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Unauthorized"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"code":"FORBIDDEN","message":"Forbidden"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/traders":{"get":{"tags":["Discovery"],"operationId":"listTraders","summary":"List traders","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Case-insensitive partial match against trader name or slug."},"required":false,"description":"Case-insensitive partial match against trader name or slug.","name":"search","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Filter to specific trader IDs."},"required":false,"description":"Filter to specific trader IDs.","name":"traderIds","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Filter to traders with eligible positions on specific asset IDs."},"required":false,"description":"Filter to traders with eligible positions on specific asset IDs.","name":"assetIds","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum number of rows to return."},"required":false,"description":"Maximum number of rows to return.","name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Forward pagination cursor from `meta.nextCursor`."},"required":false,"description":"Forward pagination cursor from `meta.nextCursor`.","name":"cursor","in":"query"}],"responses":{"200":{"description":"Paginated list of traders","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/TradersResponseData"},"requestId":{"type":"string","example":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}},"required":["success","data","requestId"]}}}},"400":{"description":"Invalid cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"code":"INVALID_CURSOR","message":"Malformed cursor"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Unauthorized"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"code":"FORBIDDEN","message":"Forbidden"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/assets":{"get":{"tags":["Discovery"],"operationId":"listAssets","summary":"List assets","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Case-insensitive partial match against asset name or symbol."},"required":false,"description":"Case-insensitive partial match against asset name or symbol.","name":"search","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Filter to specific asset IDs."},"required":false,"description":"Filter to specific asset IDs.","name":"assetIds","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Filter to assets with eligible positions from specific trader IDs."},"required":false,"description":"Filter to assets with eligible positions from specific trader IDs.","name":"traderIds","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum number of rows to return."},"required":false,"description":"Maximum number of rows to return.","name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Forward pagination cursor from `meta.nextCursor`."},"required":false,"description":"Forward pagination cursor from `meta.nextCursor`.","name":"cursor","in":"query"}],"responses":{"200":{"description":"Paginated list of assets","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/AssetsResponseData"},"requestId":{"type":"string","example":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}},"required":["success","data","requestId"]}}}},"400":{"description":"Invalid cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"code":"INVALID_CURSOR","message":"Malformed cursor"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Unauthorized"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"code":"FORBIDDEN","message":"Forbidden"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/traders/{traderId}/stats":{"get":{"tags":["Stats"],"operationId":"getTraderStats","summary":"Get trader stats","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"description":"Trader ID to fetch stats for."},"required":true,"description":"Trader ID to fetch stats for.","name":"traderId","in":"path"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Filter to specific asset IDs."},"required":false,"description":"Filter to specific asset IDs.","name":"assetIds","in":"query"},{"schema":{"allOf":[{"$ref":"#/components/schemas/TraderDirection"},{"description":"Filter to a single direction: `long` or `short`."}]},"required":false,"description":"Filter to a single direction: `long` or `short`.","name":"direction","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Inclusive ISO-8601 lower time bound."},"required":false,"description":"Inclusive ISO-8601 lower time bound.","name":"startTime","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Inclusive ISO-8601 upper time bound."},"required":false,"description":"Inclusive ISO-8601 upper time bound.","name":"endTime","in":"query"}],"responses":{"200":{"description":"Trader stats","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/TraderStats"},"requestId":{"type":"string","example":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}},"required":["success","data","requestId"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Unauthorized"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"code":"FORBIDDEN","message":"Forbidden"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}}}},"404":{"description":"Trader not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"code":"NOT_FOUND","message":"Trader not found"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/assets/{assetId}/stats":{"get":{"tags":["Stats"],"operationId":"getAssetStats","summary":"Get asset stats","security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"description":"Asset ID to fetch stats for."},"required":true,"description":"Asset ID to fetch stats for.","name":"assetId","in":"path"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"number"}}],"description":"Filter to specific trader IDs."},"required":false,"description":"Filter to specific trader IDs.","name":"traderIds","in":"query"},{"schema":{"allOf":[{"$ref":"#/components/schemas/TraderDirection"},{"description":"Filter to a single direction: `long` or `short`."}]},"required":false,"description":"Filter to a single direction: `long` or `short`.","name":"direction","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Inclusive ISO-8601 lower time bound."},"required":false,"description":"Inclusive ISO-8601 lower time bound.","name":"startTime","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Inclusive ISO-8601 upper time bound."},"required":false,"description":"Inclusive ISO-8601 upper time bound.","name":"endTime","in":"query"}],"responses":{"200":{"description":"Asset stats","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/AssetStats"},"requestId":{"type":"string","example":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}},"required":["success","data","requestId"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"Unauthorized"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"code":"FORBIDDEN","message":"Forbidden"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}}}},"404":{"description":"Asset not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"success":false,"error":{"code":"NOT_FOUND","message":"Asset not found"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/healthz":{"get":{"tags":["System"],"operationId":"getHealth","summary":"Get service health","description":"Returns the current service health status.","responses":{"200":{"description":"Service health","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/HealthResponseData"},"requestId":{"type":"string","example":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}},"required":["success","data","requestId"]},"example":{"success":true,"data":{"status":"ok"},"requestId":"c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8"}}}}}}}}}