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

# Getting Started

> Make your first API call in under 5 minutes. Query blockchain data across 18+ networks with simple REST endpoints.

## Your First API Call

Let's fetch information about a Solana address in three simple steps:

<Steps>
  <Step title="Get Your API Key">
    Sign up at [app.range.org](https://app.range.org) and generate your free API key from the dashboard.
  </Step>

  <Step title="Make Your First Request">
    Query the Circle CCTP address on Solana:

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X GET "https://api.range.org/v1/address?address=CCTPiPYPc6AsJuwueEnWgSgucamXDZwBd53dQ11YiKX3&network=solana" \
        -H "Authorization: Bearer your_api_key_here"
      ```

      ```javascript JavaScript theme={null}
      const response = await fetch(
        'https://api.range.org/v1/address?address=CCTPiPYPc6AsJuwueEnWgSgucamXDZwBd53dQ11YiKX3&network=solana',
        { headers: { 'Authorization': 'Bearer your_api_key_here' } }
      );
      const data = await response.json();
      console.log(data);
      ```

      ```python Python theme={null}
      import requests

      response = requests.get(
          'https://api.range.org/v1/address',
          params={
              'address': 'CCTPiPYPc6AsJuwueEnWgSgucamXDZwBd53dQ11YiKX3',
              'network': 'solana'
          },
          headers={'Authorization': 'Bearer your_api_key_here'}
      )
      print(response.json())
      ```

      ```typescript TypeScript theme={null}
      const response = await fetch(
        'https://api.range.org/v1/address?address=CCTPiPYPc6AsJuwueEnWgSgucamXDZwBd53dQ11YiKX3&network=solana',
        { headers: { 'Authorization': 'Bearer your_api_key_here' } }
      );
      const data = await response.json();
      console.log(data);
      ```
    </CodeGroup>
  </Step>

  <Step title="Explore the Response">
    You'll receive comprehensive address information including labels, network, and entity details.
  </Step>
</Steps>

<Accordion title="View Example Response">
  ```json theme={null}
  {
    "address": "CCTPiPYPc6AsJuwueEnWgSgucamXDZwBd53dQ11YiKX3",
    "network": "solana",
    "labels": ["Circle", "CCTP", "Bridge"],
    "entity": {
      "name": "Circle CCTP",
      "category": "Bridge",
      "website": "https://circle.com"
    },
    "first_seen": "2023-06-15T10:30:00Z",
    "last_seen": "2025-11-25T14:22:00Z"
  }
  ```
</Accordion>

***

## API Fundamentals

### Base URL

All API requests are made to:

```
https://api.range.org
```

### Authentication

Include your API key in the `Authorization` header with every request:

```bash theme={null}
Authorization: Bearer your_api_key_here
```

<Card title="Authentication Guide" icon="key" href="/data-api/authentication">
  Learn more about API keys, rate limits, and security best practices
</Card>

### Request Format

All endpoints use **GET** or **POST** methods with:

* **Query parameters** for filtering and pagination
* **JSON request bodies** for complex queries (POST endpoints)
* **JSON responses** for all successful requests

### Response Format

All responses return JSON with consistent structure:

```json theme={null}
{
  "data": {
    /* Your requested data */
  },
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 100
  }
}
```

***

## Common Use Cases

<CardGroup cols={2}>
  <Card title="Query Address Information" icon="location-dot">
    Get labels, entity info, and activity for any blockchain address `GET
            /v1/address`
  </Card>

  {" "}

  <Card title="Track Transactions" icon="arrow-right-arrow-left">
    Fetch transaction history with filters for date, amount, and type `GET
          /v1/address/transactions`
  </Card>

  {" "}

  <Card title="Monitor Network Metrics" icon="chart-line">
    Access network-wide volume, active accounts, and whale movements `GET
          /v1/network/volume`
  </Card>

  <Card title="Analyze Protocols" icon="cubes">
    Track DeFi protocol stats, cross-chain transfers, and bridge activity `    POST /v1/protocols/stats`
  </Card>
</CardGroup>

***

## Pagination

Many endpoints return paginated results. Control pagination with query parameters:

| Parameter | Type    | Description                | Default |
| --------- | ------- | -------------------------- | ------- |
| `page`    | integer | Page number (1-indexed)    | 1       |
| `limit`   | integer | Results per page (max 100) | 10      |

**Example:**

```bash theme={null}
curl "https://api.range.org/v1/address/transactions?address=YOUR_ADDRESS&network=solana&page=2&limit=50" \
  -H "Authorization: Bearer your_api_key_here"
