{ "openapi": "3.0.0", "paths": { "/api/v1/keys": { "post": { "description": "Secret is shown only once in the response.", "operationId": "AuthController_createKey", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKeyInputDto" } } } }, "responses": { "201": { "description": "Created. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/ApiKeyOutputDto" } }, "required": [ "object", "data" ] } } } }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Create API key", "tags": [ "Keys" ], "x-thesauros-scopes": [ "keys:admin" ], "x-thesauros-public": false, "x-thesauros-handler": "AuthController.createKey" }, "get": { "operationId": "AuthController_listKeys", "parameters": [], "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyOutputDto" } } }, "required": [ "object", "data" ] } } } }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "List API keys (secrets masked)", "tags": [ "Keys" ], "x-thesauros-scopes": [ "keys:admin" ], "x-thesauros-public": false, "x-thesauros-handler": "AuthController.listKeys" } }, "/api/v1/keys/{id}": { "delete": { "operationId": "AuthController_revokeKey", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/RevokedApiKey" } }, "required": [ "object", "data" ] } } } }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Revoke an API key", "tags": [ "Keys" ], "x-thesauros-scopes": [ "keys:admin" ], "x-thesauros-public": false, "x-thesauros-handler": "AuthController.revokeKey" } }, "/api/v1/partners": { "post": { "description": "Creates a partner and generates a scoped API key.", "operationId": "PartnerController_createPartner", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePartnerInputDto" } } } }, "responses": { "201": { "description": "Created. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/PartnerCreated" } }, "required": [ "object", "data" ] } } } }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Create partner", "tags": [ "Partners (Admin)" ], "x-thesauros-scopes": [ "partner:admin" ], "x-thesauros-public": false, "x-thesauros-handler": "PartnerController.createPartner" }, "get": { "operationId": "PartnerController_listPartners", "parameters": [ { "name": "status", "required": false, "in": "query", "schema": { "enum": [ "active", "disabled" ], "type": "string" } } ], "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerOutputDto" } } }, "required": [ "object", "data" ] } } } }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "List partners", "tags": [ "Partners (Admin)" ], "x-thesauros-scopes": [ "partner:admin" ], "x-thesauros-public": false, "x-thesauros-handler": "PartnerController.listPartners" } }, "/api/v1/partners/{id}": { "get": { "operationId": "PartnerController_getPartner", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "example": "ptn_seed_acme", "type": "string" } } ], "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/PartnerOutputDto" } }, "required": [ "object", "data" ] } } } }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Get partner by ID", "tags": [ "Partners (Admin)" ], "x-thesauros-scopes": [ "partner:admin" ], "x-thesauros-public": false, "x-thesauros-handler": "PartnerController.getPartner" }, "patch": { "description": "Partial update. Pass status:\"disabled\" to soft-disable without deleting history/attributions. Disabling a partner immediately revokes all of its API keys; re-enabling does not restore them, issue a new key instead.", "operationId": "PartnerController_updatePartner", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "example": "ptn_seed_acme", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePartnerInputDto" } } } }, "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/PartnerOutputDto" } }, "required": [ "object", "data" ] } } } }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Update partner", "tags": [ "Partners (Admin)" ], "x-thesauros-scopes": [ "partner:admin" ], "x-thesauros-public": false, "x-thesauros-handler": "PartnerController.updatePartner" } }, "/api/v1/partners/{id}/campaigns": { "post": { "operationId": "PartnerController_createCampaign", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "example": "ptn_seed_acme", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCampaignInputDto" } } } }, "responses": { "201": { "description": "Created. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/CampaignOutputDto" } }, "required": [ "object", "data" ] } } } }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Create campaign for partner", "tags": [ "Partners (Admin)" ], "x-thesauros-scopes": [ "partner:admin" ], "x-thesauros-public": false, "x-thesauros-handler": "PartnerController.createCampaign" }, "get": { "operationId": "PartnerController_listCampaigns", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "example": "ptn_seed_acme", "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "enum": [ "active", "disabled" ], "type": "string" } } ], "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignOutputDto" } } }, "required": [ "object", "data" ] } } } }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "List campaigns for partner", "tags": [ "Partners (Admin)" ], "x-thesauros-scopes": [ "partner:admin" ], "x-thesauros-public": false, "x-thesauros-handler": "PartnerController.listCampaigns" } }, "/api/v1/partners/{id}/campaigns/{campaignId}": { "patch": { "description": "Partial update. Pass status:\"disabled\" to soft-disable a campaign without deleting it.", "operationId": "PartnerController_updateCampaign", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "example": "ptn_seed_acme", "type": "string" } }, { "name": "campaignId", "required": true, "in": "path", "schema": { "example": "cmp_seed_acme_launch", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCampaignInputDto" } } } }, "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/CampaignOutputDto" } }, "required": [ "object", "data" ] } } } }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Update campaign", "tags": [ "Partners (Admin)" ], "x-thesauros-scopes": [ "partner:admin" ], "x-thesauros-public": false, "x-thesauros-handler": "PartnerController.updateCampaign" } }, "/api/v1/partner/summary": { "get": { "operationId": "PartnerApiController_getSummary", "parameters": [], "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/PartnerSummary" } }, "required": [ "object", "data" ] } } } }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Partner summary", "tags": [ "Partner API (Self-Service)" ], "x-thesauros-scopes": [ "partner:read" ], "x-thesauros-public": false, "x-thesauros-handler": "PartnerApiController.getSummary" } }, "/api/v1/partner/users": { "get": { "operationId": "PartnerApiController_getUsers", "parameters": [], "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AttributedUser" } } }, "required": [ "object", "data" ] } } } }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Attributed users", "tags": [ "Partner API (Self-Service)" ], "x-thesauros-scopes": [ "partner:read" ], "x-thesauros-public": false, "x-thesauros-handler": "PartnerApiController.getUsers" } }, "/api/v1/partner/deposits": { "get": { "operationId": "PartnerApiController_getDeposits", "parameters": [], "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/PartnerDeposits" } }, "required": [ "object", "data" ] } } } }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Attributed deposits", "tags": [ "Partner API (Self-Service)" ], "x-thesauros-scopes": [ "partner:read" ], "x-thesauros-public": false, "x-thesauros-handler": "PartnerApiController.getDeposits" } }, "/api/v1/partner/withdrawals": { "get": { "operationId": "PartnerApiController_getWithdrawals", "parameters": [], "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/PartnerWithdrawals" } }, "required": [ "object", "data" ] } } } }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Attributed withdrawals", "tags": [ "Partner API (Self-Service)" ], "x-thesauros-scopes": [ "partner:read" ], "x-thesauros-public": false, "x-thesauros-handler": "PartnerApiController.getWithdrawals" } }, "/api/v1/partner/tvl": { "get": { "operationId": "PartnerApiController_getTvl", "parameters": [], "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/PartnerTvl" } }, "required": [ "object", "data" ] } } } }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Net TVL for partner", "tags": [ "Partner API (Self-Service)" ], "x-thesauros-scopes": [ "partner:read" ], "x-thesauros-public": false, "x-thesauros-handler": "PartnerApiController.getTvl" } }, "/api/v1/partner/yield": { "get": { "operationId": "PartnerApiController_getYield", "parameters": [], "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/PartnerYield" } }, "required": [ "object", "data" ] } } } }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Attributed yield", "tags": [ "Partner API (Self-Service)" ], "x-thesauros-scopes": [ "partner:read" ], "x-thesauros-public": false, "x-thesauros-handler": "PartnerApiController.getYield" } }, "/api/v1/partner/yield/history/{asset}": { "get": { "deprecated": true, "description": "Deprecated — use `GET /api/v1/yield/history/:asset` instead. The series is protocol-wide blended APY, identical for every partner, so it does not belong under the partner-scoped namespace. This alias returns an identical payload but still requires a partner-scoped key, because every route under /partner/* does.", "operationId": "PartnerApiController_getYieldHistory", "parameters": [ { "name": "asset", "required": true, "in": "path", "schema": { "enum": [ "USDC", "USDT0" ], "type": "string" } } ], "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/YieldHistory" } }, "required": [ "object", "data" ] } } } }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Yield history for asset (deprecated)", "tags": [ "Partner API (Self-Service)" ], "x-thesauros-scopes": [ "partner:read" ], "x-thesauros-public": false, "x-thesauros-handler": "PartnerApiController.getYieldHistory" } }, "/api/v1/partner/points": { "get": { "operationId": "PartnerApiController_getPoints", "parameters": [], "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/PartnerPoints" } }, "required": [ "object", "data" ] } } } }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Attributed points", "tags": [ "Partner API (Self-Service)" ], "x-thesauros-scopes": [ "partner:read" ], "x-thesauros-public": false, "x-thesauros-handler": "PartnerApiController.getPoints" } }, "/api/v1/partner/revenue": { "get": { "operationId": "PartnerApiController_getRevenue", "parameters": [], "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/RevenueShareOutputDto" } }, "required": [ "object", "data" ] } } } }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Revenue share calculation", "tags": [ "Partner API (Self-Service)" ], "x-thesauros-scopes": [ "partner:read" ], "x-thesauros-public": false, "x-thesauros-handler": "PartnerApiController.getRevenue" } }, "/api/v1/partner/user/{id}/positions": { "get": { "operationId": "PartnerApiController_getUserPositions", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "example": "usr_seed_nova", "type": "string" } } ], "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerPosition" } } }, "required": [ "object", "data" ] } } } }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "User positions (partner-scoped)", "tags": [ "Partner API (Self-Service)" ], "x-thesauros-scopes": [ "partner:read" ], "x-thesauros-public": false, "x-thesauros-handler": "PartnerApiController.getUserPositions" } }, "/api/v1/yield/history/{asset}": { "get": { "description": "Protocol-wide blended APY across active Thesauros vaults for the asset. The series is identical for every caller and contains no partner-attributed data, so a partner binding is not required — any key with `read` or `partner:read` works.", "operationId": "YieldController_getHistory", "parameters": [ { "name": "asset", "required": true, "in": "path", "schema": { "enum": [ "USDC", "USDT0" ], "type": "string" } } ], "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/YieldHistory" } }, "required": [ "object", "data" ] } } } }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Blended APY history for an asset", "tags": [ "Yield (Protocol)" ], "x-thesauros-scopes": [ "read", "partner:read" ], "x-thesauros-public": false, "x-thesauros-handler": "YieldController.getHistory" } }, "/api/v1/analytics/signals": { "get": { "description": "Scope: `read` or `partner:read` (protocol-level, same answer for every caller). Volatility/trend fields are null with `insufficient_history: true` until enough hourly snapshots exist.", "operationId": "AnalyticsController_signals", "parameters": [ { "name": "asset", "required": false, "in": "query", "description": "Filter by asset symbol.", "schema": { "type": "string", "enum": [ "USDC", "USDT0" ] } } ], "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SignalDto" } } } } } } }, "401": { "description": "Missing or invalid API key." }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Risk-adjusted venue signals from observed APY history", "tags": [ "Analytics" ], "x-thesauros-scopes": [ "read", "partner:read" ], "x-thesauros-public": false, "x-thesauros-handler": "AnalyticsController.signals" } }, "/api/v1/analytics/regime": { "get": { "description": "Scope: `read` or `partner:read` (protocol-level). `regime` is \"unknown\" until enough observations exist — never guessed.", "operationId": "AnalyticsController_regime", "parameters": [ { "name": "asset", "required": false, "in": "query", "description": "Filter by asset symbol.", "schema": { "type": "string", "enum": [ "USDC", "USDT0" ] } } ], "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string", "example": "object" }, "data": { "$ref": "#/components/schemas/RegimeDto" } } } } } }, "401": { "description": "Missing or invalid API key." }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Current rate regime and per-asset trend", "tags": [ "Analytics" ], "x-thesauros-scopes": [ "read", "partner:read" ], "x-thesauros-public": false, "x-thesauros-handler": "AnalyticsController.regime" } }, "/api/v1/analytics/uplift": { "get": { "description": "Scope: `partner:read` only — computed over the calling partner’s attributed positions. `user_id` must be a user attributed to the caller.", "operationId": "AnalyticsController_uplift", "parameters": [ { "name": "asset", "required": false, "in": "query", "description": "Filter by asset symbol.", "schema": { "type": "string", "enum": [ "USDC", "USDT0" ] } }, { "name": "user_id", "required": false, "in": "query", "description": "Restrict to one end-user (usr_…).", "schema": { "example": "usr_seed_nova", "type": "string" } }, { "name": "position_id", "required": false, "in": "query", "description": "Restrict to one position (pos_…).", "schema": { "example": "pos_seed_alpha", "type": "string" } } ], "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string", "example": "object" }, "data": { "$ref": "#/components/schemas/UpliftDto" } } } } } }, "401": { "description": "Missing or invalid API key." }, "403": { "description": "Key is not partner-scoped." }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Routed value vs the passive baseline, realized and projected", "tags": [ "Analytics" ], "x-thesauros-scopes": [ "read", "partner:read" ], "x-thesauros-public": false, "x-thesauros-handler": "AnalyticsController.uplift" } }, "/api/v1/analytics/decisions": { "get": { "description": "Scope: `partner:read` only — the caller sees decisions on its own positions. Paginated: pass `limit` and the previous page’s `meta.next_cursor` as `cursor`.", "operationId": "AnalyticsController_decisions", "parameters": [ { "name": "asset", "required": false, "in": "query", "description": "Filter by asset symbol.", "schema": { "type": "string", "enum": [ "USDC", "USDT0" ] } }, { "name": "user_id", "required": false, "in": "query", "description": "Restrict to one end-user (usr_…).", "schema": { "example": "usr_seed_nova", "type": "string" } }, { "name": "position_id", "required": false, "in": "query", "description": "Restrict to one position (pos_…).", "schema": { "example": "pos_seed_alpha", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Page size, 1–200 (default 50).", "schema": { "example": 50, "type": "string" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor from the previous page’s meta.next_cursor. Omit for the first page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DecisionDto" } }, "meta": { "$ref": "#/components/schemas/ListMetaDto" } } } } } }, "401": { "description": "Missing or invalid API key." }, "403": { "description": "Key is not partner-scoped." }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Executed routing and rebalance decisions with rationale", "tags": [ "Analytics" ], "x-thesauros-scopes": [ "read", "partner:read" ], "x-thesauros-public": false, "x-thesauros-handler": "AnalyticsController.decisions" } }, "/api/v1/analytics/advisor": { "get": { "description": "Scope: `partner:read` only — the portfolio section reflects the calling partner’s positions.", "operationId": "AnalyticsController_advisor", "parameters": [ { "name": "asset", "required": false, "in": "query", "description": "Filter by asset symbol.", "schema": { "type": "string", "enum": [ "USDC", "USDT0" ] } } ], "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string", "example": "object" }, "data": { "$ref": "#/components/schemas/AdvisorDto" } } } } } }, "401": { "description": "Missing or invalid API key." }, "403": { "description": "Key is not partner-scoped." }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Current recommendations with rationale", "tags": [ "Analytics" ], "x-thesauros-scopes": [ "read", "partner:read" ], "x-thesauros-public": false, "x-thesauros-handler": "AnalyticsController.advisor" } }, "/api/v1/webhooks": { "post": { "description": "The signing secret is returned in full exactly once, at creation.", "operationId": "WebhooksController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookInputDto" } } } }, "responses": { "201": { "description": "Created. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "required": [ "object", "data" ] } } } }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Register a webhook endpoint", "tags": [ "Webhooks" ], "x-thesauros-scopes": [ "partner:read" ], "x-thesauros-public": false, "x-thesauros-handler": "WebhooksController.create" }, "get": { "operationId": "WebhooksController_list", "parameters": [], "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } } }, "required": [ "object", "data" ] } } } }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "List webhook endpoints (secrets masked)", "tags": [ "Webhooks" ], "x-thesauros-scopes": [ "partner:read" ], "x-thesauros-public": false, "x-thesauros-handler": "WebhooksController.list" } }, "/api/v1/webhooks/events": { "get": { "operationId": "WebhooksController_listEvents", "parameters": [], "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/WebhookEventTypes" } }, "required": [ "object", "data" ] } } } }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Supported webhook event types", "tags": [ "Webhooks" ], "x-thesauros-scopes": [ "partner:read" ], "x-thesauros-public": false, "x-thesauros-handler": "WebhooksController.listEvents" } }, "/api/v1/webhooks/deliveries": { "get": { "operationId": "WebhooksController_deliveries", "parameters": [ { "name": "webhook_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } }, "required": [ "object", "data" ] } } } }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Recent delivery attempts, newest first", "tags": [ "Webhooks" ], "x-thesauros-scopes": [ "partner:read" ], "x-thesauros-public": false, "x-thesauros-handler": "WebhooksController.deliveries" } }, "/api/v1/webhooks/{id}": { "patch": { "operationId": "WebhooksController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookInputDto" } } } }, "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "required": [ "object", "data" ] } } } }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Update a webhook endpoint", "tags": [ "Webhooks" ], "x-thesauros-scopes": [ "partner:read" ], "x-thesauros-public": false, "x-thesauros-handler": "WebhooksController.update" }, "delete": { "operationId": "WebhooksController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/DeletedResource" } }, "required": [ "object", "data" ] } } } }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Delete a webhook endpoint", "tags": [ "Webhooks" ], "x-thesauros-scopes": [ "partner:read" ], "x-thesauros-public": false, "x-thesauros-handler": "WebhooksController.remove" } }, "/api/v1/webhooks/{id}/test": { "post": { "operationId": "WebhooksController_test", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Created. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/WebhookDelivery" } }, "required": [ "object", "data" ] } } } }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Send a signed test event to the endpoint and record the delivery", "tags": [ "Webhooks" ], "x-thesauros-scopes": [ "partner:read" ], "x-thesauros-public": false, "x-thesauros-handler": "WebhooksController.test" } }, "/api/v1/usage": { "get": { "operationId": "UsageController_getUsage", "parameters": [ { "name": "range", "required": false, "in": "query", "schema": { "enum": [ "24h", "7d", "30d" ], "type": "string" } } ], "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/UsageReport" } }, "required": [ "object", "data" ] } } } }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Request/latency time series + totals from real request logs", "tags": [ "Usage" ], "x-thesauros-scopes": [ "partner:read" ], "x-thesauros-public": false, "x-thesauros-handler": "UsageController.getUsage" } }, "/api/v1/users": { "post": { "operationId": "UsersController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserInputDto" } } } }, "responses": { "201": { "description": "Created. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/UserRecord" } }, "required": [ "object", "data" ] } } } }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Create an attributed end-user", "tags": [ "Users" ], "x-thesauros-scopes": [ "partner:read" ], "x-thesauros-public": false, "x-thesauros-handler": "UsersController.create" } }, "/api/v1/users/{id}/ledger": { "get": { "operationId": "UsersController_ledger", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/UserLedgerEvent" } } }, "required": [ "object", "data" ] } } } }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Per-user event ledger (deposits, withdrawals, rebalances, yield accruals)", "tags": [ "Users" ], "x-thesauros-scopes": [ "partner:read" ], "x-thesauros-public": false, "x-thesauros-handler": "UsersController.ledger" } }, "/api/v1/status": { "get": { "operationId": "StatusController_getStatus", "parameters": [], "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/ServiceStatus" } }, "required": [ "object", "data" ] } } } }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "summary": "Component health (public, no auth)", "tags": [ "Status" ], "x-thesauros-scopes": [], "x-thesauros-public": true, "x-thesauros-handler": "StatusController.getStatus" } }, "/api/v1/reconciliation/balances": { "get": { "description": "Scope: `partner:read` only. Active positions of the calling partner, grouped by user and asset.", "operationId": "ReconciliationController_balances", "parameters": [ { "name": "asset", "required": false, "in": "query", "description": "Filter by asset symbol.", "schema": { "type": "string", "enum": [ "USDC", "USDT0" ] } }, { "name": "user_id", "required": false, "in": "query", "description": "Restrict to one end-user (usr_…).", "schema": { "example": "usr_seed_nova", "type": "string" } }, { "name": "position_id", "required": false, "in": "query", "description": "Restrict to one position (pos_…).", "schema": { "example": "pos_seed_alpha", "type": "string" } } ], "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BalanceDto" } } } } } } }, "401": { "description": "Missing or invalid API key." }, "403": { "description": "Key is not partner-scoped." }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Recorded balances by user and asset", "tags": [ "Reconciliation" ], "x-thesauros-scopes": [ "read", "partner:read" ], "x-thesauros-public": false, "x-thesauros-handler": "ReconciliationController.balances" } }, "/api/v1/reconciliation/ledger": { "get": { "description": "Scope: `partner:read` only. Deposits, withdrawals, closes and an accrual row per position (`settled: false` while the position is open). Paginated via `limit`/`cursor`.", "operationId": "ReconciliationController_ledger", "parameters": [ { "name": "asset", "required": false, "in": "query", "description": "Filter by asset symbol.", "schema": { "type": "string", "enum": [ "USDC", "USDT0" ] } }, { "name": "user_id", "required": false, "in": "query", "description": "Restrict to one end-user (usr_…).", "schema": { "example": "usr_seed_nova", "type": "string" } }, { "name": "position_id", "required": false, "in": "query", "description": "Restrict to one position (pos_…).", "schema": { "example": "pos_seed_alpha", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Page size, 1–200 (default 50).", "schema": { "example": 50, "type": "string" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor from the previous page’s meta.next_cursor. Omit for the first page.", "schema": { "type": "string" } }, { "name": "type", "required": false, "in": "query", "description": "Filter to one movement type.", "schema": { "type": "string", "enum": [ "deposit", "withdraw", "close", "accrual" ] } } ], "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/LedgerEntryDto" } }, "meta": { "$ref": "#/components/schemas/ListMetaDto" } } } } } }, "401": { "description": "Missing or invalid API key." }, "403": { "description": "Key is not partner-scoped." }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Movement rows with running balance", "tags": [ "Reconciliation" ], "x-thesauros-scopes": [ "read", "partner:read" ], "x-thesauros-public": false, "x-thesauros-handler": "ReconciliationController.ledger" } }, "/api/v1/reconciliation/snapshots": { "get": { "description": "Scope: `partner:read` only. One row per day in [`from`, `to`] (default: trailing 30 days).", "operationId": "ReconciliationController_snapshots", "parameters": [ { "name": "asset", "required": false, "in": "query", "description": "Filter by asset symbol.", "schema": { "type": "string", "enum": [ "USDC", "USDT0" ] } }, { "name": "from", "required": false, "in": "query", "description": "Window start, ISO 8601. Default: 29 days before `to`.", "schema": { "example": "2026-07-01", "type": "string" } }, { "name": "to", "required": false, "in": "query", "description": "Window end, ISO 8601. Default: now.", "schema": { "example": "2026-08-01", "type": "string" } } ], "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BalanceSnapshotDto" } } } } } } }, "401": { "description": "Missing or invalid API key." }, "403": { "description": "Key is not partner-scoped." }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Daily balance snapshots for period accounting", "tags": [ "Reconciliation" ], "x-thesauros-scopes": [ "read", "partner:read" ], "x-thesauros-public": false, "x-thesauros-handler": "ReconciliationController.snapshots" } }, "/api/v1/reconciliation/report": { "get": { "description": "Scope: admin `read` only (protocol-wide by design). Needs `MONITOR_API_URL` configured — otherwise returns the same shape with `status: \"unavailable\"` and the chain side nulled.", "operationId": "ReconciliationController_report", "parameters": [ { "name": "asset", "required": false, "in": "query", "description": "Filter by asset symbol.", "schema": { "type": "string", "enum": [ "USDC", "USDT0" ] } } ], "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string", "example": "object" }, "data": { "$ref": "#/components/schemas/ReconciliationReportDto" } } } } } }, "401": { "description": "Missing or invalid API key." }, "403": { "description": "Partner keys cannot read the protocol-wide report." }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Recorded accounting vs observed on-chain balances", "tags": [ "Reconciliation" ], "x-thesauros-scopes": [ "read" ], "x-thesauros-public": false, "x-thesauros-handler": "ReconciliationController.report" } }, "/api/v1/vaults": { "get": { "description": "Scope: `read` or `partner:read` (protocol-level). `apy_7d_avg`/`apy_30d_avg` come from recorded hourly observations and are null until enough exist.", "operationId": "VaultsController_list", "parameters": [ { "name": "asset", "required": false, "in": "query", "description": "Filter by asset symbol.", "schema": { "type": "string", "enum": [ "USDC", "USDT0" ] } }, { "name": "network", "required": false, "in": "query", "description": "Filter to one chain. Omit for every chain — no server state is switched.", "schema": { "type": "string", "enum": [ "arbitrum", "base", "plasma", "monad", "mainnet" ] } } ], "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/VaultDto" } } } } } } }, "401": { "description": "Missing or invalid API key." }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Vaults with observed trailing APY averages and risk tier", "tags": [ "Vaults" ], "x-thesauros-scopes": [ "read", "partner:read" ], "x-thesauros-public": false, "x-thesauros-handler": "VaultsController.list" } }, "/api/v1/apy/history": { "get": { "description": "Scope: `read` or `partner:read` (protocol-level). `vault` is required; `days` is 1-90 (default 7). Points are the recorded hourly observations, oldest first.", "operationId": "VaultsController_apyHistory", "parameters": [ { "name": "vault", "required": false, "in": "query", "description": "Vault id. Required.", "schema": { "example": "vault_aave_base_usdc", "type": "string" } }, { "name": "days", "required": false, "in": "query", "description": "Window in days, 1-90 (default 7).", "schema": { "minimum": 1, "maximum": 90, "example": 7, "type": "number" } } ], "responses": { "200": { "description": "Success. The resource is returned inside data.", "headers": { "X-Request-Id": { "description": "Identifier for this response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string", "example": "object" }, "data": { "$ref": "#/components/schemas/ApyHistoryDto" } } } } } }, "401": { "description": "Missing or invalid API key." }, "default": { "description": "Request failed. Inspect error.code and error.message; see the error guide for recovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearer": [] } ], "summary": "Observed APY series for one vault", "tags": [ "Vaults" ], "x-thesauros-scopes": [ "read", "partner:read" ], "x-thesauros-public": false, "x-thesauros-handler": "VaultsController.apyHistory" } } }, "info": { "title": "Thesauros Partner API", "description": "Partner Attribution v1 & Partner API v1.\n\nEvery response is enveloped: `{object, data}` for a single resource, `{object:\"list\", data, meta}` for collections. Paginated lists take `?limit=` and `?cursor=`, where the cursor is the previous page's `meta.next_cursor` — omit it for the first page.", "version": "1.0", "contact": {} }, "tags": [], "servers": [], "components": { "securitySchemes": { "bearer": { "scheme": "bearer", "bearerFormat": "JWT", "type": "http", "description": "API key (tsk_test_...)" } }, "schemas": { "CreateKeyInputDto": { "type": "object", "properties": { "label": { "type": "string", "example": "My integration key" }, "environment": { "type": "string", "enum": [ "test" ], "default": "test", "description": "Only test keys can be created via API." }, "scopes": { "type": "string", "example": [ "read" ], "enum": [ "read", "write", "partner:read", "partner:admin" ], "description": "Permitted scopes. Wildcards and keys:admin are not assignable." }, "partner_id": { "type": "string", "example": "ptn_seed_acme", "description": "Bind key to a partner for scoped access" } }, "required": [ "label" ] }, "ApiKeyOutputDto": { "type": "object", "properties": { "id": { "type": "string", "example": "key_a1b2c3d4e5f60718" }, "object": { "type": "string", "example": "api_key" }, "label": { "type": "string", "example": "My integration key" }, "secret": { "type": "string", "example": "tsk_test_...a1b2", "description": "Masked secret (full shown only on creation)" }, "prefix": { "type": "string", "example": "tsk_test_My" }, "environment": { "type": "string", "example": "test", "enum": [ "test", "live" ] }, "scopes": { "example": [ "read", "write" ], "type": "array", "items": { "type": "string" } }, "partner_id": { "type": "string", "example": "ptn_seed_acme", "nullable": true }, "created_at": { "type": "string", "example": "2026-07-28T12:00:00.000Z" }, "last_used_at": { "type": "string", "nullable": true }, "revoked": { "type": "boolean", "example": false } }, "required": [ "id", "object", "label", "secret", "prefix", "environment", "scopes", "created_at", "revoked" ] }, "CreatePartnerInputDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Acme Wallet" }, "slug": { "type": "string", "example": "acme-wallet", "description": "URL-friendly slug (auto-generated from name if omitted)" }, "contact_email": { "type": "string", "example": "dev@acmewallet.io" }, "webhook_url": { "type": "string", "example": "https://acme.io/webhooks/thesauros" }, "revenue_share_pct": { "type": "number", "example": 0.15, "description": "Revenue share percentage (0–1)", "default": 0.15 }, "metadata": { "type": "object", "example": { "tier": "enterprise" } } }, "required": [ "name" ] }, "PartnerOutputDto": { "type": "object", "properties": { "id": { "type": "string", "example": "ptn_a1b2c3d4e5f60718" }, "object": { "type": "string", "example": "partner" }, "name": { "type": "string", "example": "Acme Wallet" }, "slug": { "type": "string", "example": "acme-wallet" }, "contact_email": { "type": "string", "example": "dev@acmewallet.io", "nullable": true }, "webhook_url": { "type": "string", "nullable": true }, "revenue_share_pct": { "type": "number", "example": 0.15 }, "status": { "type": "string", "example": "active", "enum": [ "active", "disabled" ] }, "metadata": { "type": "object", "example": {} }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "name", "slug", "revenue_share_pct", "status", "created_at", "updated_at" ] }, "UpdatePartnerInputDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Acme Wallet" }, "slug": { "type": "string", "example": "acme-wallet", "description": "URL-friendly slug (auto-generated from name if omitted)" }, "contact_email": { "type": "string", "example": "dev@acmewallet.io" }, "webhook_url": { "type": "string", "example": "https://acme.io/webhooks/thesauros" }, "revenue_share_pct": { "type": "number", "example": 0.15, "description": "Revenue share percentage (0–1)", "default": 0.15 }, "metadata": { "type": "object", "example": { "tier": "enterprise" } }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "Disable a partner without deleting (soft-disable). Disabled partners stay in DB for history." } } }, "CreateCampaignInputDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Summer 2026 Launch" }, "slug": { "type": "string", "example": "summer-2026", "description": "Unique within partner" }, "utm_source": { "type": "string", "example": "twitter" }, "utm_medium": { "type": "string", "example": "cpc" } }, "required": [ "name" ] }, "CampaignOutputDto": { "type": "object", "properties": { "id": { "type": "string", "example": "cmp_a1b2c3d4e5f60718" }, "object": { "type": "string", "example": "campaign" }, "partner_id": { "type": "string", "example": "ptn_seed_acme" }, "name": { "type": "string", "example": "Summer 2026 Launch" }, "slug": { "type": "string", "example": "summer-2026" }, "utm_source": { "type": "string", "nullable": true }, "utm_medium": { "type": "string", "nullable": true }, "status": { "type": "string", "example": "active", "enum": [ "active", "paused" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "object", "partner_id", "name", "slug", "status", "created_at", "updated_at" ] }, "UpdateCampaignInputDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Summer 2026 Launch" }, "slug": { "type": "string", "example": "summer-2026", "description": "Unique within partner" }, "utm_source": { "type": "string", "example": "twitter" }, "utm_medium": { "type": "string", "example": "cpc" }, "status": { "type": "string", "enum": [ "active", "disabled" ], "description": "Disable a campaign without deleting (soft-disable)." } } }, "SummaryUsersDto": { "type": "object", "properties": { "total": { "type": "number", "example": 2 } }, "required": [ "total" ] }, "SummaryDepositsDto": { "type": "object", "properties": { "total": { "type": "number", "example": 85000 }, "count": { "type": "number", "example": 3 } }, "required": [ "total", "count" ] }, "TvlBreakdownDto": { "type": "object", "properties": { "asset": { "type": "string", "example": "USDC" }, "tvl": { "type": "number", "example": 75420.5 }, "positions": { "type": "number", "example": 2 } }, "required": [ "asset", "tvl", "positions" ] }, "SummaryTvlDto": { "type": "object", "properties": { "total": { "type": "number", "example": 85420.5 }, "breakdown": { "type": "array", "items": { "$ref": "#/components/schemas/TvlBreakdownDto" } } }, "required": [ "total", "breakdown" ] }, "SummaryYieldDto": { "type": "object", "properties": { "total": { "type": "number", "example": 420.5 } }, "required": [ "total" ] }, "SummaryPointsDto": { "type": "object", "properties": { "total": { "type": "number", "example": 0 } }, "required": [ "total" ] }, "SummaryRevenueDto": { "type": "object", "properties": { "revenue_share_pct": { "type": "number", "example": 0.15 }, "annual_partner_revenue": { "type": "number", "example": 72.31 }, "daily_partner_revenue": { "type": "number", "example": 0.198 } }, "required": [ "revenue_share_pct", "annual_partner_revenue", "daily_partner_revenue" ] }, "PartnerSummaryOutputDto": { "type": "object", "properties": { "object": { "type": "string", "example": "partner_summary" }, "partner": { "type": "object" }, "users": { "$ref": "#/components/schemas/SummaryUsersDto" }, "deposits": { "$ref": "#/components/schemas/SummaryDepositsDto" }, "tvl": { "$ref": "#/components/schemas/SummaryTvlDto" }, "yield": { "$ref": "#/components/schemas/SummaryYieldDto" }, "points": { "$ref": "#/components/schemas/SummaryPointsDto" }, "revenue": { "$ref": "#/components/schemas/SummaryRevenueDto" }, "as_of": { "type": "string" } }, "required": [ "object", "partner", "users", "deposits", "tvl", "yield", "points", "revenue", "as_of" ] }, "RevenueTimescaleDto": { "type": "object", "properties": { "yield": { "type": "number", "example": 4820 }, "protocol_fees": { "type": "number", "example": 482 }, "partner_revenue": { "type": "number", "example": 72.3 } }, "required": [ "yield", "protocol_fees", "partner_revenue" ] }, "RevenueShareOutputDto": { "type": "object", "properties": { "object": { "type": "string", "example": "revenue_share" }, "partner_id": { "type": "string", "example": "ptn_seed_acme" }, "partner_name": { "type": "string", "example": "Acme Wallet" }, "revenue_share_pct": { "type": "number", "example": 0.15 }, "protocol_fee_rate": { "type": "number", "example": 0.1 }, "tvl": { "type": "number", "example": 85420.5 }, "protocol_blend_apy": { "type": "number", "example": 0.0565, "description": "Protocol-wide allocation-weighted APY across all active Thesauros vaults. Identical for every partner — only `tvl` and `revenue_share_pct` are partner-specific." }, "annual": { "$ref": "#/components/schemas/RevenueTimescaleDto" }, "daily": { "$ref": "#/components/schemas/RevenueTimescaleDto" }, "as_of": { "type": "string" } }, "required": [ "object", "partner_id", "partner_name", "revenue_share_pct", "protocol_fee_rate", "tvl", "protocol_blend_apy", "annual", "daily", "as_of" ] }, "SignalDto": { "type": "object", "properties": { "object": { "type": "string", "example": "signal" }, "vault_id": { "type": "string", "example": "vault_plasma_usdt0" }, "name": { "type": "string", "example": "Thesauros USDT0 Vault" }, "provider": { "type": "string", "example": "morpho" }, "asset": { "type": "string", "enum": [ "USDC", "USDT0" ], "example": "USDT0" }, "chain": { "type": "string", "example": "plasma" }, "risk_tier": { "type": "string", "enum": [ "bluechip", "core", "opportunistic" ], "example": "core" }, "apy": { "type": "number", "example": 0.076, "description": "Current APY as a fraction (0.076 = 7.6%)." }, "volatility": { "type": "number", "nullable": true, "example": 0.0012, "description": "Stddev of observed APY. null while `insufficient_history` is true — withheld rather than estimated." }, "trend_slope_bps_day": { "type": "number", "nullable": true, "example": 3.4, "description": "Trend in bps/day. null while `insufficient_history` is true — withheld rather than estimated." }, "forecast_apy": { "type": "number", "nullable": true, "example": 0.079, "description": "7-day extrapolation. null while `insufficient_history` is true — withheld rather than estimated." }, "risk_factor": { "type": "number", "example": 0.92, "description": "Risk multiplier implied by risk_tier." }, "risk_adjusted_apy": { "type": "number", "example": 0.0699, "description": "apy * risk_factor - 0.5 * volatility." }, "observations": { "type": "number", "example": 6, "description": "Hourly APY snapshots behind these statistics." }, "insufficient_history": { "type": "boolean", "example": false, "description": "True when fewer than 3 observations exist." }, "rank": { "type": "number", "example": 1, "description": "1 = best risk-adjusted venue." }, "recommendation": { "type": "string", "enum": [ "overweight", "neutral", "underweight" ], "example": "overweight" } }, "required": [ "object", "vault_id", "name", "provider", "asset", "chain", "risk_tier", "apy", "volatility", "trend_slope_bps_day", "forecast_apy", "risk_factor", "risk_adjusted_apy", "observations", "insufficient_history", "rank", "recommendation" ] }, "RegimePerAssetDto": { "type": "object", "properties": { "asset": { "type": "string", "enum": [ "USDC", "USDT0" ] }, "regime": { "type": "string", "enum": [ "rising", "falling", "volatile", "stable", "unknown" ], "example": "stable" }, "blend_apy": { "type": "number", "nullable": true, "example": 0.0526, "description": "Allocation-weighted blend, latest observation." }, "trend_slope_bps_day": { "type": "number", "nullable": true, "example": -0.8 }, "volatility": { "type": "number", "nullable": true, "example": 0.0009 }, "observations": { "type": "number", "example": 12 } }, "required": [ "asset", "regime", "blend_apy", "trend_slope_bps_day", "volatility", "observations" ] }, "RegimeDto": { "type": "object", "properties": { "object": { "type": "string", "example": "regime" }, "as_of": { "type": "string", "example": "2026-08-24T10:00:00.000Z" }, "regime": { "type": "string", "enum": [ "rising", "falling", "volatile", "stable", "unknown" ], "description": "Most cautious classification across assets; \"unknown\" until enough history exists." }, "description": { "type": "string", "example": "Rates are range-bound; optimize on risk-adjusted carry and low turnover." }, "per_asset": { "type": "array", "items": { "$ref": "#/components/schemas/RegimePerAssetDto" } } }, "required": [ "object", "as_of", "regime", "description", "per_asset" ] }, "UpliftTotalsDto": { "type": "object", "properties": { "principal": { "type": "number", "example": 85000 }, "current_value": { "type": "number", "example": 85618.06 }, "aave_baseline": { "type": "number", "example": 75452.04 }, "hold_baseline": { "type": "number", "example": 85618.06 }, "uplift_vs_aave": { "type": "number", "example": 74.46 }, "uplift_vs_hold": { "type": "number", "example": 0 }, "uplift_vs_aave_pct": { "type": "number", "example": 0.0987 }, "baseline_coverage": { "type": "number", "example": 0.6667, "description": "Share of positions whose asset has a baseline venue; the rest are excluded from baseline totals." } }, "required": [ "principal", "current_value", "aave_baseline", "hold_baseline", "uplift_vs_aave", "uplift_vs_hold", "uplift_vs_aave_pct", "baseline_coverage" ] }, "UpliftRowDto": { "type": "object", "properties": { "object": { "type": "string", "example": "uplift_row" }, "position_id": { "type": "string", "example": "pos_seed_alpha" }, "user_id": { "type": "string", "nullable": true, "example": "usr_seed_nova" }, "asset": { "type": "string", "enum": [ "USDC", "USDT0" ] }, "vault_id": { "type": "string", "example": "vault_aave_base_usdc" }, "principal": { "type": "number", "example": 25000 }, "current_value": { "type": "number", "example": 25342.19 }, "apy": { "type": "number", "example": 0.052 }, "aave_baseline": { "type": "number", "nullable": true, "example": 25180.4, "description": "Value under the passive baseline venue. null when the asset has no baseline venue." }, "baseline_provider": { "type": "string", "example": "aave", "description": "Baseline venue provider (ANALYTICS_BASELINE_PROVIDER)." }, "baseline_apy": { "type": "number", "nullable": true, "example": 0.052 }, "hold_baseline": { "type": "number", "example": 25342.19, "description": "Value had the position stayed in its origin vault." }, "uplift_vs_aave": { "type": "number", "nullable": true, "example": 161.79 }, "uplift_vs_hold": { "type": "number", "example": 0 }, "realized_uplift": { "type": "number", "nullable": true, "example": 161.79, "description": "Accrued so far vs the baseline." }, "projected_uplift_annual": { "type": "number", "nullable": true, "example": 800, "description": "Today's APY spread annualised over principal." } }, "required": [ "object", "position_id", "user_id", "asset", "vault_id", "principal", "current_value", "apy", "aave_baseline", "baseline_provider", "baseline_apy", "hold_baseline", "uplift_vs_aave", "uplift_vs_hold", "realized_uplift", "projected_uplift_annual" ] }, "UpliftDto": { "type": "object", "properties": { "object": { "type": "string", "example": "uplift" }, "as_of": { "type": "string" }, "scope": { "type": "string", "example": "partner:ptn_seed_acme" }, "totals": { "$ref": "#/components/schemas/UpliftTotalsDto" }, "positions": { "type": "array", "items": { "$ref": "#/components/schemas/UpliftRowDto" } } }, "required": [ "object", "as_of", "scope", "totals", "positions" ] }, "DecisionAlternativeDto": { "type": "object", "properties": { "vault_id": { "type": "string", "example": "vault_morpho_base_usdc" }, "name": { "type": "string", "example": "Morpho Blue USDC Yield" }, "provider": { "type": "string", "example": "morpho" }, "apy": { "type": "number", "example": 0.068 }, "risk_tier": { "type": "string", "example": "core" } }, "required": [ "vault_id", "name", "provider", "apy", "risk_tier" ] }, "DecisionDto": { "type": "object", "properties": { "id": { "type": "string", "example": "dec_evt_seed_alpha_dep" }, "object": { "type": "string", "example": "decision" }, "at": { "type": "string" }, "position_id": { "type": "string", "example": "pos_seed_alpha" }, "user_id": { "type": "string", "nullable": true, "example": "usr_seed_nova" }, "asset": { "type": "string", "enum": [ "USDC", "USDT0" ] }, "type": { "type": "string", "enum": [ "initial_routing", "rebalance" ] }, "from_vault": { "type": "string", "nullable": true, "description": "null for initial_routing." }, "to_vault": { "type": "string", "example": "vault_aave_base_usdc" }, "apy_before": { "type": "number", "nullable": true, "example": 0.052 }, "apy_after": { "type": "number", "nullable": true, "example": 0.068 }, "expected_uplift_bps": { "type": "number", "nullable": true, "example": 160, "description": "apy_after - apy_before, in bps." }, "reason": { "type": "string", "nullable": true, "example": "rate_spread" }, "alternatives": { "description": "Venues available for this asset at read time.", "type": "array", "items": { "$ref": "#/components/schemas/DecisionAlternativeDto" } }, "rationale": { "type": "string", "example": "Routed USDC deposit to Aave V3 USDC Core at 5.20%." }, "status": { "type": "string", "example": "executed" } }, "required": [ "id", "object", "at", "position_id", "user_id", "asset", "type", "from_vault", "to_vault", "apy_before", "apy_after", "expected_uplift_bps", "alternatives", "rationale", "status" ] }, "ListMetaDto": { "type": "object", "properties": { "total": { "type": "number", "example": 42, "description": "Total rows matching the query, across all pages." }, "limit": { "type": "number", "example": 50, "description": "Page size in effect (1-200)." }, "has_more": { "type": "boolean", "example": true }, "next_cursor": { "type": "string", "nullable": true, "example": "bzo1MA", "description": "Pass back as ?cursor= for the next page. null on the last page." } }, "required": [ "total", "limit", "has_more", "next_cursor" ] }, "AdvisorOpportunityDto": { "type": "object", "properties": { "vault_id": { "type": "string" }, "name": { "type": "string" }, "asset": { "type": "string", "enum": [ "USDC", "USDT0" ] }, "risk_adjusted_apy": { "type": "number", "example": 0.0699 }, "forecast_apy": { "type": "number", "nullable": true, "example": 0.079 }, "recommendation": { "type": "string", "enum": [ "overweight", "neutral", "underweight" ] } }, "required": [ "vault_id", "name", "asset", "risk_adjusted_apy", "forecast_apy", "recommendation" ] }, "AdvisorPortfolioDto": { "type": "object", "properties": { "current_value": { "type": "number", "example": 85618.06 }, "uplift_vs_aave": { "type": "number", "example": 74.46 }, "uplift_vs_aave_pct": { "type": "number", "example": 0.0987 }, "positions": { "type": "number", "example": 3 } }, "required": [ "current_value", "uplift_vs_aave", "uplift_vs_aave_pct", "positions" ] }, "AdvisorDto": { "type": "object", "properties": { "object": { "type": "string", "example": "advisor" }, "as_of": { "type": "string" }, "headline": { "type": "string", "example": "Routing is beating the passive baseline; hold the strategy and keep monitoring the regime." }, "regime": { "type": "string", "enum": [ "rising", "falling", "volatile", "stable", "unknown" ] }, "bullets": { "description": "Plain-language findings, each traceable to a computed figure.", "type": "array", "items": { "type": "string" } }, "top_opportunities": { "type": "array", "items": { "$ref": "#/components/schemas/AdvisorOpportunityDto" } }, "portfolio": { "$ref": "#/components/schemas/AdvisorPortfolioDto" }, "disclaimer": { "type": "string" } }, "required": [ "object", "as_of", "headline", "regime", "bullets", "top_opportunities", "portfolio", "disclaimer" ] }, "CreateWebhookInputDto": { "type": "object", "properties": { "url": { "type": "string", "example": "https://partner.example.com/webhooks/thesauros" }, "events": { "example": [ "position.opened", "position.closed" ], "description": "Event types, or [\"*\"] for all. Default: [\"*\"].", "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean", "default": true } }, "required": [ "url" ] }, "UpdateWebhookInputDto": { "type": "object", "properties": { "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" } } }, "CreateUserInputDto": { "type": "object", "properties": { "external_id": { "type": "string", "example": "customer-42", "description": "Your customer id — unique per user." }, "label": { "type": "string", "example": "Ada L." }, "email": { "type": "string", "example": "ada@example.com" }, "wallets": { "example": [ "0x0000000000000000000000000000000000000001" ], "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object" } }, "required": [ "external_id" ] }, "BalanceDto": { "type": "object", "properties": { "object": { "type": "string", "example": "balance" }, "user_id": { "type": "string", "nullable": true, "example": "usr_seed_nova" }, "asset": { "type": "string", "enum": [ "USDC", "USDT0" ] }, "principal": { "type": "number", "example": 75000 }, "current_value": { "type": "number", "example": 75526.5 }, "accrued_yield": { "type": "number", "example": 526.5 }, "positions": { "type": "number", "example": 2, "description": "Active positions folded into this row." } }, "required": [ "object", "user_id", "asset", "principal", "current_value", "accrued_yield", "positions" ] }, "LedgerEntryDto": { "type": "object", "properties": { "id": { "type": "string", "example": "led_evt_seed_alpha_dep" }, "object": { "type": "string", "example": "ledger_entry" }, "user_id": { "type": "string", "nullable": true, "example": "usr_seed_nova" }, "position_id": { "type": "string", "example": "pos_seed_alpha" }, "wallet": { "type": "string", "example": "0x8a3f1c9e2b7d4065a1c8e9f0b2d4c6a8e1f3b5d7" }, "asset": { "type": "string", "enum": [ "USDC", "USDT0" ] }, "vault_id": { "type": "string", "example": "vault_aave_base_usdc" }, "at": { "type": "string", "example": "2026-06-20T12:00:00.000Z" }, "type": { "type": "string", "enum": [ "deposit", "withdraw", "close", "accrual" ] }, "amount": { "type": "number", "example": 25000, "description": "Signed: withdrawals and closes are negative." }, "balance_after": { "type": "number", "example": 25000, "description": "Running balance for this position after the row." }, "settled": { "type": "boolean", "example": true, "description": "false for accrual on an open position — unrealized until it settles on-chain." }, "ref": { "type": "string", "example": "evt_seed_alpha_dep", "description": "Source event id." } }, "required": [ "id", "object", "user_id", "position_id", "wallet", "asset", "vault_id", "at", "type", "amount", "balance_after", "settled", "ref" ] }, "SnapshotAssetDto": { "type": "object", "properties": { "asset": { "type": "string", "enum": [ "USDC", "USDT0" ] }, "principal": { "type": "number", "example": 75000 }, "value": { "type": "number", "example": 75526.5 }, "accrued": { "type": "number", "example": 526.5 } }, "required": [ "asset", "principal", "value", "accrued" ] }, "BalanceSnapshotDto": { "type": "object", "properties": { "object": { "type": "string", "example": "balance_snapshot" }, "date": { "type": "string", "example": "2026-08-24" }, "t": { "type": "number", "example": 1787918400000, "description": "Epoch ms of the day boundary." }, "principal": { "type": "number", "example": 85000 }, "value": { "type": "number", "example": 85618.06 }, "accrued": { "type": "number", "example": 618.06 }, "positions": { "type": "number", "example": 3 }, "users": { "type": "number", "example": 2 }, "by_asset": { "type": "array", "items": { "$ref": "#/components/schemas/SnapshotAssetDto" } } }, "required": [ "object", "date", "t", "principal", "value", "accrued", "positions", "users", "by_asset" ] }, "ReconciliationRowDto": { "type": "object", "properties": { "asset": { "type": "string", "enum": [ "USDC", "USDT0" ] }, "recorded": { "type": "number", "example": 75526.5 }, "onchain": { "type": "number", "nullable": true, "example": 75530.1, "description": "null when monitoring could not supply this asset." }, "discrepancy": { "type": "number", "nullable": true, "example": -3.6 }, "diff_bps": { "type": "number", "nullable": true, "example": -0.48, "description": "Discrepancy in basis points of the chain balance." }, "observed": { "type": "boolean", "example": true } }, "required": [ "asset", "recorded", "onchain", "discrepancy", "diff_bps", "observed" ] }, "ReconciliationReportDto": { "type": "object", "properties": { "object": { "type": "string", "example": "reconciliation" }, "as_of": { "type": "string" }, "scope": { "type": "string", "example": "protocol" }, "status": { "type": "string", "enum": [ "reconciled", "mismatch", "unavailable" ], "description": "\"unavailable\" when MONITOR_API_URL is unset or monitoring is unreachable." }, "unavailable_reason": { "type": "string", "example": "MONITOR_API_URL is not configured" }, "recorded_total": { "type": "number", "example": 85618.06 }, "onchain_total": { "type": "number", "nullable": true, "example": 85620.4 }, "discrepancy": { "type": "number", "nullable": true, "example": -2.34 }, "diff_bps": { "type": "number", "nullable": true, "example": -0.27 }, "tolerance_bps": { "type": "number", "example": 10, "description": "RECONCILIATION_TOLERANCE_BPS." }, "positions": { "type": "number", "example": 3 }, "observed_at": { "type": "string", "nullable": true, "example": "2026-08-24T10:00:00.000Z" }, "observed_networks": { "example": [ "arbitrumRebalancer", "plasma" ], "type": "array", "items": { "type": "string" } }, "breakdown": { "type": "array", "items": { "$ref": "#/components/schemas/ReconciliationRowDto" } }, "open_discrepancies": { "description": "Rows past the tolerance.", "type": "array", "items": { "$ref": "#/components/schemas/ReconciliationRowDto" } } }, "required": [ "object", "as_of", "scope", "status", "recorded_total", "onchain_total", "discrepancy", "diff_bps", "tolerance_bps", "positions", "observed_at", "observed_networks", "breakdown", "open_discrepancies" ] }, "VaultDto": { "type": "object", "properties": { "object": { "type": "string", "example": "vault" }, "id": { "type": "string", "example": "vault_aave_base_usdc" }, "name": { "type": "string", "example": "Aave V3 USDC Core" }, "provider": { "type": "string", "example": "aave" }, "asset": { "type": "string", "enum": [ "USDC", "USDT0" ] }, "chain": { "type": "string", "example": "base" }, "apy": { "type": "number", "example": 0.052, "description": "Current APY as a fraction." }, "apy_7d_avg": { "type": "number", "nullable": true, "example": 0.0511, "description": "Mean of observed hourly snapshots over 7 days. null until observations exist." }, "apy_30d_avg": { "type": "number", "nullable": true, "example": 0.0498, "description": "Same over 30 days." }, "tvl_usd": { "type": "number", "example": 48200000 }, "capacity_usd": { "type": "number", "example": 120000000 }, "risk_tier": { "type": "string", "enum": [ "bluechip", "core", "opportunistic" ] }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "allocation_pct": { "type": "number", "example": 0.28 } }, "required": [ "object", "id", "name", "provider", "asset", "chain", "apy", "apy_7d_avg", "apy_30d_avg", "tvl_usd", "capacity_usd", "risk_tier", "status", "allocation_pct" ] }, "ApyHistoryPointDto": { "type": "object", "properties": { "t": { "type": "number", "example": 1787918400000, "description": "Epoch ms of the observation." }, "apy": { "type": "number", "example": 0.052 } }, "required": [ "t", "apy" ] }, "ApyHistoryDto": { "type": "object", "properties": { "object": { "type": "string", "example": "apy_history" }, "vault_id": { "type": "string", "example": "vault_aave_base_usdc" }, "name": { "type": "string", "nullable": true, "example": "Aave V3 USDC Core" }, "asset": { "type": "string", "nullable": true, "enum": [ "USDC", "USDT0" ] }, "chain": { "type": "string", "nullable": true, "example": "base" }, "days": { "type": "number", "example": 7 }, "apy_avg": { "type": "number", "nullable": true, "example": 0.0511, "description": "Mean over the window. null with no observations." }, "observations": { "type": "number", "example": 168 }, "points": { "type": "array", "items": { "$ref": "#/components/schemas/ApyHistoryPointDto" } } }, "required": [ "object", "vault_id", "name", "asset", "chain", "days", "apy_avg", "observations", "points" ] }, "UserRecord": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "user" ] }, "external_id": { "type": "string", "nullable": true }, "label": { "type": "string" }, "email": { "type": "string", "nullable": true }, "wallets": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "object", "external_id", "label", "email", "wallets", "status", "metadata", "created_at", "updated_at" ] }, "UserAttribution": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "user_id": { "type": "string" }, "partner_id": { "type": "string" }, "campaign_id": { "type": "string", "nullable": true }, "source": { "type": "string" }, "attributed_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "object", "user_id", "partner_id", "campaign_id", "source", "attributed_at" ] }, "AttributedUser": { "allOf": [ { "$ref": "#/components/schemas/UserRecord" }, { "type": "object", "properties": { "attribution": { "anyOf": [ { "$ref": "#/components/schemas/UserAttribution" }, { "type": "object", "nullable": true, "enum": [ null ] } ] } }, "required": [ "attribution" ] } ] }, "PartnerCreated": { "type": "object", "properties": { "partner": { "$ref": "#/components/schemas/PartnerOutputDto" }, "api_key": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "secret": { "type": "string", "description": "One-time secret for the new partner. Store it securely." } }, "required": [ "id", "label", "secret" ] } }, "required": [ "partner", "api_key" ] }, "PartnerSummary": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "partner_summary" ] }, "partner": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "name", "slug", "status" ] }, "users": { "type": "object", "properties": { "total": { "type": "integer" } }, "required": [ "total" ] }, "deposits": { "type": "object", "properties": { "total": { "type": "number" }, "count": { "type": "integer" } }, "required": [ "total", "count" ] }, "tvl": { "type": "object", "properties": { "total": { "type": "number" }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string" }, "tvl": { "type": "number" }, "positions": { "type": "integer" } }, "required": [ "asset", "tvl", "positions" ] } } }, "required": [ "total", "breakdown" ] }, "yield": { "type": "object", "properties": { "total": { "type": "number" } }, "required": [ "total" ] }, "points": { "type": "object", "properties": { "total": { "type": "number" } }, "required": [ "total" ] }, "revenue": { "type": "object", "properties": { "revenue_share_pct": { "type": "number" }, "annual_partner_revenue": { "type": "number" }, "daily_partner_revenue": { "type": "number" } }, "required": [ "revenue_share_pct", "annual_partner_revenue", "daily_partner_revenue" ] }, "as_of": { "type": "string", "format": "date-time" } }, "required": [ "object", "partner", "users", "deposits", "tvl", "yield", "points", "revenue", "as_of" ] }, "PartnerDeposits": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "partner_deposits" ] }, "partner_id": { "type": "string" }, "total": { "type": "number" }, "count": { "type": "integer" }, "deposits": { "type": "array", "items": { "type": "object", "properties": { "position_id": { "type": "string" }, "user_id": { "type": "string", "nullable": true }, "wallet": { "type": "string" }, "asset": { "type": "string" }, "principal": { "type": "number" }, "opened_at": { "type": "string", "format": "date-time" } }, "required": [ "position_id", "user_id", "wallet", "asset", "principal", "opened_at" ] } } }, "required": [ "object", "partner_id", "total", "count", "deposits" ] }, "PartnerWithdrawals": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "partner_withdrawals" ] }, "partner_id": { "type": "string" }, "total": { "type": "number" }, "count": { "type": "integer" } }, "required": [ "object", "partner_id", "total", "count" ] }, "PartnerTvl": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "partner_tvl" ] }, "partner_id": { "type": "string" }, "tvl": { "type": "number" }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string" }, "tvl": { "type": "number" }, "positions": { "type": "integer" } }, "required": [ "asset", "tvl", "positions" ] } } }, "required": [ "object", "partner_id", "tvl", "breakdown" ] }, "PartnerYield": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "partner_yield" ] }, "partner_id": { "type": "string" }, "total_yield": { "type": "number" }, "positions": { "type": "array", "items": { "type": "object", "properties": { "position_id": { "type": "string" }, "asset": { "type": "string" }, "principal": { "type": "number" }, "accrued_yield": { "type": "number" }, "apy": { "type": "number", "description": "Annualized rate as a decimal fraction. 0.052 means 5.2%." } }, "required": [ "position_id", "asset", "principal", "accrued_yield", "apy" ] } } }, "required": [ "object", "partner_id", "total_yield", "positions" ] }, "PartnerPoints": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "partner_points" ] }, "partner_id": { "type": "string" }, "total_points": { "type": "number" }, "users": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string" }, "label": { "type": "string" }, "points": { "type": "number" } }, "required": [ "user_id", "label", "points" ] } } }, "required": [ "object", "partner_id", "total_points", "users" ] }, "PartnerPosition": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "position" ] }, "user_id": { "type": "string" }, "wallet": { "type": "string" }, "asset": { "type": "string" }, "chain": { "type": "string" }, "vault_id": { "type": "string" }, "principal": { "type": "number" }, "apy": { "type": "number", "description": "Annualized rate as a decimal fraction. 0.052 means 5.2%." }, "strategy": { "type": "string" }, "status": { "type": "string" }, "last_rebalance_at": { "type": "string", "format": "date-time", "nullable": true }, "withdrawn_total": { "type": "number" }, "opened_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "tx_hash": { "type": "string", "nullable": true }, "partner_id": { "type": "string", "nullable": true }, "campaign_id": { "type": "string", "nullable": true }, "current_value": { "type": "number" }, "accrued_yield": { "type": "number" } }, "required": [ "id", "object", "user_id", "wallet", "asset", "chain", "vault_id", "principal", "apy", "strategy", "status", "last_rebalance_at", "withdrawn_total", "opened_at", "updated_at", "tx_hash", "partner_id", "campaign_id", "current_value", "accrued_yield" ] }, "UserLedgerEvent": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "ledger_entry" ] }, "user_id": { "type": "string" }, "position_id": { "type": "string" }, "asset": { "type": "string", "nullable": true }, "type": { "type": "string" }, "amount": { "type": "number" }, "apy": { "type": "number", "description": "Annualized rate as a decimal fraction. 0.052 means 5.2%.", "nullable": true }, "vault_id": { "type": "string", "nullable": true }, "note": { "type": "string", "nullable": true }, "at": { "type": "string", "format": "date-time" } }, "required": [ "id", "object", "user_id", "position_id", "asset", "type", "amount", "apy", "vault_id", "note", "at" ] }, "YieldHistory": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "yield_history" ] }, "scope": { "type": "string", "enum": [ "protocol" ] }, "asset": { "type": "string" }, "blend_apy": { "type": "number", "description": "Annualized rate as a decimal fraction. 0.052 means 5.2%." }, "observations": { "type": "integer" }, "history": { "type": "array", "items": { "type": "object", "properties": { "t": { "type": "integer", "description": "Unix milliseconds." }, "apy": { "type": "number", "description": "Annualized rate as a decimal fraction. 0.052 means 5.2%." } }, "required": [ "t", "apy" ] } }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "vault_id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" }, "chain": { "type": "string" }, "risk_tier": { "type": "string" }, "apy": { "type": "number", "description": "Annualized rate as a decimal fraction. 0.052 means 5.2%." }, "apy_7d_avg": { "type": "number", "description": "Annualized rate as a decimal fraction. 0.052 means 5.2%.", "nullable": true }, "allocation_pct": { "type": "number", "description": "Percentage points: 25 means 25%." }, "tvl_usd": { "type": "number" } }, "required": [ "vault_id", "name", "provider", "chain", "risk_tier", "apy", "apy_7d_avg", "allocation_pct", "tvl_usd" ] } } }, "required": [ "object", "scope", "asset", "blend_apy", "observations", "history", "breakdown" ] }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "webhook" ] }, "partner_id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "secret": { "type": "string", "description": "Signing secret, returned once at creation; masked on list and update." }, "active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "object", "partner_id", "url", "events", "secret", "active", "created_at" ] }, "WebhookEventTypes": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "webhook_events" ] }, "events": { "type": "array", "items": { "type": "string" } } }, "required": [ "object", "events" ] }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "delivery" ] }, "webhook_id": { "type": "string" }, "partner_id": { "type": "string" }, "url": { "type": "string" }, "event": { "type": "string" }, "payload": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": true } }, "required": [ "id", "type", "created_at", "data" ] }, "signature": { "type": "string" }, "status": { "type": "string", "enum": [ "delivered", "failed" ] }, "attempts": { "type": "integer" }, "at": { "type": "string", "format": "date-time" }, "latency_ms": { "type": "number" } }, "required": [ "id", "object", "webhook_id", "partner_id", "url", "event", "payload", "signature", "status", "attempts", "at", "latency_ms" ] }, "DeletedResource": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "id", "deleted" ] }, "RevokedApiKey": { "type": "object", "properties": { "id": { "type": "string" }, "revoked": { "type": "boolean" } }, "required": [ "id", "revoked" ] }, "UsageReport": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "usage" ] }, "range": { "type": "string", "enum": [ "24h", "7d", "30d" ] }, "totals": { "type": "object", "properties": { "requests": { "type": "integer" }, "errors": { "type": "integer" }, "error_rate": { "type": "number" }, "p50_ms": { "type": "number" }, "p99_ms": { "type": "number" } }, "required": [ "requests", "errors", "error_rate", "p50_ms", "p99_ms" ] }, "series": { "type": "array", "items": { "type": "object", "properties": { "t": { "type": "string", "format": "date-time" }, "requests": { "type": "integer" }, "errors": { "type": "integer" }, "p50_ms": { "type": "number" }, "p99_ms": { "type": "number" } }, "required": [ "t", "requests", "errors", "p50_ms", "p99_ms" ] } }, "top_endpoints": { "type": "array", "items": { "type": "object", "properties": { "endpoint": { "type": "string" }, "requests": { "type": "integer" }, "errors": { "type": "integer" } }, "required": [ "endpoint", "requests", "errors" ] } } }, "required": [ "object", "range", "totals", "series", "top_endpoints" ] }, "ServiceHealth": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "operational", "degraded", "down" ] }, "latency_ms": { "type": "number", "nullable": true }, "detail": { "type": "string" } }, "required": [ "id", "name", "status", "latency_ms" ] }, "ChainHealth": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "chainId": { "type": "integer", "nullable": true }, "status": { "type": "string", "enum": [ "operational", "degraded", "down" ] }, "block_lag_s": { "type": "number", "nullable": true }, "rpc_error": { "type": "string", "nullable": true } }, "required": [ "key", "name", "chainId", "status", "block_lag_s", "rpc_error" ] }, "ServiceStatus": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "status" ] }, "status": { "type": "string", "enum": [ "operational", "degraded", "down" ] }, "version": { "type": "string" }, "uptime_s": { "type": "integer" }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceHealth" } }, "chains": { "type": "array", "items": { "$ref": "#/components/schemas/ChainHealth" } }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "object", "status", "version", "uptime_s", "services", "chains", "updated_at" ] }, "ErrorEnvelope": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message", "doc_url" ] } }, "required": [ "error" ] } } }, "x-thesauros-source": "Exported from the locally imported Partner API controllers and DTOs; scopes read from guard metadata." }