ZEAM :: Pass client

@zeampass/client, version 4.0.0. Source: https://github.com/zeam-labs/x402-mcp-bridge

The Pass client is for an agent that carries its own wallet: it stands in front of a paid MCP server or URL and pays from that wallet. To fund an agent without installing anything, give it a pass, a funded link: https://zeampass.com/pass

ZEAM :: Pass is the buyer side: a pass, or this client. Over MCP the client pays x402: per call, or it buys time and rides a line on a ZEAM :: Bridge seller. Over HTTP, paid_fetch pays a URL's 402 as an x402 exact payment, as an MPP charge, or from an x402 batch-settlement channel. It works with ZEAM Prism, with any ZEAM :: Bridge seller over MCP and over HTTP, with any x402 seller and, over HTTP, with a URL that takes an MPP evm charge. With a session escrow pinned in PASS_SESSION_ESCROW it also pays by MPP session, over MCP and over HTTP: see Paying by session.

Formerly x402-mcp-bridge

Up to 3.2.2 this was @zeam-labs/x402-mcp-bridge. It is now part of ZEAM :: Pass and pays MPP charges as well as x402. What you already run keeps working:

• @zeam-labs/x402-mcp-bridge 3.2.2 and earlier stay on npm and run as before; new versions are @zeampass/client;

• the command x402-mcp-bridge is installed beside zeam-pass;

• every X402_… setting is read when its PASS_… name is not set. With both set and different, PASS_… wins and the Pass client says so once on stderr;

• the tool name x402_fetch is answered as paid_fetch. Only paid_fetch is listed;

• the state directory is still ~/.x402-mcp-bridge, so a channel you funded is still found;

• the error code x402_bridge_spend_cap_reached is unchanged.

Related MCP server: x402 MCP Proxy

Run it

--help and --version print and exit; neither contacts a server.

It needs Node.js 20 or later. Export your key as PASS_PRIVATE_KEY. It signs locally and is never sent.

npx -y @zeampass/client --tools
npx -y @zeampass/client --call call_rpc \
  '{"chain":"base","method":"eth_blockNumber","params":[]}'
PASS_MCP_URL=https://seller.example/agents/mcp \
  npx -y @zeampass/client --call add '{"a":1,"b":2}'

--times N repeats a --call in one process. With no arguments the Pass client is an MCP stdio server:

{
  "mcpServers": {
    "prism": {
      "command": "npx",
      "args": ["-y", "@zeampass/client@4.0.0"],
      "env": { "PASS_PRIVATE_KEY": "0x..." }
    }
  }
}

Without a key it serves tools/list and the free tools; a paid call returns the seller's terms. --tools and --call do the same: a free tool runs, and a paid one prints the seller's terms and exits 1. --refund and paid_fetch need the key. A key that is set and malformed is reported as that, and --call stops.

The seller's instructions reach your MCP client, under a note that the Pass client is paying.

Results pass through whole: content, structuredContent, isError and _meta.

Paying per call

1. The Pass client reads the terms once from /.well-known/x402, or from the seller's first 402.

2. The first paid call deposits into a batch-settlement channel: price × PASS_DEPOSIT_MULTIPLIER (default 40, minimum 3), raised to the seller's floor (the 402's deposit line, or neededMicroUSD), and no more than PASS_MAX_SPEND leaves room for. On Prism: 250 µUSD × 40 = $0.01.

3. Later calls sign vouchers against that deposit. No gas, no round trip to ask the price.

The deposit sits in x402's batch-settlement escrow 0x4020074e9dF2ce1deE5A9C1b5c3f541D02a10003, hardcoded in @x402/evm. No owner, no pause, no upgrade. Only your key can withdraw it.

Line time

A ZEAM :: Bridge seller that sells time lists buy_time and line, and tags its time tools {"per":"time"}. Prism: 1 µUSD per ms. A paid call without a line costs $0.00025 and runs at most 250 ms. On a line a call costs the milliseconds it runs; calls at once burn once.

1. Buy. buy_time {"ms": N} pays for N milliseconds from the channel. Before a call the Pass client fills an empty line to PASS_LINE_AHEAD_MS (default 2000 ms): no more per purchase than the channel's collateral covers, never less than 250 ms. A seller on an older version of the plugin that sells time in blocks is asked for blocks.

