{"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":"/api/v1","description":"Sandbox (relative to deployed host)"}],"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/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"}}}},"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/Webhook"},"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’s 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":{"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=<unix>,v1=<hmac_sha256(secret, t + \".\" + body)>"},"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"}}}}}}