Skip to main content

​
Overview

The Route API is the most critical endpoint for the Earn integration. It provides optimal transaction routes for deposits while ensuring proper attribution to distributors. Every deposit must use this endpoint to be tracked and assigned correctly.
Depositors must be members before they can deposit. See the Membership API for more information.
Critical: Always include the distributor_id parameter when requesting routes. This is essential for tracking deposits and proper attribution to your distributor account.

​
Endpoint

​
Get Route

Request an optimal trading route that will be tracked and attributed to your distributor. 
curl -X GET "https://earn.turtle.xyz/v1/route?\
user=0x000000000000000000000000000000000000dead&\
chain=1&\
slippage=0.015&\
token_in=0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee&\
token_out=0x69d210d3b60E939BFA6E87cCcC4fAb7e8F44C16B&\
amount=7756692997833272&\
distributor_id=your-distributor-id&\
Query Parameters
​
user
string
required
The user’s EOA (Externally Owned Account) address that will execute the transaction
​
chain
integer
required
The chain ID where the transaction will be executed (e.g., 1 for Ethereum Mainnet, 137 for Polygon)
​
slippage
number
required
Acceptable slippage tolerance as a decimal (min: 0.001 = 0.1%, max: 0.5 = 50%)
​
token_in
string
required
Input token address or native for the chain’s native token (e.g., ETH on Ethereum)
​
token_out
string
required
Output token address (opportunity’s receipt token address)
​
amount
string
required
Amount to trade in the smallest unit (wei for ETH, base units for tokens)
​
distributor_id
string
required
CRITICAL: Your unique distributor identifier for tracking and attribution
Response 
{
  "data": {
    "amount_out": "7713405331954853",
    "approve_failed": false,
    "price_impact": 0.0007,
    "steps": [
      {
        "kind": "enso",
        "amount_out": "7713405331954853",
        "asset": {
          "name": "Enso",
          "data": [{ "kind": "image", "url": "https://cdn.turtle.club/EnsoLogo.png" }]
        },
        "substeps": [
          {
            "kind": "deposit",
            "protocol": "turtle-club-katana-veda",
            "vault": "0x739a1eff...",
            "from": [{ "symbol": "ETH", "decimals": 18, "price": 4168.57 }],
            "to": [{ "address": "0x69d210d3...", "decimals": 18 }]
          }
        ],
        "tx": {
          "from": "0x0000...dead",
          "to": "0xf75584ef...",
          "data": "0xb94c36090...000",
          "value": "7756692997833272",
          "gas": 274625
        }
      }
    ]
  },
  "exp": 1760376664634
}

​
Response Fields

The route response contains one or more steps, each with a ready-to-sign transaction (tx field) that should be executed sequentially. The substeps array provides detailed information about what each transaction will do (swap, deposit, etc.).
​
data
object
required
Contains the route data with steps and execution details
​
data.steps
Step[]
required
Array of steps required to execute the route. Each step represents an action (e.g., approval, swap, deposit)
​
data.amount_out
string
required
Expected output amount in the smallest unit of the output token
​
data.price_impact
number
required
Expected price impact as a decimal (e.g., 0.0007 = 0.07%)
​
data.approve_failed
boolean
required
Whether the approval step failed
​
exp
integer
required
Unix timestamp when this route expires. Routes should be executed before this time

​
Step Object

​
kind
string
required
The type of step (e.g., “enso” for Enso protocol operations)
​
amount_out
string
required
The output amount for this specific step
​
asset
object
required
Information about the asset/protocol being used in this step
​
substeps
array
required
Detailed substeps showing the token flow and operations
​
tx
object
required
The transaction object to execute for this step

​
Transaction Object (tx)

​
from
string
required
The user’s address (same as the user parameter)
​
to
string
required
The contract address to send the transaction to
​
data
string
required
Encoded transaction data (calldata)
​
value
string
required
Amount of native token to send with the transaction (in wei)
​
gas
number
required
Estimated gas limit for the transaction

​
Substep Object

​
kind
string
required
The type of operation (e.g., “deposit”, “swap”, “approve”)
​
amount
string
required
The amount being processed in this substep
​
protocol
string
required
The protocol identifier handling this operation
​
vault
string
required
The vault contract address receiving the deposit
​
from
array
required
Array of token(s) being sent, including address, chain, decimals, symbol, price, and logos
​
to
array
required
Array of token(s) being received, including address, chain, decimals, symbol, and logos
​
price_impact
number | null
Price impact for this specific substep (if applicable)

​
Slippage Guidelines

Low Slippage

0.1% - 0.5%Stablecoin swaps and low volatility pairs

Medium Slippage

0.5% - 2%Normal market conditions for most tokens

High Slippage

2% - 5%High volatility or low liquidity pairs

​
Important Notes

Routes have an expiration time (exp field). Execute transactions before this timestamp to ensure the route is still valid and prices haven’t changed significantly.
Distributor ID is mandatory! Without it, deposits will not be tracked or attributed to your account. Always include distributor_id in every route request.
Routes may contain multiple steps (e.g., approval, swap, deposit). Each step contains a transaction object (tx) that must be executed sequentially in the order provided.

​
Error Handling

​
Common Errors

Status Code: 400 Bad RequestResponse:
{
  "error": {
    "status": "INVALID_ARGUMENT",
    "error": "slippage must be between 0.001 (0.1%) and 0.5 (50%)"
  }
}
Solution: Use a slippage value between 0.001 and 0.5
Status Code: 400 Bad RequestResponse:
{
  "error": {
    "status": "INVALID_ARGUMENT",
    "error": "distributor_id is required"
  }
}
Solution: Always include your distributor ID in the request
Status Code: 400 Bad RequestResponse:
{
  "error": {
    "status": "INVALID_ARGUMENT",
    "error": "unsupported chain"
  }
}
Solution: Use a supported chain ID. Check the opportunities endpoint for available chains
Status Code: 400 Bad RequestResponse:
{
  "error": {
    "status": "INVALID_ARGUMENT",
    "error": "invalid token address"
  }
}
Solution: Verify token addresses are valid for the specified chain. Use native for native tokens
Status Code: 404 Not FoundResponse:
{
  "error": {
    "status": "NOT_FOUND",
    "error": "no route found for given parameters"
  }
}
Solution: The requested swap is not possible. Verify the token addresses and chain.
Status Code: 400 Bad RequestResponse:
{
  "error": {
    "status": "INVALID_ARGUMENT",
    "error": "amount too low"
  }
}
Solution: Increase the deposit amount. Very small amounts may not be economical due to gas costs
⌘I