2. Open. POST <base>/line {"op":"open","channelId"} returns a message. The Pass client signs it (EIP-191) with the payer key and posts {"op":"prove","channelId","nonce","signature"}; the answer carries the credential.

3. Ride. Each time-tool call carries the credential in _meta["zeam-pass/line"]; no payment per call. The answer's _meta["zeam-pass/meter"] states msRemaining. A call runs until the seller answers, the connection drops or the MCP client that asked cancels it, which the Pass client passes on to the seller and which stops its purchases.

4. Stay ahead. While a call runs the line burns 1 ms per ms and the seller keeps the call going as long as the line holds time. When half of PASS_LINE_AHEAD_MS is left (or twice the slowest purchase so far, if longer; one that carried a deposit counts only while the next will carry one) the Pass client buys again: as much as the call has run so far, at least PASS_LINE_AHEAD_MS. The call is not run again. At PASS_MAX_SPEND it stops buying; the call ends when the line runs out and the answer is x402_bridge_spend_cap_reached. A purchase that fails is said and tried again; the call runs on what is left.

5. Meter. After PASS_LINE_IDLE_MS (default 1000) with no call the Pass client sends {"op":"off"}; the next call sends {"op":"on"}. meter_off is switched on and called again; line_unknown opens a new line; out_of_time, which now means a purchase failed or came late, buys twice the time and calls again.

6. Exit. On exit the Pass client sends off, then close. Unburned time comes back with a refund.

PASS_LINE:

• auto (default): per call until 2 time-tool calls arrive within 10 s (PASS_AUTO_FAST_RUN, PASS_AUTO_GAP_MS), then a line while it holds time. A call cut for running past what one call buys (out_of_time) is called again on a line. When the seller says how long the call needs (needsMs), the Pass client buys that much, plus a quarter, before it calls again.

• on: every time-tool call rides a line.

• off: per call only.

Tools priced per call never ride a line.

Refunds

npx -y @zeampass/client --refund

1. The Pass client posts {channelId, issued, signature} to the refund route the seller names (its 402 or /.well-known/x402), else <base>/refund. The key signs:

    ZEAM Pass refund
    channel: <channel id, lowercase>
    issued: <ISO time>
   

2. When the channel's fees cover the gas, the seller sends the balance and the unburned time: returnedMicroUSD, timeReturnedMs, gasMicroUSD: 0.

3. When they do not, the seller answers 409 refund_quote with the exact gas. The Pass client signs a gasless USDC payment of it and posts again; one transaction returns the rest.

4. When the gas is more than what is left: nothing_to_return with the numbers.

--refund --self-send asks for a signed refund of all of it and sends it from your key, at your gas, if the key holds ETH on Base. Otherwise it prints the transaction for any wallet to send.

No answer from the seller: initiateWithdraw, then finalizeWithdraw after the channel's withdrawDelay.

--refund also closes an MPP session channel: see Paying by session.

Paying by session

An MPP session (draft-evm-session-00, method evm) is a payment channel in an escrow contract: one deposit, then one signed voucher per call for the running total, and what is not spent comes back when the channel closes. The seller's relay sends the deposit from an EIP-3009 authorization the key signs, so the key needs USDC and no ETH.

It is off until you pin an escrow. No escrow is built in: the contracts are deployed on Base and are not audited.

• PASS_SESSION_ESCROW: the escrow, or escrows, the Pass client may pay into. A session into any other escrow is not paid.

• PASS_SESSION_FACTORY: that escrow's payee factory. With it, before the deposit, the Pass client checks that the payee in the challenge is the factory's address for the seller's signer and split (receiverAuthorizer and payTo in the seller's 402) and signs nothing when it is not. Without it, or when the 402 names neither, the Pass client says the payee could not be checked, and pays.

• PASS_SESSION (default auto): auto pays by session when the seller offers one into a pinned escrow: after an x402 exact quote, before an MPP charge and before a new batch-settlement channel. A batch-settlement channel that still holds money is spent first; an open session channel is used before either. on pays by session first whenever one is offered. off never does.

Over MCP, with an escrow pinned, a tool priced per call is asked without payment for its session challenge: once when it offers none, and again each time the challenge is about to expire when it does. The answer of a free tool is returned as it is. A tool sold by time is paid the same way when it does not ride a line: with PASS_LINE=off, and with auto until a line holds time. A session channel opened over HTTP pays the MCP calls to the same seller.

