Data API Quickstart - Range Docs

This guide walks you through your first calls to the Data API. By the end, you’ll understand the request format, response structure, and key fields for three flagship endpoints — one for addresses, one for transfers, and one for tokens.

You’ll need an API key. All requests require a Bearer token. Sign up at app.range.org to generate one for free.

Authentication

Every Data API request uses the same authentication pattern. Pass your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Base URL: https://api.range.org

Keep your API key server-side. Never expose it in client-side code or public repositories.

1. Look Up an Address

The Get Address Information endpoint is the most common starting point. It returns labels, entity attribution, and metadata for any address across 18+ supported networks. Try it with Circle’s CCTP program on Solana:

curl -G https://api.range.org/v1/address \
  --data-urlencode "address=CCTPiPYPc6AsJuwueEnWgSgucamXDZwBd53dQ11YiKX3" \
  --data-urlencode "network=solana" \
  -H "Authorization: Bearer YOUR_API_KEY"

const params = new URLSearchParams({
  address: "CCTPiPYPc6AsJuwueEnWgSgucamXDZwBd53dQ11YiKX3",
  network: "solana",
});

const response = await fetch(`https://api.range.org/v1/address?${params}`, {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});
const data = await response.json();

import requests

response = requests.get(
    "https://api.range.org/v1/address",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={
        "address": "CCTPiPYPc6AsJuwueEnWgSgucamXDZwBd53dQ11YiKX3",
        "network": "solana",
    },
)
data = response.json()

Example Response

{
  "address": "CCTPiPYPc6AsJuwueEnWgSgucamXDZwBd53dQ11YiKX3",
  "network": "solana",
  "is_validator": false,
  "malicious": false,
  "name": "Circle CCTP",
  "tags_source": "range",
  "tags": {
    "entity": "Circle",
    "category": "Bridge"
  },
  "type": {
    "is_contract": true
  }
}

Key Response Fields

Field	What It Tells You
`name`	Human-readable label for the address, when known.
`malicious`	`true` if Range has flagged this address as malicious.
`is_validator`	`true` if the address is a known network validator.
`tags`	Structured attribution — entity name, category, and other metadata.
`tags_source`	Where the attribution came from.

2. Get Token Transfers

The Get token transfers endpoint returns cross-chain and same-chain transfers (IBC, CCTP, bridges, and more) for an address, with cursor-based pagination. Try it against the same address:

curl -G https://api.range.org/v2/transfers \
  --data-urlencode "address=CCTPiPYPc6AsJuwueEnWgSgucamXDZwBd53dQ11YiKX3" \
  --data-urlencode "network=solana" \
  --data-urlencode "size=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

const params = new URLSearchParams({
  address: "CCTPiPYPc6AsJuwueEnWgSgucamXDZwBd53dQ11YiKX3",
  network: "solana",
  size: "5",
});

const response = await fetch(`https://api.range.org/v2/transfers?${params}`, {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});
const data = await response.json();

import requests

response = requests.get(
    "https://api.range.org/v2/transfers",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={
        "address": "CCTPiPYPc6AsJuwueEnWgSgucamXDZwBd53dQ11YiKX3",
        "network": "solana",
        "size": 5,
    },
)
data = response.json()

Example Response (Abbreviated)

{
  "items": [
    {
      "id": "9359/AX/2352",
      "time": "2024-05-08T13:05:57.779Z",
      "status": "SUCCEEDED",
      "type": "cctp",
      "sender": {
        "address": "AuZrspySopxfZUiXY6YxDyfS211KvXLe197kj3M2cLpq",
        "network": "solana"
      },
      "receiver": {
        "address": "0x1da5821544e25c636c1417ba96ade4cf6d2f9b5a",
        "network": "ethereum"
      }
    }
  ],
  "meta": {
    "next_cursor": "eyJpZCI6IjkzNTkvQVgvMjM1MiJ9",
    "has_more": true
  }
}

Key Response Fields

Field	What It Tells You
`status`	Current state of the transfer: `SUCCEEDED`, `PENDING`, `ERROR_ON_DESTINATION`, or `TIMEOUT`.
`type`	Transfer mechanism — e.g. `ibc`, `cctp`, or a specific bridge name.
`sender` / `receiver`	Address and network on each side of the transfer. Networks can differ for cross-chain transfers.
`meta.next_cursor`	Pass this as the `cursor` parameter to fetch the next page.

GET /v2/transfers supports dozens of filters — token_symbols, bridges, min_usd/max_usd, start_time/end_time, and more. See the endpoint reference for the full list.

3. Get a Token’s Total Supply

The Get total supply for a token endpoint returns current supply and decimals for any token. Try it with USDC on Solana:

curl -G https://api.range.org/v2/tokens/total-supply \
  --data-urlencode "network=solana" \
  --data-urlencode "token=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" \
  -H "Authorization: Bearer YOUR_API_KEY"

const params = new URLSearchParams({
  network: "solana",
  token: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
});

const response = await fetch(
  `https://api.range.org/v2/tokens/total-supply?${params}`,
  { headers: { Authorization: "Bearer YOUR_API_KEY" } }
);
const data = await response.json();

import requests

response = requests.get(
    "https://api.range.org/v2/tokens/total-supply",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={
        "network": "solana",
        "token": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    },
)
data = response.json()

Example Response

{
  "token": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "network": "solana",
  "symbol": "USDC",
  "name": "USD Coin",
  "total_supply": 24817364521.32,
  "total_supply_raw": "24817364521320000",
  "decimals": 6
}

Key Response Fields

Field	What It Tells You
`total_supply`	Total supply with decimals already applied — use this for display.
`total_supply_raw`	Raw on-chain integer string — use this for precise math.
`decimals`	Number of decimal places the token uses.

Common Errors

HTTP Code	Meaning	What to Do
400	Invalid parameters (missing address, bad format)	Check your query parameters.
401	Invalid or missing API key	Verify your `Authorization: Bearer` header. See Authentication.
404	Address, token, or network not found	Check the network identifier against Supported Chains.
429	Rate limit exceeded	Implement exponential backoff. See Rate Limits.
5xx	Server error	Retry after a delay. Contact support if persistent.

What’s Next

Authentication

API keys, rate limits, and security best practices.

Data API Overview

See what you can build across addresses, networks, protocols, and stablecoins.

Supported Chains

The full list of networks the Data API covers.

Get Support

Questions? Our team is here to help.

​Authentication

​1. Look Up an Address

​Key Response Fields

​2. Get Token Transfers

​Key Response Fields

​3. Get a Token’s Total Supply

​Key Response Fields

​Common Errors

​What’s Next

Authentication

Data API Overview

Supported Chains

Get Support

Authentication

1. Look Up an Address

Key Response Fields

2. Get Token Transfers

Key Response Fields

3. Get a Token’s Total Supply

Key Response Fields

Common Errors

What’s Next