Skip to main content

​
October 2026

Earn API /v1 removed
  • Every /v1 endpoint has been removed and now returns 404. All but GET /v1/route (below) have a /v2 path for the same resource.
  • /v2 reads camelCase parameters only (for example distributorId, tokenIn, slippageBps). The snake_case names that /v1 accepted are now ignored.
  • GET /v1/route has no /v2 counterpart: set mode=swap on the deposit request, or call GET /v2/swap/ for a standalone swap. See Swap Mode.
  • OpenAPI operationIds dropped their V2 suffix: GetEarnSwapV2 is now GetSwap, and BuildSwapOrderV2, SubmitSwapOrderV2, GetSwapOrderStatusV2, ReportSwapExecutionV2, GetDistributorDepositsV2, CreateMembershipV2 and CreateMembershipAgreementV2 lose the suffix. Five more operationIds get real names: GetAttribution (was getDistributeAttribution), GetDistributorMetrics (was getDistributorMetrics), GetDistributorLPs (was getDistributorLPs), GetMerkleProofs (was turtle/streams.GetMerkleProofsHandler) and GetWalletPortfolio (was turtle/portfolio.GetTurtleBalanceHandler). The membership request schemas are now V2CreateMembershipInput and V2CreateMembershipAgreementInput. Clients generated from the OpenAPI spec get the new method and type names when regenerated; requests and responses are unchanged.
Streams: withdraw funds and active admin operations
  • New POST /v2/streams/{id}/withdrawals signs a withdrawal of the reward tokens a token stream holds beyond what it must keep for rewards: the surplus above its budget while it runs, and the undistributed leftover once it is fully processed. The stream admin submits the returned txParams to withdrawFunds on the StreamFactory.
  • to and amount are optional and default to the stream admin and the max withdrawable amount. signatureExpirationSeconds (300 by default, up to 86400) gives multisig admins time to collect signatures.
  • A stream accepts one admin operation (a withdrawal or a budget increase) at a time. New GET /v2/streams/{id}/admin-operations/active returns the operation blocking a stream, its blockingUntil, whether it executed, and the same signed txParams so a client that lost them can still submit them before the deadline.
  • Both endpoints are available on /v2 only, and require a secret key and the organization:incentivize:streams permission.
  • Documented on Withdraw Funds and Get Active Admin Operation.

​
August 2026

Wallet portfolio matches the app holdings payload
  • GET /v1/wallet/{address}/portfolio and GET /v2/wallet/{address}/portfolio now return the same holdings envelope as the main Turtle API GET /wallet/{address}/balance (the shape the app uses).
  • The response is { portfolio: { productsEarnings, holdings } }. Idle ERC-20 and native balances live under holdings.wallets[].tokens; structured DeFi positions live under holdings.wallets[].protocols.
  • Breaking: the previous DeFi-only { total_stats, protocols } top-level shape is gone from Earn. Read protocol positions from portfolio.holdings.wallets[].protocols.
  • New query param includeProtocolTokens (default false) keeps protocol receipt tokens out of the token list so they are not double-counted with DeFi rows.
  • Documented on User Positions.

​
July 2026

Deposit and withdraw: on-chain balance preflight
  • Deposit and withdraw endpoints now read the user’s on-chain balance of tokenIn (or vault shares, for withdraw) before building the transactions.
  • Requests where the wallet holds less than amount are rejected up front with 400 INVALID_ARGUMENT and error insufficient token balance, instead of failing later on-chain.
  • Documented on the Deposit and Withdraw pages under Error Handling.
Streams: 1.5% creation fee, with Turtle Pro exempt
  • Token streams now include a 1.5% creation fee, charged in the reward token and pulled at stream creation on top of the net reward budget. Point streams remain free.
  • Turtle Pro organizations are exempt (0%).
  • The exact fee is surfaced as FeeAmount in the create-stream response and shown on the Client Portal review screen before you confirm.
  • See Streams: before you start for prerequisites and funding requirements.
Genesis Airdrop: in-app claiming
  • Eligible wallets can now check allocations and claim $TURTLE directly in the Turtle app under Your Earnings on the Liquidity Campaigns page.
  • Allocations are bound to the wallet used to contribute to the Turtle DAO — connecting a different wallet will show nothing to claim.
  • Claiming once forfeits any unvested portion. Review Vesting & Mechanics before you claim.
  • Full walkthrough: Genesis Airdrop.

​
April 2026

Documentation revamp
  • Added new pages: Authentication Overview, Opportunities Overview, Historical Data (stub), Earn API Overview, Swap Mode, Async Deposits, Portfolio Overview, Streams Overview, Distributor Model, Error Codes, OpenAPI Spec, and Changelog
  • Removed Route API page
  • Removed the POST /v1/actions/attribute endpoint; attribution is now fully automatic and documented in the Distributor Model concept
  • Retitled the distributor deposits page to “Distributor Activity” and grouped it with the wallet-scoped activity and positions endpoints under “Portfolio & Activity”
  • Added three previously undocumented response fields to Opportunities: minDepositAmountUsd, swapDirectEnabled, swapRouteEnabled
  • Added three previously undocumented query filters to Opportunities: chainIds, depositToken, tvlGreaterThan