What it signs, over MCP and in paid_fetch alike:

• The deposit is price × PASS_DEPOSIT_MULTIPLIER, at least the seller's suggestedDeposit. When the next call would pass the deposit, a top-up of the same size is signed first.

• A voucher is for what the seller's receipts show spent plus the price of the call, and never for more than the deposit. A receipt that claims more than the key has signed is refused, and nothing more is signed on that channel.

• The deposit and every top-up count toward PASS_MAX_SPEND when they are signed, and one that would pass it is not signed. A call paid out of a deposit this run signed is not counted again; a call paid out of an earlier run's deposit is. In paid_fetch, maxAmount refuses a deposit or top-up above it, as it refuses a price.

• One channel per seller, payee, token and escrow. Its record is <state directory>/session/<channel id>.json; it holds amounts and addresses, and the signed payments the Pass client may have to send again rather than sign a second one: a deposit or top-up until the escrow shows it, the gas payment of a close, and, after --refund --exit, the withdrawal and gas payment the relay holds. Each pays only the addresses it names (the escrow, the relay's gas wallet, the key), so the file cannot send money anywhere else, but anyone who reads it can send them while they are valid: keep the state directory private. A new run resumes the channel after checking the record against the escrow. When a seller later names another escrow or payee, nothing is signed and the open channel stays where it is until you close it.

Leaving:

• --refund asks the seller to close the channel: the seller is paid what was spent and the rest returns to the key in the same transaction. When the channel's fees do not cover that transaction's gas, the seller quotes it and the Pass client pays it in USDC out of what returns, under the checks in Limits. The key needs no ETH.

• --refund --exit leaves without the seller and without ETH, through the relay: a close request signed by the key, and, run again after the escrow's grace period (15 minutes in ZEAM's escrow), a signed withdrawal of everything the seller has not settled. These two signed calls are ZEAM's addition to the draft's escrow. The relay sends them free when the fees on what the channel has settled cover their gas. When they do not, the Pass client asks the relay its price and signs the withdrawal and a USDC payment of that price along with the request; the relay sends the request, holds the rest and sends it after the grace period. The gas comes out of what returns, the key needs no ETH, and there is nothing to run again: a later --refund shows the channel closed. The relay needs the seller's split, which a ZEAM :: Bridge seller publishes beside its session challenge and the Pass client keeps in the channel's record; for a seller that publishes none, give it as PASS_SESSION_SPLIT, {"split":{"recipients":[…],"allocations":[…],"totalAllocation":"…","distributionIncentive":0},"salt":"0x…"}. The Pass client uses it only when the 0xSplits factory gives the seller's split address for it.

• --refund --self-send sends the draft's own requestClose, and after the grace period withdraw, from the key at its own gas. It needs nothing from the seller or the relay.

Gates and grants

A ZEAM :: Bridge gate admits listed keys by a zero-value payment: nothing moves. PASS_GRANT is sent as the x-grant header on every request to the seller's own origin (the origin of PASS_MCP_URL), over MCP and HTTP, so a key admitted by grant passes the gate. It is not sent to a relay, to a paid_fetch URL on another origin, or across a redirect to another origin.

Any paid URL

paid_fetch is offered beside the seller's tools. It calls a URL and pays a 402 with the first of these the URL offers:

1. x402 exact: one signed transfer.

2. An MPP (WWW-Authenticate: Payment) charge, method evm.

3. x402 batch-settlement: a payment channel, as in Paying per call. A ZEAM :: Bridge seller quotes this on its HTTP routes (POST <base>/v1/<tool>, and its own routes behind the paywall), with an MPP charge beside it only where the price covers the gas.

With a session escrow pinned, an MPP session the URL offers into it is paid after 1 and before 2, as Paying by session says. The result carries protocol: "mpp", intent: "session", channelId, charged, the receipt, payeeVerified and, when one was signed, deposit or topUp.

npx -y @zeampass/client --call paid_fetch \
  '{"url":"https://api.example.com/v1/quote","body":{"symbol":"ETH"}}'

• pay: false returns the terms without paying.

• maxAmount (base units) refuses a larger quote before signing.

• USDC counts toward PASS_MAX_SPEND. Another asset is paid only with maxAmount.

