> ## Documentation Index
> Fetch the complete documentation index at: https://docs.range.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Data API Quickstart

> Make your first Data API calls in under 5 minutes and learn how to interpret the responses.

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.

<Info>
  **You'll need an API key.** All requests require a Bearer token. Sign up at [app.range.org](https://app.range.org) to generate one for free.
</Info>

***

## 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`

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

***

## 1. Look Up an Address

The [Get Address Information](/api-reference/address-information/get-address-information) endpoint is the most common starting point. It returns labels, entity attribution, and metadata for any address across [18+ supported networks](/risk-api/product-info/supported-chains). Try it with Circle's CCTP program on Solana:

<CodeGroup>
  ```bash cURL theme={null}
  curl -G https://api.range.org/v1/address \
    --data-urlencode "address=CCTPiPYPc6AsJuwueEnWgSgucamXDZwBd53dQ11YiKX3" \
    --data-urlencode "network=solana" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  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();
  ```

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

<Accordion title="Example Response">
  ```json theme={null}
  {
    "address": "CCTPiPYPc6AsJuwueEnWgSgucamXDZwBd53dQ11YiKX3",
    "network": "solana",
    "is_validator": false,
    "malicious": false,
    "name": "Circle CCTP",
    "tags_source": "range",
    "tags": {
      "entity": "Circle",
      "category": "Bridge"
    },
    "type": {
      "is_contract": true
    }
  }
  ```
</Accordion>

### 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](/api-reference/token-transfers/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:

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```

  ```javascript JavaScript theme={null}
  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();
  ```

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

<Accordion title="Example Response (Abbreviated)">
  ```json theme={null}
  {
    "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
    }
  }
  ```
</Accordion>

### 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.                                      |

<Tip>
  `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.
</Tip>

***

## 3. Get a Token's Total Supply

The [Get total supply for a token](/api-reference/token-information/get-total-supply-for-a-token) endpoint returns current supply and decimals for any token. Try it with USDC on Solana:

<CodeGroup>
  ```bash cURL theme={null}
  curl -G https://api.range.org/v2/tokens/total-supply \
    --data-urlencode "network=solana" \
    --data-urlencode "token=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  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();
  ```

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

<Accordion title="Example Response">
  ```json theme={null}
  {
    "token": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "network": "solana",
    "symbol": "USDC",
    "name": "USD Coin",
    "total_supply": 24817364521.32,
    "total_supply_raw": "24817364521320000",
    "decimals": 6
  }
  ```
</Accordion>

### 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](/data-api/authentication).       |
|   **404** | Address, token, or network not found             | Check the network identifier against [Supported Chains](/risk-api/product-info/supported-chains). |
|   **429** | Rate limit exceeded                              | Implement exponential backoff. See [Rate Limits](/data-api/authentication#rate-limits).           |
|   **5xx** | Server error                                     | Retry after a delay. Contact support if persistent.                                               |

***

## What's Next

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/data-api/authentication">
    API keys, rate limits, and security best practices.
  </Card>

  <Card title="Data API Overview" icon="database" href="/data-api/data-introduction">
    See what you can build across addresses, networks, protocols, and stablecoins.
  </Card>

  <Card title="Supported Chains" icon="link" href="/risk-api/product-info/supported-chains">
    The full list of networks the Data API covers.
  </Card>

  <Card title="Get Support" icon="headset" href="https://www.range.org/get-in-touch">
    Questions? Our team is here to help.
  </Card>
</CardGroup>