Skip to main content
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.
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:
FieldWhat it means
schemeAlways "exact" on Meterlane — the agent pays the stated amount exactly
networkEIP-155 chain ID string, e.g. "eip155:84532" for Base Sepolia
maxAmountRequiredUSDC amount in the smallest unit (6 decimals), e.g. "1000000" = 1 USDC
assetThe USDC contract address on the target network
payToThe wallet address that will receive the USDC
maxTimeoutSecondsHow 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 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 currencyCountry/Region
BRLBrazil
MXNMexico
NGNNigeria
KESKenya
ZARSouth 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. 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 SepoliaBase Mainnet
EIP-155 chain IDeip155:84532eip155:8453
PurposeSandbox / developmentProduction
USDCTest USDC (no value)Real USDC
FacilitatorPublic x402.orgPrivate (Meterlane-managed)
AccessAvailable immediatelyRequires go-live review
All documentation examples use Base Sepolia. When you are ready to accept real payments, request production access from your Meterlane dashboard.

Quickstart

See these concepts in action — make your first paid API call in under five minutes.

Agent Gateway Overview

Configure routes, set prices, and connect your upstream API.