> ## 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.
# Meterlane Concepts: x402, Routes, Corridors Explained
> Plain-language definitions for every term you will encounter while building with Meterlane — x402, routes, facilitators, corridors, and more.
This page explains the core ideas behind Meterlane in plain language. You do not need a background in blockchain or payment systems to follow along — every term is defined from the perspective of what it means when you are building with the platform.
**x402** is an open HTTP payment protocol. The name comes from HTTP status code **402 Payment Required** — a status code that has existed in the HTTP specification since 1991 but was never widely used until x402 gave it a standard machine-readable format.
Here is how it works in practice:
* Your agent calls a URL that is protected by a price.
* Instead of an authorization error, the server returns **HTTP 402** with an `X-Payment-Requirements` header. That header is a JSON object describing the amount required, the accepted currency (USDC), the network, and the facilitator address.
* Your agent client reads the requirements, constructs a payment, and retries the same request with an `X-PAYMENT` header containing a signed authorization.
* The server verifies the payment and returns the normal response.
The key insight is that this entire flow is **machine-to-machine** — no human is involved, no browser checkout page is shown, and no API key representing a billing relationship is passed. The agent simply pays for what it uses, one request at a time.
Meterlane implements x402 on Base using USDC as the payment currency. Learn more about the open protocol at [x402.org](https://x402.org).
`X-Payment-Requirements` is the response header your gateway sends alongside an HTTP 402. It is a JSON object that tells the agent client exactly what payment to make. Key fields include:
| Field | What it means |
| ------------------- | ------------------------------------------------------------------------ |
| `scheme` | Always `"exact"` on Meterlane — the agent pays the stated amount exactly |
| `network` | EIP-155 chain ID string, e.g. `"eip155:84532"` for Base Sepolia |
| `maxAmountRequired` | USDC amount in the smallest unit (6 decimals), e.g. `"1000000"` = 1 USDC |
| `asset` | The USDC contract address on the target network |
| `payTo` | The wallet address that will receive the USDC |
| `maxTimeoutSeconds` | How long the signed payment authorization remains valid |
You rarely need to read this header manually — the `@meterlane/x402` SDK handles it automatically. However, understanding it helps you set route prices and debug payment failures.
`X-PAYMENT` is the request header an agent client adds when retrying a request after receiving a 402. It contains a Base64-encoded ERC-3009 signed authorization — essentially a cryptographic promise that the agent's wallet will transfer the required USDC to the route's `payTo` address. The facilitator verifies this authorization and settles the transfer on-chain before the gateway proxies the request upstream.
ERC-3009 is an Ethereum token standard that allows a token holder to sign a `transferWithAuthorization` message off-chain. The signed message authorizes a third party (the facilitator) to move a specific amount of USDC from the agent's wallet to the payment recipient — but only once, only up to a stated amount, and only within a time window.
This is what makes x402 payments safe for agents. Your private key never leaves your environment; you only sign a scoped, time-limited authorization. The facilitator submits that authorization to the USDC contract on-chain to complete the transfer. Replay is prevented because each authorization includes a unique nonce.
You do not need to write ERC-3009 code yourself. `createAgentClient` in the `@meterlane/x402` SDK handles signing automatically.
An **org** is your tenant in Meterlane. When you sign up at [meterlane.app](https://meterlane.app) and complete onboarding, you create an org. Everything in Meterlane belongs to an org:
* **API keys** — credentials you use to call the Gateway and Corridor REST APIs
* **Routes** — URL patterns you define and gate behind a USDC price
* **Wallets** — the addresses that receive USDC from agent payments or hold funds for corridor payouts
* **Billing plan** — the Meterlane subscription tier that determines your request limits and corridor access
Your org has a unique **slug** that appears in your gateway URLs: `https://gateway.meterlane.app/gateway/{your-org-slug}/{route-name}`.
API keys follow the format `bp_live_…` for production. Sandbox keys are clearly labeled in the dashboard.
API keys authenticate your server-side calls to the Meterlane REST APIs (dashboard management, corridor quote/settle). They are **not** used by agent clients making x402 payments — agents authenticate via signed ERC-3009 authorizations, not API keys.
Production API keys use the format `bp_live_…`. Keep them in environment variables and never expose them in client-side code or public repositories.
A **route** is a URL pattern you register in the Meterlane dashboard under your org. Each route has a **price per request** denominated in USDC and points to an **upstream URL** — the actual API endpoint you want to protect.
When an agent calls `https://gateway.meterlane.app/gateway/{org-slug}/{route-name}`, the gateway checks whether a valid x402 payment was made for that route's price. If yes, it proxies the request to your upstream and returns the response. If no, it returns HTTP 402.
Routes are scoped to your org, so only your org's pricing and upstream configuration are applied.
The **facilitator** is the service that verifies and settles x402 payments on-chain. When the gateway receives a request with an `X-PAYMENT` header, it forwards the signed ERC-3009 authorization to the facilitator. The facilitator validates the signature, checks for replay attacks, submits the `transferWithAuthorization` transaction to the USDC contract, and confirms settlement.
In the Meterlane sandbox, the public facilitator at `x402.org` handles verification on Base Sepolia. For production mainnet traffic, Meterlane uses a private mainnet-capable facilitator — you do not configure this yourself; it is managed as part of your plan.
A **corridor** is a USDC-to-local-fiat payout rail. You call the Corridor API to request a quote for a destination currency, then send USDC from your org wallet to initiate settlement. Circle CPN handles the fiat leg and delivers local currency to your beneficiary's bank account.
Meterlane currently supports the following corridors:
| Destination currency | Country/Region |
| -------------------- | -------------- |
| BRL | Brazil |
| MXN | Mexico |
| NGN | Nigeria |
| KES | Kenya |
| ZAR | South Africa |
Corridor transaction fees range from 0.25% to 0.65% depending on your plan. Settlement typically completes in minutes rather than the 3–5 business days typical of correspondent-bank wire transfers.
**USDC** is a fully-reserved US dollar stablecoin issued by Circle. One USDC is always worth one US dollar. Meterlane uses USDC as the payment currency for all Agent Gateway transactions and as the source currency for all Stablecoin Corridor payouts.
On-chain, USDC uses 6 decimal places. An amount of `1000000` in the `X-Payment-Requirements` header equals exactly **1.00 USDC**.
In the sandbox, you use **test USDC** on Base Sepolia — available for free from the [Circle faucet](https://faucet.circle.com). Test USDC has no real-world value and can be used freely during development.
Meterlane runs on **Base**, a Layer 2 network built on Ethereum by Coinbase. Base offers fast, low-cost transactions suitable for per-request micropayments.
| | Base Sepolia | Base Mainnet |
| ---------------- | --------------------- | --------------------------- |
| EIP-155 chain ID | `eip155:84532` | `eip155:8453` |
| Purpose | Sandbox / development | Production |
| USDC | Test USDC (no value) | Real USDC |
| Facilitator | Public `x402.org` | Private (Meterlane-managed) |
| Access | Available immediately | Requires go-live review |
All documentation examples use Base Sepolia. When you are ready to accept real payments, request production access from your Meterlane dashboard.
See these concepts in action — make your first paid API call in under five minutes.
Configure routes, set prices, and connect your upstream API.