@zeampass/client

@zeampass/client, version 4.1.1. Source: https://github.com/zeam-labs/pass-client

The buyer side of ZEAM :: Pass, 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/

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.

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 client is an MCP stdio server:

{
  "mcpServers": {
    "prism": {
      "command": "npx",
      "args": ["-y", "@zeampass/client@4.1.1"],
      "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 client is paying.

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

Related MCP server: x402 MCP Proxy

Paying per call

1. The client reads the terms once from the seller's /.well-known/x402 (Prism publishes it) and pays from them. A seller that publishes none, as a ZEAM :: Bridge seller does not, is asked each time: before every paid call and every buy_time purchase the client sends the call unpaid and pays from the 402 that answers it. A run with PASS_LINE=on that does not yet know which channel this key and PASS_SALT pay this seller asks once before its first purchase: a first run, a run whose state directory holds only other channels, and a run whose recorded channel the seller answers unknown_channel. That one ask is the unpaid buy_time that learns the channel, after which the client asks for a line on it (a channel the seller does not know yet answers unknown_channel) and, when it must buy time, pays from that same 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, with no gas. With the seller's /.well-known/x402 terms no round trip asks the price; without them each paid call is the unpaid call and then the paid one.

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 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 client signs it (EIP-191) with the payer key and posts {"op":"prove","channelId","nonce","signature"}; the answer carries the credential. A line opened on a channel with no other line open switches the channel's meter on. A line opened while another line is open on the channel leaves the meter as it is: if an agent switched it off, the answer's metering is false, and the client sends {"op":"on"} before it rides.

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 or the MCP client that asked cancels it, which the client passes on to the seller and which stops its purchases. A hang-up ends the call and its bill on a Node seller and on a Python seller served over ASGI; a WordPress seller, and a Python seller served over WSGI, cannot see one, and the call burns until it returns. Cancel a call before you hang up.

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 client buys again: as much as the call has run so far, at least twice that threshold (PASS_LINE_AHEAD_MS, or four times the slowest purchase, so a slow purchase still lands with time in hand): no more per purchase than the channel's collateral covers or PASS_MAX_SPEND leaves room for, never less than 250 ms. It buys only while a call runs: a purchase whose turn comes after the last call has ended is not made, and one whose price is answered after that is not signed. One already signed when the call ends is completed, and its time stays on the line until a refund returns it. 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 client sends {"op":"off"}; the next call sends {"op":"on"}. The meter is the channel's, not the line's: this off, and the off on exit, switch it off for every line open on that channel, and another agent riding the same channel must send on again. close ends only the client's own line; it leaves the meter and every other line as they are. 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. Every exit takes one path: the end of --call or --tools, an error, stdin closing, SIGINT or SIGTERM. The client signs nothing new, waits up to PASS_EXIT_WAIT_MS (default 30000) for every purchase still in flight, deposit or voucher, and records each answer in PASS_STATE_DIR; then it sends off, then close. A purchase still unanswered at that bound is said, and the line is let go without its answer. 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 much more the call needs (needsMs), the client runs the whole call again, so it buys what the call already ran (the time one call buys) plus needsMs, plus a quarter, and never less than PASS_LINE_AHEAD_MS, before it calls again. A call already on a line that is cut with needsMs is called again on what it ran plus needsMs, plus half; no purchase is under 250 ms. It calls a cut call again at most three times on a line; a call still cut after that answers with the seller's cut: what the call got done, and needsMs for what is left. Where the seller's cut says how to continue, continue from that answer, and continue a continuation that is cut again the same way, from its own answer: the wallet-audits scans say to call again with to_block one below scanned.from, and each cut's needsMs is for what is left below its own scanned.from, so a continuation cut again is called with to_block one below the new scanned.from, and needs the new needsMs.

• 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 client posts {channelId, issued, signature} to the refund route the seller names (its 402 or /.well-known/x402), else <base>/refund. The channel is the one this key and PASS_SALT pay: the one the seller's /.well-known/x402 fixes, or, against a seller that publishes none, the one a run from this PASS_STATE_DIR last paid into with them. The seller is the one in PASS_MCP_URL, by its origin: a state directory shared by several sellers keeps each one's refund route and channel apart, and --refund asks only that seller, for its own channel. When no run from this PASS_STATE_DIR recorded that channel (a state directory from 4.0.0 or earlier, or a lost one), the client works it out from this key, PASS_SALT and the seller's terms (against a seller that publishes none, it calls one paid tool unpaid, buy_time where there is one, to read its 402), and asks for it when it holds something the payer can withdraw: the escrow's balance for it, less what the seller has claimed or is owed (the larger of the escrow's totalClaimed and the amount charged that this state directory records), as the seller judges a refund; it then records it. When that channel holds nothing the payer can withdraw, --refund says so, with its balance and what the seller has claimed or is owed, asks nobody and exits 2. A channel recorded at another seller, or paid with another key or PASS_SALT, is never asked for; when none is this seller's, --refund says so and asks nobody. --refund --channel <id> asks this seller for that channel by name: the seller refunds it only to a proof signed by the channel's payer, and a channel whose voucher in the state directory another key signed is not asked for. The key signs:

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

2. Our relay pays the gas of a refund when our fee on what the buyer spent covers the gas of the deposit, of the refund and of settling any calls not yet settled, and of every further deposit and every earlier refund it paid for on that channel, with a 15% margin; otherwise the buyer pays the refund's gas, with a 15% margin, in USDC, quoted before the buyer signs that payment. Our fee is the fee share the seller's refund terms name: 9.99% for most sellers, 100% at Prism. The seller counts the gas at the current gas and ETH price: free when feeMicroUSD >= coverMicroUSD. Then 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 feeMicroUSD, coverMicroUSD and gasMicroUSD: this refund's gas, as the relay estimates it now, plus 15%. The client signs a gasless USDC payment of it and posts again; one transaction returns the rest. If the gas has risen past the payment by the time the relay sends, nothing is sent and the answer is refund_quote with requoted: true and the new figure: run --refund again.

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 the MPP session channels opened at that seller: 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. ZEAM's session contracts are the escrow EvmPaymentChannel at 0x5e09aD70b644414cD1cD7Df1d9a10fF7899D92B8 on Base and its payee factory at 0xE18fCE1266056becA4a3B0edfc15F8634EA6901B: both deployed on 2026-10-13, immutable, and not audited.

• PASS_SESSION_ESCROW: the escrow, or escrows, the 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 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 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 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 plus 15%, the seller quotes it and the 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 plus 15%. When they do not, the 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 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 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.

• A channel that already has a close request on chain, sent from another state directory or by another tool, is not closed through the seller: --refund answers session_exit_waiting with when the withdrawal can be sent (readyAt) and, once the grace period has passed, sends the withdrawal through the relay when the relay sends it free. When the relay asks for its gas, --refund signs nothing and says so; --refund --exit pays that gas in USDC out of what returns, and --refund --self-send sends withdraw at the key's own gas.

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 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 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 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 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 while the channel's collateral and PASS_MAX_SPEND leave room for it.

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

• PASS_EXIT_WAIT_MS (default 30000): how long an exit waits for a purchase in flight to be answered before it lets the line go.

• 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, and in seller.json, for each seller by origin, its refund route and the channel each key and PASS_SALT last paid into there; 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 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 @zeampass/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 once the purchases in flight are answered.

• It stops at PASS_MAX_SPEND: further calls return x402_bridge_spend_cap_reached, with spentMicroUSD, what this run counted toward it, and capMicroUSD, for an MCP tool and from paid_fetch alike.

• 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. When the client does not sign it, the answer keeps the seller's code: "gas_payment_needed", leftMicroUSD, returnedMicroUSD, gasMicroUSD and its detail as why, and adds refused: "gas_payment_refused" and refusedWhy, the client's reason. 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 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 is rebuilt from the seller: the first payment on the channel after it is lost is refused with the seller's corrective 402, which carries the channel's state, and is made again from that state; nothing is charged for the refused one. Against a seller that publishes no /.well-known/x402 terms, the unpaid calls that ask the price come first. A channel that holds nothing then takes one deposit.

Verify before you run it

The versions are pinned exactly.

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

Upgrading from @zeam-labs/x402-mcp-bridge

Up to 3.2.2 the client was published as @zeam-labs/x402-mcp-bridge. Those versions stay on npm and run as before. Moving to @zeampass/client changes nothing you run:

• 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 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.

Apache-2.0. Patent pending.