How the x402 payment protocol works with Laso

What is x402?

x402 is an open payment protocol that uses the HTTP 402 Payment Required status code to enable instant stablecoin payments over HTTP. Instead of API keys or subscriptions, you pay per request with USDC. The protocol was created by Coinbase and is designed for both human users and AI agents.

The payment flow

Request a protected resource

Your agent sends a normal HTTP request to a paywalled endpoint (like GET /get-card?amount=50).

Server returns 402

The server responds with 402 Payment Required. The price and payment instructions ride in the PAYMENT-REQUIRED response header as base64-encoded JSON.

Client signs a payment

Your x402 client library reads the payment requirements, constructs an EIP-3009 transferWithAuthorization payload, and signs it with your wallet’s private key. No on-chain transaction is submitted — just a signature.

Client retries with payment header

The client replays the original request with a PAYMENT-SIGNATURE header containing the signed x402 v2 payment envelope. (The API is x402 v2 only; legacy v1 X-PAYMENT envelopes are rejected with errorReason: "unsupported_x402_version".)

Server verifies and serves

The server forwards the payment to a facilitator (Coinbase) for verification. If valid, the server returns the requested resource and the facilitator settles the USDC transfer on-chain.

The 402 response

When you hit a paywalled endpoint without paying, the challenge arrives in the PAYMENT-REQUIRED response header as base64-encoded JSON, and the same challenge is echoed as the JSON response body. It looks like this:

{
  "x402Version": 2,
  "resource": {
    "url": "https://laso.finance/get-card?amount=5",
    "description": "Get a prepaid card for use inside the United States",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "5000000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x3291e96b3bff7ed56e3ca8364273c5b4654b2b37",
      "maxTimeoutSeconds": 300
    },
    {
      "scheme": "exact",
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "amount": "5000000",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "payTo": "3MZVk97x9SeRxbYpc3jhzRfU2fyA3emYutnqfn9kNfYX",
      "maxTimeoutSeconds": 300
    }
  ]
}

Field	Description
`scheme`	Payment method — `"exact"` means pay the exact amount
`network`	Blockchain network in CAIP-2 format (`eip155:8453` = Base mainnet)
`amount`	Amount in token base units (6 decimals for USDC, so `5000000` = $5)
`payTo`	Wallet address that receives the payment
`asset`	USDC token contract address on that network

Key concepts

Your wallet signs, the facilitator pays gas

Your agent never submits a blockchain transaction. It only signs an authorization (EIP-3009 transferWithAuthorization). The facilitator — hosted by Coinbase — handles the on-chain settlement and pays gas fees.

Client libraries handle everything

If you use @x402/axios or @x402/fetch, the entire 402 → sign → retry flow happens automatically. Your code looks like a normal HTTP request:

import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { registerExactEvmScheme } from "@x402/evm/exact/client";

const client = new x402Client();
registerExactEvmScheme(client, { signer: account });
const payFetch = wrapFetchWithPayment(fetch, client);
// This looks like a normal request — x402 is handled under the hood
const response = await payFetch("https://laso.finance/get-card?amount=50");

Base mainnet + Solana mainnet (USDC)

Laso Finance accepts USDC payments on Base (Coinbase’s L2) and Solana mainnet. Both networks have low fees and fast finality, making them ideal for the per-card payment flows on /get-card, /order-gift-card, /get-push-to-card, and /order-intl-card.

The three actors

Actor	Role	Example
Client	Signs payment authorizations with a wallet	Your AI agent using `@x402/axios`
Resource server	Protects endpoints behind a paywall, verifies payments	Laso Finance API at `laso.finance`
Facilitator	Verifies signatures and settles payments on-chain	Coinbase’s hosted facilitator

Supported networks

x402 is chain-agnostic. The current ecosystem supports:

Network	CAIP-2 ID	Token
Base mainnet	`eip155:8453`	USDC
Solana mainnet	`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`	USDC

Laso Finance accepts payments on Base mainnet (eip155:8453) and Solana mainnet (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp).

Paying with MPP

Every paid route also accepts the Machine Payments Protocol. You need a Base wallet holding USDC and the mppx client. Point it at your wallet and at Base USDC, then call the route like any other URL:

import { Mppx, evm } from "mppx/client";
import { assets } from "mppx/evm";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.WALLET_PRIVATE_KEY);
const mppx = Mppx.create({
  methods: [evm({ account, currencies: [assets.base.USDC] })],
});

const res = await mppx.fetch("https://laso.finance/get-card?amount=50");

mppx.fetch handles the whole exchange: it reads the WWW-Authenticate: Payment challenge on the 402, signs an EIP-3009 USDC authorization for the quoted amount, and replays the request with Authorization: Payment .... Laso verifies the signature, settles the transfer on Base, and serves the response. The currencies entry is required because the challenge names the token address but not its signing domain. Your signing wallet is your Laso identity: the auth credentials in a paid response belong to that address, and the payment credits that account. The amount in the challenge is the fee-inclusive total, so budget for it rather than the amount parameter you passed. A refused credential returns another 402 with an application/problem+json body whose detail names the reason (a bad signature, an expired challenge, or a wallet that cannot cover the total). Nothing is charged for a refused attempt. MPP settles on Base only; a Solana wallet pays with x402 instead. A route that answers with an error after this point has already taken the payment: x402 settles only after a route succeeds, while MPP settles first, so the USDC lands in your Laso account balance. Recover it with POST /withdraw or retry.

Partner attribution (enterprise)

This section applies only to platforms with an enterprise agreement with Laso Finance. Individual agents and developers can ignore it. Nothing here changes how a request is priced or settled.

Platforms that embed Laso Finance endpoints in their own product send an X-Laso-Partner header on every request. Its value is the partner id you receive during onboarding. When a request from a new wallet creates an account, that account is recorded as having come through your platform. Requests without the header, or with an id we have not issued, are processed normally and simply are not attributed.

GET /get-card?amount=25 HTTP/1.1
Host: laso.finance
X-Laso-Partner: your-partner-id
PAYMENT-SIGNATURE: ...

x402 Protocol

Official x402 protocol site and whitepaper.

x402 GitHub

Open-source protocol specification and client libraries.

Get started

Solutions

Spend

Banking

Wallet

Platform

Integrations

How the x402 payment protocol works with Laso

What is x402?

The payment flow

The 402 response

Key concepts

Your wallet signs, the facilitator pays gas

Client libraries handle everything

Base mainnet + Solana mainnet (USDC)

The three actors

Supported networks

Paying with MPP

Partner attribution (enterprise)

Further reading

x402 Protocol

x402 GitHub

​What is x402?

​The payment flow

​The 402 response

​Key concepts

​Your wallet signs, the facilitator pays gas

​Client libraries handle everything

​Base mainnet + Solana mainnet (USDC)

​The three actors

​Supported networks

​Paying with MPP

​Partner attribution (enterprise)

​Further reading

x402 Protocol

x402 GitHub

What is x402?

The payment flow

The 402 response

Key concepts

Your wallet signs, the facilitator pays gas

Client libraries handle everything

Base mainnet + Solana mainnet (USDC)

The three actors

Supported networks

Paying with MPP

Partner attribution (enterprise)

Further reading