• A zero-value gate: signed, admitted, paid: false.

• An MPP charge is paid when it is method evm, intent charge, on the Pass client's network, taking an EIP-3009 authorization: one signed USDC transfer, no channel. The result carries protocol: "mpp" and the receipt.

• A signed MPP charge counts toward PASS_MAX_SPEND when it is sent, receipt or not: its seller can collect it until the challenge expires. With no receipt the result says signed: true and paid: false. A signed x402 exact transfer counts the same way; a URL that answers it with an error gets signed: true and paid: false.

• Other MPP methods (tempo, stripe) are listed under mpp in the terms and not paid.

• A batch-settlement payment: the first call to a seller signs a deposit, price × PASS_DEPOSIT_MULTIPLIER, at least the floor its 402 names; later calls sign vouchers against it. The result carries scheme, channelId, charged and, when one was signed, deposit.

• A deposit counts toward PASS_MAX_SPEND when it is signed, and maxAmount refuses a deposit above it as it refuses a price. Refused, nothing is signed and needed is the amount that would be. A call paid out of a deposit this run signed is not counted again; a call paid out of an earlier deposit is.

• Channel state is kept per host: ~/.x402-mcp-bridge/<host>/<address>, or <PASS_STATE_DIR>/hosts/<host>/<address> when PASS_STATE_DIR is set. A URL on the host of PASS_MCP_URL pays from the channel the MCP tools pay from. A record is named by its channel, which the receiver in the terms fixes: other terms are another channel, and a seller's answer updates only the channel its own terms name.

• To take back what such a channel has not spent: PASS_MCP_URL=https://<host> with --refund, and with PASS_STATE_DIR set, that host's directory as PASS_STATE_DIR. The Pass client prints the settings when it signs a deposit.

• A 402 after a payment: funding_requires_open_fee deposits the floor it names; a count the seller proves with this key's own voucher resyncs the channel; payment_invalid drops the local record and resyncs from the chain. The call is then paid again, three payments at most, every deposit among them inside maxAmount and PASS_MAX_SPEND.

• A seller that takes the voucher and fails: its error comes back, paid: false, nothing counted. An answer with no PAYMENT-RESPONSE: signed: true, paid: false, and the price counts toward PASS_MAX_SPEND.

Chain clients

import { createPublicClient } from 'viem'
import { base } from 'viem/chains'
import { prism } from '@zeampass/client/viem'

const client = createPublicClient({
  chain: base,
  transport: prism({ key: process.env.PASS_PRIVATE_KEY }),
})
await client.getBlockNumber()

The ethers provider needs ethers 6 or later installed beside the Pass client (npm install ethers).

import { PrismProvider } from '@zeampass/client/ethers'
const provider = new PrismProvider({ key: process.env.PASS_PRIVATE_KEY })

1. The first request pays per call at /rpc/base (or /rpc/eth, chain: 'eth') and funds the channel: 40 × the price, at least the seller's floor.

2. Then it opens a line, buys aheadMs (2000) of time, and sends x-line. While a request runs it buys more before the line runs out, as above.

3. maxMicroUSD (default PASS_MAX_SPEND) bounds everything one request signs for: a deposit or top-up, the call, the line time bought before and during it. Each counts when it is signed; a call or line time paid out of a deposit the same request signed is not counted again, and one paid out of an earlier request's deposit is. A deposit that would pass it is made smaller to fit, down to what the call and the seller's floor need. Below that nothing is signed and the request is refused with an error whose code is x402_bridge_spend_cap_reached and whose needed is the amount. During a call, purchases stop at it and the call runs on the time left. refund() holds its gas payment to it.

4. The meter goes off after idleMs (1000) idle; the line is let go after dropAfterMs (10000).

5. state(), close(), refund(). Call close() or refund() before exit.

Options: url, chain, network, stateDir, depositMultiplier, asset, salt, rpcUrl, grant, relayUrl, maxMicroUSD, aheadMs, idleMs, dropAfterMs, log. The PASS_* variables are the defaults; the state directory is shared with the Pass client.

Configuration

• PASS_PRIVATE_KEY (no default): funds the channel and signs.

