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

# Corridor API Reference: Endpoints and Authentication

> Complete reference for the Meterlane Corridor API — base URL, Bearer auth, supported currencies, error codes, and a full endpoint index.

The Corridor API lets you create USDC-to-local-currency payout corridors, fetch real-time FX quotes, and initiate bank-rail payments for recipients in Brazil, Mexico, Nigeria, Kenya, and South Africa. Every request (except the health check) must be authenticated with your org API key, and all responses follow a consistent JSON structure.

## Base URL

| Environment | URL                              |
| ----------- | -------------------------------- |
| Production  | `https://corridor.meterlane.app` |

## Authentication

Include your API key as a Bearer token in the `Authorization` header of every request.

```bash theme={null}
Authorization: Bearer bp_live_…
```

You can find and rotate your API keys in the Meterlane dashboard under **Settings → API Keys**.

## Supported Currencies

| Code  | Country      |
| ----- | ------------ |
| `BRL` | Brazil       |
| `MXN` | Mexico       |
| `NGN` | Nigeria      |
| `KES` | Kenya        |
| `ZAR` | South Africa |

## Error Format

All errors return a JSON object with three fields: `code`, `message`, and `requestId`. Use `requestId` when contacting support to help diagnose issues faster.

```json theme={null}
{
  "code": "CORRIDOR_NOT_ACTIVE",
  "message": "Corridor must be ACTIVE to initiate payment",
  "requestId": "req_01j9z8k2m4p6q7r3s5t0"
}
```

| Code                      | HTTP Status | Description                                                               |
| ------------------------- | ----------- | ------------------------------------------------------------------------- |
| `BAD_REQUEST`             | 400         | Malformed request body or missing required field                          |
| `CORRIDOR_NOT_ACTIVE`     | 409         | The corridor's status is not `ACTIVE`                                     |
| `INVALID_CURRENCY`        | 400         | `destCurrency` is not in the supported set                                |
| `INVALID_AMOUNT`          | 400         | Amount is missing, non-numeric, or not positive                           |
| `INVALID_BENEFICIARY`     | 400         | Beneficiary field failed validation (e.g. wrong digit count for country)  |
| `MISSING_IDEMPOTENCY_KEY` | 400         | `Idempotency-Key` header was not provided on a pay request                |
| `NOT_FOUND`               | 404         | Corridor ID does not exist or does not belong to your org                 |
| `UPSTREAM_ERROR`          | 502         | Circle API returned an error while fetching a quote or initiating payment |

## Endpoints

The table below summarises every available route. Click the page links in the right column for full request/response details.

| Method | Path                   | Auth Required    | Purpose                       |
| ------ | ---------------------- | ---------------- | ----------------------------- |
| `GET`  | `/healthz`             | No               | Service health check          |
| `POST` | `/corridors`           | Yes              | Create a new corridor         |
| `GET`  | `/corridors/:id`       | Yes              | Retrieve a corridor by ID     |
| `GET`  | `/corridors/:id/quote` | Yes              | Get a live FX quote           |
| `POST` | `/corridors/:id/pay`   | Yes              | Initiate a payout             |
| `POST` | `/webhooks/circle`     | Circle-Signature | Receive Circle payment events |

<Note>
  `POST /corridors/:id/pay` requires an additional `Idempotency-Key` header to safely retry requests without creating duplicate payments. Omitting it returns a `400 MISSING_IDEMPOTENCY_KEY` error.
</Note>

<CardGroup cols={2}>
  <Card title="Corridors" icon="arrow-right-arrow-left" href="/api-reference/corridor-corridors">
    Create corridors, fetch FX quotes, and initiate payouts.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/corridor-webhooks">
    Receive Circle payment status events via HMAC-verified webhooks.
  </Card>
</CardGroup>