{ "openapi": "3.1.0", "info": { "title": "Thesauros Developer Platform API", "version": "1.0.0", "description": "Enterprise yield-infrastructure sandbox API. Deterministic simulation of the Thesauros routing engine: vaults, aggregated yield, positions with live accrual, rebalances, webhooks and usage telemetry. All APY values are decimal fractions (0.052 = 5.2%).", "contact": { "name": "Thesauros", "url": "https://developer.thesauros.io" } }, "servers": [ { "url": "/developers/api/v1", "description": "Earn sandbox" } ], "tags": [ { "name": "keys", "description": "API key management" }, { "name": "users", "description": "Partner end-users" }, { "name": "vaults", "description": "Yield vaults" }, { "name": "yield", "description": "Aggregated yield" }, { "name": "positions", "description": "Positions & lifecycle" }, { "name": "rebalances", "description": "Rebalance history" }, { "name": "webhooks", "description": "Webhook endpoints & events" }, { "name": "reconciliation", "description": "Ledger, balances & reconciliation" }, { "name": "analytics", "description": "Uplift, decision log, signals, regime & advisor" }, { "name": "telemetry", "description": "Usage & status" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/keys": { "post": { "tags": [ "keys" ], "summary": "Create an API key", "description": "Creates a key. The full secret is returned exactly once. Scopes are server-assigned; creating live keys requires the keys:live scope.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Client-generated key. Retries with the same key replay the original response.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKeyRequest" } } } }, "responses": { "201": { "description": "Key created (secret shown once)", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/ApiKey" }, "meta": { "type": "object" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden (key lacks the required scope)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on 429).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "get": { "tags": [ "keys" ], "summary": "List API keys", "description": "Lists keys with masked secrets.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size (1-500, default 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned as meta.next_cursor", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Masked keys", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on 429).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/keys/{id}": { "delete": { "tags": [ "keys" ], "summary": "Revoke an API key", "description": "Revokes a key. The shared sandbox key (key_bootstrap) cannot be revoked.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Key id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Key revoked", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/RevokedKey" }, "meta": { "type": "object" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on 429).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/users": { "post": { "tags": [ "users" ], "summary": "Create an end-user", "description": "Maps one of your customers to a Thesauros user via external_id (unique) and links their wallets.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Client-generated key. Retries with the same key replay the original response.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserRequest" } } } }, "responses": { "201": { "description": "User created", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/User" }, "meta": { "type": "object" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on 429).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "get": { "tags": [ "users" ], "summary": "List end-users", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter by status", "schema": { "type": "string", "enum": [ "active", "disabled" ] } }, { "name": "wallet", "in": "query", "required": false, "description": "Filter by linked wallet", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (1-500, default 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned as meta.next_cursor", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Users", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on 429).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/users/{id}": { "get": { "tags": [ "users" ], "summary": "Get an end-user", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "User id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The user", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/User" }, "meta": { "type": "object" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on 429).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "tags": [ "users" ], "summary": "Update an end-user", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "User id", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserRequest" } } } }, "responses": { "200": { "description": "Updated user", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/User" }, "meta": { "type": "object" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on 429).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/users/{id}/positions": { "get": { "tags": [ "users" ], "summary": "A user's positions", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "User id", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (1-500, default 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned as meta.next_cursor", "schema": { "type": "string" } } ], "responses": { "200": { "description": "User's positions with live accrual", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Position" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on 429).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/users/{id}/ledger": { "get": { "tags": [ "users" ], "summary": "A user's reconciliation ledger", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "User id", "schema": { "type": "string" } }, { "name": "asset", "in": "query", "required": false, "description": "Filter by asset", "schema": { "type": "string", "enum": [ "USDC", "USDT" ] } }, { "name": "type", "in": "query", "required": false, "description": "Filter by entry type", "schema": { "type": "string", "enum": [ "deposit", "withdraw", "close", "accrual" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (1-500, default 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned as meta.next_cursor", "schema": { "type": "string" } } ], "responses": { "200": { "description": "User's ledger", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/LedgerEntry" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on 429).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/vaults": { "get": { "tags": [ "vaults" ], "summary": "List vaults", "parameters": [ { "name": "asset", "in": "query", "required": false, "description": "Filter by asset", "schema": { "type": "string", "enum": [ "USDC", "USDT" ] } }, { "name": "chain", "in": "query", "required": false, "description": "Filter by chain", "schema": { "type": "string", "enum": [ "base", "arbitrum" ] } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status", "schema": { "type": "string", "enum": [ "active", "paused" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (1-500, default 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned as meta.next_cursor", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Matching vaults", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Vault" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on 429).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/vaults/{id}": { "get": { "tags": [ "vaults" ], "summary": "Get a vault", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Vault id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The vault", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/Vault" }, "meta": { "type": "object" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on 429).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/yield": { "get": { "tags": [ "yield" ], "summary": "Aggregated yield", "description": "Best and allocation-blended APY. Omit asset to aggregate all active vaults.", "parameters": [ { "name": "asset", "in": "query", "required": false, "description": "Asset to aggregate", "schema": { "type": "string", "enum": [ "USDC", "USDT" ] } } ], "responses": { "200": { "description": "Aggregated yield", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/Yield" }, "meta": { "type": "object" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on 429).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/yield/{asset}": { "get": { "tags": [ "yield" ], "summary": "Per-asset yield detail", "parameters": [ { "name": "asset", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "USDC", "USDT" ] } } ], "responses": { "200": { "description": "Per-asset yield with breakdown + history", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/Yield" }, "meta": { "type": "object" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on 429).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/positions": { "post": { "tags": [ "positions" ], "summary": "Open a position", "description": "Validates the wallet/asset/amount and routes to a vault. Settlement is synchronous: the position is active immediately.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Client-generated key. Retries with the same key replay the original response.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePositionRequest" } } } }, "responses": { "201": { "description": "Position created and active", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/Position" }, "meta": { "type": "object" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on 429).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "get": { "tags": [ "positions" ], "summary": "List positions", "parameters": [ { "name": "wallet", "in": "query", "required": false, "description": "Filter by wallet address", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status", "schema": { "type": "string", "enum": [ "active", "closed" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (1-500, default 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned as meta.next_cursor", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Positions with live accrual", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Position" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on 429).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/positions/{id}": { "get": { "tags": [ "positions" ], "summary": "Get a position", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Position id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Position with live accrued yield", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/Position" }, "meta": { "type": "object" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on 429).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/positions/{id}/withdraw": { "post": { "tags": [ "positions" ], "summary": "Withdraw from a position", "description": "Partial or full withdrawal. Partial withdrawals preserve accrued yield exactly (the remaining value keeps compounding).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Position id", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawRequest" } } } }, "responses": { "200": { "description": "Updated position", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/Position" }, "meta": { "type": "object" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on 429).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/positions/{id}/history": { "get": { "tags": [ "positions" ], "summary": "Position event timeline", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Position id", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (1-500, default 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned as meta.next_cursor", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Chronological events", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PositionEvent" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on 429).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/rebalances": { "get": { "tags": [ "rebalances" ], "summary": "List rebalances", "parameters": [ { "name": "position_id", "in": "query", "required": false, "description": "Filter by position", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (1-500, default 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned as meta.next_cursor", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Rebalances, newest first", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Rebalance" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on 429).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/webhooks": { "post": { "tags": [ "webhooks" ], "summary": "Register a webhook endpoint", "description": "Registers an endpoint. The URL is SSRF-guarded (loopback, private, link-local and metadata addresses are rejected). The signing secret is returned once.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Client-generated key. Retries with the same key replay the original response.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } } } }, "responses": { "201": { "description": "Endpoint registered", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/Webhook" }, "meta": { "type": "object" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on 429).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "get": { "tags": [ "webhooks" ], "summary": "List webhook endpoints", "description": "Lists endpoints with masked signing secrets.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size (1-500, default 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned as meta.next_cursor", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Endpoints", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on 429).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/webhooks/events": { "get": { "tags": [ "webhooks" ], "summary": "Webhook delivery log", "parameters": [ { "name": "webhook_id", "in": "query", "required": false, "description": "Filter by webhook", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (1-500, default 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned as meta.next_cursor", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deliveries, newest first", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on 429).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/webhooks/{id}": { "delete": { "tags": [ "webhooks" ], "summary": "Delete a webhook endpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Endpoint deleted", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/DeletedWebhook" }, "meta": { "type": "object" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on 429).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/webhooks/{id}/test": { "post": { "tags": [ "webhooks" ], "summary": "Send a test event", "description": "Dispatches a synthetic system.status event and returns the delivery record.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Resulting delivery (delivered or failed)", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/Delivery" }, "meta": { "type": "object" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on 429).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/reconciliation/ledger": { "get": { "tags": [ "reconciliation" ], "summary": "Reconciliation ledger", "description": "Append-only ledger of balance-affecting entries with running balance per position.", "parameters": [ { "name": "user_id", "in": "query", "required": false, "description": "Filter by user", "schema": { "type": "string" } }, { "name": "position_id", "in": "query", "required": false, "description": "Filter by position", "schema": { "type": "string" } }, { "name": "asset", "in": "query", "required": false, "description": "Filter by asset", "schema": { "type": "string", "enum": [ "USDC", "USDT" ] } }, { "name": "type", "in": "query", "required": false, "description": "Filter by entry type", "schema": { "type": "string", "enum": [ "deposit", "withdraw", "close", "accrual" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (1-500, default 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned as meta.next_cursor", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Ledger entries", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/LedgerEntry" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on 429).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/reconciliation/balances": { "get": { "tags": [ "reconciliation" ], "summary": "Current balances", "description": "Current recorded balances grouped by user and asset (active positions).", "parameters": [ { "name": "user_id", "in": "query", "required": false, "description": "Filter by user", "schema": { "type": "string" } }, { "name": "asset", "in": "query", "required": false, "description": "Filter by asset", "schema": { "type": "string", "enum": [ "USDC", "USDT" ] } } ], "responses": { "200": { "description": "Balances by user/asset", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Balance" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on 429).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/reconciliation/report": { "get": { "tags": [ "reconciliation" ], "summary": "Reconciliation report", "description": "Recorded (ledger) vs on-chain (settled) totals. The difference is intraday unsettled yield; within tolerance the status is \"reconciled\".", "parameters": [ { "name": "scope", "in": "query", "required": false, "description": "all, a user id (usr_...) or a position id (pos_...)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Reconciliation result", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/Reconciliation" }, "meta": { "type": "object" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on 429).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/reconciliation/snapshots": { "get": { "tags": [ "reconciliation" ], "summary": "Balance snapshots", "description": "Daily balance snapshots over a range, for period accounting.", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "End date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "asset", "in": "query", "required": false, "description": "Filter by asset", "schema": { "type": "string", "enum": [ "USDC", "USDT" ] } } ], "responses": { "200": { "description": "Daily snapshots", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BalanceSnapshot" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on 429).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/analytics/uplift": { "get": { "tags": [ "analytics" ], "summary": "Uplift vs baselines", "description": "Routed portfolio value versus passive baselines (Aave-only and hold-original-vault). The concept\u2019s primary proof point.", "parameters": [ { "name": "user_id", "in": "query", "required": false, "description": "Scope to a user", "schema": { "type": "string" } }, { "name": "asset", "in": "query", "required": false, "description": "Filter by asset", "schema": { "type": "string", "enum": [ "USDC", "USDT" ] } } ], "responses": { "200": { "description": "Uplift report", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/UpliftReport" }, "meta": { "type": "object" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on 429).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/analytics/decisions": { "get": { "tags": [ "analytics" ], "summary": "Decision log", "description": "Explainable log of routing and rebalance decisions: inputs, alternatives considered, expected uplift and rationale.", "parameters": [ { "name": "user_id", "in": "query", "required": false, "description": "Filter by user", "schema": { "type": "string" } }, { "name": "position_id", "in": "query", "required": false, "description": "Filter by position", "schema": { "type": "string" } }, { "name": "asset", "in": "query", "required": false, "description": "Filter by asset", "schema": { "type": "string", "enum": [ "USDC", "USDT" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (1-500, default 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned as meta.next_cursor", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Decisions, newest first", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Decision" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on 429).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/analytics/signals": { "get": { "tags": [ "analytics" ], "summary": "Risk-adjusted signals", "description": "Per-vault risk-adjusted APY (APY discounted by risk tier and volatility) with a naive trend forecast and a recommendation. Ranked.", "parameters": [ { "name": "asset", "in": "query", "required": false, "description": "Filter by asset", "schema": { "type": "string", "enum": [ "USDC", "USDT" ] } } ], "responses": { "200": { "description": "Signals, best risk-adjusted first", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "meta" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Signal" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on 429).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/analytics/regime": { "get": { "tags": [ "analytics" ], "summary": "Market regime", "description": "Classifies the current rate regime (rising/falling/stable/volatile) from recent yield trend and volatility.", "parameters": [ { "name": "asset", "in": "query", "required": false, "description": "Restrict to one asset", "schema": { "type": "string", "enum": [ "USDC", "USDT" ] } } ], "responses": { "200": { "description": "Regime classification", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/Regime" }, "meta": { "type": "object" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on 429).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/analytics/advisor": { "get": { "tags": [ "analytics" ], "summary": "Strategy advisor", "description": "Template-generated (non-LLM) strategy summary: regime, top risk-adjusted opportunities, portfolio uplift and rationale bullets.", "responses": { "200": { "description": "Advisor summary", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/Advisor" }, "meta": { "type": "object" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on 429).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/usage": { "get": { "tags": [ "telemetry" ], "summary": "Usage time series", "parameters": [ { "name": "range", "in": "query", "required": false, "description": "Time range", "schema": { "type": "string", "enum": [ "24h", "7d", "30d" ], "default": "30d" } } ], "responses": { "200": { "description": "Series + totals", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/Usage" }, "meta": { "type": "object" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on 429).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/status": { "get": { "tags": [ "telemetry" ], "summary": "Platform status", "security": [], "responses": { "200": { "description": "Component health", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string" }, "data": { "$ref": "#/components/schemas/Status" }, "meta": { "type": "object" } } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/openapi.json": { "get": { "tags": [ "telemetry" ], "summary": "OpenAPI document", "security": [], "responses": { "200": { "description": "This OpenAPI 3.1 document", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key. Format tsk_test_... (sandbox) or tsk_live_... (live)." } }, "schemas": { "RevokedKey": { "type": "object", "required": [ "id", "object", "revoked" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "api_key" }, "revoked": { "type": "boolean" } } }, "DeletedWebhook": { "type": "object", "required": [ "id", "object", "deleted" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "webhook" }, "deleted": { "type": "boolean" } } }, "ListMeta": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total items matching the filter" }, "limit": { "type": "integer", "description": "Page size applied" }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page, or null when exhausted" } }, "required": [ "total" ] }, "ErrorEnvelope": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "doc_url" ], "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "invalid_request", "not_found", "rate_limited", "internal" ] }, "message": { "type": "string" }, "doc_url": { "type": "string", "format": "uri" } } } } }, "CreateKeyRequest": { "type": "object", "properties": { "label": { "type": "string", "description": "Human label for the key" }, "environment": { "type": "string", "enum": [ "test", "live" ], "default": "test" } } }, "ApiKey": { "type": "object", "required": [ "id", "object", "label", "environment", "created_at", "revoked", "scopes" ], "properties": { "id": { "type": "string", "example": "key_bootstrap" }, "object": { "type": "string", "enum": [ "api_key" ] }, "label": { "type": "string" }, "secret": { "type": "string", "description": "Full secret only on create; masked (tsk_test_...a1b2) on list" }, "prefix": { "type": "string", "description": "First 12 chars of the secret" }, "environment": { "type": "string", "enum": [ "test", "live" ] }, "created_at": { "type": "string", "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "revoked": { "type": "boolean" }, "scopes": { "type": "array", "items": { "type": "string" } } } }, "Vault": { "type": "object", "required": [ "id", "object", "name", "provider", "asset", "chain", "apy", "status", "risk_tier" ], "properties": { "id": { "type": "string", "example": "vault_aave_base_usdc" }, "object": { "type": "string", "enum": [ "vault" ] }, "name": { "type": "string" }, "provider": { "type": "string", "enum": [ "aave", "morpho", "compound", "dolomite", "treasury" ] }, "asset": { "type": "string", "enum": [ "USDC", "USDT" ] }, "chain": { "type": "string", "enum": [ "base", "arbitrum" ] }, "apy": { "type": "number", "description": "Decimal fraction (0.052 = 5.2%)" }, "apy_7d_avg": { "type": "number" }, "apy_30d_avg": { "type": "number" }, "tvl_usd": { "type": "number" }, "capacity_usd": { "type": "number" }, "risk_tier": { "type": "string", "enum": [ "bluechip", "core", "opportunistic" ] }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "inception_date": { "type": "string", "format": "date" }, "description": { "type": "string" }, "allocation_pct": { "type": "number" } } }, "YieldBreakdown": { "type": "object", "properties": { "vault_id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" }, "apy": { "type": "number" }, "allocation": { "type": "number" } } }, "YieldHistoryPoint": { "type": "object", "properties": { "t": { "type": "integer", "description": "Epoch ms" }, "apy": { "type": "number" } } }, "Yield": { "type": "object", "required": [ "object", "asset", "best_apy", "blend_apy" ], "properties": { "object": { "type": "string", "enum": [ "yield" ] }, "asset": { "type": "string", "example": "USDC" }, "best_apy": { "type": "number" }, "blend_apy": { "type": "number", "description": "Allocation-weighted blended APY" }, "blended_30d": { "type": "number" }, "breakdown": { "type": "array", "items": { "$ref": "#/components/schemas/YieldBreakdown" } }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/YieldHistoryPoint" } } } }, "CreatePositionRequest": { "type": "object", "required": [ "wallet", "asset", "amount" ], "properties": { "wallet": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "asset": { "type": "string", "enum": [ "USDC", "USDT" ] }, "amount": { "type": "number", "exclusiveMinimum": 0 }, "strategy": { "type": "string", "description": "\"auto\" or a target vault id", "default": "auto" }, "user": { "type": "string", "description": "Optional user id (usr_...) or external_id to associate" } } }, "WithdrawRequest": { "type": "object", "description": "Provide a positive amount for a partial withdrawal, or { \"all\": true } to close.", "properties": { "amount": { "type": "number", "exclusiveMinimum": 0 }, "all": { "type": "boolean" } } }, "Position": { "type": "object", "required": [ "id", "object", "wallet", "asset", "chain", "vault_id", "principal", "current_value", "accrued_yield", "apy", "status" ], "properties": { "id": { "type": "string", "example": "pos_seed_alpha" }, "object": { "type": "string", "enum": [ "position" ] }, "user_id": { "type": [ "string", "null" ], "description": "Owning end-user, if associated" }, "wallet": { "type": "string" }, "asset": { "type": "string", "enum": [ "USDC", "USDT" ] }, "chain": { "type": "string", "enum": [ "base", "arbitrum" ] }, "vault_id": { "type": "string" }, "strategy": { "type": "string" }, "principal": { "type": "number" }, "current_value": { "type": "number", "description": "principal * (1 + apy * elapsedYears)" }, "accrued_yield": { "type": "number" }, "apy": { "type": "number" }, "status": { "type": "string", "enum": [ "active", "closed" ] }, "opened_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "last_rebalance_at": { "type": [ "string", "null" ], "format": "date-time" }, "tx_hash": { "type": "string" } } }, "PositionEvent": { "type": "object", "required": [ "id", "type", "at" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "position_event" ] }, "position_id": { "type": "string" }, "type": { "type": "string", "enum": [ "deposit", "rebalance", "accrual", "withdraw", "close" ] }, "at": { "type": "string", "format": "date-time" }, "amount": { "type": "number" }, "apy": { "type": "number" }, "vault_id": { "type": "string" }, "note": { "type": "string" } } }, "Rebalance": { "type": "object", "required": [ "id", "object", "position_id", "from_vault", "to_vault", "at" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "rebalance" ] }, "position_id": { "type": "string" }, "from_vault": { "type": "string" }, "to_vault": { "type": "string" }, "amount": { "type": "number" }, "reason": { "type": "string", "enum": [ "yield_optimization", "risk_adjustment", "capacity_rebalance" ] }, "apy_before": { "type": "number" }, "apy_after": { "type": "number" }, "at": { "type": "string", "format": "date-time" }, "tx_hash": { "type": "string" } } }, "CreateWebhookRequest": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "*", "position.opened", "position.active", "position.rebalanced", "position.withdrawn", "position.closed", "yield.threshold", "system.status" ] }, "description": "Defaults to [\"*\"]" }, "active": { "type": "boolean", "default": true } } }, "Webhook": { "type": "object", "required": [ "id", "object", "url", "events", "secret", "active", "created_at" ], "properties": { "id": { "type": "string", "example": "wh_seed_example" }, "object": { "type": "string", "enum": [ "webhook" ] }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "secret": { "type": "string", "description": "whsec_... used to compute Webhook-Signature" }, "active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "Delivery": { "type": "object", "required": [ "id", "object", "event", "status", "at" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "delivery" ] }, "webhook_id": { "type": "string" }, "url": { "type": "string", "description": "Target endpoint URL" }, "event": { "type": "string", "enum": [ "position.opened", "position.active", "position.rebalanced", "position.withdrawn", "position.closed", "yield.threshold", "system.status" ] }, "payload": { "type": "object", "description": "The signed event payload { id, type, created_at, data }" }, "signature": { "type": "string", "description": "t=,v1=" }, "status": { "type": "string", "enum": [ "delivered", "failed" ] }, "attempts": { "type": "integer" }, "at": { "type": "string", "format": "date-time" }, "latency_ms": { "type": "integer" } } }, "UsageTotals": { "type": "object", "properties": { "requests": { "type": "integer" }, "errors": { "type": "integer" }, "p50_ms": { "type": "integer" }, "p99_ms": { "type": "integer" }, "unique_keys": { "type": "integer" } } }, "UsagePoint": { "type": "object", "properties": { "t": { "type": "integer", "description": "Epoch ms bucket start" }, "requests": { "type": "integer" }, "errors": { "type": "integer" }, "p50_ms": { "type": "integer" }, "p99_ms": { "type": "integer" } } }, "Usage": { "type": "object", "required": [ "object", "range", "totals", "series" ], "properties": { "object": { "type": "string", "enum": [ "usage" ] }, "range": { "type": "string", "enum": [ "24h", "7d", "30d" ] }, "totals": { "$ref": "#/components/schemas/UsageTotals" }, "series": { "type": "array", "items": { "$ref": "#/components/schemas/UsagePoint" } } } }, "StatusComponent": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "operational", "degraded", "outage" ] }, "uptime_90d": { "type": "number" }, "latency_ms": { "type": "integer" } } }, "Status": { "type": "object", "required": [ "object", "overall", "components", "incidents", "updated_at" ], "properties": { "object": { "type": "string", "enum": [ "status" ] }, "overall": { "type": "string", "enum": [ "operational", "degraded", "outage" ] }, "components": { "type": "array", "items": { "$ref": "#/components/schemas/StatusComponent" } }, "incidents": { "type": "array", "items": { "type": "object" } }, "uptime_s": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CreateUserRequest": { "type": "object", "required": [ "external_id" ], "properties": { "external_id": { "type": "string", "description": "Your customer id (unique)" }, "label": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "metadata": { "type": "object" }, "wallets": { "type": "array", "items": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } } }, "UpdateUserRequest": { "type": "object", "properties": { "label": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "metadata": { "type": "object" }, "wallets": { "type": "array", "items": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, "status": { "type": "string", "enum": [ "active", "disabled" ] } } }, "User": { "type": "object", "required": [ "id", "object", "external_id", "wallets", "status", "created_at" ], "properties": { "id": { "type": "string", "example": "usr_seed_nova" }, "object": { "type": "string", "enum": [ "user" ] }, "external_id": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "metadata": { "type": "object" }, "wallets": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "LedgerEntry": { "type": "object", "required": [ "id", "object", "at", "position_id", "asset", "type", "amount", "balance_after", "settled" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "ledger_entry" ] }, "at": { "type": "string", "format": "date-time" }, "user_id": { "type": [ "string", "null" ] }, "position_id": { "type": "string" }, "wallet": { "type": "string" }, "asset": { "type": "string", "enum": [ "USDC", "USDT" ] }, "type": { "type": "string", "enum": [ "deposit", "withdraw", "close", "accrual" ] }, "amount": { "type": "number", "description": "Signed delta" }, "balance_after": { "type": "number", "description": "Running balance for the position" }, "vault_id": { "type": "string" }, "settled": { "type": "boolean" }, "ref": { "type": "string" } } }, "Balance": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "balance" ] }, "user_id": { "type": [ "string", "null" ] }, "asset": { "type": "string", "enum": [ "USDC", "USDT" ] }, "principal": { "type": "number" }, "current_value": { "type": "number" }, "accrued_yield": { "type": "number" }, "positions": { "type": "integer" } } }, "Reconciliation": { "type": "object", "required": [ "object", "as_of", "scope", "recorded_total", "onchain_total", "discrepancy", "status" ], "properties": { "object": { "type": "string", "enum": [ "reconciliation" ] }, "as_of": { "type": "string", "format": "date-time" }, "scope": { "type": "string" }, "recorded_total": { "type": "number" }, "onchain_total": { "type": "number" }, "discrepancy": { "type": "number" }, "unsettled_yield": { "type": "number" }, "tolerance": { "type": "number" }, "status": { "type": "string", "enum": [ "reconciled", "mismatch" ] }, "positions": { "type": "integer" }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string" }, "recorded": { "type": "number" }, "onchain": { "type": "number" }, "discrepancy": { "type": "number" } } } } } }, "BalanceSnapshot": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "balance_snapshot" ] }, "date": { "type": "string" }, "t": { "type": "integer", "description": "Epoch ms" }, "principal": { "type": "number" }, "value": { "type": "number" }, "accrued": { "type": "number" }, "positions": { "type": "integer" }, "users": { "type": "integer" }, "by_asset": { "type": "array", "items": { "type": "object" } } } }, "Signal": { "type": "object", "description": "Per-vault risk-adjusted signal. APY fields are decimal fractions.", "properties": { "object": { "type": "string", "enum": [ "signal" ] }, "vault_id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" }, "asset": { "type": "string", "enum": [ "USDC", "USDT" ] }, "chain": { "type": "string" }, "risk_tier": { "type": "string", "enum": [ "bluechip", "core", "opportunistic" ] }, "apy": { "type": "number" }, "volatility": { "type": "number" }, "trend_slope_bps_day": { "type": "number" }, "forecast_apy": { "type": "number", "description": "Naive 7-day trend forecast (decimal fraction)" }, "risk_factor": { "type": "number" }, "risk_adjusted_apy": { "type": "number" }, "rank": { "type": "integer" }, "recommendation": { "type": "string", "enum": [ "overweight", "neutral", "underweight" ] } } }, "Regime": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "regime" ] }, "as_of": { "type": "string", "format": "date-time" }, "regime": { "type": "string", "enum": [ "rising", "falling", "stable", "volatile" ] }, "description": { "type": "string" }, "per_asset": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string" }, "regime": { "type": "string", "enum": [ "rising", "falling", "stable", "volatile" ] }, "blend_apy": { "type": "number" }, "trend_slope_bps_day": { "type": "number" }, "volatility": { "type": "number" } } } } } }, "UpliftRow": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "uplift_row" ] }, "position_id": { "type": "string" }, "user_id": { "type": [ "string", "null" ] }, "asset": { "type": "string" }, "vault_id": { "type": "string" }, "principal": { "type": "number" }, "current_value": { "type": "number" }, "apy": { "type": "number" }, "aave_baseline": { "type": "number" }, "baseline_apy": { "type": "number" }, "hold_baseline": { "type": "number" }, "uplift_vs_aave": { "type": "number" }, "uplift_vs_hold": { "type": "number" } } }, "UpliftReport": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "uplift" ] }, "as_of": { "type": "string", "format": "date-time" }, "scope": { "type": "string" }, "totals": { "type": "object", "properties": { "principal": { "type": "number" }, "current_value": { "type": "number" }, "aave_baseline": { "type": "number" }, "hold_baseline": { "type": "number" }, "uplift_vs_aave": { "type": "number" }, "uplift_vs_hold": { "type": "number" }, "uplift_vs_aave_pct": { "type": "number" } } }, "positions": { "type": "array", "items": { "$ref": "#/components/schemas/UpliftRow" } } } }, "Decision": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "decision" ] }, "id": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "position_id": { "type": "string" }, "user_id": { "type": [ "string", "null" ] }, "asset": { "type": "string" }, "type": { "type": "string", "enum": [ "initial_routing", "rebalance" ] }, "from_vault": { "type": [ "string", "null" ] }, "to_vault": { "type": "string" }, "apy_before": { "type": [ "number", "null" ] }, "apy_after": { "type": "number" }, "expected_uplift_bps": { "type": [ "number", "null" ] }, "reason": { "type": "string" }, "alternatives": { "type": "array", "items": { "type": "object", "properties": { "vault_id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" }, "apy": { "type": "number" }, "risk_tier": { "type": "string" } } } }, "rationale": { "type": "string" }, "status": { "type": "string" } } }, "Advisor": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "advisor" ] }, "as_of": { "type": "string", "format": "date-time" }, "headline": { "type": "string" }, "regime": { "type": "string" }, "bullets": { "type": "array", "items": { "type": "string" } }, "top_opportunities": { "type": "array", "items": { "type": "object", "properties": { "vault_id": { "type": "string" }, "name": { "type": "string" }, "asset": { "type": "string" }, "risk_adjusted_apy": { "type": "number" }, "forecast_apy": { "type": "number" }, "recommendation": { "type": "string" } } } }, "portfolio": { "type": "object", "properties": { "current_value": { "type": "number" }, "uplift_vs_aave": { "type": "number" }, "uplift_vs_aave_pct": { "type": "number" }, "positions": { "type": "integer" } } }, "disclaimer": { "type": "string" } } } } } }