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.

All verification requests require an API key via the X-API-Key header. See Authentication for details.
Lumon’s attribution data is independently verifiable — both through Turtle’s verify endpoint and directly from on-chain calldata. This page covers practical verification workflows for DD teams, audit processes, and automated reconciliation.

​
Verify a Single Transaction

The verify endpoint extracts and validates the tracking signature from any deposit transaction: 
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
}

​
Interpreting Results

FieldWhat it tells you
tagThe full tracking signature extracted from the transaction’s calldata
metadata.distributorIdThe partner the deposit is attributed to — confirm this matches your distributor ID
metadata.referralCodeThe referral code provided at deposit time (if any)
signatureValidtrue if the calldata contains a valid, unmodified Turtle tracking signature matching the extracted metadata
​
chainId
integer
required
The chain ID where the transaction was submitted (e.g., 1 for Ethereum mainnet, 137 for Polygon).
​
txHash
string
required
The transaction hash to verify.

​
Verification Workflows

​
Spot Checks (Manual)

For ad-hoc verification during integration testing or audits:
1

Obtain the transaction hash

Get the tx hash from your deposit logs, the distributor activity feed, or a block explorer.
2

Call the verify endpoint

Pass the chainId and txHash as query parameters.
3

Confirm attribution

Check that signatureValid is true and metadata.distributorId matches your expected distributor ID.
4

Cross-reference on-chain (optional)

Look up the transaction on a block explorer (Etherscan, Polygonscan, etc.). Decode the calldata’s trailing bytes to confirm the turtle:v1:... signature matches the verify endpoint’s response. See Tracking Signature for extraction details.

​
Batch Reconciliation (Automated)

For systematic verification of all attributed deposits:
1

Pull your deposit activity

Fetch your full deposit history from the distributor activity endpoint:
curl -X GET "https://earn.turtle.xyz/v1/deposit/{distributor_id}?limit=2000&offset=0" \
  -H "X-API-Key: pk_live_xxxxx"
2

Verify each transaction

For each deposit record, call the verify endpoint with the tx_hash and chain from the activity response:
TypeScript
for (const deposit of deposits) {
  const verifyResponse = await fetch(
    `https://earn.turtle.xyz/v1/actions/verify?chainId=${deposit.chain_id}&txHash=${deposit.tx_hash}`,
    { headers: { 'X-API-Key': 'pk_live_xxxxx' } }
  );
  const result = await verifyResponse.json();

  if (!result.signatureValid || result.metadata.distributorId !== myDistributorId) {
    console.warn(`Attribution mismatch: ${deposit.tx_hash}`);
  }
}
3

Compare against your internal records

Cross-reference Turtle’s deposit amounts and timestamps against your own ledger to confirm consistency.

​
Due Diligence Audit

For third-party DD teams verifying deposit provenance:
  1. Request the distributor’s activity feed — the partner provides their deposit list via the distributor activity endpoint
  2. Independently verify each deposit — call the verify endpoint for each tx hash, confirming signatureValid: true and the correct distributorId
  3. Cross-reference on-chain — for maximum independence, extract the tracking signature directly from calldata on a block explorer without relying on Turtle’s API
  4. Validate deposit amounts — compare deposited_amount_usd from the activity feed against on-chain token transfer amounts
The tracking signature is embedded in public calldata. A DD team can verify attribution without any access to Turtle’s internal systems — only a block explorer and the signature format specification are needed. See Tracking Signature.

​
Error Handling

Status Code: 404 Not Found
{
  "code": 404,
  "status": "NOT_FOUND",
  "error": "Transaction not found"
}
Solution: Confirm the chainId is correct for the chain where the transaction was submitted. The transaction may not have been indexed yet — retry after a few minutes.
Status Code: 200 OK (with signatureValid: false)
{
  "tag": null,
  "metadata": {},
  "signatureValid": false
}
Solution: The transaction does not contain a Turtle tracking signature. This can happen if the deposit was not routed through the Earn API’s deposit endpoint, or if the transaction is an approval (not the deposit itself).
Status Code: 429 Too Many RequestsSolution: Reduce request frequency. Rate limits are per-key and hourly. For large batch verifications, add a delay between requests.

Tracking Signature

Signature format and on-chain extraction details.

Distributor Activity

Pull your full deposit history for reconciliation.

Data Flow

How attribution records flow through the settlement pipeline.

Verify Endpoint

Full API reference for the verify endpoint.