```

**Response includes pagination metadata:**

```json theme={null}
{
  "data": [...],
  "meta": {
    "page": 2,
    "limit": 50,
    "total": 1234,
    "pages": 25
  }
}
```

<Info>
  Some endpoints support **scroll API** for efficient iteration through large
  datasets. Check individual endpoint docs for details.
</Info>

***

## Supported Networks

Query data from 18+ blockchains with consistent API structure:

<AccordionGroup>
  <Accordion title="Solana Ecosystem" icon="s">
    **Mainnet:** `solana`

    Full support for transactions, payments, token transfers, and Solana-specific features.
  </Accordion>

  {" "}

  <Accordion title="Cosmos Ecosystem" icon="atom">
    **Networks:** `cosmoshub`, `osmosis`, `celestia`, `dydx`, `neutron`,
    `injective`, `noble`, `stride`, `stargaze`, `juno`, `kujira`, `axelar` IBC
    transfers, cross-chain messaging, and cosmos-specific transaction types.
  </Accordion>

  {" "}

  <Accordion title="EVM Chains" icon="ethereum">
    **Networks:** `ethereum`, `arbitrum`, `polygon`, `base`, `optimism` Smart
    contract interactions, ERC-20 transfers, and EVM-specific data.
  </Accordion>

  <Accordion title="Other Networks" icon="link">
    **Stellar:** `stellar`

    Full ledger and payment path data for Stellar network.
  </Accordion>
</AccordionGroup>

Use the `network` parameter to specify which blockchain to query.

***

## Error Handling

The API uses standard HTTP status codes:

| Status Code | Meaning           | Common Causes                           |
| ----------- | ----------------- | --------------------------------------- |
| **200**     | Success           | Request completed successfully          |
| **400**     | Bad Request       | Invalid parameters or malformed request |
| **401**     | Unauthorized      | Missing or invalid API key              |
| **404**     | Not Found         | Resource doesn't exist                  |
| **429**     | Too Many Requests | Rate limit exceeded                     |
| **500**     | Server Error      | Internal server error (rare)            |

**Error Response Format:**

```json theme={null}
{
  "statusCode": 400,
  "message": "Invalid network parameter",
  "error": "Bad Request"
}
```

<Warning>
  Always check the `statusCode` in your error handling logic and implement retry
  logic with exponential backoff for 429 and 5xx errors.
</Warning>

***

## Rate Limits

Monitor your usage with rate limit headers included in every response:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1732543200
```

| Plan           | Rate Limit | Monthly Quota |
| -------------- | ---------- | ------------- |
| **Free**       | 10 req/min | 100 req/month |
| **Enterprise** | Custom     | Custom        |

<Card title="Upgrade Your Plan" icon="arrow-up" href="https://app.range.org">
  Need higher limits? Upgrade to Pro or Enterprise for production workloads.
</Card>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Cache Responses" icon="database">
    Cache frequently accessed data like address labels and entity information to reduce API calls and improve performance.
  </Accordion>

  {" "}

  <Accordion title="Use Pagination Wisely" icon="list">
    Request only the data you need with appropriate `limit` values. For large
    datasets, use scroll API when available.
  </Accordion>

  {" "}

  <Accordion title="Handle Errors Gracefully" icon="triangle-exclamation">
    Implement retry logic with exponential backoff for transient errors (429,
    5xx). Log all errors for debugging.
  </Accordion>

  {" "}

  <Accordion title="Monitor Rate Limits" icon="gauge">
    Track the `X-RateLimit-Remaining` header and implement throttling before
    hitting limits.
  </Accordion>

  <Accordion title="Use Webhooks" icon="webhook">
    Coming soon! Subscribe to real-time events instead of polling for updates.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Explore Endpoints" icon="book-open">
    Browse all available endpoints with interactive examples below
  </Card>

  {" "}

  <Card title="Authentication" icon="key" href="/data-api/authentication">
    Learn about API keys, security, and rate limits
  </Card>

  {" "}

  <Card title="Faraday SDK" icon="code" href="/faraday-api/integration/index">
    TypeScript SDK for cross-chain stablecoin transfers
  </Card>

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