L402-EL2 lets an AI agent pay an MCP server for every tool call in wrapped BTC (cbBTC, WBTC, tBTC). Payments travel off-chain as EIP-712 signatures on a prefunded channel: the blockchain is touched only twice — when the channel opens and when the provider collects.
npm install && npm run compile:contracts && npm run example:e2e
No chain, no account, no configuration: the end-to-end demo runs on an in-process EVM.
/mcp · tools/call search_webPayment RequiredWWW-Authenticate: L402 macaroon="…", invoice="…", payment_request="…"EIP-712 voucher · cumulativeAmount 250 · 0 gas · <1 msAuthorization: L402 <macaroon>:<voucher>result · verified in ~5 mssettleBatch() · 1 L2 tx collects everythingAssumptions from the README: 20,000 calls per day, $0.005 of gas per L2 transaction.
Even on a cheap Layer 2 it would pay more in gas than for the service, and wait for a block on every call.
L402 was born on the Lightning Network: the server answers 402 Payment Required with a credential
and an invoice, the client pays and retries with a proof. Here the proof is a signed voucher
on a payment channel — verifiable in memory, not a transaction hash to look up on-chain.
The agent deposits wrapped BTC in the L402Escrow contract in favour of the provider — for example openChannel(0.001 cbBTC). With ERC-4337, approve and open are one atomic operation.
The server answers with a macaroon and a payment request that already contains the exact cumulative amount to sign — the client needs no RPC call.
The agent signs an EIP-712 voucher: “in total you may take up to N”. Its SpendingPolicy checks price, budget, provider, escrow and chain first.
Authorization: L402 <macaroon>:<voucher>. The Gatekeeper checks macaroon, signature, channel and amount, advances the voucher store atomically, and returns the result. Next calls pay in a single round trip.
The settler turns the latest voucher of each channel into one settleBatch() transaction — most urgent deadlines first, never below a profitable threshold.
A deposit by the payer, locked in the contract for one provider and one token. Money flows one way. The id is computable offline:
channelId = keccak256(abi.encode(payer, provider, token))The payer can take back what wasn't spent — after a 24-hour window that lets the provider collect first.
Each signature authorizes a total, not a delta. The provider only keeps the latest one.
A macaroon can be attenuated by whoever holds it, without the server's key. An agent can hand a sub-agent a token valid “only for search_web, for 60 seconds” — and the server still verifies it.
Caveats are verified fail-closed: an unknown key means the request is refused.
“The agent may spend up to 0.0005 cbBTC” isn't a client rule — it is a line in the contract:
escrow.authorizeSigner(sessionKey, maxCumulative, validUntil);If the key leaks, the loss is bounded. Delegations can be widened at any time, but narrowing or revoking takes effect after the same 24-hour grace period.
A browser simulation using the numbers of examples/e2e.ts: a 1,000,000-sat channel, search_web at 250 sat, heavy_analysis at 2,000 sat.
core is shared by everyone; the server and the settler share the same voucher store (Redis).
packages/contracts
Unidirectional payment channel with cumulative EIP-712 vouchers, on-chain session keys and batch settlement.
packages/core
Macaroons, EIP-712 types and digests, L402 header encoding, ABI and float-free unit conversions.
packages/server
Payment verification, HTTP and MCP middlewares, voucher stores (memory or Redis with atomic Lua scripts).
packages/client
EOA, ERC-4337 or session-key wallet, a self-paying fetch interceptor and a paid MCP client.
packages/settler
A separate process that turns accumulated vouchers into L2 transactions. Ships with a CLI.
examples/
A paid MCP server, a paying agent and an end-to-end run on an in-process EVM.
| Actor | Runs | Touches the chain? |
|---|---|---|
| Agent | client, inside the agent's process | Only to open / top up the channel and register the session key |
| MCP server | server (Express + MCP SDK) | Reads only, with a short-TTL cache |
| Settler | settler, separate process + CLI | Yes — sends settleBatch |
| Contract | L402Escrow on the L2 | — |
No chain, no account, no configuration. You'll see the contracts deployed on an in-process EVM, a paid MCP server start, an agent open a channel with a session key, pay four calls off-chain, and everything collected in a single transaction.
npm install
npm run compile:contracts
npm run example:e2e
# tests
npm run test:contracts # 21 escrow tests on a real in-process EVM
npx vitest run # 81 tests, incl. attack scenarios
Deploy the escrow on your L2 (Base, Arbitrum, Optimism…) with the Node script or with Foundry.
npm run compile:contracts
cd packages/contracts
DEPLOYER_PRIVATE_KEY=0x… CHAIN=base ESCROW_OWNER=0x… node tools/deploy.mjs
# or
forge script script/Deploy.s.sol --rpc-url base --broadcast --verify
initialize, tools/list and notifications stay free, so agents can discover what you offer before opening a channel. Only tools/call, resources/read and prompts/get are billed.
const app = createMcpL402App({
gatekeeper,
createServer: () => {
const server = new McpServer({ name: "…", version: "0.1.0" });
server.registerTool("search_web", { inputSchema: { query: z.string() } }, handler);
return server;
},
});
Copy .env.example to .env and fill in ESCROW_ADDRESS, TOKEN_ADDRESS, PROVIDER_PRIVATE_KEY, MACAROON_ROOT_KEY and REDIS_URL, then npm run example:server.
The settler runs next to the server and must share its voucher store (Redis).
npm run build
npx l402-settler plan # what it would collect, without sending anything
npx l402-settler once # one settlement and exit
npx l402-settler loop # keeps running and settles at intervals
On the agent side the tools look free: payment happens inside the transport, within the limits of a SpendingPolicy.
const client = await connectPaidMcpClient({
url: "https://mcp.example.com/mcp",
channels,
policy: {
maxPricePerCall: parseUnits("0.0001", 8),
totalBudget: parseUnits("0.0005", 8),
allowedProviders: [provider],
allowedEscrows: [escrow],
},
});
// From here on the agent calls tools as if they were free.
await client.callTool({ name: "search_web", arguments: { query: "…" } });
It can collect at most the latest amount the payer signed.
The same voucher can't be spent twice; parallel requests are serialized by an atomic store.
Only the channel's provider can settle; EIP-712 domains prevent cross-chain replay.
A compromised session key costs at most its on-chain cap per channel.
Closes, revocations and narrowed delegations wait 24 hours, so the provider can collect.
pause() only blocks new deposits; settlements and withdrawals always work.
It is the design choice of the protocol. A signature is verified in memory in milliseconds; a transaction hash would have to be looked up on-chain, bringing back the block wait and the RPC dependency that L402-EL2 exists to remove.
Challenges never read the chain — they only use cached state — and the on-chain read cache is bounded to 10,000 entries per kind, so random X-L402-Payer headers can't trigger RPC calls or grow memory.
Each challenge carries the last voucher the server accepted. The client verifies it's settleable (signed by the payer or a key it delegated), adopts it, and pays only the new increment — instead of refusing every payment.
ERC-4337 smart accounts are verified through ERC-1271 (SignatureChecker) both on-chain and on the server. ERC-6492 signatures of not-yet-deployed accounts are refused, because the escrow couldn't verify them at settlement.
The contract is tested but has not been externally reviewed. Before mainnet: an audit, third-party caveats, the type: "tx" fallback, rate limiting tuned to your traffic, and idle MCP session cleanup.
Tokens: cbBTC · Base WBTC · Arbitrum / Optimism tBTC
What L402-EL2 is, how to try it in one minute, how payment works, the cost model, production setup and the security choices.
How every piece works, from the Solidity contract to the AI agent that pays on its own. Written for whoever maintains, extends or deploys the code.