Skip to main content
This is the shortest path from nothing to a deposit attributed to your distributor: authenticate, register the user’s wallet, find an opportunity, generate the deposit, and confirm attribution. Each step links to the full reference where the request bodies and response schemas live. New to the Turtle API? Start with the API overview for access and the full product set. This page covers the Earn deposit flow specifically.
Every call requires the X-API-Key header. See API Keys.

​
Prerequisites

You need three things before the first call:
  1. A Turtle organization, created in the Client Portal. New organizations are approved by the Turtle team before keys are issued.
  2. An API key (pk_live_ for client-side, sk_live_ for server-side). See API Keys.
  3. Your distributor ID, found under Distribution in the Client Portal.
If your organization has not been approved yet, reach out on Discord.

​
Step 1: Confirm your key works

Fetch the opportunity catalog. A 200 with an opportunities array means authentication is set up. 
curl https://earn.turtle.xyz/v1/opportunities/ \
  -H "X-API-Key: pk_live_xxxxx"
A 401 means the key is missing or wrong. See API Keys for key types, the auth header, and rate limits.

​
Step 2: Register the user’s wallet

Every wallet must be a Turtle member before it can deposit. Membership is a three-step EIP-4361 flow: check membership, request a sign-in message, submit the signature. The full request and response for each step is on Register Wallet. 
# 1. Already a member?
curl "https://earn.turtle.xyz/v1/membership/?address=0xYOUR_WALLET&walletEcosystem=evm" \
  -H "X-API-Key: pk_live_xxxxx"

# 2. If not, request a message, have the user sign it, and submit the signature.
#    See Register Wallet for the agreement and create-membership request bodies.
Pass your distributorId when you create the membership to attribute the signup to your integration.

​
Step 3: Find an opportunity

Fetch your distributor’s configured set, or browse the full catalog with filters. Each opportunity has an id you use in the next step. 
curl "https://earn.turtle.xyz/v1/opportunities/distributors/YOUR_DISTRIBUTOR_ID" \
  -H "X-API-Key: pk_live_xxxxx"
See Opportunities for the full object reference, filters, and the distributor-scoped variant.

​
Step 4: Generate the deposit

Call the deposit action with the opportunity ID, wallet, token, amount, and your distributor ID. The API returns an ordered transactions array (typically an approval followed by the deposit) for the user to sign in order. 
curl -X POST "https://earn.turtle.xyz/v1/actions/deposit/OPPORTUNITY_ID" \
  -H "X-API-Key: pk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "userAddress": "0xYOUR_WALLET",
    "tokenIn": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "amount": "1000000",
    "distributorId": "YOUR_DISTRIBUTOR_ID"
  }'
The wallet must be a member (Step 2) before this call.
For the full request body, swap mode, async (pending) deposits, and the broadcast loop, see Deposit.

​
Step 5: Confirm attribution

After the deposit confirms on-chain, verify that Turtle attributed it to you. 
curl "https://earn.turtle.xyz/v1/actions/verify?chainId=1&txHash=0xYOUR_TX_HASH" \
  -H "X-API-Key: pk_live_xxxxx"
A metadata.distributorId matching yours and signatureValid: true means attribution worked. Nothing else is required; attribution is automatic. See Verify Attribution.

​
What’s next

  • Deposit - The full deposit reference: request body, swap mode, and broadcasting.
  • Opportunities - The opportunity catalog and the full object schema.
  • Verify Attribution - Confirm a transaction was attributed to your distributor.
  • Distributor Model - How attribution and revenue share work end to end.