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.

Lumon builds a continuous balance timeseries from ERC20 transfer events across all indexed chains. This timeseries powers portfolio views, TVL computation, and commission calculations. Attributed deposits flow through a settlement pipeline on top of this data layer before appearing in your API queries.

​
Balance Timeseries

Lumon indexes every ERC20 Transfer event on supported chains and maintains an append-only balance timeseries keyed on (user, token, block). 
Transfer event detected
        │
        ▼
  Snapshot balance updated
  balance = prevBalance +/- transferAmount
        │
        ▼
  Latest balance = most recent snapshot
When multiple transfers involving the same user and token occur in the same block, they coalesce into a single snapshot row. Each row links back to the list of (txHash, log_index) references that contributed to it. This model means:
  • Latest balances are simply the most recent data point in the timeseries — no separate job needed
  • Historical balances are reconstructable at any block by reading the snapshot at or before that block
  • TVL at time t is computed as erc20_balance(t) * price_usd(t) — the price timeseries is maintained by a separate service
The Token Indexing API exposes this data via portfolio, balance, and snapshot endpoints. The GET /erc20_stats endpoint shows the latest processed block per chain.

​
Attribution Settlement

When a deposit confirms on-chain, the Lumon collector detects the tracking signature and records the attribution. The deposit then flows through a settlement pipeline before appearing in API queries. 
On-chain deposit confirmed
        │
        ▼
  Lumon collector detects
  tracking signature
        │
        ▼
  Attribution recorded
  and verified
        │
        ▼
  Queryable via API
  (activity feed, verify endpoint)
Once verified, the deposit is immediately available through the distributor activity endpoint and the verify endpoint. Aggregate analytics (volume, wallet counts, dashboard metrics) sync shortly after.

​
Latency

StageTypical Latency
On-chain confirmation → Lumon detectionMinutes (varies by chain finality)
Detection → queryable via APINear-instant
End-to-end: deposit → API-queryableMinutes
There is no formal SLA on attribution latency. In practice, deposits are queryable within minutes of on-chain confirmation. If a deposit does not appear after 30 minutes, verify the transaction contains a valid tracking signature using the verify endpoint.

​
Reconciliation Endpoints

Two endpoints provide different views of attributed deposits:

​
Distributor Activity

GET /v1/deposit/{distributor_id} — all deposits attributed to your integration. 
curl -X GET "https://earn.turtle.xyz/v1/deposit/{distributor_id}?limit=100&offset=0" \
  -H "X-API-Key: pk_live_xxxxx"
Returns: 
[
  {
    "tx_hash": "0xabc...",
    "depositor": "0x123...",
    "deposited_amount_usd": 50000.00,
    "chain": "ethereum",
    "timestamp": "2026-05-06T14:30:00Z"
  }
]
Pagination via limit (max 2000) and offset. Use this for reconciling all deposits flowing through your integration.

​
Wallet Activity

GET /v1/wallets/activity — deposits and withdrawals for specific wallet addresses, across all distributors. 
curl -X GET "https://earn.turtle.xyz/v1/wallets/activity?addresses=0x123...&limit=20&page=1" \
  -H "X-API-Key: pk_live_xxxxx"
Returns deposits[] and withdrawals[] arrays with opportunity details, token info, amounts, USD values, chain, and timestamps. Page-based pagination via page/limit.

​
When to Use Which

Use caseEndpoint
”Show me all deposits attributed to my integration”Distributor Activity (/v1/deposit/{id})
“Show me what this wallet has done across all distributors”Wallet Activity (/v1/wallets/activity)
“Verify a specific transaction’s attribution”Verify (/v1/actions/verify)

​
Supported Chains

Lumon indexes all chains supported by the Earn API. Two ways to check the current chain list:
  • Token Indexing API — GET /erc20_stats returns the latest processed block number per chain, showing which chains are actively indexed
  • Macrodata API — GET https://macrodata.turtle.xyz/api/query/chains returns all configured chains with current indexing status, block head, and checkpoint progress
Each opportunity also includes chain metadata, so the opportunities endpoint doubles as a chain reference.

Token Indexing API

Query the balance timeseries via portfolio, balance, and snapshot endpoints.

Independent Verification

Verification workflows for audits and reconciliation.

Distributor Activity

Full API reference for the distributor deposit activity endpoint.

Wallet Activity

Full API reference for the wallet activity endpoint.