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

# Faraday API Reference

> Complete API documentation for stablecoin transfers, compliance, and transaction monitoring

## Overview

The Faraday API provides secure, compliant infrastructure for stablecoin transactions, identity verification, and transaction monitoring across multiple blockchains.

<CardGroup cols={2}>
  <Card title="Swap Routing" icon="route">
    Discover optimal swap paths for stablecoin transfers, including cross-chain
    routes with best execution
  </Card>

  {" "}

  <Card title="Person Records" icon="user-check">
    Create and manage IVMS101-compliant person data for FATF Travel Rule
    compliance
  </Card>

  {" "}

  <Card title="Transaction Management" icon="arrow-right-arrow-left">
    Submit and track stablecoin transactions with real-time status updates
  </Card>

  <Card title="Reporting" icon="chart-bar">
    Access historical transaction reports with associated compliance records
  </Card>
</CardGroup>

***

## Authentication

All Faraday API requests require authentication using a Bearer token (API key).

### Getting Your API Key

**Step-by-Step:**

1. **Sign In**: Log in to the Range platform at [https://app.range.org/](https://app.range.org/)

2. **Navigate to APIs**: Find the "APIs" section in the left navigation menu

3. **Copy Your Key**: Your API key will be displayed. Copy it for use in your requests

<Info>
  A free monthly credit allowance is available for all accounts. Paid plans
  offer additional credits for higher volume usage.
</Info>

### Using Your API Key

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

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET 'https://api.faraday.range.org/v1/persons' \
    --header 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```typescript TypeScript SDK theme={null}
  import { FaradayClient } from "@rangesecurity/faraday-sdk";

  const faraday = new FaradayClient({
    apiKey: process.env.RANGE_API_KEY,
  });
  ```

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

  headers = {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
  }

  response = requests.get(
      'https://api.faraday.range.org/v1/persons',
      headers=headers
  )
  ```
</CodeGroup>

***

## Base URL

**Base URL:** `https://api.faraday.range.org`

Use this environment for live transactions with real funds.

***

## Core Endpoints

### Quote & Routing

Get the best execution path for stablecoin transfers:

| Endpoint                 | Method | Description                               |
| ------------------------ | ------ | ----------------------------------------- |
| `/v1/transactions/quote` | GET    | Request a quote for a stablecoin transfer |
| `/v1/chains`             | GET    | List all supported blockchains            |
| `/v1/aggregators`        | GET    | View integrated DEX aggregators           |

### Person Records (IVMS101)

Manage compliance records for Travel Rule requirements:

| Endpoint           | Method | Description                       |
| ------------------ | ------ | --------------------------------- |
| `/v1/persons`      | POST   | Create a new person record        |
| `/v1/persons`      | GET    | List all person records           |
| `/v1/persons/{id}` | GET    | Retrieve a specific person record |
| `/v1/persons/{id}` | PUT    | Update an existing person record  |
| `/v1/persons/{id}` | DELETE | Delete a person record            |

### Transaction Management

Submit and monitor stablecoin transactions:

| Endpoint                | Method | Description                        |
| ----------------------- | ------ | ---------------------------------- |
| `/v1/transactions`      | POST   | Submit a new transaction           |
| `/v1/transactions`      | GET    | List transactions                  |
| `/v1/transactions/{id}` | GET    | Get transaction details and status |

### Reporting

Access historical data and compliance reports:

| Endpoint                   | Method | Description                          |
| -------------------------- | ------ | ------------------------------------ |
| `/v1/reports/transactions` | GET    | Generate transaction history reports |

***

## Rate Limits

API rate limits vary by plan:

| Plan           | Rate Limit       | Credits/Month  |
| -------------- | ---------------- | -------------- |
| **Free**       | 10 requests/min  | 100 credits    |
| **Pro**        | 100 requests/min | 10,000 credits |
| **Enterprise** | Custom           | Custom         |

<Warning>
  Rate limit headers are included in every response: - `X-RateLimit-Limit`,
  Maximum requests per window - `X-RateLimit-Remaining`, Requests remaining -
  `X-RateLimit-Reset`, Time when limit resets (Unix timestamp)
</Warning>

***

## Error Handling

Faraday uses conventional HTTP response codes:

| Code  | Status                | Description                        |
| ----- | --------------------- | ---------------------------------- |
| `200` | OK                    | Request succeeded                  |
| `400` | Bad Request           | Invalid request parameters         |
| `401` | Unauthorized          | Missing or invalid API key         |
| `403` | Forbidden             | API key lacks required permissions |
| `404` | Not Found             | Resource does not exist            |
| `429` | Too Many Requests     | Rate limit exceeded                |
| `500` | Internal Server Error | Server error (contact support)     |

### Error Response Format

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "The 'amount' field is required",
    "details": {
      "field": "amount",
      "issue": "missing_required_field"
    }
  }
}
```

***

## Quick Start Example

Here's a complete example of getting a quote and submitting a transaction:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { FaradayClient } from '@rangesecurity/faraday-sdk';

  const faraday = new FaradayClient({
  apiKey: process.env.RANGE_API_KEY
  });

  // 1. Get a quote
  const quote = await faraday.getQuote({
  sourceChain: 'solana',
  sourceToken: 'USDT',
  destChain: 'ethereum',
  destToken: 'USDC',
  amount: '1000',
  slippageBps: 50
  });

  console.log('Quote:', quote);

  // 2. Execute the transaction
  const tx = await faraday.executeQuote(quote.id);

  console.log('Transaction submitted:', tx.id);

  // 3. Monitor status
  const status = await faraday.getTransaction(tx.id);
  console.log('Status:', status.state);

  ```

  ```bash cURL theme={null}
  # 1. Get a quote
  curl -G 'https://api.faraday.range.org/v1/transactions/quote' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    --data-urlencode 'from_chain=solana' \
    --data-urlencode 'from_asset=USDT' \
    --data-urlencode 'to_chain=ethereum' \
    --data-urlencode 'to_asset=USDC' \
    --data-urlencode 'amount=1000' \
    --data-urlencode 'slippage_bps=50'

  # 2. Submit transaction (using quote ID from step 1)
  curl -X POST 'https://api.faraday.range.org/v1/transactions' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{"quote_id": "quote_abc123", "signed_tx": "0x..."}'

  # 3. Check status
  curl 'https://api.faraday.range.org/v1/transactions/tx_xyz789' \
    -H 'Authorization: Bearer YOUR_API_KEY'
  ```