• PASS_MCP_URL (default https://mcp.zeamprism.com/mcp): any x402 MCP endpoint.

• PASS_LINE (default auto): auto, on, off.

• PASS_LINE_AHEAD_MS (default 2000): line time kept ahead of a call; the least bought per buy_time.

• PASS_LINE_IDLE_MS (default 1000): meter off after this idle.

• PASS_MAX_SPEND (default 10000000, $10): ceiling on what this run pays, µUSD; 0 removes it. Every deposit and top-up counts when it is signed, x402 or session, for an MCP tool or in paid_fetch; so does every signed transfer: an exact payment, an MPP charge, a gas payment. A call paid out of a deposit this run signed is not counted again. What the channel was charged before this run is not counted. For an MCP tool an x402 deposit that would pass the cap is made smaller to fit, down to what the call and the seller's floor need; below that nothing is signed.

• PASS_DEPOSIT_MULTIPLIER (default 40): deposit = price × this, at least the seller's floor; minimum 3.

• PASS_GRANT (no default): x-grant on every request to the seller's own origin.

• PASS_RPC_URL (default the chain's public RPC): your node for chain reads.

• PASS_STATE_DIR (default ~/.x402-mcp-bridge/<host>/<address>): channel state; keep it.

• PASS_SALT (default the scheme's): a distinct channel.

• PASS_ASSET (default first quoted): address or symbol.

• PASS_NETWORK (default eip155:8453): CAIP-2.

• PASS_SESSION (default auto): auto, on, off. Nothing is paid by session until an escrow is pinned.

• PASS_SESSION_ESCROW (no default): the MPP session escrow addresses the Pass client may pay into.

• PASS_SESSION_FACTORY (no default): the payee factory of that escrow, to check a seller's payee.

• PASS_SESSION_SPLIT (no default): a seller's split and its salt, for --refund --exit.

Every request to a seller, a relay or a paid_fetch URL is sent with User-Agent: zeam-pass-client/<version> node, so the other side can see it is the Pass client and which version. A User-Agent you put in paid_fetch's headers is sent instead. Nothing else about you is added: no address, no host name.

USDT, DAI and WETH settle through Permit2: approve 0x000000000022D473030F116dDEE9F6B43aC78BA3 once. USDC needs no approval.

Limits

• It exits when stdin closes, and lets its line go.

• It stops at PASS_MAX_SPEND: further calls return x402_bridge_spend_cap_reached.

• On --refund, when the seller asks for the refund's gas in USDC, it signs only a payment to the relay's own gas wallet, in USDC on its own chain, for the amount quoted, no more than twice what the relay prices that gas at, less than the refund and within PASS_MAX_SPEND. Otherwise it signs nothing and says why. The relay is ZEAM's (https://api.zeampass.com/relay); PASS_RELAY_URL names another. The gas of a session channel's close is checked the same way. For --refund --exit the price is the relay's own, and the payment is signed only when it is less than what is left in the channel and within PASS_MAX_SPEND; it cannot be taken before the grace period ends. Signed with the close request, it is valid from 30 s after the grace period the chain gives at that moment, for 15 minutes; the answer says from when (gasPaymentValidFrom), and says so if the request landed so late that this falls inside the grace period. Signed after the request is on chain, it is valid from the end of that request's grace period. A close's gas payment is signed only when it is valid at once and for no more than 10 minutes, is less than what the escrow shows would return, and the relay does not say the channel's fees cover the gas. Each payment is kept in the channel's record, and no other is signed for that channel while one is unexpired and unused: the same one is sent again, or --refund says until when to wait (gas_payment_pending).

• On --refund --self-send it sends only the escrow's signed refund of this channel: refundWithSignature, alone or with its claim in the escrow's multicall. Any other transaction a seller hands back is not sent; the answer is signed_refund_refused and says why. initiateWithdraw needs nothing from the seller.

• The ETH gas that --self-send pays is not counted toward PASS_MAX_SPEND. The Pass client knows its cost in ETH before sending but holds no ETH price of its own, and a price asked of the seller or the relay would make the exit depend on them. It sends only when the key holds 1.5 × the estimate, and the answer states what was paid (gasWei).

• Lost state costs one probe to resync, then one deposit.

Verify before you run it

The versions are pinned exactly.

npm view @zeampass/client@4.0.0 version dist.integrity
npm pack @zeampass/client@4.0.0
less package/index.mjs

Apache-2.0. Patent pending.