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.

Every deposit routed through the Earn API carries a tracking signature appended to the transaction calldata. This signature is the cryptographic proof that links a deposit to the partner that sourced it.

​
Signature Format

turtle:v1:{distributorId}:{referralCode}
FieldDescription
turtleProtocol identifier — confirms this is a Turtle-attributed transaction
v1Signature version
{distributorId}The partner’s unique distributor ID (set via the distributorId parameter in the deposit request)
{referralCode}Optional referral code — empty if none was provided at deposit time
Example: 
turtle:v1:dist_abc123:ref_001
This signature tells you: the deposit was sourced by distributor dist_abc123 with referral code ref_001.

​
Where It Lives

The tracking signature is UTF-8 encoded and appended to the tail of the deposit transaction’s calldata. It does not interfere with the deposit function’s ABI-encoded parameters — it occupies trailing bytes that the smart contract ignores but the Lumon collector reads. 
┌─────────────────────────────────────────────────────────────┐
│  Transaction calldata                                       │
│  ┌──────────────────────┬──────────────────────────────┐    │
│  │  ABI-encoded deposit │  Tracking signature (tail)   │    │
│  │  function params     │  turtle:v1:dist_abc123:...   │    │
│  └──────────────────────┴──────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
The signature is only present in the deposit transaction. The token approval transaction (if returned) does not carry a tracking signature.

​
Extracting the Signature

​
From the Verify Endpoint

The simplest way to extract and validate a tracking signature is through the verify endpoint: 
curl -X GET "https://earn.turtle.xyz/v1/actions/verify?chainId=1&txHash=0xabc123..." \
  -H "X-API-Key: pk_live_xxxxx"
Response: 
{
  "tag": "turtle:v1:dist_abc123:ref_001",
  "metadata": {
    "distributorId": "dist_abc123",
    "referralCode": "ref_001"
  },
  "signatureValid": true
}

​
From Raw Calldata

For independent verification without calling Turtle’s API, the signature can be extracted directly from the transaction calldata available on any block explorer or via an RPC node.
1

Get the transaction calldata

Retrieve the deposit transaction’s input (calldata) field from the chain — via Etherscan, a block explorer, or an RPC call (eth_getTransactionByHash).
2

Decode the trailing bytes

The tracking signature occupies the trailing bytes of the calldata, UTF-8 encoded. Decode the tail of the hex-encoded input field to reveal the turtle:v1:... string.
3

Parse the fields

Split on : to extract the protocol identifier, version, distributor ID, and referral code.
The exact byte offset depends on the vault contract’s deposit function signature and parameter encoding. For a guided walkthrough of byte-level extraction for your integration, contact the Turtle team.

​
On-Chain Proof

Because the tracking signature is embedded in calldata — part of the permanent on-chain record — it provides several guarantees:
PropertyGuarantee
ImmutabilityOnce the transaction is finalized, the signature cannot be altered or removed
Public auditabilityAnyone can read the calldata from the blockchain without special access
Independence from TurtleThe proof exists on-chain regardless of Turtle’s systems or API availability
Tamper evidenceThe signatureValid check in the verify endpoint confirms the signature was generated by Turtle’s deposit flow

How Attribution Works

The full four-step attribution flow.

Independent Verification

Verification workflows for audits and reconciliation.

Verify Endpoint

API reference for the transaction verification endpoint.