Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.turtle.xyz/llms.txt

Use this file to discover all available pages before exploring further.

Attribution is fully automatic. After the deposit transaction confirms on-chain, the Lumon collector handles detection and recording — no additional API calls required.

​
Attribution Flow

Partner calls         Turtle returns tx        User signs tx         Lumon collector
deposit endpoint  →   with tracking sig    →   on-chain          →   detects & records
                      in calldata
1

Request deposit transactions

Your integration calls the deposit endpoint with the depositor’s wallet and your distributorId:
curl -X POST "https://earn.turtle.xyz/v1/actions/deposit/{opportunityId}" \
  -H "X-API-Key: pk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "userAddress": "0x1234...abcd",
    "tokenIn": "0xA0b8...eB48",
    "amount": "1000000000000000000",
    "distributorId": "your_distributor_id",
    "mode": "direct"
  }'
The distributorId is the critical field — it determines who the deposit is attributed to. See Distributor Model for how distributor identity works.
2

Turtle returns transactions with embedded signature

The API returns an ordered transactions[] array. Typically two transactions:
  1. Token approval — authorizes the vault contract to spend the deposit token
  2. Deposit — the actual vault deposit, with your tracking signature embedded in the calldata
{
  "actionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "transactions": [
    {
      "type": "approve",
      "transaction": {
        "to": "0xA0b8...eB48",
        "data": "0x095ea7b3...",
        "value": "0",
        "chainId": 1
      },
      "description": "Approve USDC spending"
    },
    {
      "type": "deposit",
      "transaction": {
        "to": "0x7890...1234",
        "data": "0x6e553f65...747572746c653a76313a796f75725f6469737472696275746f725f6964",
        "value": "0",
        "chainId": 1
      },
      "description": "Deposit USDC into vault"
    }
  ]
}
The tracking signature is automatically appended to the deposit transaction’s calldata. You do not need to construct or manage it — the API handles this.
3

User signs and submits on-chain

The user (or your backend signing service) signs and submits the transactions in order. Once confirmed, the tracking signature is permanently recorded in the blockchain.
TypeScript
for (const tx of transactions) {
  const txResponse = await wallet.sendTransaction(tx.transaction);
  await txResponse.wait();
}
The tracking signature is part of the on-chain calldata. This means attribution proof exists independently of Turtle’s systems — anyone can extract and verify it from the raw transaction data.
4

Lumon detects and records attribution

The Lumon collector continuously monitors all supported chains for Turtle tracking signatures in calldata. When a matching deposit is detected:
  1. The deposit is recorded with verified status
  2. The record syncs to the analytics layer via the two-phase pipeline
  3. The deposit appears in your distributor activity feed
Detection typically occurs within minutes of on-chain confirmation, depending on the chain’s finality characteristics.

​
What You Don’t Need to Do

The POST /v1/actions/attribute endpoint has been removed. Attribution is fully automatic via the Lumon collector. You do not need to call any endpoint to record attribution.
  • No manual attribution calls — Lumon handles detection automatically
  • No webhook registration — the system is polling-based on Turtle’s side
  • No calldata construction — the deposit endpoint embeds the signature for you
  • No chain-specific logic — Lumon monitors all supported chains with a single distributorId

​
Verifying Attribution

After a deposit confirms, you can verify attribution was recorded correctly: 
curl -X GET "https://earn.turtle.xyz/v1/actions/verify?chainId=1&txHash=0xabc123..." \
  -H "X-API-Key: pk_live_xxxxx"
For detailed verification workflows, see Independent Verification.

Tracking Signature

How the tracking signature is formatted and where to find it in calldata.

Deposit Endpoint

Full API reference for the deposit action endpoint.

Distributor Model

How distributor identity and attribution are connected.

Verify Endpoint

API reference for the transaction verification endpoint.