Corridor API Reference: Endpoints and Authentication

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.

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.

{
  "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

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.

Corridors

Create corridors, fetch FX quotes, and initiate payouts.

Webhooks

Receive Circle payment status events via HMAC-verified webhooks.

​Base URL

​Authentication

​Supported Currencies

​Error Format

​Endpoints

Corridors

Webhooks

Base URL

Authentication

Supported Currencies

Error Format

Endpoints