Skip to main content
This guide walks you through the core integration flow: discover opportunities, onboard a wallet, generate a deposit transaction, and verify attribution.
1

Get your API key

Sign in to the Turtle Dashboard and generate an API key for your distributor. You will receive two keys:
  • pk_live_ — Public key. Safe to use in client-side code. Used for read-only endpoints like fetching opportunities.
  • sk_live_ — Secret key. Must be kept server-side. Required for write operations like generating deposit transactions.
Pass your key via the X-API-Key header on every request. See Authentication for full details.
2

Discover opportunities

Fetch the opportunities available for your distributor.
curl -X GET "https://earn.turtle.xyz/v1/opportunities/distributors/{distributor_id}" \
  -H "X-API-Key: pk_live_xxxxx"
The response contains an array of opportunity objects with APR, TVL, supported tokens, and chain information. See Opportunities for the full schema.
3

Onboard a wallet

Before a user can deposit, they must accept the Turtle membership agreement and be registered as a member.
# Step 1: Fetch the membership agreement
curl -X POST "https://earn.turtle.xyz/v1/membership/agreement" \
  -H "X-API-Key: sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"walletAddress": "0xUserWalletAddress"}'

# Step 2: Create the membership (after user signs the agreement)
curl -X POST "https://earn.turtle.xyz/v1/membership" \
  -H "X-API-Key: sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "walletAddress": "0xUserWalletAddress",
    "signature": "0xSignedAgreement...",
    "distributor_id": "your-distributor-id"
  }'
See Membership for details on the agreement flow.
4

Generate a deposit transaction

Once the wallet is onboarded, generate a deposit transaction for a specific opportunity.
curl -X POST "https://earn.turtle.xyz/v1/actions/deposit/{opportunityId}" \
  -H "X-API-Key: sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "walletAddress": "0xUserWalletAddress",
    "depositAmount": "1000000",
    "depositToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "chainId": "1",
    "distributor_id": "your-distributor-id"
  }'
The API supports two deposit modes. Direct mode deposits the token directly into the vault. Route mode swaps the deposit token into the vault’s base token first. The mode is selected automatically based on the opportunity’s swapDirectEnabled and swapRouteEnabled flags.
The response includes a transaction object (tx) that your frontend can pass to the user’s wallet for signing.
5

Verify attribution

After the user submits the transaction on-chain, verify that Turtle’s tracking data was included correctly.
curl -X GET "https://earn.turtle.xyz/v1/actions/verify?txHash=0xYourTxHash&chainId=1" \
  -H "X-API-Key: pk_live_xxxxx"
A successful verification confirms the deposit is attributed to your distributor and will count toward your revenue share.

​
Next steps

  • Opportunities API — Full reference for filtering and querying opportunities
  • Distributor Model — Understand how distributor scoping and revenue attribution work
  • Deposits API — Query and track deposits made through your distributor