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.

The Token Indexing API provides real-time and historical ERC20 data powered by Lumon’s on-chain indexing infrastructure. All endpoints are unauthenticated and available at: 
https://indexing.turtle.xyz/token
The full OpenAPI 3.0 spec is available at indexing.turtle.xyz/token/docs.

​
ERC20 Endpoints

​
Portfolio

Returns all current ERC20 token balances for a wallet address. 
curl -X POST https://indexing.turtle.xyz/token/erc20_portfolio \
  -H "Content-Type: application/json" \
  -d '{
    "user": "0x1234...abcd",
    "chain": 1
  }'
​
user
string
required
Wallet address to query.
​
chain
integer
EVM chain ID. Omit to return balances across all indexed chains.
Response: Array of portfolio entries, each containing a token object and balance. 
[
  {
    "token": {
      "chain": 1,
      "token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "name": "USD Coin",
      "symbol": "USDC",
      "decimals": 6,
      "transfers": 234567890,
      "total_supply": "26000000000000000"
    },
    "balance": "1500000000"
  }
]

​
Balance

Returns the current balance of a specific token for a user on a given chain. 
curl -X POST https://indexing.turtle.xyz/token/erc20_balance_of \
  -H "Content-Type: application/json" \
  -d '{
    "chain": 1,
    "token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "user": "0x1234...abcd"
  }'
​
chain
integer
required
EVM chain ID.
​
token
string
required
ERC20 token contract address.
​
user
string
required
Wallet address to query.

​
Top Holders

Returns the largest holders of a token, ordered by balance descending. 
curl -X POST https://indexing.turtle.xyz/token/erc20_top_holders \
  -H "Content-Type: application/json" \
  -d '{
    "chain": 1,
    "token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "limit": 25
  }'
​
chain
integer
required
EVM chain ID.
​
token
string
required
ERC20 token contract address.
​
limit
integer
Maximum number of holders to return. Default: 50, max: 100.
Response: 
{
  "token": { "chain": 1, "token": "0xA0b8...", "name": "USD Coin", "symbol": "USDC", "decimals": 6 },
  "holders": [
    { "address": "0xabcd...", "balance": "500000000000" },
    { "address": "0xef01...", "balance": "250000000000" }
  ]
}

​
Token Info

Returns metadata for a specific ERC20 token. 
curl -X POST https://indexing.turtle.xyz/token/erc20_info \
  -H "Content-Type: application/json" \
  -d '{
    "chain": 1,
    "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
  }'
​
chain
integer
required
EVM chain ID.
​
address
string
required
ERC20 token contract address.

​
Token List

Returns all indexed ERC20 tokens, optionally filtered by chain. 
curl -X POST https://indexing.turtle.xyz/token/erc20_tokenlist \
  -H "Content-Type: application/json" \
  -d '{ "chain": 1 }'
​
chain
integer
EVM chain ID. Omit to return tokens across all indexed chains.

​
Indexing Stats

Returns the latest block number processed for ERC20 transfers on each supported chain. Use this to check indexing coverage and freshness. 
curl https://indexing.turtle.xyz/token/erc20_stats
Response: 
[
  { "chain": 1, "latest_block": 22412345 },
  { "chain": 137, "latest_block": 69876543 },
  { "chain": 8453, "latest_block": 31234567 }
]
This is the only GET endpoint — all others are POST.

​
Snapshot Endpoints

Historical balance data for time-series analysis, TVL computation, and reward calculations.

​
User Balance History

Returns point-in-time balance snapshots for a specific user/token/chain combination. 
curl -X POST https://indexing.turtle.xyz/token/snapshot/balances \
  -H "Content-Type: application/json" \
  -d '{
    "chain": 1,
    "token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "user": "0x1234...abcd",
    "since": "2026-01-01T00:00:00",
    "until": "2026-05-06T00:00:00"
  }'