</CodeGroup>

***

## OpenAPI Specification

For complete API details, use our OpenAPI specification to generate clients in any language:

**OpenAPI JSON:** [https://api.faraday.range.org/api-docs/openapi.json](https://api.faraday.range.org/api-docs/openapi.json)

<CardGroup cols={2}>
  <Card title="View Full API Docs" icon="book" href="/faraday-api/api-introduction">
    Interactive API reference with all endpoints
  </Card>

  {" "}

  <Card title="Integration Guide" icon="code" href="/faraday-api/integration/index">
    Step-by-step guide to integrating Faraday
  </Card>

  {" "}

  <Card title="SDK Documentation" icon="github" href="https://github.com/rangesecurity/faraday-sdk">
    TypeScript SDK repository and documentation
  </Card>

  <Card title="Code Examples" icon="book-open" href="https://github.com/rangesecurity/faraday-examples">
    Ready-to-run example code on GitHub
  </Card>
</CardGroup>

***

## Need Help?

<CardGroup cols={2}>
  <Card title="FAQ" icon="circle-question" href="/faraday-api/architecture/faq">
    Common questions about Faraday API
  </Card>

  <Card title="Get Support" icon="life-ring" href="https://www.range.org/get-in-touch">
    Contact our team for assistance
  </Card>
</CardGroup>