{"openapi":"3.0.0","paths":{"/health":{"get":{"operationId":"HealthController_check","parameters":[],"responses":{"200":{"description":"The Health Check is successful","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"info":{"type":"object","example":{"database":{"status":"up"}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true},"nullable":true},"error":{"type":"object","example":{},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true},"nullable":true},"details":{"type":"object","example":{"database":{"status":"up"}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true}}}}}}},"503":{"description":"The Health Check is not successful","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"error"},"info":{"type":"object","example":{"database":{"status":"up"}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true},"nullable":true},"error":{"type":"object","example":{"redis":{"status":"down","message":"Could not connect"}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true},"nullable":true},"details":{"type":"object","example":{"database":{"status":"up"},"redis":{"status":"down","message":"Could not connect"}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true}}}}}}}},"summary":"Health check","tags":["health"]}},"/api/v1/auth/login":{"get":{"operationId":"AuthController_signInGet_v1","parameters":[],"responses":{"200":{"description":"SIWE login is POST only. MCP OAuth uses GET /api/v1/oauth/consent after /api/v1/oauth/authorize.","paginationType":"offset"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"summary":"Sign in (GET not supported)","tags":["auth"]},"post":{"operationId":"AuthController_signIn_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginReqDto"}}}},"responses":{"200":{"description":"Authenticate with a SIWE message and signature. Returns a JWT access token for subsequent requests.","paginationType":"offset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginResDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"summary":"Sign in","tags":["auth"]}},"/api/v1/auth/challenge":{"post":{"operationId":"AuthController_challenge_v1","parameters":[],"responses":{"200":{"description":"Returns a Sign-In With Ethereum nonce to embed in the message the user signs before calling POST /auth/login.","paginationType":"offset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChallengeResDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"summary":"Get SIWE nonce","tags":["auth"]}},"/api/v1/auth/siwe/prepare":{"post":{"operationId":"AuthController_prepareSiwe_v1","parameters":[],"responses":{"200":{"description":"Returns the exact EIP-4361 string and message fields for POST /auth/login (checksum address, matches server verification).","paginationType":"offset"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"summary":"Build SIWE message to sign","tags":["auth"]}},"/api/v1/oauth/.well-known/oauth-authorization-server":{"get":{"operationId":"McpOAuthController_authorizationServerMetadata_v1","parameters":[],"responses":{"200":{"description":"OK","paginationType":"offset"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"summary":"OAuth 2.0 authorization server metadata (RFC 8414)","tags":["oauth"]}},"/api/v1/oauth/.well-known/openid-configuration":{"get":{"operationId":"McpOAuthController_openIdConfiguration_v1","parameters":[],"responses":{"200":{"description":"OK","paginationType":"offset"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"summary":"OpenID Provider metadata (legacy path suffix)","tags":["oauth"]}},"/api/v1/oauth/register":{"post":{"operationId":"McpOAuthController_register_v1","parameters":[],"responses":{"200":{"description":"OK","paginationType":"offset"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"summary":"OAuth dynamic client registration (RFC 7591)","tags":["oauth"]}},"/api/v1/oauth/.well-known/oauth-protected-resource":{"get":{"operationId":"McpOAuthController_protectedResourceMetadata_v1","parameters":[],"responses":{"200":{"description":"OK","paginationType":"offset"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"summary":"OAuth 2.0 protected resource metadata (RFC 9728)","tags":["oauth"]}},"/api/v1/oauth/authorize":{"get":{"operationId":"McpOAuthController_authorize_v1","parameters":[{"name":"response_type","required":true,"in":"query","schema":{"type":"string"}},{"name":"client_id","required":true,"in":"query","schema":{"type":"string"}},{"name":"redirect_uri","required":true,"in":"query","schema":{"type":"string"}},{"name":"code_challenge","required":true,"in":"query","schema":{"type":"string"}},{"name":"code_challenge_method","required":true,"in":"query","schema":{"type":"string"}},{"name":"scope","required":true,"in":"query","schema":{"type":"string"}},{"name":"resource","required":true,"in":"query","schema":{"type":"string"}},{"name":"state","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","paginationType":"offset"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"summary":"Start OAuth authorization code flow (PKCE)","tags":["oauth"]}},"/api/v1/oauth/consent":{"get":{"operationId":"McpOAuthController_consentPage_v1","parameters":[{"name":"state","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","paginationType":"offset"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"summary":"SIWE consent page for MCP OAuth","tags":["oauth"]}},"/api/v1/oauth/consent/complete":{"post":{"operationId":"McpOAuthController_consentComplete_v1","parameters":[],"responses":{"200":{"description":"OK","paginationType":"offset"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"summary":"Finish OAuth consent after SIWE login","tags":["oauth"]}},"/api/v1/oauth/session-credential":{"post":{"operationId":"McpOAuthController_sessionCredential_v1","parameters":[],"responses":{"200":{"description":"OK","paginationType":"offset"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"summary":"Exchange MCP access token for Zyfai user API credential (MCP server only)","tags":["oauth"]}},"/api/v1/oauth/token":{"post":{"operationId":"McpOAuthController_token_v1","parameters":[],"responses":{"200":{"description":"OK","paginationType":"offset"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"summary":"OAuth token endpoint (authorization_code + PKCE)","tags":["oauth"]}},"/api/v1/oauth/revoke":{"post":{"operationId":"McpOAuthController_revoke_v1","parameters":[],"responses":{"200":{"description":"OK","paginationType":"offset"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"summary":"OAuth token revocation (RFC 7009-style)","tags":["oauth"]}},"/.well-known/oauth-authorization-server/api/v1/oauth":{"get":{"operationId":"McpOAuthDiscoveryController_authorizationServerMetadata","parameters":[],"responses":{"200":{"description":"OK","paginationType":"offset"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"summary":"OAuth AS metadata (RFC 8414 path-style issuer)","tags":["oauth"]}},"/.well-known/openid-configuration/api/v1/oauth":{"get":{"operationId":"McpOAuthDiscoveryController_openIdConfiguration","parameters":[],"responses":{"200":{"description":"OK","paginationType":"offset"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"summary":"OpenID Provider metadata (RFC 8414 path-style issuer)","tags":["oauth"]}},"/register":{"post":{"operationId":"McpOAuthDiscoveryController_register","parameters":[],"responses":{"200":{"description":"OK","paginationType":"offset"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"summary":"OAuth dynamic client registration (RFC 7591)","tags":["oauth"]}},"/api/v1/users/me":{"get":{"operationId":"UserController_getCurrentUser_v1","parameters":[],"responses":{"200":{"description":"OK","paginationType":"offset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserResDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"security":[{"bearer":[]}],"summary":"Get current user","tags":["users"]},"patch":{"operationId":"UserController_updateUser_v1","parameters":[],"requestBody":{"required":true,"description":"You can specify smart wallet address and list of supported protocols","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUserReqDto"}}}},"responses":{"200":{"description":"OK","paginationType":"offset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserResDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"security":[{"bearer":[]}],"summary":"Update user","tags":["users"]}},"/api/v1/users/position":{"get":{"operationId":"UserController_getPosition_v1","parameters":[],"responses":{"200":{"description":"OK","paginationType":"offset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetPositionResDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"security":[{"bearer":[]}],"summary":"Get user's current position","tags":["users"]}},"/api/v1/users/portfolio":{"get":{"operationId":"UserController_getPortfolio_v1","parameters":[],"responses":{"200":{"description":"OK","paginationType":"offset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortfolioResDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"security":[{"bearer":[]}],"summary":"Get user's portfolio (positions + balance status)","tags":["users"]}},"/api/v1/users/active-positions":{"get":{"operationId":"UserController_getActivePositions_v1","parameters":[],"responses":{"200":{"description":"OK","paginationType":"offset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivePositionsResDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"security":[{"bearer":[]}],"summary":"Get user's active positions","tags":["users"]}},"/api/v1/users/balance-status":{"get":{"operationId":"UserController_getBalanceStatus_v1","parameters":[],"responses":{"200":{"description":"OK","paginationType":"offset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceStatusResDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"security":[{"bearer":[]}],"summary":"Get user's balance status","tags":["users"]}},"/api/v1/users/withdraw":{"get":{"description":"Queues a full withdrawal from protocol positions to idle for the given chain and token. Idempotent while a withdraw lock is held.","operationId":"UserController_withdraw_v1","parameters":[{"name":"chainId","required":true,"in":"query","schema":{"example":8453,"type":"number"}},{"name":"tokenSymbol","required":false,"in":"query","description":"Token symbol; defaults to the chain default (e.g. USDC)","schema":{"example":"USDC","type":"string"}}],"responses":{"200":{"description":"OK","paginationType":"offset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithdrawResDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"security":[{"bearer":[]}],"summary":"Withdraw full balance on a chain","tags":["users"]}},"/api/v1/users/me/agent-deposit-setup":{"post":{"operationId":"UserController_agentDepositSetup_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDepositSetupReqDto"}}}},"responses":{"200":{"description":"OK","paginationType":"offset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDepositSetupResDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"security":[{"bearer":[]}],"summary":"Apply first-deposit asset settings for MCP prepare (agent channel only)","tags":["users"]}},"/api/v1/users/me/agent-token-uri":{"post":{"description":"Upload (pin) the agent identity JSON to IPFS via Pinata and return tokenUri (ipfs://CID).","operationId":"UserController_createAgentTokenUri_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentTokenUriReqDto"}}}},"responses":{"200":{"description":"OK","paginationType":"offset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentTokenUriResDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"security":[{"bearer":[]}],"summary":"Create agent tokenUri for Identity Registry","tags":["users"]}},"/api/v1/users/asset-type-settings":{"get":{"description":"Returns persisted per-asset-type settings including linked protocols.","operationId":"UserController_getAssetTypeSettings_v1","parameters":[],"responses":{"200":{"description":"OK","paginationType":"offset"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"security":[{"bearer":[]}],"summary":"Get user's per-asset-type settings","tags":["users"]}},"/api/v1/users/log_deposit":{"post":{"operationId":"UserController_logDeposit_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogDepositReqDto"}}}},"responses":{"201":{"description":"OK","paginationType":"offset"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"security":[{"bearer":[]}],"summary":"Log deposit","tags":["users"]}},"/api/v1/users/log_deposit/v2":{"post":{"description":"Records a deposit and returns immediately with its custody handover lifecycle state.","operationId":"UserController_logDepositV2_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogDepositReqDto"}}}},"responses":{"202":{"description":"OK","paginationType":"offset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepositLifecycleResDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"security":[{"bearer":[]}],"summary":"Log deposit with lifecycle response","tags":["users"]}},"/api/v1/users/deposits/{depositId}":{"get":{"operationId":"UserController_getDepositLifecycle_v1","parameters":[],"responses":{"200":{"description":"OK","paginationType":"offset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepositLifecycleResDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"security":[{"bearer":[]}],"summary":"Get verified deposit handover and credit status","tags":["users"]}},"/api/v1/users/log_swap":{"post":{"description":"Records a vault-share swap transaction and may queue a rebalance for all wallets on the chain.","operationId":"UserController_logSwap_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogSwapReqDto"}}}},"responses":{"200":{"description":"OK","paginationType":"offset"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"security":[{"bearer":[]}],"summary":"Log vault-share swap and sync source positions","tags":["users"]}},"/api/v1/users/notifications":{"get":{"description":"Returns cached rebalancing, withdraw, and async-withdrawal notifications keyed by type/chain.","operationId":"UserController_notifications_v1","parameters":[],"responses":{"200":{"description":"OK","paginationType":"offset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationsResDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"security":[{"bearer":[]}],"summary":"Get pending user notifications","tags":["users"]}},"/api/v1/users/autoselect":{"get":{"operationId":"UserController_getUsersAutoselect_v1","parameters":[{"name":"page","required":false,"in":"query","schema":{"example":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"example":100,"type":"number"}}],"responses":{"200":{"description":"Returns paginated list of users with their smart wallet addresses and autoSelectProtocols status","paginationType":"offset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserAutoselectResDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"summary":"Get all users with their autoselect status","tags":["users"]}},"/api/v1/users/async-withdrawals":{"get":{"operationId":"UserController_getAsyncWithdrawals_v1","parameters":[{"name":"chainId","required":true,"in":"query","schema":{"type":"string"}},{"name":"tokenSymbol","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","paginationType":"offset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncWithdrawalsResDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"security":[{"bearer":[]}],"summary":"List user's active async withdrawal requests (REQUESTED + CLAIMABLE)","tags":["users"]}},"/api/v1/users/partial-withdraw":{"post":{"description":"Queues a partial withdrawal of the specified raw token amount from protocol positions.","operationId":"UserController_partialWithdraw_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartialWithdrawReqDto"}}}},"responses":{"200":{"description":"OK","paginationType":"offset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartialWithdrawResDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"security":[{"bearer":[]}],"summary":"Initiate partial withdrawal from protocol position","tags":["users"]}},"/api/v1/users/update-telegram-id":{"post":{"description":"Updates the Telegram ID for a user identified by their smart wallet address. Requires server API key.","operationId":"UserController_updateTelegramId_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTelegramIdReqDto"}}}},"responses":{"200":{"description":"OK","paginationType":"offset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTelegramResDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"security":[{"Api-Key":[]}],"summary":"Update Telegram ID for user","tags":["users"]}},"/api/v1/users/reset-telegram":{"patch":{"operationId":"UserController_resetTelegram_v1","parameters":[],"responses":{"200":{"description":"OK","paginationType":"offset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResetTelegramResDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"security":[{"bearer":[]}],"summary":"Reset Telegram ID for current user","tags":["users"]}},"/api/v1/session-keys/config":{"get":{"description":"Returns SmartSessions (4337) session configs for the user chains, hardened for userOp-only usage.","operationId":"SessionKeysController_getConfig_v1","parameters":[],"responses":{"200":{"description":"OK","paginationType":"offset"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"security":[{"bearer":[]}],"summary":"Get personalized session key config","tags":["session-keys"]}},"/api/v1/session-keys/add":{"post":{"description":"Registers a session key after the user signs the permission enable hash, or via intent-only registration when hash is omitted.","operationId":"SessionKeysController_addSessionKey_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddSessionKeyReqDto"}}}},"responses":{"200":{"description":"OK","paginationType":"offset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionKeyResDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"security":[{"bearer":[]}],"summary":"Add session key","tags":["session-keys"]}},"/api/v1/session-keys/revoke":{"post":{"description":"Withdraws all positions to idle and revokes the active session key for the user.","operationId":"SessionKeysController_revokeSessionKey_v1","parameters":[],"responses":{"200":{"description":"OK","paginationType":"offset"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"security":[{"bearer":[]}],"summary":"Revoke session key","tags":["session-keys"]}},"/api/v1/history/latest":{"get":{"operationId":"HistoryController_getLatestWalletHistory_v1","parameters":[],"responses":{"200":{"description":"OK","paginationType":"offset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletHistoryResponseDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"security":[{"bearer":[]}],"summary":"Get latest wallet transaction history","tags":["History"]}},"/api/v1/history/all":{"get":{"description":"Returns paginated wallet transaction history with optional date range and chain filters.","operationId":"HistoryController_getWalletHistory_v1","parameters":[{"name":"limit","required":false,"in":"query","schema":{"example":100,"type":"number"}},{"name":"offset","required":false,"in":"query","schema":{"example":0,"type":"number"}},{"name":"fromDate","required":false,"in":"query","description":"ISO 8601 start date","schema":{"example":"2025-01-01T00:00:00.000Z","type":"string"}},{"name":"toDate","required":false,"in":"query","description":"ISO 8601 end date","schema":{"example":"2025-12-31T23:59:59.999Z","type":"string"}},{"name":"chainId","required":false,"in":"query","schema":{"example":8453,"type":"number"}}],"responses":{"200":{"description":"OK","paginationType":"offset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletHistoryResponseDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"security":[{"bearer":[]}],"summary":"Get wallet transaction history for a wallet address","tags":["History"]}},"/api/v1/customization/pools":{"get":{"description":"Public pool discovery for customization UI. Returns an empty object on handler error.","operationId":"CustomizationController_getPoolsByProtocolId_v1","parameters":[{"name":"protocolId","required":true,"in":"query","schema":{"type":"string"}},{"name":"assetType","required":false,"in":"query","description":"Optional asset type filter","schema":{"enum":["usdc","eth","cbeth","wbtc","cbbtc","eurc","usdt","pyusd","nvdac","googlc","aaplc","metac"],"type":"string"}},{"name":"strategy","required":false,"in":"query","description":"Rebalance strategy filter","schema":{"enum":["not_strategy","safe_strategy","degen_strategy","aave_strategy","async_strategy"],"type":"string"}}],"responses":{"200":{"description":"Returns eligible pools grouped by chain and token for the given protocol, strategy, and optional asset type.","paginationType":"offset"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"summary":"Get pools for a protocol","tags":["Customization"]}},"/api/v1/customization/selected-pools":{"get":{"description":"Returns the user saved pool selection and autoselect flag for a protocol on a chain.","operationId":"CustomizationController_getSelectedPools_v1","parameters":[{"name":"protocolId","required":true,"in":"query","schema":{"type":"string"}},{"name":"chainId","required":true,"in":"query","schema":{"type":"number"}},{"name":"assetType","required":false,"in":"query","schema":{"enum":["usdc","eth","cbeth","wbtc","cbbtc","eurc","usdt","pyusd","nvdac","googlc","aaplc","metac"],"type":"string"}}],"responses":{"200":{"description":"OK","paginationType":"offset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SelectedPoolsResDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"security":[{"bearer":[]}],"summary":"Get selected pools for a user","tags":["Customization"]}},"/api/v1/customization/customize":{"post":{"description":"Persists protocol pool selection and autoselect preference for one chain.","operationId":"CustomizationController_customize_v1","parameters":[],"requestBody":{"required":true,"description":"Protocol, chain, pools, and autoselect preference","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomizeReqDto"}}}},"responses":{"200":{"description":"OK","paginationType":"offset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomizationResDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"security":[{"bearer":[]}],"summary":"Save protocol and pools for a user","tags":["Customization"]}},"/api/v1/customization/customize-batch":{"post":{"description":"Persists multiple protocol/pool customizations in one request. Body is a JSON array of customization objects.","operationId":"CustomizationController_customizeBatch_v1","parameters":[],"requestBody":{"required":true,"description":"Array of protocol/pool customizations to save","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CustomizeReqDto"}}}}},"responses":{"200":{"description":"OK","paginationType":"offset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomizationResDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"security":[{"bearer":[]}],"summary":"Save multiple protocol customizations","tags":["Customization"]}},"/api/v1/protocols":{"get":{"operationId":"ProtocolController_findAll_v1","parameters":[{"name":"chainId","required":false,"in":"query","schema":{"type":"number"}},{"name":"type","required":false,"in":"query","schema":{"enum":["lending","dex","perpetuals","other"],"type":"string"}},{"name":"asset","required":false,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"summary":"Get all supported protocols","tags":["Protocols"]}},"/api/v1/protocols/{id}":{"get":{"operationId":"ProtocolController_findOne_v1","parameters":[{"name":"id","required":true,"in":"path","description":"Protocol ID","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProtocolResponseDto"}}}},"404":{"description":"Protocol not found"}},"summary":"Get protocol by id","tags":["Protocols"]}},"/api/supported-tokens":{"get":{"description":"Returns all active supported tokens, optionally filtered by chain ID.","operationId":"SupportedTokensController_findAll","parameters":[{"name":"chainId","required":false,"in":"query","schema":{"example":8453,"type":"number"}}],"responses":{"default":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SupportedTokenResDto"}}}}}},"summary":"Get all supported tokens","tags":["Supported Tokens"]}},"/api/supported-tokens/{id}":{"get":{"operationId":"SupportedTokensController_findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportedTokenResDto"}}}},"404":{"description":"Protocol not found"}},"summary":"Get a supported token by id","tags":["Supported Tokens"]}},"/api/v1/simulate/best-positions":{"get":{"operationId":"SimulateController_getBestPositions_v1","parameters":[{"name":"amount","required":true,"in":"query","description":"Amount to simulate","schema":{"minimum":0,"example":1000,"type":"number"}},{"name":"token","required":true,"in":"query","description":"Token symbol to simulate","schema":{"example":"USDC","type":"string"}},{"name":"networks","required":true,"in":"query","description":"Array of network IDs to simulate","schema":{"type":"array","items":{"type":"string"}}},{"name":"strategy","required":true,"in":"query","description":"Strategy to simulate","schema":{"example":"safe_strategy","enum":["not_strategy","safe_strategy","degen_strategy","aave_strategy","async_strategy"],"type":"string"}},{"name":"minSplit","required":false,"in":"query","description":"Minimum number of pools the allocation tries to spread across. Diversification scales with `minSplit`; higher values surface additional pools (within the strategy's eligible universe and the `protocols` filter). The actual number of returned positions can still be lower if the universe is small.","schema":{"minimum":1,"example":2,"type":"number"}},{"name":"protocols","required":false,"in":"query","description":"Comma-separated list of protocol slugs (case-insensitive, spaces ignored) to restrict allocations to. Example: `morpho,compound,spark`. Matched against protocol names like \"Morpho\", \"Compound V3\", \"Aave V3\".","schema":{"type":"array","items":{"type":"string"}}},{"name":"pools","required":false,"in":"query","description":"Comma-separated list of pool name fragments (case-insensitive, spaces ignored) to restrict allocations to. Example: `gauntletusdcprime`. Matched against pool names like \"Gauntlet USDC Prime\".","schema":{"type":"array","items":{"type":"string"}}},{"name":"partOfZyfiTvl","required":false,"in":"query","description":"When true (default), the caller's positions are assumed to already be part of ZyFAI's aggregate on-chain TVL — correct for ZyFAI-managed wallets. When false, ZyFAI's existing footprint is ignored in eligibility checks, showing the pool as fully open from ZyFAI's perspective.","schema":{"default":true,"type":"boolean"}},{"name":"userPositions","required":false,"in":"query","description":"Existing positions the caller already holds. Used as a substitute for ZyFAI TVL in eligibility checks — each entry's TVL is treated as the caller's current footprint in that pool.","schema":{"type":"array","items":{"$ref":"#/components/schemas/UserPositionDto"}}}],"responses":{"200":{"description":"Returns the best positions based on amount, networks, and strategy for simulation purposes. Calldata `parameters` may contain the sentinel `<RECEIVER>`; replace it with the executing wallet address before broadcasting.","paginationType":"offset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BestPositionsResDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"summary":"Get best positions for simulation","tags":["simulate"]}},"/api/v1/simulate/best-crosschain-positions":{"get":{"operationId":"SimulateController_getBestCrosschainPositions_v1","parameters":[{"name":"sourceChain","required":true,"in":"query","description":"Source chain ID","schema":{"example":1,"type":"number"}},{"name":"targetChains","required":true,"in":"query","description":"Array of target chain IDs","schema":{"type":"array","items":{"type":"string"}}},{"name":"token","required":true,"in":"query","description":"Token symbol to simulate","schema":{"example":"USDC","type":"string"}},{"name":"amount","required":true,"in":"query","description":"Amount to simulate for crosschain positions","schema":{"minimum":0,"example":1000,"type":"number"}}],"responses":{"200":{"description":"Returns the best crosschain positions based on source chain, target chains, and amount for simulation purposes","paginationType":"offset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BestCrosschainPositionsResDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"summary":"Get best crosschain positions for simulation","tags":["simulate"]}}},"info":{"title":"Zyfai Execution API","description":"Execution and custody backend for ZyfAI (`/api/v1`). Authenticate with Bearer JWT for user routes, or `Api-Key` for partner/SDK routes. Product documentation: https://docs.zyf.ai","version":"1.0","contact":{"name":"ZyfAI","url":"https://zyf.ai","email":"support@zyf.ai"}},"tags":[],"servers":[{"url":"https://api.zyf.ai","description":"Production"},{"url":"https://staging-api.zyf.ai","description":"Staging"},{"url":"https://api.zyf.ai","description":"Local"}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"},"Api-Key":{"type":"apiKey","in":"header","name":"Api-Key"}},"schemas":{"ErrorDetailDto":{"type":"object","properties":{"property":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"ErrorDto":{"type":"object","properties":{"timestamp":{"type":"string"},"statusCode":{"type":"number"},"error":{"type":"string"},"errorCode":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetailDto"}}},"required":["timestamp","statusCode","error","message"]},"LoginReqDto":{"type":"object","properties":{"message":{"type":"string"},"signature":{"type":"string"},"referralSource":{"type":"string"}},"required":["message","signature"]},"LoginResDto":{"type":"object","properties":{"userId":{"type":"string"},"accessToken":{"type":"string"},"refreshToken":{"type":"string"},"tokenExpires":{"type":"number"},"hasActiveSessionKey":{"type":"boolean"},"smartWallet":{"type":"string","nullable":true},"predeployed":{"type":"boolean"}},"required":["userId","accessToken","refreshToken","tokenExpires","hasActiveSessionKey","smartWallet","predeployed"]},"ChallengeResDto":{"type":"object","properties":{"nonce":{"type":"string"}},"required":["nonce"]},"SupportedTokenResDto":{"type":"object","properties":{"id":{"type":"string"},"chainId":{"type":"number"},"name":{"type":"string"},"symbol":{"type":"string"},"decimals":{"type":"number"},"address":{"type":"string"},"icon":{"type":"string"}},"required":["id","chainId","name","symbol","decimals","address","icon"]},"ProtocolResponseDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"type":{"type":"string","enum":["lending","dex","perpetuals","other"]},"chains":{"type":"array","items":{"type":"number"}},"imageUrl":{"type":"string"},"description":{"type":"string"},"strategies":{"type":"array","items":{"type":"string","enum":["not_strategy","safe_strategy","degen_strategy","aave_strategy","async_strategy"]}},"website":{"type":"string"},"pools":{"type":"array","items":{"type":"string"}},"assets":{"type":"array","items":{"$ref":"#/components/schemas/SupportedTokenResDto"}}},"required":["id","name","type","chains","imageUrl","strategies","website","pools","assets"]},"UserResDto":{"type":"object","properties":{"id":{"type":"string"},"address":{"type":"string"},"protocols":{"$ref":"#/components/schemas/ProtocolResponseDto"},"smartWallet":{"type":"string"},"hasActiveSessionKey":{"type":"boolean"},"email":{"type":"string"},"strategy":{"type":"string"},"telegramId":{"type":"string"},"accountType":{"type":"string"},"autoSelectProtocols":{"type":"boolean"},"autocompounding":{"type":"boolean"},"omniAccount":{"type":"boolean"},"agentName":{"type":"string"},"crosschainStrategy":{"type":"boolean"},"executorProxy":{"type":"boolean"},"splitting":{"type":"boolean"},"v1SmartSessions":{"type":"boolean"},"predeployed":{"type":"boolean"},"ownershipTransferred":{"type":"boolean"}},"required":["id","address","protocols","smartWallet","hasActiveSessionKey","email","strategy","telegramId","accountType","autoSelectProtocols","autocompounding","omniAccount","agentName","crosschainStrategy","executorProxy","splitting","v1SmartSessions","predeployed","ownershipTransferred"]},"GetPositionResDto":{"type":"object","properties":{"hasActiveSessionKey":{"type":"boolean"},"hasBalance":{"type":"boolean"},"predeployed":{"type":"boolean"},"ownershipTransferred":{"type":"boolean"},"splitting":{"type":"boolean"},"minSplits":{"type":"number"}},"required":["hasActiveSessionKey","hasBalance","predeployed","ownershipTransferred","splitting","minSplits"]},"PortfolioResDto":{"type":"object","properties":{"hasActiveSessionKey":{"type":"boolean"},"hasBalance":{"type":"boolean"}},"required":["hasActiveSessionKey","hasBalance"]},"ActivePositionsResDto":{"type":"object","properties":{"hasActiveSessionKey":{"type":"boolean"}},"required":["hasActiveSessionKey"]},"BalanceStatusResDto":{"type":"object","properties":{"hasBalance":{"type":"boolean"}},"required":["hasBalance"]},"WithdrawResDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the withdrawal was queued"},"message":{"type":"string","description":"Human-readable status message"}},"required":["success","message"]},"AgentDepositSetupReqDto":{"type":"object","properties":{"asset":{"type":"string","example":"USDC"},"chainId":{"type":"number","example":8453},"strategy":{"type":"string","enum":["conservative","aggressive","yieldmaxxing"]},"assetTypeSettings":{"type":"object","description":"Single-asset settings payload (one key, matching internal asset type e.g. usdc)","example":{"usdc":{"chains":[8453],"protocols":["protocol-id"],"rebalanceStrategy":"safe_strategy"}}}},"required":["asset","chainId","assetTypeSettings"]},"AgentDepositSetupResDto":{"type":"object","properties":{"applied":{"type":"boolean","description":"True when chain/protocol settings were written; false when chain was already configured"}},"required":["applied"]},"UpdateUserReqDto":{"type":"object","properties":{"smartWallet":{"type":"string","description":"Smart wallet address"},"protocols":{"type":"array","items":{"type":"string"}},"strategy":{"type":"string","description":"Strategy"},"chains":{"type":"array","items":{"type":"number"}},"accountType":{"type":"string","description":"Account type","enum":["EOA","Safe","CoinbaseSmartWallet","ERC4626Wrapper","Unknown"]},"autoSelectProtocols":{"type":"boolean","description":"Auto select protocols"},"omniAccount":{"type":"boolean","description":"Omni account"},"autocompounding":{"type":"boolean","description":"Auto compounding"},"agentName":{"type":"string","description":"Agent name"},"crosschainStrategy":{"type":"boolean","description":"Crosschain strategy"},"executorProxy":{"type":"boolean","description":"Executor proxy enabled"},"splitting":{"type":"boolean","description":"Splitting strategy enabled"},"minSplits":{"type":"number","description":"Minimum number of splits for position allocation"},"assetTypeSettings":{"type":"object","description":"Per-asset-type settings overrides, keyed by asset type (e.g. { \"eth\": { \"protocols\": [\"...\"] } })"}}},"CreateAgentTokenUriReqDto":{"type":"object","properties":{"smartWallet":{"type":"string","description":"Smart wallet address that will be registered as the agent"},"agentName":{"type":"string","description":"Agent display name (stored in the pinned JSON)","example":"Zyfai Rebalancer Agent"},"agentType":{"type":"string","description":"Agent type/category (stored in the pinned JSON)","example":"DeFi Rebalancer"},"description":{"type":"string","description":"Agent description (stored in the pinned JSON)"},"image":{"type":"string","description":"Image URI (http(s):// or ipfs://). If omitted, registry UI may show a default placeholder."}},"required":["smartWallet"]},"CreateAgentTokenUriResDto":{"type":"object","properties":{"tokenUri":{"type":"string","description":"ERC-8004 token URI (ipfs://CID)"},"ipfsHash":{"type":"string","description":"IPFS content identifier"},"gatewayUrl":{"type":"string","description":"HTTPS gateway URL for the pinned JSON"}},"required":["tokenUri","ipfsHash","gatewayUrl"]},"LogDepositReqDto":{"type":"object","properties":{"chainId":{"type":"number"},"transaction":{"type":"string"},"token":{"type":"string"},"amount":{"type":"string"}},"required":["chainId","transaction","token","amount"]},"DepositLifecycleResDto":{"type":"object","properties":{"id":{"type":"string","description":"Persistent deposit lifecycle UUID"},"status":{"type":"string","enum":["handover_pending","credited","recovered_to_eoa"],"description":"Custody and credit lifecycle. Only credited means the balance is available to execute."},"balanceCredited":{"type":"boolean","description":"Whether this deposit has been added to the wallet balance"},"statusUrl":{"type":"string","description":"Authenticated endpoint for polling lifecycle state"}},"required":["id","status","balanceCredited","statusUrl"]},"LogSwapReqDto":{"type":"object","properties":{"chainId":{"type":"number"},"transaction":{"type":"string"},"fromToken":{"type":"string"},"toToken":{"type":"string"},"fromAmount":{"type":"string"},"toAmount":{"type":"string"}},"required":["chainId","transaction","fromToken","toToken","fromAmount","toAmount"]},"RebalancingNotificationDto":{"type":"object","properties":{"timestamp":{"type":"number","example":1704067200000}},"required":["timestamp"]},"AsyncWithdrawalNotificationDto":{"type":"object","properties":{"status":{"type":"string","enum":["requested","claimed"],"example":"requested"},"txHash":{"type":"string","example":"0x1234567890abcdef..."},"amount":{"type":"string","example":"1000000000000000000"},"amountFormatted":{"type":"string","example":"1.0"},"tokenSymbol":{"type":"string","example":"USDC"},"timestamp":{"type":"number","example":1704067200000}},"required":["status","txHash","amount","amountFormatted","tokenSymbol","timestamp"]},"NotificationsResDto":{"type":"object","properties":{"rebalancing":{"$ref":"#/components/schemas/RebalancingNotificationDto"},"withdraw":{"type":"object","description":"Per-chain withdrawal notifications. Keys are chain IDs (e.g., 324 for zkSync)","example":{"324":{"success":true,"txHash":"0x1234...","amount":"1000000000000000000","amountFormatted":"1.0","tokenSymbol":"USDC","timestamp":1704067200000}}},"asyncWithdrawal":{"description":"Per-chain async withdrawal notifications (request submitted / funds redeemed). Keys are chain IDs.","example":{"8453":{"status":"requested","txHash":"0x1234...","amount":"1000000000000000000","amountFormatted":"1.0","tokenSymbol":"USDC","timestamp":1704067200000}},"allOf":[{"$ref":"#/components/schemas/AsyncWithdrawalNotificationDto"}]}}},"UserAutoselectItemDto":{"type":"object","properties":{"smartWallet":{"type":"string","description":"Smart wallet address"},"autoSelectProtocols":{"type":"boolean","description":"Auto select protocols status"}},"required":["smartWallet","autoSelectProtocols"]},"UserAutoselectResDto":{"type":"object","properties":{"users":{"description":"List of users with autoselect status","type":"array","items":{"$ref":"#/components/schemas/UserAutoselectItemDto"}},"total":{"type":"number","description":"Total number of users"},"page":{"type":"number","description":"Current page number"},"limit":{"type":"number","description":"Number of items per page"},"totalPages":{"type":"number","description":"Total number of pages"}},"required":["users","total","page","limit","totalPages"]},"AsyncWithdrawalDto":{"type":"object","properties":{"id":{"type":"string","description":"Tracking entity UUID"},"status":{"type":"string","enum":["REQUESTED","CLAIMABLE","CLAIMED","FAILED"],"description":"REQUESTED → waiting for protocol; CLAIMABLE → claim tx queued; CLAIMED → funds released; FAILED → timed out (not claimable past estimatedClaimAt)"},"chainId":{"type":"number","description":"EVM chain id"},"tokenSymbol":{"type":"string","description":"Underlying token symbol (USDC, WETH, …)"},"tokenAddress":{"type":"string","description":"Underlying token contract address"},"tokenDecimals":{"type":"number","description":"Token decimals (for formatting `amount`)"},"protocolName":{"type":"string","description":"Protocol name (e.g. \"Superform\")"},"poolName":{"type":"string","description":"Pool / vault identifier (e.g. \"USDC\")"},"amount":{"type":"string","description":"Asset amount being redeemed, as a base-units string (apply tokenDecimals to format)"},"withdrawalTarget":{"type":"object","nullable":true,"description":"\"user_eoa\" for user-initiated withdrawals (claimed funds go to EOA); null for rebalancer-initiated (claimed funds get redeployed)"},"estimatedClaimAt":{"type":"object","nullable":true,"description":"ISO timestamp when the protocol is expected to allow claiming. Past this time without claim → status flips to FAILED."},"claimedAt":{"type":"object","nullable":true,"description":"ISO timestamp of successful claim (only for CLAIMED status)"},"requestTxHash":{"type":"object","nullable":true,"description":"Tx hash of the request-withdraw transaction (once confirmed)"},"claimTxHash":{"type":"object","nullable":true,"description":"Tx hash of the claim transaction (once confirmed)"},"retryCount":{"type":"number","description":"Failed claim attempts so far (cron retries indefinitely)"},"createdAt":{"type":"string","description":"ISO timestamp when the request was submitted"},"statusMessage":{"type":"object","nullable":true,"description":"User-facing pause / delay copy when the protocol is temporarily refusing claims (e.g. IPOR weekend pause)."}},"required":["id","status","chainId","tokenSymbol","tokenAddress","tokenDecimals","protocolName","poolName","amount","withdrawalTarget","estimatedClaimAt","claimedAt","requestTxHash","claimTxHash","retryCount","createdAt","statusMessage"]},"AsyncWithdrawalsResDto":{"type":"object","properties":{"withdrawals":{"type":"array","items":{"$ref":"#/components/schemas/AsyncWithdrawalDto"}}},"required":["withdrawals"]},"PartialWithdrawReqDto":{"type":"object","properties":{"chainId":{"type":"number","description":"Chain ID where the partial withdrawal should occur","example":8453},"tokenSymbol":{"type":"string","description":"Token symbol to withdraw. Defaults to USDC (Base/Arbitrum/Mainnet), USDC.e (Sonic), USDT0 (Plasma)","example":"USDC"},"amount":{"type":"string","description":"Amount to withdraw in token units (as string to handle large numbers taking into account the decimals)","example":"1000000"}},"required":["chainId","amount"]},"PartialWithdrawResDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the partial withdrawal was successful","example":true},"message":{"type":"string","description":"Message describing the result of the operation","example":"Partial withdrawal initiated successfully"},"transactionId":{"type":"string","description":"Transaction ID if withdrawal was submitted to blockchain","example":"pending"}},"required":["success","message"]},"UpdateTelegramIdReqDto":{"type":"object","properties":{"telegramId":{"type":"string","description":"Telegram user ID to associate with the wallet"},"smartWallet":{"type":"string","description":"User smart wallet address (checksummed or lowercase)"}},"required":["telegramId","smartWallet"]},"UpdateTelegramResDto":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}},"required":["success","message"]},"ResetTelegramResDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the operation was successful","example":true},"message":{"type":"string","description":"Message describing the result","example":"Telegram ID reset successfully"}},"required":["success","message"]},"AddSessionKeyReqDto":{"type":"object","properties":{"hash":{"type":"string"},"nonces":{"type":"array","items":{"type":"string"}},"chainId":{"type":"number"}}},"SessionKeyResDto":{"type":"object","properties":{"id":{"type":"string","description":"Session key UUID"},"signer":{"type":"string","description":"Session signer address"},"expiresAt":{"format":"date-time","type":"string","description":"Session key expiration timestamp"},"hash":{"type":"string","description":"Permission enable hash or empty for intent-only keys"},"permissionEnableHash":{"type":"string","nullable":true},"permissionId":{"type":"string","nullable":true},"txHash":{"type":"string","nullable":true},"isEnabled":{"type":"boolean"},"isActive":{"type":"boolean"},"customHash":{"type":"string","nullable":true},"nonces":{"description":"Session nonces used when signing","type":"array","items":{"type":"number"}}},"required":["id","signer","expiresAt","hash","isEnabled","isActive","nonces"]},"WalletHistory":{"type":"object","properties":{"id":{"type":"string"},"action":{"type":"string"},"date":{"format":"date-time","type":"string"},"chainId":{"type":"number"},"destinationChainId":{"type":"number"},"transactionHash":{"type":"string"},"strategy":{"type":"string"},"positions":{"type":"array","items":{"type":"string"}},"sourceChains":{"type":"array","items":{"type":"string"}},"feeAmount":{"type":"string"},"rewards":{"type":"string"},"tokenId":{"type":"string"},"crosschain":{"type":"boolean"},"rebalance":{"type":"boolean"},"rebalanceLog":{"type":"object"},"rebalanceReasons":{"type":"array","items":{"type":"string"}},"rebalanceDetails":{"type":"object","description":"Structured rebalance explanation: { version, type: APY_IMPROVEMENT | FORCED_EXIT | NO_HEALTHY_POOL, apyBefore, apyAfter, exits: [{ pool, apy, checks: [{ code, value?, limit? }] }], targets: [{ pool, amount, apy, health }] }"},"totalBalance":{"type":"string"},"zkProofIpfsHash":{"type":"string"},"validationRegistryTxHash":{"type":"string"},"validationRegistryChainId":{"type":"number"},"validationRegistryAddress":{"type":"string"},"feeData":{"type":"object"}},"required":["id","action","date","chainId","destinationChainId","transactionHash","strategy","positions","sourceChains"]},"WalletHistoryResponseDto":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WalletHistory"}},"total":{"type":"number"}},"required":["data","total"]},"SelectedPoolsResDto":{"type":"object","properties":{"pools":{"description":"Selected pool names","type":"array","items":{"type":"string"}},"autoselect":{"type":"boolean","description":"Whether autoselect is enabled for this protocol"}},"required":["pools","autoselect"]},"CustomizeReqDto":{"type":"object","properties":{"protocolId":{"type":"string","description":"Protocol ID"},"pools":{"description":"Array of pool names","type":"array","items":{"type":"string"}},"chainId":{"type":"number","description":"Chain ID"},"assetType":{"type":"string","description":"Asset type","enum":["usdc","eth","cbeth","wbtc","cbbtc","eurc","usdt","pyusd","nvdac","googlc","aaplc","metac"]},"autoselect":{"type":"boolean","description":"Autoselect"}},"required":["protocolId","pools","chainId","autoselect"]},"CustomizationResDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the customization was saved"}},"required":["success"]},"UserPositionDto":{"type":"object","properties":{"protocol":{"type":"string","description":"Protocol name","example":"Morpho"},"pool":{"type":"string","description":"Pool name","example":"Gauntlet USDC Prime"},"tvl":{"type":"number","description":"Existing TVL in USD","example":1000,"minimum":0}},"required":["protocol","pool","tvl"]},"BestPositionsResDto":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","description":"Best simulated positions keyed by chain ID"},"messages":{"type":"object","description":"Human-readable messages keyed by chain ID"},"excluded":{"type":"object","description":"Pools considered but not selected, keyed by chain ID"}},"required":["success","data","messages","excluded"]},"BestCrosschainPositionsResDto":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","description":"Best cross-chain opportunity (highest simulated APY across target chains), or undefined when none qualify"}},"required":["success"]}}}}