{ "openapi": "3.1.0", "info": { "title": "Turtle Earn API — v2", "version": "v2.0.0" }, "paths": { "/v2/actions/cancel-deposit/{opportunityId}": { "post": { "tags": [ "Actions" ], "summary": "Create Cancel Deposit Interaction", "description": "Cancel a pending async deposit.", "operationId": "CreateCancelDepositInteraction", "parameters": [ { "name": "opportunityId", "in": "path", "description": "Opportunity unique identifier", "required": true, "schema": { "$ref": "#/components/schemas/UuidUUID", "description": "Opportunity unique identifier" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionsCancelDepositRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionsInteractionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/actions/claim-deposit/{opportunityId}": { "post": { "tags": [ "Actions" ], "summary": "Create Claim Deposit Interaction", "description": "Claim a pending async deposit. Only requires user wallet address.", "operationId": "CreateClaimDepositInteraction", "parameters": [ { "name": "opportunityId", "in": "path", "description": "Opportunity unique identifier", "required": true, "schema": { "$ref": "#/components/schemas/UuidUUID", "description": "Opportunity unique identifier" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionsClaimDepositRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionsInteractionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/actions/deposit/{opportunityId}": { "post": { "tags": [ "Actions" ], "summary": "Create Deposit Interaction", "description": "Record a deposit interaction", "operationId": "CreateDepositInteraction", "parameters": [ { "name": "opportunityId", "in": "path", "description": "Opportunity unique identifier", "required": true, "schema": { "$ref": "#/components/schemas/UuidUUID", "description": "Opportunity unique identifier" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionsInteractionRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionsInteractionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/actions/verify": { "get": { "tags": [ "Actions" ], "summary": "Verify Tracking", "description": "Verify the Turtle attribution carried by a transaction", "operationId": "VerifyTracking", "parameters": [ { "name": "chainId", "in": "query", "description": "Chain ID where the transaction was executed", "required": true, "schema": { "description": "Chain ID where the transaction was executed", "type": "integer" } }, { "name": "txHash", "in": "query", "description": "Transaction hash to verify", "required": true, "schema": { "description": "Transaction hash to verify", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionsVerifyTrackingResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/actions/withdraw/{opportunityId}": { "post": { "tags": [ "Actions" ], "summary": "Create Withdraw Interaction", "description": "Record a withdraw interaction", "operationId": "CreateWithdrawInteraction", "parameters": [ { "name": "opportunityId", "in": "path", "description": "Opportunity unique identifier", "required": true, "schema": { "$ref": "#/components/schemas/UuidUUID", "description": "Opportunity unique identifier" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionsWithdrawRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionsInteractionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/attribution/{txHash}": { "get": { "tags": [ "Attribution" ], "summary": "Get Distribute Attribution", "description": "Public ERC-8021 Schema 2 attribution debugger. Looks up the transaction in the Lumon watcher tables and the interactions ledger. When chainId is provided, also inspects calldata for an ERC-8021 suffix or the legacy 0xdeadbeef tracker. Does not require authentication.", "operationId": "GetAttribution", "parameters": [ { "name": "chainId", "in": "query", "description": "Chain the transaction was executed on. Narrows the lookup and enables calldata inspection.", "schema": { "description": "Chain the transaction was executed on. Narrows the lookup and enables calldata inspection.", "minimum": 1, "type": [ "null", "integer" ] } }, { "name": "txHash", "in": "path", "description": "Transaction hash", "required": true, "schema": { "description": "Transaction hash", "pattern": "^0[xX][0-9a-fA-F]{64}$", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributionResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/chains/": { "get": { "tags": [ "Chains" ], "summary": "Get Supported Chains", "description": "Returns all supported chains with pagination. Chains are filtered to active status only.", "operationId": "GetChains", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "pageLimit", "in": "query", "schema": { "type": "integer" } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginationPaginatedResponseGithubComTurtleDAOTurtlePartnersGoServicesEarnHandlersV2SharedChainResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/deposit/{distributorId}": { "get": { "tags": [ "Deposits" ], "summary": "Get Distributor Deposits", "description": "Get paginated verified deposit interactions for a specific distributor, ordered by date descending. Optionally filter by opportunityId and/or productId.", "operationId": "GetDistributorDeposits", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "opportunityId", "in": "query", "description": "Optional opportunity UUID to filter deposits", "schema": { "description": "Optional opportunity UUID to filter deposits", "type": "string" } }, { "name": "productId", "in": "query", "description": "Optional product UUID to filter deposits to opportunities belonging to that product", "schema": { "description": "Optional product UUID to filter deposits to opportunities belonging to that product", "type": "string" } }, { "name": "distributorId", "in": "path", "description": "Distributor ID to filter deposits", "required": true, "schema": { "description": "Distributor ID to filter deposits", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionsDistributorDepositsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/interactions/": { "get": { "tags": [ "Interactions" ], "summary": "List Interactions", "description": "Returns paginated verified earn interactions (deposits and withdrawals), ordered by date descending by default. Optionally filter by interactionType, distributorId, opportunityId and/or productId.", "operationId": "ListInteractions", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "pageLimit", "in": "query", "schema": { "type": "integer" } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer" } }, { "name": "interactionType", "in": "query", "description": "Filter by interaction type: 'deposit' or 'withdraw' (absent returns both)", "schema": { "description": "Filter by interaction type: 'deposit' or 'withdraw' (absent returns both)", "enum": [ "deposit", "withdraw" ], "type": "string" } }, { "name": "distributorId", "in": "query", "description": "Optional distributor ID to scope interactions", "schema": { "description": "Optional distributor ID to scope interactions", "type": "string" } }, { "name": "opportunityId", "in": "query", "description": "Optional opportunity UUID to scope interactions", "schema": { "description": "Optional opportunity UUID to scope interactions", "type": "string" } }, { "name": "productId", "in": "query", "description": "Optional product UUID to scope interactions to opportunities belonging to that product", "schema": { "description": "Optional product UUID to scope interactions to opportunities belonging to that product", "type": "string" } }, { "name": "sortBy", "in": "query", "description": "One of: date, usdValue, amount, opportunity, distributor, wallet, type (defaults to date)", "schema": { "description": "One of: date, usdValue, amount, opportunity, distributor, wallet, type (defaults to date)", "type": "string" } }, { "name": "sortOrder", "in": "query", "description": "asc or desc (defaults to desc)", "schema": { "description": "asc or desc (defaults to desc)", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginationPaginatedResponseGithubComTurtleDAOTurtlePartnersGoServicesEarnHandlersV2ActionsWalletActivityItem" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/membership/": { "get": { "tags": [ "Membership" ], "summary": "Check Membership", "description": "Check if a wallet address is associated with a user", "operationId": "GetMembership", "parameters": [ { "name": "address", "in": "query", "description": "Wallet address to check", "required": true, "schema": { "description": "Wallet address to check", "type": "string" } }, { "name": "walletEcosystem", "in": "query", "description": "Wallet ecosystem", "schema": { "default": "evm", "description": "Wallet ecosystem", "enum": [ "evm", "solana", "ton" ], "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2GetMembershipOutput" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } }, "post": { "tags": [ "Membership" ], "summary": "Create Membership", "description": "Create a new user and associate wallet (signup only, no session)", "operationId": "CreateMembership", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2CreateMembershipInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2CreateMembershipOutput" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/membership/agreement": { "post": { "tags": [ "Membership" ], "summary": "Create Membership Agreement", "description": "Generate a message to be signed by a new wallet for signup", "operationId": "CreateMembershipAgreement", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2CreateMembershipAgreementInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2CreateMembershipAgreementOutput" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/metrics/distributor/{distributorId}": { "get": { "tags": [ "Analytics" ], "summary": "Get Distributor TVL", "description": "TVL time-series attributed to a distributor (builder code), with optional top wallets.", "operationId": "GetDistributorMetrics", "parameters": [ { "name": "startDate", "in": "query", "description": "Start of range (RFC 3339)", "required": true, "schema": { "description": "Start of range (RFC 3339)", "format": "date-time", "type": "string" } }, { "name": "endDate", "in": "query", "description": "End of range (RFC 3339)", "required": true, "schema": { "description": "End of range (RFC 3339)", "format": "date-time", "type": "string" } }, { "name": "step", "in": "query", "description": "Bucket size in seconds (default 900)", "schema": { "description": "Bucket size in seconds (default 900)", "minimum": 0, "type": [ "null", "integer" ] } }, { "name": "opportunityIds", "in": "query", "description": "Optional opportunity UUID filter", "schema": { "$ref": "#/components/schemas/UuidUUIDs", "description": "Optional opportunity UUID filter" } }, { "name": "productIds", "in": "query", "description": "Optional product UUID filter", "schema": { "$ref": "#/components/schemas/UuidUUIDs", "description": "Optional product UUID filter" } }, { "name": "includeTopWallets", "in": "query", "description": "Include the top 50 wallets by attributed TVL", "schema": { "description": "Include the top 50 wallets by attributed TVL", "type": "boolean" } }, { "name": "distributorId", "in": "path", "description": "Distributor ID (builder code)", "required": true, "schema": { "description": "Distributor ID (builder code)", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricsGetDistributorMetricsOutput" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/metrics/distributor/{distributorId}/lps": { "get": { "tags": [ "Analytics" ], "summary": "Get Distributor LP Counts", "description": "Active and cumulative LP counts attributed to a distributor over time.", "operationId": "GetDistributorLPs", "parameters": [ { "name": "startDate", "in": "query", "description": "Start of range (RFC 3339)", "required": true, "schema": { "description": "Start of range (RFC 3339)", "format": "date-time", "type": "string" } }, { "name": "endDate", "in": "query", "description": "End of range (RFC 3339)", "required": true, "schema": { "description": "End of range (RFC 3339)", "format": "date-time", "type": "string" } }, { "name": "step", "in": "query", "description": "Bucket size in seconds (default 900)", "schema": { "description": "Bucket size in seconds (default 900)", "minimum": 0, "type": [ "null", "integer" ] } }, { "name": "opportunityIds", "in": "query", "description": "Optional opportunity UUID filter", "schema": { "$ref": "#/components/schemas/UuidUUIDs", "description": "Optional opportunity UUID filter" } }, { "name": "productIds", "in": "query", "description": "Optional product UUID filter", "schema": { "$ref": "#/components/schemas/UuidUUIDs", "description": "Optional product UUID filter" } }, { "name": "distributorId", "in": "path", "description": "Distributor ID (builder code)", "required": true, "schema": { "description": "Distributor ID (builder code)", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricsGetDistributorLPsOutput" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/opportunities/": { "get": { "tags": [ "Opportunities" ], "summary": "List Opportunities", "description": "Returns active opportunities with pagination, filtering and sorting. Deposit/withdrawal availability is reported per opportunity in meta. Use /opportunities/filter-options to discover valid filter and sort values.", "operationId": "ListOpportunities", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "pageLimit", "in": "query", "schema": { "type": "integer" } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer" } }, { "name": "search", "in": "query", "description": "Case-insensitive match on name, description or token address", "schema": { "description": "Case-insensitive match on name, description or token address", "type": "string" } }, { "name": "chainIds", "in": "query", "description": "Comma-separated numeric chain IDs (deposit tokens), e.g. '1,43114'", "schema": { "description": "Comma-separated numeric chain IDs (deposit tokens), e.g. '1,43114'", "type": "string" } }, { "name": "depositToken", "in": "query", "description": "Deposit token in 'address-chainId' format, e.g. '0xb31f...-43114'", "schema": { "description": "Deposit token in 'address-chainId' format, e.g. '0xb31f...-43114'", "type": "string" } }, { "name": "depositTokenSymbols", "in": "query", "description": "Comma-separated deposit token symbols (case-insensitive, OR logic)", "schema": { "description": "Comma-separated deposit token symbols (case-insensitive, OR logic)", "type": "string" } }, { "name": "tags", "in": "query", "description": "Comma-separated tag codes", "schema": { "description": "Comma-separated tag codes", "type": "string" } }, { "name": "curatorId", "in": "query", "description": "Comma-separated curator organization ids", "schema": { "description": "Comma-separated curator organization ids", "type": "string" } }, { "name": "providerId", "in": "query", "description": "Comma-separated provider organization ids", "schema": { "description": "Comma-separated provider organization ids", "type": "string" } }, { "name": "partnerId", "in": "query", "description": "Comma-separated partner organization ids", "schema": { "description": "Comma-separated partner organization ids", "type": "string" } }, { "name": "lendingProtocolId", "in": "query", "description": "Comma-separated lending protocol organization ids", "schema": { "description": "Comma-separated lending protocol organization ids", "type": "string" } }, { "name": "tvlMin", "in": "query", "description": "Minimum TVL in USD", "schema": { "description": "Minimum TVL in USD", "type": "number" } }, { "name": "tvlMax", "in": "query", "description": "Maximum TVL in USD", "schema": { "description": "Maximum TVL in USD", "type": "number" } }, { "name": "minApr", "in": "query", "description": "Minimum estimated APR", "schema": { "description": "Minimum estimated APR", "type": "number" } }, { "name": "maxApr", "in": "query", "description": "Maximum estimated APR", "schema": { "description": "Maximum estimated APR", "type": "number" } }, { "name": "featured", "in": "query", "description": "Filter by featured flag", "schema": { "description": "Filter by featured flag", "type": [ "null", "boolean" ] } }, { "name": "directInteractionEnabled", "in": "query", "description": "When true, only opportunities with direct interaction enabled", "schema": { "description": "When true, only opportunities with direct interaction enabled", "type": "boolean" } }, { "name": "routedSwapEnabled", "in": "query", "description": "When true, only opportunities with routed swap entry enabled", "schema": { "description": "When true, only opportunities with routed swap entry enabled", "type": "boolean" } }, { "name": "depositEnabled", "in": "query", "description": "When true, only opportunities with deposits enabled", "schema": { "description": "When true, only opportunities with deposits enabled", "type": "boolean" } }, { "name": "withdrawEnabled", "in": "query", "description": "When true, only opportunities with withdrawals enabled", "schema": { "description": "When true, only opportunities with withdrawals enabled", "type": "boolean" } }, { "name": "asyncDeposit", "in": "query", "description": "When true, only opportunities with asynchronous deposits", "schema": { "description": "When true, only opportunities with asynchronous deposits", "type": "boolean" } }, { "name": "asyncWithdraw", "in": "query", "description": "When true, only opportunities with asynchronous withdrawals", "schema": { "description": "When true, only opportunities with asynchronous withdrawals", "type": "boolean" } }, { "name": "includeDeltas", "in": "query", "description": "When true, include each opportunity's TVL, LP count and APY with their movement over the trailing day, week and month", "schema": { "description": "When true, include each opportunity's TVL, LP count and APY with their movement over the trailing day, week and month", "type": "boolean" } }, { "name": "sortBy", "in": "query", "description": "One of: tvl, name, type, apr, curator, provider, tvlD1, tvlD7, tvlD30, lpsD1, lpsD7, lpsD30, growthApyD1, growthApyD7, growthApyD30 (defaults to tvl). An unknown value is rejected", "schema": { "description": "One of: tvl, name, type, apr, curator, provider, tvlD1, tvlD7, tvlD30, lpsD1, lpsD7, lpsD30, growthApyD1, growthApyD7, growthApyD30 (defaults to tvl). An unknown value is rejected", "type": "string" } }, { "name": "sortOrder", "in": "query", "description": "asc or desc (defaults to desc)", "schema": { "description": "asc or desc (defaults to desc)", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginationPaginatedResponseGithubComTurtleDAOTurtlePartnersGoServicesEarnHandlersV2OpportunitiesOpportunityResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/opportunities/distributors/{distributorId}": { "get": { "tags": [ "Opportunities" ], "summary": "List Opportunities By Distributor", "description": "Returns active opportunities visible to a distributor (per its earn details configuration), with the same pagination, filtering and sorting as /opportunities.", "operationId": "ListOpportunitiesByDistributor", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "pageLimit", "in": "query", "schema": { "type": "integer" } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer" } }, { "name": "search", "in": "query", "description": "Case-insensitive match on name, description or token address", "schema": { "description": "Case-insensitive match on name, description or token address", "type": "string" } }, { "name": "chainIds", "in": "query", "description": "Comma-separated numeric chain IDs (deposit tokens), e.g. '1,43114'", "schema": { "description": "Comma-separated numeric chain IDs (deposit tokens), e.g. '1,43114'", "type": "string" } }, { "name": "depositToken", "in": "query", "description": "Deposit token in 'address-chainId' format, e.g. '0xb31f...-43114'", "schema": { "description": "Deposit token in 'address-chainId' format, e.g. '0xb31f...-43114'", "type": "string" } }, { "name": "depositTokenSymbols", "in": "query", "description": "Comma-separated deposit token symbols (case-insensitive, OR logic)", "schema": { "description": "Comma-separated deposit token symbols (case-insensitive, OR logic)", "type": "string" } }, { "name": "tags", "in": "query", "description": "Comma-separated tag codes", "schema": { "description": "Comma-separated tag codes", "type": "string" } }, { "name": "curatorId", "in": "query", "description": "Comma-separated curator organization ids", "schema": { "description": "Comma-separated curator organization ids", "type": "string" } }, { "name": "providerId", "in": "query", "description": "Comma-separated provider organization ids", "schema": { "description": "Comma-separated provider organization ids", "type": "string" } }, { "name": "partnerId", "in": "query", "description": "Comma-separated partner organization ids", "schema": { "description": "Comma-separated partner organization ids", "type": "string" } }, { "name": "lendingProtocolId", "in": "query", "description": "Comma-separated lending protocol organization ids", "schema": { "description": "Comma-separated lending protocol organization ids", "type": "string" } }, { "name": "tvlMin", "in": "query", "description": "Minimum TVL in USD", "schema": { "description": "Minimum TVL in USD", "type": "number" } }, { "name": "tvlMax", "in": "query", "description": "Maximum TVL in USD", "schema": { "description": "Maximum TVL in USD", "type": "number" } }, { "name": "minApr", "in": "query", "description": "Minimum estimated APR", "schema": { "description": "Minimum estimated APR", "type": "number" } }, { "name": "maxApr", "in": "query", "description": "Maximum estimated APR", "schema": { "description": "Maximum estimated APR", "type": "number" } }, { "name": "featured", "in": "query", "description": "Filter by featured flag", "schema": { "description": "Filter by featured flag", "type": [ "null", "boolean" ] } }, { "name": "directInteractionEnabled", "in": "query", "description": "When true, only opportunities with direct interaction enabled", "schema": { "description": "When true, only opportunities with direct interaction enabled", "type": "boolean" } }, { "name": "routedSwapEnabled", "in": "query", "description": "When true, only opportunities with routed swap entry enabled", "schema": { "description": "When true, only opportunities with routed swap entry enabled", "type": "boolean" } }, { "name": "depositEnabled", "in": "query", "description": "When true, only opportunities with deposits enabled", "schema": { "description": "When true, only opportunities with deposits enabled", "type": "boolean" } }, { "name": "withdrawEnabled", "in": "query", "description": "When true, only opportunities with withdrawals enabled", "schema": { "description": "When true, only opportunities with withdrawals enabled", "type": "boolean" } }, { "name": "asyncDeposit", "in": "query", "description": "When true, only opportunities with asynchronous deposits", "schema": { "description": "When true, only opportunities with asynchronous deposits", "type": "boolean" } }, { "name": "asyncWithdraw", "in": "query", "description": "When true, only opportunities with asynchronous withdrawals", "schema": { "description": "When true, only opportunities with asynchronous withdrawals", "type": "boolean" } }, { "name": "includeDeltas", "in": "query", "description": "When true, include each opportunity's TVL, LP count and APY with their movement over the trailing day, week and month", "schema": { "description": "When true, include each opportunity's TVL, LP count and APY with their movement over the trailing day, week and month", "type": "boolean" } }, { "name": "sortBy", "in": "query", "description": "One of: tvl, name, type, apr, curator, provider, tvlD1, tvlD7, tvlD30, lpsD1, lpsD7, lpsD30, growthApyD1, growthApyD7, growthApyD30 (defaults to tvl). An unknown value is rejected", "schema": { "description": "One of: tvl, name, type, apr, curator, provider, tvlD1, tvlD7, tvlD30, lpsD1, lpsD7, lpsD30, growthApyD1, growthApyD7, growthApyD30 (defaults to tvl). An unknown value is rejected", "type": "string" } }, { "name": "sortOrder", "in": "query", "description": "asc or desc (defaults to desc)", "schema": { "description": "asc or desc (defaults to desc)", "type": "string" } }, { "name": "distributorId", "in": "path", "description": "Distributor ID whose earn details config scopes the results", "required": true, "schema": { "description": "Distributor ID whose earn details config scopes the results", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginationPaginatedResponseGithubComTurtleDAOTurtlePartnersGoServicesEarnHandlersV2OpportunitiesOpportunityResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/opportunities/filter-options": { "get": { "tags": [ "Opportunities" ], "summary": "Get Opportunity Filter Options", "description": "Returns the distinct filter dimensions (chains, providers, curators, partners, tags, lending protocols, deposit token symbols) and the valid sort options for the opportunities list.", "operationId": "GetOpportunityFilterOptions", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunitiesGetOpportunitiesFilterOptionsOutput" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/opportunities/{chainId}/{vaultAddress}/historical": { "get": { "tags": [ "Historical Data" ], "summary": "Get Vault Historical Data", "description": "Get combined historical time-series (TVL, share price, base APY) for a vault, bucketed by interval over [from, to].", "operationId": "GetOpportunityHistorical", "parameters": [ { "name": "step", "in": "query", "description": "Point spacing (granularity) in seconds, at most 31536000 (365 days). Defaults to 86400 (1 day). The range may span at most 10,000 buckets at this step", "schema": { "default": 86400, "description": "Point spacing (granularity) in seconds, at most 31536000 (365 days). Defaults to 86400 (1 day). The range may span at most 10,000 buckets at this step", "maximum": 31536000, "minimum": 1, "type": "integer" } }, { "name": "apyInterval", "in": "query", "description": "APY/APR trailing window (lookback) in seconds, independent of step, at most 7776000 (90 days). Defaults to 2592000 (30 days)", "schema": { "default": 2592000, "description": "APY/APR trailing window (lookback) in seconds, independent of step, at most 7776000 (90 days). Defaults to 2592000 (30 days)", "maximum": 7776000, "minimum": 1, "type": "integer" } }, { "name": "startDate", "in": "query", "description": "Inclusive lower bound (RFC3339/ISO-8601). At most 365 days before now", "required": true, "schema": { "description": "Inclusive lower bound (RFC3339/ISO-8601). At most 365 days before now", "format": "date-time", "type": "string" } }, { "name": "endDate", "in": "query", "description": "Inclusive upper bound (RFC3339/ISO-8601). Omit it — or send a future instant — to mean \"the latest data available\"; clients that want a live trailing series should do that rather than sending a client clock, so the query key stays stable while the answer keeps moving.", "schema": { "description": "Inclusive upper bound (RFC3339/ISO-8601). Omit it — or send a future instant — to mean \"the latest data available\"; clients that want a live trailing series should do that rather than sending a client clock, so the query key stays stable while the answer keeps moving.", "format": "date-time", "type": "string" } }, { "name": "chainId", "in": "path", "description": "EVM chain ID (e.g. 1 for Ethereum)", "required": true, "schema": { "description": "EVM chain ID (e.g. 1 for Ethereum)", "minimum": 1, "type": "integer" } }, { "name": "vaultAddress", "in": "path", "description": "0x-prefixed 40-hex vault contract address", "required": true, "schema": { "description": "0x-prefixed 40-hex vault contract address", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunitiesGetOpportunityHistoricalResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/opportunities/{chainId}/{vaultAddress}/historical/apr": { "get": { "tags": [ "Historical Data" ], "summary": "Get Vault Historical APR", "description": "Simple-rate (non-compound) APR per point over [from, to]. Each point annualizes share-price growth over effectiveIntervalSeconds, the real span between its two snapshots, which is at least the trailing apyInterval window (seconds) and can exceed it on a sparse series; points are spaced by step (granularity), independent of apyInterval. Reward APR is reserved for future rewards indexing and is always 0. Withheld series carry a machine-readable reason: INDEXING_NOT_STARTED or INDEXING_STALLED on 503 (both still resolvable, with a Retry-After hint), PROTOCOL_UNSUPPORTED on 404 (permanent — the vault's protocol has no price indexer, so no retry can ever succeed). Switch on reason rather than matching the error prose. The indexing-status endpoint reports the same state without erroring.", "operationId": "GetOpportunityHistoricalAPR", "parameters": [ { "name": "step", "in": "query", "description": "Point spacing (granularity) in seconds, at most 31536000 (365 days). Defaults to 86400 (1 day). The range may span at most 10,000 buckets at this step", "schema": { "default": 86400, "description": "Point spacing (granularity) in seconds, at most 31536000 (365 days). Defaults to 86400 (1 day). The range may span at most 10,000 buckets at this step", "maximum": 31536000, "minimum": 1, "type": "integer" } }, { "name": "apyInterval", "in": "query", "description": "APY/APR trailing window (lookback) in seconds, independent of step, at most 7776000 (90 days). Defaults to 2592000 (30 days)", "schema": { "default": 2592000, "description": "APY/APR trailing window (lookback) in seconds, independent of step, at most 7776000 (90 days). Defaults to 2592000 (30 days)", "maximum": 7776000, "minimum": 1, "type": "integer" } }, { "name": "startDate", "in": "query", "description": "Inclusive lower bound (RFC3339/ISO-8601). At most 365 days before now", "required": true, "schema": { "description": "Inclusive lower bound (RFC3339/ISO-8601). At most 365 days before now", "format": "date-time", "type": "string" } }, { "name": "endDate", "in": "query", "description": "Inclusive upper bound (RFC3339/ISO-8601). Omit it — or send a future instant — to mean \"the latest data available\"; clients that want a live trailing series should do that rather than sending a client clock, so the query key stays stable while the answer keeps moving.", "schema": { "description": "Inclusive upper bound (RFC3339/ISO-8601). Omit it — or send a future instant — to mean \"the latest data available\"; clients that want a live trailing series should do that rather than sending a client clock, so the query key stays stable while the answer keeps moving.", "format": "date-time", "type": "string" } }, { "name": "chainId", "in": "path", "description": "EVM chain ID (e.g. 1 for Ethereum)", "required": true, "schema": { "description": "EVM chain ID (e.g. 1 for Ethereum)", "minimum": 1, "type": "integer" } }, { "name": "vaultAddress", "in": "path", "description": "0x-prefixed 40-hex vault contract address", "required": true, "schema": { "description": "0x-prefixed 40-hex vault contract address", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunitiesGetOpportunityHistoricalAPRResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "404": { "description": "The vault's protocol has no price indexer, so this series will never exist. Permanent — do not retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunitiesWithholdErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "503": { "description": "The vault's price series is withheld: the indexer has not checkpointed it yet (INDEXING_NOT_STARTED) or stalled and was withheld by the monitor (INDEXING_STALLED). Switch on reason; retry after the Retry-After response header (seconds).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunitiesWithholdErrResponse" } } } } } } }, "/v2/opportunities/{chainId}/{vaultAddress}/historical/apy": { "get": { "tags": [ "Historical Data" ], "summary": "Get Vault Historical APY", "description": "Compound APY from one canonical growth source over [from, to]. Each point annualizes growth over effectiveIntervalSeconds, the actual span between snapshots, at least the trailing apyInterval. Points are spaced by step. NAV sources measure USD growth. Reward APY is always 0. Missing or unindexed sources return 503 INDEXING_NOT_STARTED; paused or withheld sources return 503 INDEXING_STALLED. Ambiguous source mappings return 412. Coverage describes the selected growth source. The indexing-status endpoint still reports the legacy vault indexer.", "operationId": "GetOpportunityHistoricalAPY", "parameters": [ { "name": "step", "in": "query", "description": "Point spacing (granularity) in seconds, at most 31536000 (365 days). Defaults to 86400 (1 day). The range may span at most 10,000 buckets at this step", "schema": { "default": 86400, "description": "Point spacing (granularity) in seconds, at most 31536000 (365 days). Defaults to 86400 (1 day). The range may span at most 10,000 buckets at this step", "maximum": 31536000, "minimum": 1, "type": "integer" } }, { "name": "apyInterval", "in": "query", "description": "APY/APR trailing window (lookback) in seconds, independent of step, at most 7776000 (90 days). Defaults to 2592000 (30 days)", "schema": { "default": 2592000, "description": "APY/APR trailing window (lookback) in seconds, independent of step, at most 7776000 (90 days). Defaults to 2592000 (30 days)", "maximum": 7776000, "minimum": 1, "type": "integer" } }, { "name": "startDate", "in": "query", "description": "Inclusive lower bound (RFC3339/ISO-8601). At most 365 days before now", "required": true, "schema": { "description": "Inclusive lower bound (RFC3339/ISO-8601). At most 365 days before now", "format": "date-time", "type": "string" } }, { "name": "endDate", "in": "query", "description": "Inclusive upper bound (RFC3339/ISO-8601). Omit it — or send a future instant — to mean \"the latest data available\"; clients that want a live trailing series should do that rather than sending a client clock, so the query key stays stable while the answer keeps moving.", "schema": { "description": "Inclusive upper bound (RFC3339/ISO-8601). Omit it — or send a future instant — to mean \"the latest data available\"; clients that want a live trailing series should do that rather than sending a client clock, so the query key stays stable while the answer keeps moving.", "format": "date-time", "type": "string" } }, { "name": "chainId", "in": "path", "description": "EVM chain ID (e.g. 1 for Ethereum)", "required": true, "schema": { "description": "EVM chain ID (e.g. 1 for Ethereum)", "minimum": 1, "type": "integer" } }, { "name": "vaultAddress", "in": "path", "description": "0x-prefixed 40-hex vault contract address", "required": true, "schema": { "description": "0x-prefixed 40-hex vault contract address", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunitiesGetOpportunityHistoricalAPYResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "412": { "description": "Precondition Failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "503": { "description": "The vault's price series is withheld: the indexer has not checkpointed it yet (INDEXING_NOT_STARTED) or stalled and was withheld by the monitor (INDEXING_STALLED). Switch on reason; retry after the Retry-After response header (seconds).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunitiesWithholdErrResponse" } } } } } } }, "/v2/opportunities/{chainId}/{vaultAddress}/historical/lps": { "get": { "tags": [ "Historical Data" ], "summary": "Get Vault Historical LP Counts", "description": "Get the LP-count time-series of the opportunities behind a vault: active and cumulative participated holders of its receipt tokens, both restricted to distributor-sourced positions and over every holder. Buckets are aligned inwards to the step, which defaults to 900 seconds and must be a positive multiple of it. A vault with no receipt tokens or no metrics answers 200 with an empty series.", "operationId": "GetOpportunityHistoricalLPs", "parameters": [ { "name": "startDate", "in": "query", "description": "Start of range (RFC3339). Aligned inwards to the bucket boundary. At most 365 days before now", "required": true, "schema": { "description": "Start of range (RFC3339). Aligned inwards to the bucket boundary. At most 365 days before now", "format": "date-time", "type": "string" } }, { "name": "endDate", "in": "query", "description": "End of range (RFC3339). Aligned inwards to the bucket boundary", "required": true, "schema": { "description": "End of range (RFC3339). Aligned inwards to the bucket boundary", "format": "date-time", "type": "string" } }, { "name": "step", "in": "query", "description": "Bucket size in seconds (default 900). Must be a positive multiple of 900, at most 31536000 (365 days); maximum 10,000 buckets", "schema": { "description": "Bucket size in seconds (default 900). Must be a positive multiple of 900, at most 31536000 (365 days); maximum 10,000 buckets", "maximum": 31536000, "minimum": 1, "type": [ "null", "integer" ] } }, { "name": "chainId", "in": "path", "description": "EVM chain ID (e.g. 1 for Ethereum)", "required": true, "schema": { "description": "EVM chain ID (e.g. 1 for Ethereum)", "minimum": 1, "type": "integer" } }, { "name": "vaultAddress", "in": "path", "description": "0x-prefixed 40-hex vault contract address", "required": true, "schema": { "description": "0x-prefixed 40-hex vault contract address", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunitiesGetOpportunityHistoricalLPsResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/opportunities/{chainId}/{vaultAddress}/historical/share-price": { "get": { "tags": [ "Historical Data" ], "summary": "Get Vault Historical Share Price", "description": "Historical share prices from one canonical growth source over [from, to]. Native is in the source's base asset; rebasing receipts have native price 1. USD uses the base asset's historical price bucket and is null when unavailable. NAV sources return their stored USD value directly, with native and baseAsset null. Ambiguous source mappings return 412. Missing or unindexed sources return 503 INDEXING_NOT_STARTED; paused or withheld sources return 503 INDEXING_STALLED. Coverage describes the selected growth source.", "operationId": "GetOpportunityHistoricalSharePrice", "parameters": [ { "name": "step", "in": "query", "description": "Point spacing (granularity) in seconds, at most 31536000 (365 days). Defaults to 86400 (1 day). The range may span at most 10,000 buckets at this step", "schema": { "default": 86400, "description": "Point spacing (granularity) in seconds, at most 31536000 (365 days). Defaults to 86400 (1 day). The range may span at most 10,000 buckets at this step", "maximum": 31536000, "minimum": 1, "type": "integer" } }, { "name": "apyInterval", "in": "query", "description": "APY/APR trailing window (lookback) in seconds, independent of step, at most 7776000 (90 days). Defaults to 2592000 (30 days)", "schema": { "default": 2592000, "description": "APY/APR trailing window (lookback) in seconds, independent of step, at most 7776000 (90 days). Defaults to 2592000 (30 days)", "maximum": 7776000, "minimum": 1, "type": "integer" } }, { "name": "startDate", "in": "query", "description": "Inclusive lower bound (RFC3339/ISO-8601). At most 365 days before now", "required": true, "schema": { "description": "Inclusive lower bound (RFC3339/ISO-8601). At most 365 days before now", "format": "date-time", "type": "string" } }, { "name": "endDate", "in": "query", "description": "Inclusive upper bound (RFC3339/ISO-8601). Omit it — or send a future instant — to mean \"the latest data available\"; clients that want a live trailing series should do that rather than sending a client clock, so the query key stays stable while the answer keeps moving.", "schema": { "description": "Inclusive upper bound (RFC3339/ISO-8601). Omit it — or send a future instant — to mean \"the latest data available\"; clients that want a live trailing series should do that rather than sending a client clock, so the query key stays stable while the answer keeps moving.", "format": "date-time", "type": "string" } }, { "name": "chainId", "in": "path", "description": "EVM chain ID (e.g. 1 for Ethereum)", "required": true, "schema": { "description": "EVM chain ID (e.g. 1 for Ethereum)", "minimum": 1, "type": "integer" } }, { "name": "vaultAddress", "in": "path", "description": "0x-prefixed 40-hex vault contract address", "required": true, "schema": { "description": "0x-prefixed 40-hex vault contract address", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunitiesGetOpportunityHistoricalSharePriceResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "412": { "description": "Precondition Failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "503": { "description": "The vault's price series is withheld: the indexer has not checkpointed it yet (INDEXING_NOT_STARTED) or stalled and was withheld by the monitor (INDEXING_STALLED). Switch on reason; retry after the Retry-After response header (seconds).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunitiesWithholdErrResponse" } } } } } } }, "/v2/opportunities/{chainId}/{vaultAddress}/historical/tvl": { "get": { "tags": [ "Historical Data" ], "summary": "Get Vault Historical TVL", "description": "Get historical TVL time-series for a vault over [from, to]. Values are the time-weighted average over each bucket. USD comes from deposit_metrics. Native is denominated in the vault's underlying base asset and is null, together with blockNumber, when no share price matches the bucket. Missing share prices do not suppress USD TVL points. Step is rounded up to a 15-minute grain and the series is never zero-filled. The first and last buckets may cover a partial step when step does not divide the aligned range.", "operationId": "GetOpportunityHistoricalTVL", "parameters": [ { "name": "step", "in": "query", "description": "Point spacing (granularity) in seconds, at most 31536000 (365 days). Defaults to 86400 (1 day). The range may span at most 10,000 buckets at this step", "schema": { "default": 86400, "description": "Point spacing (granularity) in seconds, at most 31536000 (365 days). Defaults to 86400 (1 day). The range may span at most 10,000 buckets at this step", "maximum": 31536000, "minimum": 1, "type": "integer" } }, { "name": "apyInterval", "in": "query", "description": "APY/APR trailing window (lookback) in seconds, independent of step, at most 7776000 (90 days). Defaults to 2592000 (30 days)", "schema": { "default": 2592000, "description": "APY/APR trailing window (lookback) in seconds, independent of step, at most 7776000 (90 days). Defaults to 2592000 (30 days)", "maximum": 7776000, "minimum": 1, "type": "integer" } }, { "name": "startDate", "in": "query", "description": "Inclusive lower bound (RFC3339/ISO-8601). At most 365 days before now", "required": true, "schema": { "description": "Inclusive lower bound (RFC3339/ISO-8601). At most 365 days before now", "format": "date-time", "type": "string" } }, { "name": "endDate", "in": "query", "description": "Inclusive upper bound (RFC3339/ISO-8601). Omit it — or send a future instant — to mean \"the latest data available\"; clients that want a live trailing series should do that rather than sending a client clock, so the query key stays stable while the answer keeps moving.", "schema": { "description": "Inclusive upper bound (RFC3339/ISO-8601). Omit it — or send a future instant — to mean \"the latest data available\"; clients that want a live trailing series should do that rather than sending a client clock, so the query key stays stable while the answer keeps moving.", "format": "date-time", "type": "string" } }, { "name": "chainId", "in": "path", "description": "EVM chain ID (e.g. 1 for Ethereum)", "required": true, "schema": { "description": "EVM chain ID (e.g. 1 for Ethereum)", "minimum": 1, "type": "integer" } }, { "name": "vaultAddress", "in": "path", "description": "0x-prefixed 40-hex vault contract address", "required": true, "schema": { "description": "0x-prefixed 40-hex vault contract address", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunitiesGetOpportunityHistoricalTVLResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/opportunities/{id}": { "get": { "tags": [ "Opportunities" ], "summary": "Get Opportunity by ID", "description": "Returns a single active opportunity by its id. Deposit/withdrawal availability is reported in meta.", "operationId": "GetOpportunity", "parameters": [ { "name": "id", "in": "path", "description": "Opportunity unique identifier", "required": true, "schema": { "$ref": "#/components/schemas/UuidUUID", "description": "Opportunity unique identifier" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunitiesOpportunityResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/protocols/": { "get": { "tags": [ "Protocols" ], "summary": "Get Supported Protocols", "description": "Returns supported DeFi protocols with pagination. A protocol is an organization referenced as a lending protocol or vault infra provider in an earn product.", "operationId": "GetProtocols", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "pageLimit", "in": "query", "schema": { "type": "integer" } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginationPaginatedResponseGithubComTurtleDAOTurtlePartnersGoServicesEarnHandlersV2ProtocolResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/streams/": { "get": { "tags": [ "Streams" ], "summary": "Get Streams Data", "description": "Get streams, optionally filtered by stream ID or organization ID. Use estimatedLiveApr for the rate a stream is currently distributing; lastSnapshot.apr is historical and stays populated after a stream is paused or ends.", "operationId": "GetStreams", "parameters": [ { "name": "id", "in": "query", "schema": { "$ref": "#/components/schemas/UuidUUID" } }, { "name": "orgId", "in": "query", "schema": { "$ref": "#/components/schemas/UuidUUID" } }, { "name": "withSnapshots", "in": "query", "schema": { "type": "boolean" } }, { "name": "usersCount", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamsGetStreamsOutput" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } }, "post": { "tags": [ "Streams" ], "summary": "Create Stream with API Key Authentication", "description": "Handle create stream and signature request", "operationId": "CreateStream", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamsCreateStreamRequestParams" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamsCreateStreamOutput" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/streams/bulk": { "post": { "tags": [ "Streams" ], "summary": "Get Streams Data (bulk)", "description": "Get streams filtered by multiple stream IDs, organization IDs, target-token chains and/or target tokens. Same stream objects as GET /streams. Pagination is optional via the `page` and `limit` query params (`limit` is capped at 500); omit both to return all matching streams, except when no filter is provided, in which case a bounded `limit` is required. Uses POST because the multi-valued filters are sent in the request body; it is a read-only query and is not scoped to the API key's organization.", "operationId": "PostStreamsBulk", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamsPostStreamsBulkInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamsPostStreamsBulkOutput" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/streams/merkle_proofs": { "get": { "tags": [ "Streams" ], "summary": "Get Merkle Proofs for Wallet", "description": "Retrieve Merkle proofs for a wallet address across multiple streams.\n\t\n\tThe endpoint returns proofs for the latest snapshot with a committed root hash for each stream.\n\tThe proofs can be used to claim rewards on-chain.\n\t\n\t**Caching Strategy:**\n\t1. Check local in-memory LRU cache (LRU eviction ensures memory stays bounded)\n\t2. If not in cache, check Redis\n\t3. If not in Redis, rebuild from database\n\t4. Validate root hash matches the database value", "operationId": "GetMerkleProofs", "parameters": [ { "name": "wallet", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "streamIds", "in": "query", "required": true, "schema": { "items": { "$ref": "#/components/schemas/UuidUUID" }, "type": [ "array", "null" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamsGetMerkleProofsOutput" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/streams/points": { "get": { "tags": [ "Streams" ], "summary": "Get Stream Points", "description": "Get points, optionally filtered by organization ID.", "operationId": "GetStreamPoints", "parameters": [ { "name": "id", "in": "query", "schema": { "$ref": "#/components/schemas/UuidUUID" } }, { "name": "orgId", "in": "query", "schema": { "$ref": "#/components/schemas/UuidUUID" } }, { "name": "symbol", "in": "query", "schema": { "type": "string" } }, { "name": "name", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamsGetPointsOutput" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } }, "post": { "tags": [ "Streams" ], "summary": "Create Stream Point", "description": "Create a point for the organization associated with the API key.", "operationId": "CreateStreamPoint", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamsCreatePointInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamsCreatePointOutput" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/streams/tokens": { "get": { "tags": [ "Streams" ], "summary": "Get Stream Tokens", "description": "Get all supported tokens for a chain that can be used for streams.", "operationId": "GetStreamTokens", "parameters": [ { "name": "chainId", "in": "query", "description": "Decimal chain ID", "required": true, "schema": { "description": "Decimal chain ID", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamsGetTokensOutput" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/streams/wallets/{address}": { "get": { "tags": [ "Streams" ], "summary": "Get Streams For Wallet", "description": "Retrieve all streams a wallet is participating in with its snapshot data per stream. By default only the latest snapshot per stream is returned; set withSnapshots=true to include full history. rewardsAccumulated and rewardsAccumulatedBase are in wei units.", "operationId": "GetStreamsForWallet", "parameters": [ { "name": "withSnapshots", "in": "query", "schema": { "type": "boolean" } }, { "name": "address", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamsGetStreamsForWalletOutput" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/streams/{id}/admin-operations/active": { "get": { "tags": [ "Streams" ], "summary": "Get Active Stream Admin Operation", "description": "Returns the admin operation blocking the stream - a withdrawal, or a budget increase made outside this API - and until when it does. While confirmedTxHash is null, txParams can still be submitted before txParams.params.deadline: a client that lost it gets the same payload back, nothing is re-signed. Once set, the operation executed and the stream frees up at blockingUntil, when its transaction is final.", "operationId": "GetActiveStreamAdminOperation", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UuidUUID" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamsGetActiveAdminOperationOutput" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/streams/{id}/wallets": { "get": { "tags": [ "Streams" ], "summary": "Get Stream Wallets", "description": "Retrieve the wallets participating in a stream along with their latest snapshot data. Paginate with 'page' and 'limit' query params (default: page=1, limit=20). Results are ordered by rewardsAccumulated descending. rewardsAccumulated and rewardsAccumulatedBase are in wei units.", "operationId": "GetStreamWallets", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UuidUUID" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamsGetWalletsOutput" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/streams/{id}/wallets/{address}": { "get": { "tags": [ "Streams" ], "summary": "Get Stream Wallet Data", "description": "Retrieve all reward snapshots accumulated by a wallet for a specific stream. The following fields are in wei units: wallet.snapshots[].rewardsAccumulated, wallet.stream.totalAmount, wallet.stream.lastSnapshot.amountDistributed.", "operationId": "GetStreamWallet", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UuidUUID" } }, { "name": "address", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamsGetWalletOutput" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/streams/{id}/withdrawals": { "post": { "tags": [ "Streams" ], "summary": "Withdraw Stream Funds", "description": "Signs a withdrawal of the reward tokens the stream holds beyond what it must keep for rewards. The stream admin wallet must submit txParams to the StreamFactory's withdrawFunds before the deadline. Only one admin operation per stream may be in flight at a time.", "operationId": "WithdrawStreamFunds", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/UuidUUID" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamsWithdrawFundsInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamsWithdrawFundsOutput" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/swap/": { "get": { "tags": [ "Swaps" ], "summary": "Get Swap", "description": "Build approve + swap transactions via the router for an arbitrary token pair", "operationId": "GetSwap", "parameters": [ { "name": "user", "in": "query", "description": "User's EOA address initiating the swap", "required": true, "schema": { "description": "User's EOA address initiating the swap", "type": "string" } }, { "name": "chainId", "in": "query", "description": "Chain ID for the swap", "required": true, "schema": { "description": "Chain ID for the swap", "minimum": 1, "type": "integer" } }, { "name": "distributorId", "in": "query", "description": "Distributor ID", "required": true, "schema": { "description": "Distributor ID", "type": "string" } }, { "name": "tokenIn", "in": "query", "description": "Input token address or 'native' alias", "required": true, "schema": { "description": "Input token address or 'native' alias", "type": "string" } }, { "name": "tokenOut", "in": "query", "description": "Output token address or 'native' alias", "required": true, "schema": { "description": "Output token address or 'native' alias", "type": "string" } }, { "name": "amountIn", "in": "query", "description": "Input amount in smallest unit (wei)", "required": true, "schema": { "description": "Input amount in smallest unit (wei)", "maxLength": 78, "type": "string" } }, { "name": "slippageBps", "in": "query", "description": "Slippage tolerance in basis points (e.g., 50 = 0.5%)", "required": true, "schema": { "description": "Slippage tolerance in basis points (e.g., 50 = 0.5%)", "maximum": 5000, "minimum": 1, "type": "integer" } }, { "name": "quoteOnly", "in": "query", "description": "Skip balance validation for quote preview", "schema": { "description": "Skip balance validation for quote preview", "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2GetSwapResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/swap/details": { "get": { "tags": [ "Swaps" ], "summary": "Get Swap Details", "description": "Static-ish swap picker data: supported chains plus popular tokens for the selected chain", "operationId": "GetSwapDetails", "parameters": [ { "name": "chainId", "in": "query", "description": "Optional chain ID to scope the popular tokens list", "schema": { "description": "Optional chain ID to scope the popular tokens list", "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2GetSwapDetailsResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/swap/executions": { "post": { "tags": [ "Swap Orders" ], "summary": "Report Swap Execution", "description": "Persist a client-reported classic swap row", "operationId": "ReportSwapExecution", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2ReportSwapExecutionRequest" } } } }, "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/swap/orders": { "post": { "tags": [ "Swap Orders" ], "summary": "Submit Swap Order", "description": "Forward a signed 1inch Fusion order to the relayer", "operationId": "SubmitSwapOrder", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2SubmitSwapOrderRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2SubmitSwapOrderResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/swap/orders/build": { "post": { "tags": [ "Swap Orders" ], "summary": "Build Swap Order", "description": "Build a 1inch Fusion order for a member wallet", "operationId": "BuildSwapOrder", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2BuildSwapOrderRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2BuildSwapOrderResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "412": { "description": "Precondition Failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/swap/orders/{orderHash}": { "get": { "tags": [ "Swap Orders" ], "summary": "Get Swap Order Status", "description": "Fetch the current state of a 1inch Fusion order", "operationId": "GetSwapOrderStatus", "parameters": [ { "name": "chainId", "in": "query", "required": true, "schema": { "minimum": 1, "type": "integer" } }, { "name": "orderHash", "in": "path", "required": true, "schema": { "pattern": "^0x[0-9a-fA-F]{64}$", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TypesOrderStatus" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/swap/tokens": { "get": { "tags": [ "Swaps" ], "summary": "Get Swap Tokens", "description": "Search swap tokens for a chain. Partial match on symbol/name/address against the curated catalog, with an Enso fallback (by address or exact symbol) when the catalog has no result", "operationId": "GetSwapTokens", "parameters": [ { "name": "chainId", "in": "query", "description": "Numeric chain ID to scope the search", "required": true, "schema": { "description": "Numeric chain ID to scope the search", "minimum": 1, "type": "integer" } }, { "name": "search", "in": "query", "description": "Optional search term: matches token symbol, name, or address (case-insensitive partial)", "schema": { "description": "Optional search term: matches token symbol, name, or address (case-insensitive partial)", "type": "string" } }, { "name": "page", "in": "query", "description": "1-based page number; defaults to 1", "schema": { "description": "1-based page number; defaults to 1", "type": "integer" } }, { "name": "limit", "in": "query", "description": "Page size; defaults to 20, max 300", "schema": { "description": "Page size; defaults to 20, max 300", "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2GetSwapTokensResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/swaps/": { "get": { "tags": [ "Swaps" ], "summary": "List Swaps", "description": "Returns paginated swaps history for a single wallet, newest first.", "operationId": "ListSwaps", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "pageLimit", "in": "query", "schema": { "type": "integer" } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer" } }, { "name": "userAddress", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "enum": [ "created", "submitted", "filled", "partial", "expired", "failed", "cancelled", "abandoned" ], "type": "string" } }, { "name": "chainId", "in": "query", "schema": { "type": "string" } }, { "name": "includeZaps", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginationPaginatedResponseGithubComTurtleDAOTurtlePartnersGoServicesEarnHandlersV2SwapsSwapItem" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/tokens/": { "get": { "tags": [ "Tokens" ], "summary": "Get Supported Tokens", "description": "Returns active supported tokens with pagination. Optional filters: chainId (numeric) and search (partial match on address, name or symbol).", "operationId": "GetTokens", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "pageLimit", "in": "query", "schema": { "type": "integer" } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer" } }, { "name": "chainId", "in": "query", "description": "Filter by numeric chain ID", "schema": { "description": "Filter by numeric chain ID", "type": "integer" } }, { "name": "search", "in": "query", "description": "Case-insensitive partial match across address, name and symbol", "schema": { "description": "Case-insensitive partial match across address, name and symbol", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginationPaginatedResponseGithubComTurtleDAOTurtlePartnersGoServicesEarnHandlersV2SharedTokenResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/tokens/{chainId}/{address}": { "get": { "tags": [ "Tokens" ], "summary": "Get Token by Chain and Address", "description": "Returns a single active token identified by its numeric chain ID and contract address.", "operationId": "GetTokenByAddress", "parameters": [ { "name": "chainId", "in": "path", "description": "Numeric chain ID", "required": true, "schema": { "description": "Numeric chain ID", "type": "integer" } }, { "name": "address", "in": "path", "description": "Token contract address (case-insensitive)", "required": true, "schema": { "description": "Token contract address (case-insensitive)", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SharedTokenResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/wallet/{address}/portfolio": { "get": { "tags": [ "Wallets" ], "summary": "Get Wallet Portfolio", "description": "Get a wallet's holdings: ERC-20 and native balances plus DeFi positions. Same payload as the main API GET /wallet/{address}/balance.", "operationId": "GetWalletPortfolio", "parameters": [ { "name": "includeProtocolTokens", "in": "query", "schema": { "default": false, "type": "boolean" } }, { "name": "address", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortfolioGetTurtleBalanceOutput" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } }, "/v2/wallets/activity/": { "get": { "tags": [ "Wallets" ], "summary": "Get Wallet Activity", "description": "Get paginated verified earn interactions for the given wallet addresses (comma-separated), ordered by date descending.", "operationId": "GetWalletActivity", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "addresses", "in": "query", "description": "Comma-separated list of EVM wallet addresses to fetch activity for (max 1000)", "schema": { "description": "Comma-separated list of EVM wallet addresses to fetch activity for (max 1000)", "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionsWalletActivityResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrResponse" } } } } } } } }, "components": { "schemas": { "ActionsCancelDepositRequest": { "properties": { "distributorId": { "description": "Distributor ID", "type": "string" }, "userAddress": { "description": "User wallet address", "type": "string" } }, "required": [ "userAddress", "distributorId" ], "type": "object" }, "ActionsClaimDepositRequest": { "properties": { "distributorId": { "description": "Distributor ID", "type": "string" }, "userAddress": { "description": "User wallet address", "type": "string" } }, "required": [ "userAddress", "distributorId" ], "type": "object" }, "ActionsDistributorDepositsResponse": { "properties": { "deposits": { "items": { "$ref": "#/components/schemas/ActionsWalletActivityItem" }, "type": [ "array", "null" ] }, "pagination": { "$ref": "#/components/schemas/UtilsPaginationResponse" } }, "type": "object" }, "ActionsInteractionRequest": { "properties": { "amount": { "description": "Amount in smallest unit (wei)", "type": "string" }, "distributorId": { "description": "Distributor ID", "type": "string" }, "mode": { "default": "direct", "description": "Mode: 'swap' to use router, 'direct' for direct deposit", "type": "string" }, "quoteOnly": { "description": "Skip balance validation for quote preview", "type": "boolean" }, "referralCode": { "description": "Optional referral code", "type": "string" }, "slippageBps": { "default": 50, "description": "Slippage tolerance in basis points (e.g., 50 = 0.5%)", "type": "integer" }, "tokenIn": { "description": "Input token address", "type": "string" }, "userAddress": { "description": "User wallet address (validated by middleware)", "type": "string" } }, "required": [ "userAddress", "tokenIn", "amount", "distributorId" ], "type": "object" }, "ActionsInteractionResponse": { "properties": { "actionId": { "$ref": "#/components/schemas/UuidUUID", "description": "Unique identifier for the saved interaction" }, "transactions": { "description": "Ordered list of transactions to execute", "items": { "$ref": "#/components/schemas/TypesTxResponseItem" }, "type": [ "array", "null" ] } }, "type": "object" }, "ActionsVerifyTrackingResponse": { "properties": { "error": { "description": "Error message if verification failed", "type": "string" }, "metadata": { "$ref": "#/components/schemas/TrackingEarnTrackingMetadata", "description": "Attribution metadata. Present only when the signature is valid" }, "schema": { "description": "Attribution format found in the transaction. Omitted when the transaction carries none", "enum": [ "erc8021", "legacy" ], "type": "string" }, "signatureValid": { "description": "Whether the transaction's attribution was issued by Turtle", "type": "boolean" }, "tag": { "description": "Tracking tag of a legacy marker. Absent under erc8021 and when the signature is invalid", "type": "string" } }, "type": "object" }, "ActionsWalletActivityItem": { "properties": { "amountInUsd": { "type": [ "null", "string" ] }, "amountToken": { "type": [ "null", "string" ] }, "blockTimestamp": { "type": [ "null", "string" ] }, "chainId": { "type": "integer" }, "id": { "$ref": "#/components/schemas/UuidUUID" }, "interaction": { "type": "string" }, "isSwap": { "type": "boolean" }, "opportunityId": { "$ref": "#/components/schemas/UuidUUID" }, "tokenIconUrl": { "type": [ "null", "string" ] }, "tokenSymbol": { "type": [ "null", "string" ] }, "txHash": { "type": "string" }, "walletAddress": { "type": "string" } }, "type": "object" }, "ActionsWalletActivityResponse": { "properties": { "activity": { "items": { "$ref": "#/components/schemas/ActionsWalletActivityItem" }, "type": [ "array", "null" ] }, "pagination": { "$ref": "#/components/schemas/UtilsPaginationResponse" } }, "type": "object" }, "ActionsWithdrawRequest": { "properties": { "amount": { "description": "Shares to redeem in smallest unit", "type": "string" }, "distributorId": { "description": "Distributor ID", "type": "string" }, "slippageBps": { "description": "Optional: slippage tolerance in basis points (e.g., 50 = 0.5%). Only applied to opportunities that require it", "type": "integer" }, "tokenOut": { "description": "Optional: token to receive after withdrawal (required for Midas, Mellow, Veda)", "type": "string" }, "userAddress": { "description": "User wallet address (validated by middleware)", "type": "string" } }, "required": [ "userAddress", "amount", "distributorId" ], "type": "object" }, "AdminOperationsFuncParamsGithubComTurtleDAOTurtlePartnersGoServicesEarnHandlersV2StreamsAdminOperationParams": { "properties": { "deadline": { "description": "Unix seconds when the signature expires.", "type": "integer" }, "params": { "$ref": "#/components/schemas/StreamsAdminOperationParams" }, "salt": { "type": [ "string", "null" ] }, "signature": { "format": "base64", "type": "string" } }, "type": "object" }, "AdminOperationsFuncParamsGithubComTurtleDAOTurtlePartnersGoServicesEarnHandlersV2StreamsIStreamFactoryWithdrawFundsParams": { "properties": { "deadline": { "description": "Unix seconds when the signature expires.", "type": "integer" }, "params": { "$ref": "#/components/schemas/StreamsIStreamFactoryWithdrawFundsParams" }, "salt": { "type": "string" }, "signature": { "format": "base64", "type": "string" } }, "type": "object" }, "AdminOperationsTxParamsGithubComTurtleDAOTurtlePartnersGoServicesEarnHandlersV2StreamsAdminOperationParams": { "properties": { "chainId": { "minimum": 0, "type": "integer" }, "params": { "$ref": "#/components/schemas/AdminOperationsFuncParamsGithubComTurtleDAOTurtlePartnersGoServicesEarnHandlersV2StreamsAdminOperationParams" }, "sender": { "type": "string" } }, "type": "object" }, "AdminOperationsTxParamsGithubComTurtleDAOTurtlePartnersGoServicesEarnHandlersV2StreamsIStreamFactoryWithdrawFundsParams": { "properties": { "chainId": { "minimum": 0, "type": "integer" }, "params": { "$ref": "#/components/schemas/AdminOperationsFuncParamsGithubComTurtleDAOTurtlePartnersGoServicesEarnHandlersV2StreamsIStreamFactoryWithdrawFundsParams" }, "sender": { "type": "string" } }, "type": "object" }, "AttributionResult": { "properties": { "actionId": { "type": "string" }, "distributorId": { "type": "string" }, "opportunityId": { "type": "string" }, "reason": { "enum": [ "ok", "no_suffix", "unknown_distributor", "not_matched", "legacy_deadbeef", "indexing" ], "type": "string" }, "schema": { "type": [ "null", "string" ] }, "status": { "enum": [ "credited", "pending", "not_credited" ], "type": "string" }, "txHash": { "type": "string" } }, "type": "object" }, "DeltasAPYDelta": { "properties": { "asOf": { "description": "Instant of the observation the rate was computed from", "format": "date-time", "type": [ "null", "string" ] }, "current": { "description": "Trailing 30-day APY in percent (8.24 = 8.24%)", "type": [ "null", "string" ] }, "d1": { "description": "Change in basis points against the trailing 30-day APY of 24 hours ago", "type": [ "null", "string" ] }, "d30": { "description": "Change in basis points against the trailing 30-day APY of 30 days ago", "type": [ "null", "string" ] }, "d7": { "description": "Change in basis points against the trailing 30-day APY of 7 days ago", "type": [ "null", "string" ] } }, "type": [ "object", "null" ] }, "DeltasMeasureDelta": { "properties": { "asOf": { "description": "Instant the current value was measured at", "format": "date-time", "type": [ "null", "string" ] }, "current": { "description": "Value at asOf, in the measure's own unit", "type": [ "null", "string" ] }, "d1": { "description": "Percent change over the trailing 24 hours", "type": [ "null", "string" ] }, "d30": { "description": "Percent change over the trailing 30 days", "type": [ "null", "string" ] }, "d7": { "description": "Percent change over the trailing 7 days", "type": [ "null", "string" ] } }, "type": [ "object", "null" ] }, "DeltasOpportunityDeltas": { "properties": { "growthApy": { "$ref": "#/components/schemas/DeltasAPYDelta", "description": "Trailing 30-day APY from the growth series, and its movement. On the turtle listing it is not the apy field there, which carries native-yield rates per window from a different source. Null when the opportunity has no usable growth source or has more than one receipt token" }, "lps": { "$ref": "#/components/schemas/DeltasMeasureDelta", "description": "Wallets holding a positive position, from every source, and its percent change" }, "tvl": { "$ref": "#/components/schemas/DeltasMeasureDelta", "description": "TVL in USD summed from deposit data, from every source, and its percent change. Computed from a different source than the listing's own tvl field and will not always match it" }, "unavailable": { "description": "Measures whose read failed or ran out of time. A measure named here is null because we could not read it, not because the opportunity has none", "items": { "type": "string" }, "type": "array" } }, "type": [ "object", "null" ] }, "EntitiesUserEarnings": { "properties": { "productId": { "$ref": "#/components/schemas/UuidUUID" }, "referralsEarnings": { "type": "number" }, "rewardName": { "type": "string" }, "rewardType": { "type": "string" }, "value": { "type": "number" } }, "type": "object" }, "MetricsGetDistributorLPsOutput": { "properties": { "timeseries": { "items": { "$ref": "#/components/schemas/MetricsLPsPoint" }, "type": [ "array", "null" ] } }, "type": "object" }, "MetricsGetDistributorMetricsOutput": { "properties": { "asOf": { "items": { "$ref": "#/components/schemas/MetricsOpportunityAsOf" }, "type": [ "array", "null" ] }, "timeseries": { "items": { "$ref": "#/components/schemas/MetricsTimeseriesPoint" }, "type": [ "array", "null" ] }, "topWallets": { "items": { "$ref": "#/components/schemas/MetricsTopWallet" }, "type": [ "null", "array" ] } }, "type": "object" }, "MetricsLPsPoint": { "properties": { "activeLps": { "minimum": 0, "type": "integer" }, "participatedLps": { "minimum": 0, "type": "integer" }, "timestamp": { "format": "date-time", "type": "string" } }, "type": "object" }, "MetricsOpportunityAsOf": { "properties": { "asOf": { "format": "date-time", "type": "string" }, "opportunityId": { "$ref": "#/components/schemas/UuidUUID" } }, "type": "object" }, "MetricsTimeseriesPoint": { "properties": { "timestamp": { "format": "date-time", "type": "string" }, "tvl": { "type": "string" } }, "type": "object" }, "MetricsTopWallet": { "properties": { "asOf": { "format": "date-time", "type": "string" }, "totalTvl": { "type": "string" }, "walletAddress": { "type": "string" } }, "type": "object" }, "OpportunitiesAPRBreakdown": { "properties": { "base": { "description": "APR from share-price growth alone (simple, non-compound)", "type": "number" }, "reward": { "description": "Reward APR; reserved for future rewards indexing, currently always 0", "type": "number" }, "total": { "description": "base + reward", "type": "number" } }, "type": "object" }, "OpportunitiesAPYBreakdown": { "properties": { "base": { "description": "APY from share-price growth alone (compound formula)", "type": "number" }, "reward": { "description": "Reward APY; reserved for future rewards indexing, currently always 0", "type": "number" }, "total": { "description": "base + reward", "type": "number" } }, "type": [ "object", "null" ] }, "OpportunitiesCuratorResponse": { "properties": { "description": { "description": "Curator description", "type": "string" }, "iconUrl": { "description": "Curator icon image URL", "type": "string" }, "id": { "$ref": "#/components/schemas/UuidUUID", "description": "Curator organization id" }, "landingUrl": { "description": "Curator website URL", "type": "string" }, "name": { "description": "Curator name", "type": "string" } }, "type": "object" }, "OpportunitiesDepositTokenSymbolOption": { "properties": { "logoUrl": { "description": "Representative token logo URL", "type": "string" }, "symbol": { "description": "Deposit token symbol", "type": "string" } }, "type": "object" }, "OpportunitiesGetOpportunitiesFilterOptionsOutput": { "properties": { "chains": { "description": "Chains with at least one opportunity", "items": { "$ref": "#/components/schemas/SharedChainResponse" }, "type": [ "array", "null" ] }, "curators": { "description": "Curators", "items": { "$ref": "#/components/schemas/OpportunitiesOrganizationOption" }, "type": [ "array", "null" ] }, "depositTokenSymbols": { "description": "Available deposit token symbols", "items": { "$ref": "#/components/schemas/OpportunitiesDepositTokenSymbolOption" }, "type": [ "array", "null" ] }, "lendingProtocols": { "description": "Lending protocols", "items": { "$ref": "#/components/schemas/OpportunitiesOrganizationOption" }, "type": [ "array", "null" ] }, "partners": { "description": "Partner organizations", "items": { "$ref": "#/components/schemas/OpportunitiesOrganizationOption" }, "type": [ "array", "null" ] }, "providers": { "description": "Infra providers and lending protocols", "items": { "$ref": "#/components/schemas/OpportunitiesOrganizationOption" }, "type": [ "array", "null" ] }, "sortOptions": { "description": "Valid sortBy values", "items": { "$ref": "#/components/schemas/OpportunitiesSortOption" }, "type": [ "array", "null" ] }, "tags": { "description": "Opportunity tags", "items": { "$ref": "#/components/schemas/OpportunitiesTagOption" }, "type": [ "array", "null" ] } }, "type": "object" }, "OpportunitiesGetOpportunityHistoricalAPRResponse": { "properties": { "coverage": { "$ref": "#/components/schemas/OpportunitiesHistoricalCoverage", "description": "Span of this vault's APR series over all history, independent of the requested window; null when it could not be determined" }, "data": { "items": { "$ref": "#/components/schemas/OpportunitiesHistoricalAPRPoint" }, "type": [ "array", "null" ] } }, "type": "object" }, "OpportunitiesGetOpportunityHistoricalAPYResponse": { "properties": { "coverage": { "$ref": "#/components/schemas/OpportunitiesHistoricalCoverage", "description": "Span of this vault's APY series over all history, independent of the requested window; null when it could not be determined" }, "data": { "items": { "$ref": "#/components/schemas/OpportunitiesHistoricalAPYPoint" }, "type": [ "array", "null" ] } }, "type": "object" }, "OpportunitiesGetOpportunityHistoricalLPsResponse": { "properties": { "coverage": { "$ref": "#/components/schemas/OpportunitiesHistoricalCoverage", "description": "Span of this vault's LP series over all history, independent of the requested window; resolved only when the returned series is empty, null otherwise or when it could not be determined" }, "timeseries": { "items": { "$ref": "#/components/schemas/OpportunitiesHistoricalLPsPoint" }, "type": [ "array", "null" ] } }, "type": "object" }, "OpportunitiesGetOpportunityHistoricalResponse": { "properties": { "baseAsset": { "$ref": "#/components/schemas/SharedTokenResponse", "description": "null when the vault has no snapshots yet or the underlying token is not registered in supported_tokens" }, "data": { "items": { "$ref": "#/components/schemas/OpportunitiesHistoricalCombinedPoint" }, "type": [ "array", "null" ] }, "historyTruncated": { "description": "true when backend hit the row cap and oldest APY values may be missing predecessors", "type": "boolean" } }, "type": "object" }, "OpportunitiesGetOpportunityHistoricalSharePriceResponse": { "properties": { "baseAsset": { "anyOf": [ { "$ref": "#/components/schemas/SharedTokenResponse", "description": "null for NAV sources, when the vault is unmapped or the source's underlying token is not registered in supported_tokens" }, { "type": "null" } ] }, "coverage": { "$ref": "#/components/schemas/OpportunitiesHistoricalCoverage", "description": "Span of this vault's share-price series over all history, independent of the requested window; null when it could not be determined" }, "data": { "items": { "$ref": "#/components/schemas/OpportunitiesHistoricalSharePricePoint" }, "type": [ "array", "null" ] } }, "type": "object" }, "OpportunitiesGetOpportunityHistoricalTVLResponse": { "properties": { "baseAsset": { "$ref": "#/components/schemas/SharedTokenResponse", "description": "Denomination of the native leg; null when the vault has no share-price series, no snapshots yet, or an underlying token that is not registered in supported_tokens" }, "coverage": { "$ref": "#/components/schemas/OpportunitiesHistoricalCoverage", "description": "Span of this vault's TVL series over all history, independent of the requested window. Resolved only when data is empty; null otherwise, and null when it could not be determined" }, "data": { "items": { "$ref": "#/components/schemas/OpportunitiesHistoricalTVLPoint" }, "type": [ "array", "null" ] } }, "type": "object" }, "OpportunitiesHistoricalAPRPoint": { "properties": { "apr": { "$ref": "#/components/schemas/OpportunitiesAPRBreakdown", "description": "Trailing-window simple-rate APR: annualized share-price growth over effectiveIntervalSeconds" }, "blockNumber": { "description": "On-chain block number of the snapshot chosen as the bucket representative", "minimum": 0, "type": "integer" }, "effectiveIntervalSeconds": { "description": "Seconds actually spanned by the two snapshots this rate annualizes. At least apyInterval, and more when the series has no observation at the window edge", "type": "integer" }, "timestamp": { "description": "Bucket representative time", "format": "date-time", "type": "string" } }, "type": "object" }, "OpportunitiesHistoricalAPYPoint": { "properties": { "apy": { "$ref": "#/components/schemas/OpportunitiesAPYBreakdown", "description": "Trailing-window compound APY: annualized share-price growth over effectiveIntervalSeconds" }, "blockNumber": { "description": "On-chain block number of the snapshot chosen as the bucket representative", "minimum": 0, "type": "integer" }, "effectiveIntervalSeconds": { "description": "Seconds actually spanned by the two snapshots this rate annualizes. At least apyInterval, and more when the series has no observation at the window edge", "type": "integer" }, "timestamp": { "description": "Bucket representative time", "format": "date-time", "type": "string" } }, "type": "object" }, "OpportunitiesHistoricalCombinedPoint": { "properties": { "apy": { "$ref": "#/components/schemas/OpportunitiesAPYBreakdown", "description": "Trailing-window APY at this bucket; null when no predecessor exists" }, "blockNumber": { "description": "On-chain block number of the snapshot chosen as the bucket representative", "minimum": 0, "type": "integer" }, "sharePrice": { "$ref": "#/components/schemas/OpportunitiesNativeUSDValue" }, "timestamp": { "description": "Bucket representative time", "format": "date-time", "type": "string" }, "tvl": { "$ref": "#/components/schemas/OpportunitiesNativeUSDValue" } }, "type": "object" }, "OpportunitiesHistoricalCoverage": { "properties": { "firstAt": { "description": "Oldest point in the series over all history; null when the series has never held a point", "format": "date-time", "type": [ "null", "string" ] }, "lastAt": { "description": "Newest point in the series over all history; null when the series has never held a point. A window ending at now contains data exactly when lastAt is not older than the window start", "format": "date-time", "type": [ "null", "string" ] } }, "type": [ "object", "null" ] }, "OpportunitiesHistoricalLPsPoint": { "properties": { "activeAllLps": { "description": "Wallets holding the vault at this bucket, whoever sourced the position", "minimum": 0, "type": "integer" }, "activeLps": { "description": "Wallets holding the vault at this bucket that arrived through a distributor", "minimum": 0, "type": "integer" }, "participatedAllLps": { "description": "Cumulative wallets that had ever held the vault by this bucket, whoever sourced the position", "minimum": 0, "type": "integer" }, "participatedLps": { "description": "Cumulative wallets that had ever held the vault through a distributor by this bucket", "minimum": 0, "type": "integer" }, "timestamp": { "description": "Bucket representative time", "format": "date-time", "type": "string" } }, "type": "object" }, "OpportunitiesHistoricalSharePricePoint": { "properties": { "blockNumber": { "description": "On-chain block number of the snapshot chosen as the bucket representative", "minimum": 0, "type": "integer" }, "sharePrice": { "$ref": "#/components/schemas/OpportunitiesHistoricalSharePriceValue" }, "timestamp": { "description": "Bucket representative time", "format": "date-time", "type": "string" } }, "type": "object" }, "OpportunitiesHistoricalSharePriceValue": { "properties": { "native": { "description": "Share price in the source's base asset; null for USD-denominated NAV sources", "type": [ "null", "string" ] }, "usd": { "description": "Share price in USD; NAV values are already USD, other modes use historical base-asset prices; null when unavailable", "type": [ "null", "string" ] } }, "type": "object" }, "OpportunitiesHistoricalTVLPoint": { "properties": { "blockNumber": { "description": "On-chain block number of the matching share-price snapshot; null when that bucket has no share price", "minimum": 0, "type": [ "null", "integer" ] }, "timestamp": { "description": "Bucket representative time", "format": "date-time", "type": "string" }, "tvl": { "$ref": "#/components/schemas/OpportunitiesHistoricalTVLValue" } }, "type": "object" }, "OpportunitiesHistoricalTVLValue": { "properties": { "native": { "description": "TVL denominated in the vault base asset; null when no share price matched this bucket", "type": [ "null", "string" ] }, "usd": { "description": "Time-weighted USD TVL, read pre-denominated from deposit_metrics and independent of the share-price series", "type": [ "null", "string" ] } }, "type": "object" }, "OpportunitiesHistoricalWithholdReason": { "enum": [ "PROTOCOL_UNSUPPORTED", "INDEXING_NOT_STARTED", "INDEXING_STALLED" ], "type": "string" }, "OpportunitiesIncentiveResponse": { "properties": { "apr": { "description": "Annual Percentage Rate", "type": [ "null", "number" ] }, "description": { "description": "Incentive description", "type": "string" }, "estPriceUsd": { "description": "Estimated price in USD", "type": [ "null", "number" ] }, "fdvEstimate": { "description": "Fully Diluted Valuation estimate", "type": [ "null", "number" ] }, "iconUrl": { "description": "Incentive icon URL", "type": "string" }, "id": { "$ref": "#/components/schemas/UuidUUID", "description": "Incentive unique identifier" }, "indexed": { "description": "Whether incentive is indexed", "type": "boolean" }, "maxApr": { "description": "Maximum Annual Percentage Rate", "type": [ "null", "number" ] }, "minApr": { "description": "Minimum Annual Percentage Rate", "type": [ "null", "number" ] }, "name": { "description": "Incentive name", "type": "string" }, "rewardType": { "description": "Type of reward (points, tokens, yield, vesting)", "type": "string" }, "rewardTypeName": { "description": "Human-readable reward type name", "type": "string" }, "tokenSupplyAllocation": { "description": "Token supply allocation percentage", "type": [ "null", "number" ] } }, "type": "object" }, "OpportunitiesNativeUSDValue": { "properties": { "native": { "type": [ "string", "null" ] }, "usd": { "description": "null when underlying USD price was not available for this bucket", "type": [ "string", "null" ] } }, "type": "object" }, "OpportunitiesOpportunityMeta": { "properties": { "asyncDeposit": { "description": "Whether deposits settle asynchronously", "type": "boolean" }, "asyncWithdraw": { "description": "Whether withdrawals settle asynchronously", "type": "boolean" }, "depositDisabledReason": { "description": "Reason deposits are disabled, if any", "type": "string" }, "depositEnabled": { "description": "Whether deposits are currently enabled", "type": "boolean" }, "directInteractionEnabled": { "description": "Whether direct interaction with the opportunity is available", "type": "boolean" }, "isSecondaryMarket": { "description": "Whether the opportunity can only be entered via a secondary market", "type": "boolean" }, "routedSwapEnabled": { "description": "Whether entering via a routed swap (through a routing provider) is supported", "type": "boolean" }, "withdrawEnabled": { "description": "Whether withdrawals are currently enabled", "type": "boolean" }, "withdrawalDisabledReason": { "description": "Reason withdrawals are disabled, if any", "type": "string" } }, "type": "object" }, "OpportunitiesOpportunityResponse": { "properties": { "baseToken": { "$ref": "#/components/schemas/SharedTokenResponse", "description": "Base token for the opportunity" }, "curator": { "$ref": "#/components/schemas/OpportunitiesCuratorResponse", "description": "Curator organization for the opportunity" }, "deltas": { "$ref": "#/components/schemas/DeltasOpportunityDeltas", "description": "Per-measure movement over the trailing day, week and month. Present only when includeDeltas is set, and absent when it could not be computed" }, "depositTokens": { "description": "Tokens accepted for deposit", "items": { "$ref": "#/components/schemas/SharedTokenResponse" }, "type": [ "array", "null" ] }, "description": { "description": "Opportunity detailed description", "type": "string" }, "estimatedApr": { "description": "Estimated APR (sum of active incentive yields)", "type": "number" }, "featured": { "description": "Whether opportunity is featured", "type": "boolean" }, "id": { "$ref": "#/components/schemas/UuidUUID", "description": "Opportunity unique identifier" }, "incentives": { "description": "Active incentives for the opportunity", "items": { "$ref": "#/components/schemas/OpportunitiesIncentiveResponse" }, "type": [ "array", "null" ] }, "meta": { "$ref": "#/components/schemas/OpportunitiesOpportunityMeta", "description": "Interaction and availability flags" }, "minDepositAmountUsd": { "description": "Minimum deposit amount in USD", "type": "number" }, "minWithdrawAmount": { "description": "Minimum withdraw amount in receipt-token units", "type": "number" }, "name": { "description": "Opportunity display name", "type": "string" }, "receiptToken": { "$ref": "#/components/schemas/SharedTokenResponse", "description": "Token received as receipt for deposits" }, "slug": { "description": "URL-friendly identifier", "type": "string" }, "tvl": { "description": "Total Value Locked in USD", "type": "number" }, "type": { "description": "Opportunity type (e.g. lending, vault)", "type": "string" } }, "type": "object" }, "OpportunitiesOrganizationOption": { "properties": { "iconUrl": { "description": "Organization icon URL", "type": "string" }, "id": { "$ref": "#/components/schemas/UuidUUID", "description": "Organization id (pass back as a filter value)" }, "landingUrl": { "description": "Organization website URL", "type": "string" }, "name": { "description": "Organization name", "type": "string" }, "organizationType": { "description": "Organization type", "type": "string" } }, "type": "object" }, "OpportunitiesSortOption": { "properties": { "label": { "description": "Human-readable label", "type": "string" }, "value": { "description": "Value to pass as sortBy", "type": "string" } }, "type": "object" }, "OpportunitiesTagOption": { "properties": { "code": { "description": "Tag code (pass back as the tags filter value)", "type": "string" }, "color": { "description": "Tag color", "type": "string" }, "description": { "description": "Tag description", "type": "string" }, "id": { "$ref": "#/components/schemas/UuidUUID", "description": "Tag id" }, "name": { "description": "Tag display name", "type": "string" } }, "type": "object" }, "OpportunitiesWithholdErrResponse": { "properties": { "code": { "description": "Application-specific error code.", "type": "integer" }, "context": { "additionalProperties": {}, "description": "Application context.", "type": "object" }, "error": { "description": "Error message.", "type": "string" }, "reason": { "$ref": "#/components/schemas/OpportunitiesHistoricalWithholdReason", "description": "Stable machine-readable failure reason; switch on this instead of matching the error prose" }, "status": { "description": "Status text.", "type": "string" } }, "required": [ "reason" ], "type": "object" }, "PaginationPaginatedResponseGithubComTurtleDAOTurtlePartnersGoServicesEarnHandlersV2ActionsWalletActivityItem": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ActionsWalletActivityItem" }, "type": [ "array", "null" ] }, "pagination": { "$ref": "#/components/schemas/PaginationPaginationMetadata" } }, "type": "object" }, "PaginationPaginatedResponseGithubComTurtleDAOTurtlePartnersGoServicesEarnHandlersV2OpportunitiesOpportunityResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/OpportunitiesOpportunityResponse" }, "type": [ "array", "null" ] }, "pagination": { "$ref": "#/components/schemas/PaginationPaginationMetadata" } }, "type": "object" }, "PaginationPaginatedResponseGithubComTurtleDAOTurtlePartnersGoServicesEarnHandlersV2ProtocolResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/V2ProtocolResponse" }, "type": [ "array", "null" ] }, "pagination": { "$ref": "#/components/schemas/PaginationPaginationMetadata" } }, "type": "object" }, "PaginationPaginatedResponseGithubComTurtleDAOTurtlePartnersGoServicesEarnHandlersV2SharedChainResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/SharedChainResponse" }, "type": [ "array", "null" ] }, "pagination": { "$ref": "#/components/schemas/PaginationPaginationMetadata" } }, "type": "object" }, "PaginationPaginatedResponseGithubComTurtleDAOTurtlePartnersGoServicesEarnHandlersV2SharedTokenResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/SharedTokenResponse" }, "type": [ "array", "null" ] }, "pagination": { "$ref": "#/components/schemas/PaginationPaginationMetadata" } }, "type": "object" }, "PaginationPaginatedResponseGithubComTurtleDAOTurtlePartnersGoServicesEarnHandlersV2SwapsSwapItem": { "properties": { "data": { "items": { "$ref": "#/components/schemas/SwapsSwapItem" }, "type": [ "array", "null" ] }, "pagination": { "$ref": "#/components/schemas/PaginationPaginationMetadata" } }, "type": "object" }, "PaginationPaginationMetadata": { "properties": { "limit": { "type": "integer" }, "page": { "type": "integer" }, "pageLimit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } }, "type": "object" }, "PortfolioChainInfo": { "properties": { "chainId": { "type": "string" }, "ecosystem": { "type": "string" }, "explorerUrl": { "type": "string" }, "logoUrl": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string" } }, "type": "object" }, "PortfolioGetTurtleBalanceOutput": { "properties": { "portfolio": { "$ref": "#/components/schemas/PortfolioPortfolio" } }, "type": "object" }, "PortfolioHoldingsData": { "properties": { "chains": { "items": { "$ref": "#/components/schemas/PortfolioChainInfo" }, "type": [ "array", "null" ] }, "manualPositions": { "items": { "$ref": "#/components/schemas/PortfolioManualPositionData" }, "type": "array" }, "totalAmountInUSD": { "type": "string" }, "wallets": { "items": { "$ref": "#/components/schemas/PortfolioWalletData" }, "type": [ "array", "null" ] } }, "type": "object" }, "PortfolioManualPositionData": { "properties": { "accountId": { "type": [ "null", "string" ] }, "accountName": { "type": [ "null", "string" ] }, "balance": { "type": "number" }, "entryPriceUsd": { "type": [ "null", "number" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "priceUsd": { "type": "number" }, "valueUsd": { "type": "number" } }, "type": "object" }, "PortfolioPortfolio": { "properties": { "holdings": { "$ref": "#/components/schemas/PortfolioHoldingsData" }, "productsEarnings": { "items": { "$ref": "#/components/schemas/EntitiesUserEarnings" }, "type": [ "array", "null" ] } }, "type": "object" }, "PortfolioTokenData": { "properties": { "address": { "type": "string" }, "amount": { "type": "string" }, "chain": { "$ref": "#/components/schemas/PortfolioChainInfo" }, "decimals": { "type": "integer" }, "entryPriceUsd": { "type": [ "null", "string" ] }, "id": { "type": "string" }, "isNative": { "type": "boolean" }, "logoUrl": { "type": "string" }, "name": { "type": "string" }, "opportunityId": { "$ref": "#/components/schemas/UuidUUID" }, "price": { "type": "string" }, "priceDelta1d": { "type": [ "null", "number" ] }, "priceDelta30d": { "type": [ "null", "number" ] }, "priceDelta7d": { "type": [ "null", "number" ] }, "priceStale": { "type": [ "null", "boolean" ] }, "rawAmount": { "type": "string" }, "symbol": { "type": "string" } }, "type": "object" }, "PortfolioWalletData": { "properties": { "address": { "type": "string" }, "id": { "type": "string" }, "name": { "type": [ "null", "string" ] }, "protocols": { "items": { "$ref": "#/components/schemas/TypesProtocolPositions" }, "type": [ "array", "null" ] }, "tokens": { "items": { "$ref": "#/components/schemas/PortfolioTokenData" }, "type": [ "array", "null" ] }, "totalAmountInUSD": { "type": "string" } }, "type": "object" }, "RestErrResponse": { "properties": { "code": { "description": "Application-specific error code.", "type": "integer" }, "context": { "additionalProperties": {}, "description": "Application context.", "type": "object" }, "error": { "description": "Error message.", "type": "string" }, "status": { "description": "Status text.", "type": "string" } }, "type": "object" }, "SharedChainResponse": { "properties": { "chainId": { "description": "Numeric chain ID (e.g. 1 for Ethereum, 43114 for Avalanche)", "type": "integer" }, "explorerUrl": { "description": "Block explorer base URL", "type": "string" }, "logoUrl": { "description": "Chain logo image URL", "type": "string" }, "name": { "description": "Chain full name", "type": "string" } }, "type": "object" }, "SharedTokenResponse": { "properties": { "address": { "description": "Token contract address", "type": "string" }, "chainId": { "description": "Numeric chain ID the token belongs to", "type": "integer" }, "decimals": { "description": "ERC20 decimals", "type": "integer" }, "logoUrl": { "description": "Token logo image URL", "type": "string" }, "symbol": { "description": "Token symbol (e.g. USDC, ETH)", "type": "string" } }, "type": "object" }, "StreamsActiveAdminOperation": { "properties": { "blockingUntil": { "description": "When the stream takes a new withdrawal or budget increase again.", "format": "date-time", "type": "string" }, "confirmedAt": { "description": "Block time of the transaction that executed it; null until then.", "format": "date-time", "type": [ "null", "string" ] }, "confirmedTxHash": { "description": "Transaction that executed it; null until then. Once set, do not submit txParams again.", "type": [ "string", "null" ] }, "txParams": { "$ref": "#/components/schemas/AdminOperationsTxParamsGithubComTurtleDAOTurtlePartnersGoServicesEarnHandlersV2StreamsAdminOperationParams" }, "type": { "description": "What txParams calls on the StreamFactory, and so the shape of txParams.params.params: withdraw (withdrawFunds) or add_funds (addFunds).", "type": "string" } }, "type": [ "object", "null" ] }, "StreamsAdapterConfig": { "properties": { "params": {}, "type": { "type": "string" } }, "type": "object" }, "StreamsAdapterConfigType2": { "properties": { "params": {}, "type": { "type": "string" } }, "type": "object" }, "StreamsAdapterConfigs": { "items": { "$ref": "#/components/schemas/StreamsAdapterConfig" }, "type": [ "array", "null" ] }, "StreamsAdapterConfigsType2": { "items": { "$ref": "#/components/schemas/StreamsAdapterConfigType2" }, "type": [ "array", "null" ] }, "StreamsAdminOperationParams": { "oneOf": [ { "$ref": "#/components/schemas/StreamsIStreamFactoryWithdrawFundsParams" }, { "$ref": "#/components/schemas/StreamsIStreamFactoryAddFundsParams" } ], "type": "object" }, "StreamsCreatePointInput": { "properties": { "decimals": { "minimum": 0, "type": [ "null", "integer" ] }, "logoUrl": { "type": [ "null", "string" ] }, "name": { "type": "string" }, "symbol": { "type": "string" } }, "type": "object" }, "StreamsCreatePointOutput": { "properties": { "point": { "$ref": "#/components/schemas/StreamsPoint" } }, "type": "object" }, "StreamsCreateStreamFuncParams": { "properties": { "deadline": { "type": [ "null", "string" ] }, "params": { "$ref": "#/components/schemas/StreamsIStreamFactoryCreateStreamParams" }, "signature": { "format": "base64", "type": "string" } }, "type": "object" }, "StreamsCreateStreamOutput": { "properties": { "message": { "type": "string" }, "stream": { "$ref": "#/components/schemas/StreamsStream" }, "txParams": { "$ref": "#/components/schemas/StreamsCreateStreamTxParams" } }, "type": "object" }, "StreamsCreateStreamRequestParams": { "properties": { "adapters": { "$ref": "#/components/schemas/StreamsAdapterConfigsType2" }, "customArgs": {}, "endTimestamp": { "format": "date-time", "type": [ "null", "string" ] }, "pointId": { "$ref": "#/components/schemas/UuidUUID" }, "rewardTokenId": { "$ref": "#/components/schemas/UuidUUID" }, "startTimestamp": { "format": "date-time", "type": "string" }, "totalAmount": { "type": [ "null", "string" ] }, "type": { "minimum": 0, "type": "integer" }, "walletAddress": { "type": [ "string", "null" ] } }, "type": "object" }, "StreamsCreateStreamTxParams": { "properties": { "chainId": { "minimum": 0, "type": "integer" }, "params": { "$ref": "#/components/schemas/StreamsCreateStreamFuncParams" }, "sender": { "type": [ "string", "null" ] } }, "type": "object" }, "StreamsGetActiveAdminOperationOutput": { "properties": { "operation": { "anyOf": [ { "$ref": "#/components/schemas/StreamsActiveAdminOperation", "description": "The admin operation blocking the stream; null when it takes a new one." }, { "type": "null" } ] } }, "type": "object" }, "StreamsGetMerkleProofsOutput": { "properties": { "proofs": { "items": { "$ref": "#/components/schemas/StreamsStreamMerkleProof" }, "type": [ "array", "null" ] } }, "type": "object" }, "StreamsGetPointsOutput": { "properties": { "points": { "items": { "$ref": "#/components/schemas/StreamsPoint" }, "type": [ "array", "null" ] } }, "type": "object" }, "StreamsGetStreamsForWalletOutput": { "properties": { "streams": { "items": { "$ref": "#/components/schemas/StreamsWalletData" }, "type": [ "array", "null" ] } }, "type": "object" }, "StreamsGetStreamsOutput": { "properties": { "streams": { "items": { "$ref": "#/components/schemas/StreamsStream" }, "type": [ "array", "null" ] } }, "type": "object" }, "StreamsGetTokensOutput": { "properties": { "tokens": { "items": { "$ref": "#/components/schemas/StreamsSupportedToken" }, "type": [ "array", "null" ] } }, "type": "object" }, "StreamsGetWalletOutput": { "properties": { "wallet": { "$ref": "#/components/schemas/StreamsWalletData" } }, "type": "object" }, "StreamsGetWalletsOutput": { "properties": { "data": { "items": { "$ref": "#/components/schemas/StreamsWalletWithLastSnapshot" }, "type": [ "array", "null" ] }, "pagination": { "$ref": "#/components/schemas/UtilsPaginationResponse" } }, "type": "object" }, "StreamsIStreamFactoryAddFundsParams": { "properties": { "feeAmount": { "description": "The fee charged on top, in the smallest token unit.", "type": "string" }, "netAmount": { "description": "The budget increase, in the smallest token unit.", "type": "string" }, "stream": { "type": "string" } }, "required": [ "stream", "netAmount", "feeAmount" ], "type": "object" }, "StreamsIStreamFactoryCreateStreamParams": { "type": "object" }, "StreamsIStreamFactoryWithdrawFundsParams": { "properties": { "amount": { "description": "Smallest token unit.", "type": "string" }, "stream": { "type": "string" }, "to": { "type": "string" } }, "required": [ "stream", "to", "amount" ], "type": "object" }, "StreamsPoint": { "properties": { "createdAt": { "format": "date-time", "type": "string" }, "decimals": { "minimum": 0, "type": "integer" }, "id": { "$ref": "#/components/schemas/UuidUUID" }, "logoUrl": { "type": [ "null", "string" ] }, "name": { "type": "string" }, "orgId": { "$ref": "#/components/schemas/UuidUUID" }, "symbol": { "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "type": "object" }, "StreamsPostStreamsBulkInput": { "properties": { "ids": { "$ref": "#/components/schemas/UuidUUIDs", "description": "Filter by stream IDs" }, "organizationIds": { "$ref": "#/components/schemas/UuidUUIDs", "description": "Filter by owning organization IDs" }, "targetChainIds": { "description": "Filter by streams whose target token is on these chains", "items": { "minimum": 0, "type": "integer" }, "type": [ "array", "null" ] }, "targetTokens": { "description": "Filter by streams whose target token matches these (chainId, address) tokens", "items": { "$ref": "#/components/schemas/UtilsEvmAccount" }, "type": [ "array", "null" ] }, "usersCount": { "type": "boolean" }, "withSnapshots": { "type": "boolean" } }, "type": "object" }, "StreamsPostStreamsBulkOutput": { "properties": { "pagination": { "$ref": "#/components/schemas/UtilsPaginationResponse", "description": "Pagination metadata; omitted when no pagination was requested" }, "streams": { "items": { "$ref": "#/components/schemas/StreamsStream" }, "type": [ "array", "null" ] } }, "type": "object" }, "StreamsStream": { "properties": { "adapters": { "$ref": "#/components/schemas/StreamsAdapterConfigs" }, "admin": { "type": [ "string", "null" ] }, "chainId": { "minimum": 0, "type": [ "null", "integer" ] }, "claimPaused": { "type": "boolean" }, "committedSnapshot": { "$ref": "#/components/schemas/StreamsStreamSnapshot" }, "contractAddress": { "type": [ "string", "null" ] }, "createdAt": { "format": "date-time", "type": "string" }, "creationConfirmedAt": { "format": "date-time", "type": [ "null", "string" ] }, "customArgs": {}, "endTimestamp": { "format": "date-time", "type": [ "null", "string" ] }, "estimatedLiveApr": { "description": "Estimated APR the stream is currently distributing, taken from the last snapshot. Unlike lastSnapshot.apr — a historical value tied to its own timestamp — this is only set while the stream is actively accruing; it is null when snapshot computation is paused, the stream has ended, or the last snapshot is older than 24h.", "type": [ "null", "string" ] }, "hashCommitmentPaused": { "type": "boolean" }, "id": { "$ref": "#/components/schemas/UuidUUID" }, "lastSnapshot": { "$ref": "#/components/schemas/StreamsStreamSnapshot" }, "merkleTreeComputationPaused": { "type": "boolean" }, "orgId": { "$ref": "#/components/schemas/UuidUUID" }, "point": { "$ref": "#/components/schemas/StreamsPoint" }, "rewardToken": { "$ref": "#/components/schemas/StreamsSupportedToken" }, "snapshotComputationPaused": { "type": "boolean" }, "snapshots": { "items": { "$ref": "#/components/schemas/StreamsStreamSnapshot" }, "type": "array" }, "startTimestamp": { "format": "date-time", "type": "string" }, "status": { "description": "Lifecycle state computed server-side, currently one of live, scheduled, paused, delayed or ended. A stream that finished accruing is always reported as ended, even if paused afterward; short of that, paused and delayed take precedence, so a stream in either state may also have ended - compare endTimestamp to tell. Treat this as an open set: further values may be added, so handle an unrecognized status gracefully rather than failing on it.", "type": "string" }, "strategy": { "type": "string" }, "totalAmount": { "type": [ "null", "string" ] }, "type": { "minimum": 0, "type": "integer" }, "updatedAt": { "format": "date-time", "type": "string" }, "userId": { "$ref": "#/components/schemas/UuidUUID" } }, "type": "object" }, "StreamsStreamMerkleProof": { "properties": { "amount": { "type": [ "null", "string" ] }, "chainId": { "minimum": 0, "type": [ "null", "integer" ] }, "contractAddress": { "type": "string" }, "error": { "type": "string" }, "proof": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "rootHash": { "type": "string" }, "streamId": { "$ref": "#/components/schemas/UuidUUID" }, "timestamp": { "format": "date-time", "type": [ "null", "string" ] } }, "type": "object" }, "StreamsStreamSnapshot": { "properties": { "activeUserCount": { "minimum": 0, "type": [ "null", "integer" ] }, "amountBase": { "type": [ "null", "string" ] }, "amountDistributed": { "type": [ "null", "string" ] }, "apr": { "type": [ "null", "string" ] }, "baseApr": { "type": [ "null", "string" ] }, "baseTvl": { "type": [ "null", "string" ] }, "commitTxHash": { "type": [ "string", "null" ] }, "createdAt": { "format": "date-time", "type": "string" }, "customArgs": {}, "customMetrics": {}, "rewardTokenPrice": { "type": [ "null", "string" ] }, "rootHash": { "type": [ "string", "null" ] }, "timestamp": { "format": "date-time", "type": "string" }, "tvl": { "type": [ "null", "string" ] }, "updatedAt": { "format": "date-time", "type": "string" }, "userCount": { "minimum": 0, "type": [ "null", "integer" ] } }, "type": "object" }, "StreamsSupportedToken": { "properties": { "address": { "type": "string" }, "chainId": { "minimum": 0, "type": "integer" }, "decimals": { "type": "integer" }, "id": { "$ref": "#/components/schemas/UuidUUID" }, "isAllowedRewardToken": { "type": "boolean" }, "logoUrl": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" } }, "type": "object" }, "StreamsWalletData": { "properties": { "snapshots": { "items": { "$ref": "#/components/schemas/StreamsWalletSnapshot" }, "type": [ "array", "null" ] }, "stream": { "$ref": "#/components/schemas/StreamsStream" }, "streamId": { "$ref": "#/components/schemas/UuidUUID" }, "userAddress": { "type": [ "string", "null" ] } }, "type": "object" }, "StreamsWalletSnapshot": { "properties": { "apr": { "type": [ "null", "string" ] }, "baseApr": { "type": [ "null", "string" ] }, "baseTvl": { "type": [ "null", "string" ] }, "createdAt": { "format": "date-time", "type": "string" }, "customMetrics": {}, "rewardsAccumulated": { "type": [ "string", "null" ] }, "rewardsAccumulatedBase": { "type": [ "string", "null" ] }, "timestamp": { "format": "date-time", "type": "string" }, "tvl": { "type": [ "null", "string" ] }, "updatedAt": { "format": "date-time", "type": "string" } }, "type": "object" }, "StreamsWalletWithLastSnapshot": { "properties": { "lastSnapshot": { "$ref": "#/components/schemas/StreamsWalletSnapshot" }, "userAddress": { "type": "string" } }, "type": "object" }, "StreamsWithdrawFundsInput": { "properties": { "amount": { "description": "Smallest token unit. Defaults to the maximum withdrawable amount.", "type": [ "null", "string" ] }, "signatureExpirationSeconds": { "description": "Seconds the signature stays valid: 300 (default) to 86400 (one day), e.g. for a multisig admin. The stream takes no other withdrawal or budget increase until it expires, or until this one executes and is final.", "minimum": 0, "type": [ "null", "integer" ] }, "to": { "description": "Recipient of the funds. Defaults to the stream admin.", "type": [ "string", "null" ] } }, "type": "object" }, "StreamsWithdrawFundsOutput": { "properties": { "message": { "type": "string" }, "txParams": { "$ref": "#/components/schemas/AdminOperationsTxParamsGithubComTurtleDAOTurtlePartnersGoServicesEarnHandlersV2StreamsIStreamFactoryWithdrawFundsParams" } }, "type": "object" }, "SwapsSwapItem": { "properties": { "amountIn": { "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "dstChain": { "$ref": "#/components/schemas/SharedChainResponse" }, "expectedAmountOut": { "type": [ "null", "string" ] }, "expiresAt": { "format": "date-time", "type": [ "null", "string" ] }, "filledAmountIn": { "type": [ "null", "string" ] }, "filledAmountOut": { "type": [ "null", "string" ] }, "id": { "$ref": "#/components/schemas/UuidUUID" }, "kind": { "type": "string" }, "minAmountOut": { "type": [ "null", "string" ] }, "provider": { "type": "string" }, "providerOrderRef": { "type": [ "null", "string" ] }, "slippageBps": { "type": "integer" }, "srcChain": { "$ref": "#/components/schemas/SharedChainResponse" }, "status": { "type": "string" }, "tokenIn": { "$ref": "#/components/schemas/SwapsTokenInfo" }, "tokenOut": { "$ref": "#/components/schemas/SwapsTokenInfo" }, "txHash": { "type": [ "null", "string" ] }, "updatedAt": { "format": "date-time", "type": "string" }, "userAddress": { "type": "string" } }, "type": "object" }, "SwapsTokenInfo": { "properties": { "address": { "type": "string" }, "decimals": { "type": [ "null", "integer" ] }, "logoUrl": { "type": [ "null", "string" ] }, "symbol": { "type": [ "null", "string" ] } }, "type": "object" }, "TrackingEarnTrackingMetadata": { "properties": { "action": { "type": "string" }, "actionId": { "type": "string" }, "amount": { "type": "string" }, "amountUsd": { "type": "string" }, "distributorId": { "type": "string" }, "opportunityId": { "type": "string" }, "referralCode": { "type": "string" }, "tokenIn": { "type": "string" }, "tokenInDecimals": { "type": "integer" } }, "type": "object" }, "TypesLendingAccount": { "properties": { "available_borrows_base": { "description": "Remaining borrow capacity in the pool base currency.", "type": [ "null", "string" ] }, "health_factor": { "description": "Collateral / debt health factor. Omitted when the account has no debt.", "type": [ "null", "string" ] }, "liquidation_threshold": { "description": "Weighted liquidation threshold.", "type": [ "null", "string" ] }, "ltv": { "description": "Current loan-to-value ratio.", "type": [ "null", "string" ] }, "total_collateral_base": { "description": "Total collateral in the pool base currency.", "type": [ "null", "string" ] }, "total_debt_base": { "description": "Total debt in the pool base currency.", "type": [ "null", "string" ] } }, "type": "object" }, "TypesOrderFill": { "properties": { "filledMakerAmount": { "type": "string" }, "filledTakerAmount": { "type": "string" }, "surplusFeeAmount": { "type": "string" }, "takerFeeAmount": { "type": "string" }, "txHash": { "type": "string" } }, "type": "object" }, "TypesOrderStatus": { "properties": { "fills": { "items": { "$ref": "#/components/schemas/TypesOrderFill" }, "type": [ "array", "null" ] }, "netReceived": { "type": "string" }, "orderHash": { "type": "string" }, "status": { "type": "string" } }, "type": "object" }, "TypesPortfolioDetail": { "properties": { "borrow_token_list": { "items": { "$ref": "#/components/schemas/TypesPortfolioToken" }, "type": "array" }, "description": { "type": "string" }, "reward_token_list": { "items": { "$ref": "#/components/schemas/TypesPortfolioToken" }, "type": "array" }, "supply_token_list": { "items": { "$ref": "#/components/schemas/TypesPortfolioToken" }, "type": [ "array", "null" ] } }, "type": "object" }, "TypesPortfolioItem": { "properties": { "account": { "$ref": "#/components/schemas/TypesLendingAccount", "description": "On-chain risk snapshot for one isolated lending market. Omitted when unavailable." }, "detail": { "$ref": "#/components/schemas/TypesPortfolioDetail" }, "name": { "type": "string" }, "opportunity_id": { "$ref": "#/components/schemas/UuidUUID" }, "pool": { "$ref": "#/components/schemas/TypesPortfolioPool" }, "stats": { "$ref": "#/components/schemas/TypesPortfolioStats" }, "type": { "type": "string" } }, "type": "object" }, "TypesPortfolioPool": { "properties": { "chain": { "type": "string" }, "id": { "type": "string" } }, "type": "object" }, "TypesPortfolioStats": { "properties": { "asset_usd_value": { "type": "string" }, "debt_usd_value": { "type": "string" }, "net_usd_value": { "type": "string" } }, "type": "object" }, "TypesPortfolioToken": { "properties": { "address": { "type": "string" }, "amount": { "type": "string" }, "apy": { "description": "Signed APY percent. Borrow legs are negative; omitted on supply rows.", "type": [ "null", "number" ] }, "chain": { "type": "string" }, "decimals": { "type": "integer" }, "logo_url": { "type": "string" }, "market_id": { "type": "string" }, "name": { "type": "string" }, "opportunity_id": { "$ref": "#/components/schemas/UuidUUID" }, "price": { "type": "string" }, "price_delta_1d": { "description": "Percent change over 1d, anchored at the top of the current hour. Filled by holdings routes and GET /wallet/{address}/portfolio.", "type": [ "null", "number" ] }, "price_delta_30d": { "description": "Percent change over 30d, anchored at 00:00 UTC today. Filled by holdings routes and GET /wallet/{address}/portfolio.", "type": [ "null", "number" ] }, "price_delta_7d": { "description": "Percent change over 7d, anchored at 00:00 UTC today. Filled by holdings routes and GET /wallet/{address}/portfolio.", "type": [ "null", "number" ] }, "price_stale": { "description": "True when the feed stopped quoting this token, so price and deltas come from a frozen price. Null when not checked.", "type": [ "null", "boolean" ] }, "symbol": { "type": "string" } }, "type": "object" }, "TypesProtocolPositions": { "properties": { "id": { "type": "string" }, "logo_url": { "type": "string" }, "name": { "type": "string" }, "portfolio_item_list": { "items": { "$ref": "#/components/schemas/TypesPortfolioItem" }, "type": [ "array", "null" ] }, "site_url": { "type": "string" }, "stats": { "$ref": "#/components/schemas/TypesPortfolioStats" } }, "type": "object" }, "TypesRouteStep": { "properties": { "action": { "type": "string" }, "from": { "$ref": "#/components/schemas/TypesTokenDetails" }, "protocol": { "type": "string" }, "to": { "$ref": "#/components/schemas/TypesTokenDetails" } }, "type": "object" }, "TypesSwapMetadata": { "properties": { "amountOut": { "type": "string" }, "ensoFeeAmounts": { "items": { "type": "string" }, "type": "array" }, "feeAmounts": { "items": { "type": "string" }, "type": "array" }, "gas": { "type": "string" }, "kind": { "type": "string" }, "minAmountOut": { "type": "string" }, "priceImpactBps": { "type": [ "null", "number" ] }, "provider": { "type": "string" }, "providerImg": { "type": "string" }, "route": { "items": { "$ref": "#/components/schemas/TypesRouteStep" }, "type": [ "array", "null" ] }, "slippageBps": { "type": "integer" } }, "type": "object" }, "TypesTokenDetails": { "properties": { "address": { "type": "string" }, "decimals": { "type": "integer" }, "logoUrl": { "type": "string" }, "symbol": { "type": "string" } }, "type": "object" }, "TypesTransaction": { "properties": { "chainId": { "type": "integer" }, "data": { "type": "string" }, "gasLimit": { "type": "string" }, "to": { "type": "string" }, "value": { "type": "string" } }, "type": "object" }, "TypesTxResponseItem": { "properties": { "description": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/TypesSwapMetadata" }, "transaction": { "$ref": "#/components/schemas/TypesTransaction" }, "type": { "type": "string" } }, "type": "object" }, "UtilsEvmAccount": { "properties": { "address": { "type": "string" }, "chainId": { "minimum": 0, "type": "integer" } }, "type": "object" }, "UtilsPaginationResponse": { "properties": { "hasNext": { "type": [ "null", "boolean" ] }, "hasPrevious": { "type": [ "null", "boolean" ] }, "limit": { "type": "integer" }, "page": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } }, "type": "object" }, "UuidUUID": { "examples": [ "248df4b7-aa70-47b8-a036-33ac447e668d" ], "format": "uuid", "type": [ "null", "string" ] }, "UuidUUIDs": { "items": { "$ref": "#/components/schemas/UuidUUID" }, "type": [ "array", "null" ] }, "V2BuildSwapOrderRequest": { "properties": { "actionId": { "$ref": "#/components/schemas/UuidUUID" }, "amountIn": { "maxLength": 78, "type": "string" }, "chainId": { "minimum": 1, "type": "integer" }, "distributorId": { "type": "string" }, "minAmountOut": { "maxLength": 78, "type": "string" }, "slippageBps": { "maximum": 5000, "minimum": 1, "type": "integer" }, "tokenIn": { "type": "string" }, "tokenOut": { "type": "string" }, "userAddress": { "type": "string" } }, "required": [ "chainId", "userAddress", "tokenIn", "tokenOut", "amountIn", "slippageBps", "minAmountOut" ], "type": "object" }, "V2BuildSwapOrderResponse": { "properties": { "amountOut": { "type": "string" }, "expiresAt": { "type": "integer" }, "extension": { "type": "string" }, "minAmountOut": { "type": "string" }, "orderHash": { "type": "string" }, "quoteId": { "type": "string" }, "typedData": {} }, "type": "object" }, "V2CreateMembershipAgreementInput": { "properties": { "address": { "description": "Wallet address", "type": "string" }, "chainId": { "default": 1, "description": "Chain ID for EVM wallets", "minimum": 1, "type": "integer" }, "url": { "description": "URL for the agreement", "type": "string" }, "walletEcosystem": { "description": "Wallet ecosystem", "enum": [ "evm", "solana", "ton" ], "type": "string" } }, "required": [ "address", "walletEcosystem", "url" ], "type": "object" }, "V2CreateMembershipAgreementOutput": { "properties": { "message": { "description": "Message to be signed", "type": "string" }, "nonce": { "description": "Nonce for the signature", "type": "string" } }, "type": "object" }, "V2CreateMembershipInput": { "properties": { "address": { "type": "string" }, "distributorId": { "type": "string" }, "nonce": { "type": "string" }, "signature": { "type": "string" }, "walletEcosystem": { "type": "string" } }, "required": [ "address", "walletEcosystem", "signature", "nonce" ], "type": "object" }, "V2CreateMembershipOutput": { "properties": { "error": { "description": "Error message if any", "type": "string" }, "isMember": { "description": "Whether the wallet is associated with a user", "type": "boolean" } }, "type": "object" }, "V2GetMembershipOutput": { "properties": { "isMember": { "description": "Whether the wallet is associated with a user", "type": "boolean" } }, "type": "object" }, "V2GetSwapDetailsResponse": { "properties": { "chains": { "description": "Chains supported by the swap router (intersection of router-supported chains and our chain catalog)", "items": { "$ref": "#/components/schemas/V2SwapChain" }, "type": [ "array", "null" ] }, "popularTokens": { "description": "Top tokens by TVL for the requested chain. Empty when chainId is omitted", "items": { "$ref": "#/components/schemas/V2SwapToken" }, "type": [ "array", "null" ] } }, "type": "object" }, "V2GetSwapResponse": { "properties": { "actionId": { "$ref": "#/components/schemas/UuidUUID", "description": "Unique identifier embedded in the swap tx tracking metadata" }, "transactions": { "description": "Ordered list of transactions to execute (approve + swap)", "items": { "$ref": "#/components/schemas/TypesTxResponseItem" }, "type": [ "array", "null" ] } }, "type": "object" }, "V2GetSwapTokensResponse": { "properties": { "data": { "description": "Tokens matching the query for the requested chain", "items": { "$ref": "#/components/schemas/V2SwapToken" }, "type": [ "array", "null" ] }, "pagination": { "$ref": "#/components/schemas/UtilsPaginationResponse", "description": "Pagination metadata" } }, "type": "object" }, "V2ProtocolResponse": { "properties": { "logoUrl": { "description": "Protocol logo image URL", "type": "string" }, "name": { "description": "Protocol name", "type": "string" }, "siteUrl": { "description": "Protocol website URL", "type": "string" } }, "type": "object" }, "V2ReportSwapExecutionRequest": { "properties": { "actionId": { "$ref": "#/components/schemas/UuidUUID" }, "amountIn": { "maxLength": 78, "type": "string" }, "chainId": { "minimum": 1, "type": "integer" }, "distributorId": { "type": "string" }, "expectedAmountOut": { "maxLength": 78, "type": "string" }, "minAmountOut": { "maxLength": 78, "type": "string" }, "provider": { "enum": [ "enso", "1inch" ], "type": "string" }, "slippageBps": { "maximum": 5000, "minimum": 1, "type": "integer" }, "tokenIn": { "type": "string" }, "tokenOut": { "type": "string" }, "txHash": { "pattern": "^0x[0-9a-fA-F]{64}$", "type": "string" }, "userAddress": { "type": "string" } }, "required": [ "userAddress", "chainId", "txHash", "tokenIn", "tokenOut", "amountIn", "provider", "slippageBps" ], "type": "object" }, "V2SubmitSwapOrderRequest": { "properties": { "actionId": { "$ref": "#/components/schemas/UuidUUID" }, "chainId": { "minimum": 1, "type": "integer" }, "extension": { "type": "string" }, "quoteId": { "type": "string" }, "signature": { "type": "string" }, "typedData": {}, "userAddress": { "type": "string" } }, "required": [ "chainId", "userAddress", "typedData", "extension", "quoteId", "signature" ], "type": "object" }, "V2SubmitSwapOrderResponse": { "properties": { "orderHash": { "type": "string" } }, "type": "object" }, "V2SwapChain": { "properties": { "chainId": { "description": "Numeric chain ID", "type": "string" }, "ecosystem": { "description": "Blockchain ecosystem (evm, solana)", "type": "string" }, "explorerUrl": { "description": "Block explorer base URL", "type": "string" }, "logoUrl": { "description": "Chain logo URL", "type": "string" }, "name": { "description": "Chain name", "type": "string" }, "nativePriceUsd": { "description": "USD price of the chain's native token, used for gas fee math", "type": "number" }, "slug": { "description": "URL-friendly identifier", "type": "string" } }, "type": "object" }, "V2SwapToken": { "properties": { "address": { "description": "Token contract address", "type": "string" }, "chainId": { "description": "Numeric chain ID this token belongs to", "type": "string" }, "decimals": { "description": "Token decimals", "type": "integer" }, "isNative": { "description": "Whether token is native to the chain", "type": "boolean" }, "logoUrl": { "description": "Token logo URL", "type": "string" }, "name": { "description": "Token full name", "type": "string" }, "priceUsd": { "description": "USD price", "type": "number" }, "symbol": { "description": "Token symbol", "type": "string" } }, "type": "object" } } } }