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

# API Reference

> REST endpoints for backend integration. Interactive playground, 17 languages, sandbox + production.

The Relayer API is a single REST surface. Every endpoint has its own page in the sidebar with an interactive playground that hits the live sandbox or production environment.

## Environments

<Tabs>
  <Tab title="Sandbox">
    ```
    https://testnet.relayer.fi/v1
    ```

    Use the sandbox for development. Same endpoints, same payloads — testnet wallets, no real fiat.
  </Tab>

  <Tab title="Production">
    ```
    https://api.relayer.fi/v1
    ```

    Mainnet wallets, regulated fiat rails, real settlement. Use production once you've validated your integration in the sandbox.
  </Tab>
</Tabs>

The playground in the sidebar lets you switch between environments per request.

## Authentication

The API supports three authentication modes. **Which one you use depends on who is calling.**

<CardGroup cols={3}>
  <Card title="API Key" icon="key">
    Your backend → Relayer.
    `Authorization: ApiKey rk_...`
  </Card>

  <Card title="Agent HMAC" icon="robot">
    Agent SDK → Relayer.
    Four headers, HMAC-SHA256 signature.
  </Card>

  <Card title="Session JWT" icon="user">
    Browser → Relayer dashboard.
    `Authorization: Bearer <jwt>`
  </Card>
</CardGroup>

See [Authentication](/get-started/authentication) for the full matrix, header formats, and security best practices.

## Response envelope

Every response — success or error — uses the same shape so your client can always extract the same fields.

<Tabs>
  <Tab title="Success">
    ```json theme={null}
    {
      "success": true,
      "message": "Wallet created",
      "data": {
        "walletId": "wallet_abc123",
        "name": "My Wallet",
        "createdAt": "2026-05-15T12:00:00.000Z"
      },
      "statusCode": 201,
      "timestamp": "2026-05-15T12:00:00.000Z",
      "path": "/v1/signing/wallets/confirm"
    }
    ```
  </Tab>

  <Tab title="Error">
    ```json theme={null}
    {
      "success": false,
      "message": "Validation failed: amount must be positive",
      "statusCode": 400,
      "timestamp": "2026-05-15T12:00:00.000Z",
      "path": "/v1/payout/accounts/quote"
    }
    ```
  </Tab>

  <Tab title="Paginated">
    ```json theme={null}
    {
      "success": true,
      "data": [ /* items */ ],
      "meta": {
        "page": 1,
        "limit": 50,
        "total": 247,
        "totalPages": 5
      },
      "statusCode": 200,
      "timestamp": "2026-05-15T12:00:00.000Z",
      "path": "/v1/orders"
    }
    ```
  </Tab>
</Tabs>

For the full error catalog (status codes, common business errors, retry guidance), see [Error Reference](/shared/error-reference).

## Idempotency

Mutation endpoints that can be retried safely accept an `Idempotency-Key` header:

```
Idempotency-Key: <your-uuid-v4>
```

We store the result for 24 hours. Retrying the same key returns the original response without re-executing the side effect.

Endpoints that are **idempotent by design** (no key needed) are marked in their summary — e.g. `POST /v1/payout/offramp/withdraw-addresses` returns the existing record on conflict.

## Rate limits

| Tier                                   | Limit                           |
| -------------------------------------- | ------------------------------- |
| Standard endpoints                     | 100 requests/minute per API key |
| Financial endpoints (signing, payouts) | 20 requests/minute per API key  |

When exceeded, the API returns `429 Too Many Requests`. Back off with exponential delay (1s, 2s, 4s, 8s) and retry.

## How endpoints are organized

The sidebar groups endpoints by **resource**, not by Kit. If you want to read a wallet balance, you look under **Wallets** — not under "Balance" or "Platform". If you want to assign a tool to an agent, you look under **Agents → Tools**. Every verb sits on its noun.

<CardGroup cols={3}>
  <Card title="Wallets" icon="wallet">
    Create, list, get, read balance, view activity.
  </Card>

  <Card title="Addresses" icon="address-card">
    Generate addresses derived from a wallet's root key.
  </Card>

  <Card title="Transactions" icon="arrow-right-arrow-left">
    List pending, broadcast signed transactions, retry failures, cancel before broadcast.
  </Card>

  <Card title="Agents" icon="robot">
    Lifecycle, read, control, funding, runtime (HMAC), tools.
  </Card>

  <Card title="Widget Actions" icon="puzzle-piece">
    Metadata generators + protocol/token catalog — what the Widget Kit consumes.
  </Card>

  <Card title="Beneficiaries" icon="users">
    Recipient CRUD, invites, bank-account registration.
  </Card>

  <Card title="Global Payout" icon="money-bill-transfer">
    Quote → setup → execute the sandwich payment flow (off-ramp).
  </Card>

  <Card title="On-ramp" icon="building-columns">
    Fiat deposit accounts (virtual accounts, SPEI, etc.) for on-ramping.
  </Card>
</CardGroup>

For end-user flows that require a passkey ceremony (wallet creation, transaction signing, agent provisioning), see the [Signing Kit](/signing/overview), [Agent Kit](/agent/overview), and [Widget Kit](/widget/overview) — those Kits cover the full UX.

## Try it from the playground

Every endpoint page has an **interactive playground** on the right side:

<Steps>
  <Step title="Choose an environment">
    Switch between Sandbox and Production from the server dropdown above the request panel.
  </Step>

  <Step title="Enter your auth">
    Paste your API key into the `Authorization` field. It prefixes `ApiKey` automatically.
  </Step>

  <Step title="Fill the parameters">
    Path, query, and body parameters are auto-populated from the schema. Edit them inline.
  </Step>

  <Step title="Send">
    The response panel shows the real response, the status code, and copy-able cURL / language snippets for 17 languages (bash, Node.js, Python, Go, Java, Ruby, PowerShell, Swift, C#, .NET, TypeScript, Kotlin, Rust, Dart, C, C++, PHP).
  </Step>
</Steps>

<Tip>
  The playground sends real requests. Use the sandbox while exploring — production calls move real money.
</Tip>

## Use this documentation with AI

This documentation is **MCP-ready**. AI tools like Claude Code, Cursor, ChatGPT, and Windsurf can connect directly to it and query endpoints, params, and examples without leaving your terminal or editor.

<CardGroup cols={2}>
  <Card title="Connect via MCP" icon="plug" href="/get-started/ai-assistants">
    Add Relayer docs to Claude Code, Cursor, or any MCP-compatible tool with one command.
  </Card>

  <Card title="Open this page in Claude / ChatGPT" icon="sparkles">
    Click the **Ask AI** button in the page header to send the current page as context to your preferred LLM.
  </Card>
</CardGroup>

The contextual menu (top of every page) also exposes **Copy as Markdown**, **View as Markdown**, and direct deeplinks to ChatGPT / Claude / Perplexity / Cursor / VS Code with the page content prefilled.

## Get help

* **Email**: [dev@relayer.fi](mailto:dev@relayer.fi)
* **GitHub**: [github.com/relayerfi](https://github.com/relayerfi)
* **Status**: live on the production base URL — `GET /v1/` returns service health