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

# How the x402 payment protocol works with Laso

> Learn how the x402 HTTP payment protocol enables AI agents to pay for API requests with USDC stablecoin, replacing traditional API keys and subscriptions.

## 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

**1. Request a protected resource**

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

**2. 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.

**3. 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.

**4. 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"`.)

**5. 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:

```json theme={null}
{
  "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:

```typescript theme={null}
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](https://mpp.dev). 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:

```typescript theme={null}
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)

> [!NOTE]
>
> 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.

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

## Further reading

> [card] [x402 Protocol](https://x402.org)
>
> Official x402 protocol site and whitepaper.

> [card] [x402 GitHub](https://github.com/coinbase/x402)
>
> Open-source protocol specification and client libraries.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.