​
chain
integer
required
EVM chain ID.
​
token
string
required
ERC20 token contract address.
​
user
string
required
Wallet address.
​
since
string
Start of time range (ISO 8601, e.g. 2026-01-01T00:00:00).
​
until
string
End of time range (ISO 8601).
Response: Array of snapshot entries: 
[
  {
    "balance": "1500000000",
    "max": "2000000000",
    "change": "500000000",
    "positive": true,
    "timestamp": "2026-03-15T14:30:00"
  }
]
FieldDescription
balanceToken balance at this snapshot point
maxMaximum balance observed in the period
changeAbsolute change from the previous snapshot
positiveWhether the change was an increase (true) or decrease (false)
timestampWhen this snapshot was recorded

​
All Users Balance History

Paginated balance snapshots for all holders of a token. Useful for computing aggregate TVL or building leaderboards. 
curl -X POST https://indexing.turtle.xyz/token/snapshot/balances/all \
  -H "Content-Type: application/json" \
  -d '{
    "chain": 1,
    "token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "until": "2026-05-06T00:00:00",
    "page": 1,
    "page_size": 100
  }'
​
chain
integer
required
EVM chain ID.
​
token
string
required
ERC20 token contract address.
​
until
string
required
End of time range (ISO 8601).
​
page
integer
required
Page number (1-indexed).
​
page_size
integer
required
Users per page.
​
since
string
Start of time range (ISO 8601).
Response: 
{
  "page": 1,
  "page_size": 100,
  "total_users": 4523,
  "data": [
    {
      "user": "0xabcd...",
      "snapshots": [
        { "balance": "1500000000", "max": "2000000000", "change": "500000000", "positive": true, "timestamp": "2026-03-15T14:30:00" }
      ]
    }
  ]
}

​
Volume

Returns total transfer volume for a token, optionally scoped to a specific user and time range. 
curl -X POST https://indexing.turtle.xyz/token/snapshot/volume \
  -H "Content-Type: application/json" \
  -d '{
    "chain": 1,
    "token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "user": "0x1234...abcd",
    "since": "2026-01-01T00:00:00"
  }'
​
chain
integer
required
EVM chain ID.
​
token
string
required
ERC20 token contract address.
​
user
string
Wallet address. Omit for aggregate volume across all users.
​
since
string
Start of time range (ISO 8601).

​
Transform

Applies a transformation function to balance snapshots at a given timestamp. Supports decimal scaling and vesting calculations. 
curl -X POST https://indexing.turtle.xyz/token/snapshot/transform \
  -H "Content-Type: application/json" \
  -d '{
    "chain": 1,
    "token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "timestamp": "2026-05-06T00:00:00",
    "transform": {
      "metamask": {
        "decimals": 6,
        "scalar": "1.0",
        "price": "1.0"
      }
    }
  }'
Two transform types are available:
TransformParametersUse case
metamaskdecimals, scalar, price (optional)Decimal-adjusted balances with optional USD conversion
vestingdecimals, duration, mode (linear or cliff)Vesting schedule computation
Response: Object keyed by user address: 
{
  "0x1234...abcd": {
    "balance": "1500.00",
    "max": "2000.00",
    "result": "1500.00",
    "last_snapshot": "2026-05-05T18:00:00"
  }
}

​
Transform Difference

Compares transformed snapshots between two timestamps. Returns the delta for each user. 
curl -X POST https://indexing.turtle.xyz/token/snapshot/transform/difference \
  -H "Content-Type: application/json" \
  -d '{
    "chain": 1,
    "token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "from": "2026-04-01T00:00:00",
    "to": "2026-05-01T00:00:00",
    "transform": { "metamask": { "decimals": 6, "scalar": "1.0" } }
  }'
​
from
string
required
Start timestamp (ISO 8601).
​
to
string
required
End timestamp (ISO 8601).
​
include_details
boolean
Include full from and to snapshot data in the response.
​
include_zero
boolean
Include users with zero difference in the response.

Lumon Overview

What Lumon is and how it fits into the Turtle data infrastructure.

Data Flow & Settlement

The balance timeseries model and attribution settlement pipeline.

How Attribution Works

The four-step deposit attribution flow.

Deposit Endpoint

Generate deposit transactions that Lumon attributes automatically.