> ## 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 Platform API call in minutes. Manage counterparties, accounts, and workspace data through simple REST endpoints.

## Your First API Call

Let's list your counterparties in three simple steps:

<Steps>
  <Step title="Get Your API Key">
    Sign in at [app.range.org](https://app.range.org/keys) and generate an API key from the dashboard. Keep it secure, treat it like a password.
  </Step>

  <Step title="Make Your First Request">
    List all counterparties in your workspace:

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X GET "https://api.range.org/v2/counterparties" \
        -H "X-API-KEY: your_api_key_here"
      ```

      ```javascript JavaScript theme={null}
      const response = await fetch("https://api.range.org/v2/counterparties", {
        headers: { "X-API-KEY": "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/v2/counterparties",
          headers={"X-API-KEY": "your_api_key_here"},
      )
      print(response.json())
      ```

      ```typescript TypeScript theme={null}
      const response = await fetch("https://api.range.org/v2/counterparties", {
        headers: { "X-API-KEY": "your_api_key_here" },
      });
      const data = await response.json();
      console.log(data);
      ```
    </CodeGroup>
  </Step>

  <Step title="Explore the Response">
    You'll receive a paginated list of counterparties with their addresses, bank accounts, and metadata.
  </Step>
</Steps>

<Accordion title="View Example Response">
  ```json theme={null}
  {
    "items": [
      {
        "id": "cp_abc123",
        "name": "Vercel",
        "type": "vendor",
        "website": "https://vercel.com",
        "notes": "Infrastructure hosting provider",
        "addresses": [
          {
            "id": "08846e81-b3a8-7fd9-cc39-d4023a75dcff",
            "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28",
            "network": "ethereum",
            "name": "Vercel Payment Wallet",
            "label": "payment wallet"
          }
        ],
        "bank_accounts": []
      }
    ],
    "meta": {
      "next_cursor": "eyJpZCI6IjkxeFFlV3Z...",
      "previous_cursor": null,
      "total_count": 42,
      "page_number": 1
    }
  }
  ```
</Accordion>

***

## API Fundamentals

### Base URL

All API requests are made to:

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

### Authentication

Include your API key in the `X-API-KEY` header with every request:

```bash theme={null}
X-API-KEY: your_api_key_here
```

<Warning>
  Never expose your API key in client-side code or public repositories. Use
  environment variables to store it securely.
</Warning>

<Card title="Get Your API Key" icon="key" href="https://app.range.org/keys">
  Generate and manage API keys from the Range dashboard
</Card>

### Request Format

All endpoints use **GET**, **POST**, **PATCH**, **PUT**, or **DELETE** methods with:

* **Query parameters** for filtering and pagination (GET endpoints)
* **JSON request bodies** for creates and updates (`Content-Type: application/json`)
* **Multipart form data** for document uploads
* **JSON responses** for all successful requests

### Response Format

Successful responses return JSON directly. List endpoints include a `meta` object:

```json theme={null}
{
  "items": [
    /* array of results */
  ],
  "meta": {
    "next_cursor": "eyJpZCI6...",
    "previous_cursor": null,
    "first_page_cursor": "eyJpZCI6...",
    "last_page_cursor": "eyJpZCI6...",
    "total_count": 100,
    "page_number": 1
  }
}
```

***

## Pagination

The Platform API uses **cursor-based pagination** for all list endpoints.

| Parameter | Type   | Description                                     |
| --------- | ------ | ----------------------------------------------- |
| `limit`   | number | Results per page (default 50, max 200)          |
| `cursor`  | string | Opaque cursor from a previous response's `meta` |

**Example, fetch the next page:**

```bash theme={null}
curl "https://api.range.org/v2/counterparties?limit=50&cursor=eyJpZCI6IjkxeFFlV3Z..." \
  -H "X-API-KEY: your_api_key_here"
```

Use `meta.next_cursor` to advance forward. When `next_cursor` is `null`, you've reached the last page.

<Info>
  Cursors are opaque strings, do not parse or construct them manually. Always
  use the cursor value returned in the response.
</Info>

***

## Common Use Cases

<CardGroup cols={2}>
  <Card title="Create a Counterparty" icon="user-plus">
    Add vendors, customers, and partners with crypto addresses and bank details
    `POST /v2/counterparties`
  </Card>

  {" "}

  <Card title="Search Accounts" icon="magnifying-glass">
    Find and filter your workspace accounts by type, network, or group `GET
          /v2/accounts`
  </Card>

  {" "}

  <Card title="Connect an Exchange" icon="plug">
    Link a Kraken, Coinbase, or Hyperliquid account to sync balances `POST
          /v2/account-connections`
  </Card>

  <Card title="Query Transactions" icon="list">
    Fetch canonical transfer and trade history across all connected accounts `    GET /v2/account-connections/transactions`
  </Card>
</CardGroup>

***

## Error Handling

The API uses standard HTTP status codes:

| Status Code | Meaning           | Common Causes                           |
| ----------- | ----------------- | --------------------------------------- |
| **200**     | Success           | Request completed successfully          |
| **201**     | Created           | Resource created 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": "name should not be empty",
  "error": "Bad Request"
}
```

<Warning>
  Implement retry logic with exponential backoff for 429 and 5xx errors.
</Warning>

***

## Next Steps

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

  {" "}

  <Card title="Platform Overview" icon="building" href="/platform-api/platform-introduction">
    Learn what you can build with the Platform API
  </Card>

  {" "}

  <Card title="Data API" icon="database" href="/data-api/data-introduction">
    Query blockchain addresses, networks, and stablecoin analytics
  </Card>

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