@zeam-labs/x402-mcp-bridge 2.0.5 → 2.1.0

package/README.md

@@ -98,6 +98,46 @@ A refused payment re-reads the terms and retries once, because quotes for
 non-stable assets move with the oracle. Anything still failing falls back to the
 old probe-then-pay path rather than dropping your call.
 
+## Point a chain client at it
+
+An agent that already has a viem client does not want an MCP tool called `rpc`.
+It wants its provider URL to be a wallet instead of an API key:
+
+```js
+import { createPublicClient } from 'viem'
+import { base } from 'viem/chains'
+import { prism } from '@zeam-labs/x402-mcp-bridge/viem'
+
+const client = createPublicClient({ chain: base, transport: prism({ key: process.env.X402_PRIVATE_KEY }) })
+await client.getBlockNumber()      // paid from the wallet, served by an archive node
+```
+
+Nothing else in the agent changes. The transport speaks JSON-RPC to Prism's
+`/rpc/base` (or `/rpc/eth` with `chain: 'eth'`) and x402 back. The first request
+funds a channel and buys one block. After that it holds a line: the meter is on
+while calls are flowing, off within a second of them stopping, and the line is
+let go after ten idle seconds. Vouchers cost no gas; only the deposit does.
+
+Options, all optional: `url` (the Prism host), `chain` (`base` | `eth`),
+`network`, `stateDir`, `depositMultiplier`, `asset`, `salt`, `rpcUrl` (a node
+of your own for the payment client's chain reads), `aheadMs` (bought time to
+keep on the meter while calling, default 2000), `idleMs` (meter off after this
+long with no call, default 1000), `dropAfterMs` (let the line go, default
+10000), `log`. Anything else is passed to viem's `http()`. The same `X402_*`
+environment variables the bridge reads are the defaults, and the channel state
+directory is shared, so a channel the bridge funded is the one the transport
+uses.
+
+The transport carries three extra methods: `state()` reports the address,
+channel, whether a line is held, whether the meter is on and the milliseconds
+left; `close()` switches the meter off and drops the line; `refund()` returns the
+unspent collateral and the time bought and not burned to the wallet. Call
+`close()` or `refund()` before your process exits, or the open socket keeps it
+alive.
+
+`test/viem.mjs` drives it against a live server with real money and checks each
+of those claims.
+
 ## Holding a line
 
 A server may sell **time** rather than calls, with a cheaper path than paying
@@ -158,7 +198,7 @@ time and an overlapping tick is refused as `channel_busy`.
 | `X402_STATE_DIR` | `~/.x402-mcp-bridge/<host>/<address>` | channel state |
 | `X402_SALT` | scheme default | open a distinct channel. Any string; it is hashed to bytes32 |
 | `X402_MAX_SPEND` | `10000000` (=$10) | ceiling on what **this run** may spend, in micro-USD. `0` removes it — see below |
-| `X402_DEPOSIT_MULTIPLIER` | `400` | collateral a deposit locks in escrow, as a multiple of the seller's quote for the opening call. That opening quote carries the one-time open fee, so against zeamprism the default locks ~$0.70 of **refundable** collateral — it leaves your wallet when you open the channel and returns on refund. Lower it if that is more than you want committed; the scheme refuses below 3x. |
+| `X402_DEPOSIT_MULTIPLIER` | *scheme default* | how much **refundable** collateral to lock, as a multiple of the seller's quote for the opening call. Unset, the x402 scheme sizes it (minimum 3); raise it to top up less often, lower it to commit less. It leaves your wallet when you open the channel and comes back on refund — it is not the price. |
 
 ## It stops spending when you stop watching
 

package/index.mjs

@@ -42,10 +42,9 @@ if (has('--help') || has('-h')) {
     '',
     'Env: X402_PRIVATE_KEY (required), X402_MCP_URL (X402_UPSTREAM also accepted),',
     '     X402_MAX_SPEND (0 = no cap; base units of the paid asset if the server publishes no price),',
-    '     X402_DEPOSIT_MULTIPLIER (default 400; the deposit is this times the seller\'s',
-    '     quote for the OPENING call, held as refundable collateral — against',
-    '     zeamprism ~$0.70, since the opening quote carries the one-time open',
-    '     fee), X402_LINE=auto|on|off,',
+    '     X402_DEPOSIT_MULTIPLIER (refundable collateral to lock, as a multiple of',
+    '     the opening quote; unset uses the x402 scheme default, minimum 3),',
+    '     X402_LINE=auto|on|off,',
     '     X402_SALT.',
 '     auto: buy per-call minimum holds until calls arrive faster than the',
 '     server minimum hold, then hold a line while that lasts. A held line',
@@ -103,7 +102,9 @@ try {
   if (f) channelId = f.replace(/\.json$/, '')
 } catch {}
 
-const depositPolicy = { depositMultiplier: Number(process.env.X402_DEPOSIT_MULTIPLIER ?? 400) }
+const depositPolicy = process.env.X402_DEPOSIT_MULTIPLIER
+  ? { depositMultiplier: Number(process.env.X402_DEPOSIT_MULTIPLIER) }
+  : {}
 
 const MAX_SPEND = Number(process.env.X402_MAX_SPEND ?? 10_000_000)
 let capReached = false
@@ -264,7 +265,7 @@ const explainPermit2 = (out) => {
   if (!token || approvalToldFor === token) return true
   approvalToldFor = token
   const per = Number(chosenAccept?.amount ?? 0)
-  const mult = Number(process.env.X402_DEPOSIT_MULTIPLIER ?? 400)
+  const mult = Number(process.env.X402_DEPOSIT_MULTIPLIER ?? 5)
   const suggested = per > 0 ? BigInt(Math.ceil(per * mult * 4)) : 0n
   log(`${token} moves through Permit2 and your wallet has not approved it.`)
   log(`  send once, from your wallet:  approve(${PERMIT2}, ${suggested || '<amount>'})  on ${token}`)
@@ -421,7 +422,7 @@ const callOnLine = async (name, args) => {
     dropLine(reasonFrom(out) ?? 'refused by the server')
     if (attempt === 2) {
       log('the line was refused twice; paying for this call directly. If the reason above ' +
-        'is collateral, raise X402_DEPOSIT_MULTIPLIER — the minimum of 3 buys under a second of line.')
+        'is collateral, raise X402_DEPOSIT_MULTIPLIER — the scheme minimum is 3.')
     }
   }
   return payFirst(name, args)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeam-labs/x402-mcp-bridge",
-  "version": "2.0.5",
+  "version": "2.1.0",
   "description": "Put a wallet in front of any x402-paid MCP server, and hold a metered line on the ones that sell time. Stock MCP clients cannot construct x402 payments; this one does, and proxies your existing client through it.",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "main": "index.mjs",
   "files": [
     "index.mjs",
+    "viem.mjs",
     "README.md"
   ],
   "engines": {
@@ -17,13 +18,18 @@
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.30.0",
-    "@x402/mcp": "2.22.0",
     "@x402/evm": "2.22.0",
+    "@x402/fetch": "2.22.0",
+    "@x402/mcp": "2.22.0",
     "viem": "2.55.16"
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/zeam-labs/x402-mcp-bridge"
   },
-  "homepage": "https://mcp.zeamprism.com/llms.txt"
+  "homepage": "https://mcp.zeamprism.com/llms.txt",
+  "exports": {
+    ".": "./index.mjs",
+    "./viem": "./viem.mjs"
+  }
 }

package/viem.mjs

@@ -0,0 +1,263 @@
+// A viem transport that pays ZEAM Prism from a wallet.
+//
+//   import { prism } from '@zeam-labs/x402-mcp-bridge/viem'
+//   const client = createPublicClient({ chain: base, transport: prism({ key }) })
+//
+// The agent's chain client speaks JSON-RPC to Prism's /rpc/<chain> door and
+// this transport speaks x402 back. The first request funds a channel and buys
+// one block; after that it holds a line, keeps time on the meter while calls
+// are flowing, switches the meter off when they stop, and lets the line go
+// when nothing has called for a while. Nothing in the agent changes.
+
+import { http, createPublicClient, http as plainHttp, fallback, keccak256, toHex } from 'viem'
+import { privateKeyToAccount } from 'viem/accounts'
+import * as chains from 'viem/chains'
+import { x402Client, x402HTTPClient, wrapFetchWithPayment } from '@x402/fetch'
+import { BatchSettlementEvmScheme } from '@x402/evm/batch-settlement/client'
+import { FileClientChannelStorage } from '@x402/evm/batch-settlement/client/file-storage'
+import { toClientEvmSigner } from '@x402/evm'
+import { mkdirSync, readdirSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+const LINE_HEADER = 'x-line'
+const LINE_GONE = new Set(['unknown_line', 'line_closed'])
+
+const queue = () => {
+  let tail = Promise.resolve()
+  return (fn) => { const run = tail.then(fn, fn); tail = run.then(() => {}, () => {}); return run }
+}
+
+const saltOf = (raw) => /^0x[0-9a-fA-F]{64}$/.test(String(raw).trim()) ? String(raw).trim() : keccak256(toHex(String(raw)))
+
+function wallet({ key, url, network, stateDir, depositMultiplier, asset, salt, rpcUrl, log }) {
+  if (!key || !/^0x[0-9a-fA-F]{64}$/.test(key)) {
+    throw new Error('prism(): key must be a 0x-prefixed 32-byte private key. It signs vouchers locally and is never sent anywhere.')
+  }
+  const account = privateKeyToAccount(key)
+  const chainId = Number(String(network).split(':')[1])
+  const payChain = Object.values(chains).find((c) => c?.id === chainId)
+  if (!payChain) throw new Error(`prism(): unknown network ${network}`)
+  const dir = stateDir ?? join(homedir(), '.x402-mcp-bridge', new URL(url).host, account.address.toLowerCase())
+  mkdirSync(dir, { recursive: true })
+  const readers = [...(rpcUrl ? [rpcUrl] : []), ...(payChain.rpcUrls?.default?.http ?? []), new URL('/verify', url).toString()]
+  const pub = createPublicClient({ chain: payChain, transport: fallback(readers.map((u) => plainHttp(u))) })
+
+  const want = String(asset ?? '').toLowerCase()
+  const selector = (_v, accepts) => {
+    if (want) {
+      const hit = accepts.find((a) => String(a.asset).toLowerCase() === want || String(a.extra?.name ?? '').toLowerCase() === want)
+      if (hit) return hit
+    }
+    return accepts[0]
+  }
+  const storage = new FileClientChannelStorage({ directory: dir })
+  const state = { channelId: null }
+  try {
+    const f = readdirSync(join(dir, 'client')).find((n) => n.endsWith('.json'))
+    if (f) state.channelId = f.replace(/\.json$/, '')
+  } catch { }
+  const watched = {
+    get: (k) => storage.get(k),
+    delete: (k) => { if (state.channelId === k) state.channelId = null; return storage.delete(k) },
+    set: (k, ctx) => { state.channelId = k; return storage.set(k, ctx) },
+  }
+  const payments = new x402Client(selector).register(network,
+    new BatchSettlementEvmScheme(toClientEvmSigner(account, pub), {
+      ...(depositMultiplier ? { depositPolicy: { depositMultiplier: Number(depositMultiplier) } } : {}),
+      storage: watched,
+      ...(salt ? { salt: saltOf(salt) } : {}),
+    }))
+  const httpClient = new x402HTTPClient(payments)
+  const paidFetch = wrapFetchWithPayment(fetch, payments)
+  const oneAtATime = queue()
+  log(`prism: paying as ${account.address}, state in ${dir}`)
+  return { account, state, payments, httpClient, paidFetch, oneAtATime, dir }
+}
+
+function line({ url, w, aheadMs, idleMs, dropAfterMs, log }) {
+  const ws = new URL('/pay', url); ws.protocol = ws.protocol === 'https:' ? 'wss:' : 'ws:'
+  const s = { socket: null, credential: null, remainingMs: 0, readAt: 0, metering: false,
+              opening: null, waiting: new Map(), offTimer: null, dropTimer: null, tickTerms: null, topping: null }
+  const send = (frame) => { try { s.socket?.send(JSON.stringify(frame)) } catch { } }
+  const remaining = () => Math.max(0, s.remainingMs - (s.metering ? Date.now() - s.readAt : 0))
+  const read = (ms, metering) => { s.remainingMs = Number(ms ?? 0); s.readAt = Date.now(); if (metering !== undefined) s.metering = Boolean(metering) }
+  const settle = (op, frame) => { const w = s.waiting.get(op); if (w) { s.waiting.delete(op); w(frame) } }
+  const ask = (op, frame) => new Promise((resolve) => {
+    if (!s.socket || s.socket.readyState !== 1) return resolve(null)
+    s.waiting.set(op, resolve); send(frame)
+    setTimeout(() => { if (s.waiting.get(op) === resolve) { s.waiting.delete(op); resolve(null) } }, 10_000)
+  })
+  const drop = (why) => {
+    if (s.offTimer) clearTimeout(s.offTimer); if (s.dropTimer) clearTimeout(s.dropTimer)
+    s.offTimer = s.dropTimer = null
+    for (const [, w] of s.waiting) w(null); s.waiting.clear()
+    try { s.socket?.close() } catch { }
+    if (s.credential) log(`prism: line closed (${why})`)
+    s.socket = null; s.credential = null; s.metering = false
+  }
+  const terms = async () => {
+    if (s.tickTerms) return s.tickTerms
+    try {
+      const j = await (await fetch(new URL('/.well-known/x402', url))).json()
+      const accepts = Array.isArray(j.tickAccepts) && j.tickAccepts.length ? j.tickAccepts : j.accepts
+      if (Array.isArray(accepts) && accepts.length) s.tickTerms = { x402Version: j.x402Version ?? 2, accepts }
+    } catch { }
+    return s.tickTerms
+  }
+  const open = () => {
+    if (s.credential) return Promise.resolve(s.credential)
+    if (s.opening) return s.opening
+    if (!w.state.channelId) return Promise.resolve(null)
+    s.opening = new Promise((resolve) => {
+      let socket
+      try { socket = new WebSocket(ws.toString()) } catch (e) { log(`prism: line: ${e.message}`); return resolve(null) }
+      const giveUp = setTimeout(() => { try { socket.close() } catch { } ; resolve(null) }, 10_000)
+      socket.onmessage = async (ev) => {
+        let m; try { m = JSON.parse(String(ev.data)) } catch { return }
+        if (m.op === 'challenge') {
+          try { socket.send(JSON.stringify({ op: 'prove', signature: await w.account.signMessage({ message: m.message }) })) }
+          catch (e) { clearTimeout(giveUp); log(`prism: cannot sign the open challenge: ${e.message}`); try { socket.close() } catch { } ; resolve(null) }
+          return
+        }
+        if (m.op === 'open_failed') { clearTimeout(giveUp); log(`prism: line refused: ${m.error ?? m.why}`); try { socket.close() } catch { } ; return resolve(null) }
+        if (m.op === 'opened') {
+          clearTimeout(giveUp)
+          s.socket = socket; s.credential = m.credential; read(m.msRemaining, m.metering)
+          log(`prism: line open, ${m.msRemaining}ms on the meter, collateral buys ${m.buysMs ?? '?'}ms`)
+          return resolve(s.credential)
+        }
+        if (m.op === 'meter') { read(m.msRemaining, m.metering); return }
+        if (m.op === 'on' || m.op === 'off') { read(m.msRemaining, m.op === 'on'); return settle(m.op, m) }
+        if (m.op === 'refunded' || m.op === 'refund_failed') return settle('refund', m)
+        if (m.op === 'closing') { log(`prism: line closing: ${m.why}`); return drop(m.why) }
+        if (m.op === 'error') log(`prism: /pay: ${m.error}`)
+      }
+      socket.onopen = () => socket.send(JSON.stringify({ op: 'open', channelId: w.state.channelId }))
+      socket.onclose = () => { clearTimeout(giveUp); drop('socket closed'); resolve(null) }
+      socket.onerror = () => { }
+    }).finally(() => { s.opening = null })
+    return s.opening
+  }
+  const on = async () => { if (s.metering || !s.credential) return; const r = await ask('on', { op: 'on' }); if (!r) s.metering = false }
+  const off = async () => { if (!s.metering || !s.credential) return; await ask('off', { op: 'off' }) }
+  const touch = () => {
+    if (s.offTimer) clearTimeout(s.offTimer); if (s.dropTimer) clearTimeout(s.dropTimer)
+    s.offTimer = setTimeout(() => { off().catch(() => {}) }, idleMs); s.offTimer.unref?.()
+    s.dropTimer = setTimeout(() => drop('idle'), dropAfterMs); s.dropTimer.unref?.()
+  }
+  // One block at a time, in order: a voucher signs a cumulative total.
+  const tickOnce = () => w.oneAtATime(async () => {
+    if (!s.credential) return false
+    const t = await terms()
+    let r
+    if (t) {
+      const payload = await w.payments.createPaymentPayload(t)
+      const headers = { ...w.httpClient.encodePaymentSignatureHeader(payload), [LINE_HEADER]: s.credential, 'content-type': 'application/json' }
+      r = await fetch(new URL('/v1/tick', url), { method: 'POST', headers, body: '{}' })
+      await w.httpClient.processPaymentResult(payload, (n) => r.headers.get(n), r.status).catch(() => {})
+      if (r.status === 402) { s.tickTerms = null; r = null }
+    }
+    if (!r) {
+      r = await w.paidFetch(new URL('/v1/tick', url), { method: 'POST', headers: { [LINE_HEADER]: s.credential, 'content-type': 'application/json' }, body: '{}' })
+    }
+    const j = await r.json().catch(() => null)
+    if (r.status !== 200 || j?.paid === false) { drop(`tick refused: ${j?.error ?? j?.why ?? r.status}`); return false }
+    read(j.msRemaining, s.metering)
+    return true
+  })
+  // Enough for the next call now; the rest in the background.
+  const ensure = async (minMs) => { while (s.credential && remaining() < minMs) { if (!(await tickOnce())) return false } ; return Boolean(s.credential) }
+  const topUp = () => {
+    if (s.topping) return s.topping
+    s.topping = (async () => { while (s.credential && remaining() < aheadMs) { if (!(await tickOnce())) break } })().finally(() => { s.topping = null })
+    return s.topping
+  }
+  const refund = async () => {
+    const channelId = w.state.channelId
+    if (!channelId) return { op: 'refund_failed', why: 'no channel' }
+    const issued = new Date().toISOString()
+    const signature = await w.account.signMessage({ message: `ZEAM Prism refund\nchannel: ${channelId.toLowerCase()}\nissued: ${issued}` })
+    return new Promise((resolve) => {
+      const socket = new WebSocket(ws.toString())
+      const timer = setTimeout(() => { try { socket.close() } catch { } ; resolve({ op: 'refund_failed', why: 'timeout' }) }, 90_000)
+      socket.onmessage = (ev) => {
+        let m; try { m = JSON.parse(String(ev.data)) } catch { return }
+        if (m.op === 'refunded' || m.op === 'refund_failed' || m.error) { clearTimeout(timer); try { socket.close() } catch { } ; resolve(m) }
+      }
+      socket.onopen = () => socket.send(JSON.stringify({ op: 'refund', channelId, issued, signature }))
+      socket.onerror = () => { clearTimeout(timer); resolve({ op: 'refund_failed', why: 'socket error' }) }
+    })
+  }
+  return { s, open, on, off, touch, ensure, topUp, drop, remaining, refund }
+}
+
+export function prism(opts = {}) {
+  const {
+    key = process.env.X402_PRIVATE_KEY, url = process.env.X402_MCP_URL?.replace(/\/mcp\/?$/, '') ?? 'https://mcp.zeamprism.com',
+    chain = 'base', network = process.env.X402_NETWORK ?? 'eip155:8453',
+    stateDir = process.env.X402_STATE_DIR, depositMultiplier = process.env.X402_DEPOSIT_MULTIPLIER,
+    asset = process.env.X402_ASSET, salt = process.env.X402_SALT, rpcUrl = process.env.X402_RPC_URL,
+    aheadMs = 2000, idleMs = 1000, dropAfterMs = 10_000, blockMs = 250,
+    log = (...a) => console.error(...a),
+    ...httpConfig
+  } = opts
+  const w = wallet({ key, url, network, stateDir, depositMultiplier, asset, salt, rpcUrl, log })
+  const l = line({ url, w, aheadMs, idleMs, dropAfterMs, log })
+  const door = new URL(`/rpc/${chain}`, url).toString()
+
+  const withLine = (req) => { const r = new Request(req); r.headers.set(LINE_HEADER, l.s.credential); return r }
+  const codeOf = async (r) => {
+    const j = await r.clone().json().catch(() => null)
+    const d = j?.error?.data ?? j
+    return d?.code ?? d?.error ?? null
+  }
+
+  const fetchFn = async (input, init) => {
+    const req = new Request(input, init)
+    for (let attempt = 0; attempt < 3; attempt++) {
+      if (!l.s.credential && w.state.channelId) await l.open()
+      if (l.s.credential) {
+        await l.on()
+        if (!(await l.ensure(blockMs + 50))) continue
+        l.topUp()
+        const r = await fetch(withLine(req.clone()))
+        l.touch()
+        if (r.status !== 402) return r
+        const code = await codeOf(r)
+        if (code === 'line_unpaid') { l.s.metering = false; l.s.remainingMs = 0; continue }
+        if (LINE_GONE.has(code)) { l.drop(code); continue }
+        return r
+      }
+      // No line yet: this call pays for its block, and funds the channel if
+      // there is none. One payment at a time on a channel.
+      const r = await w.oneAtATime(() => w.paidFetch(req.clone()))
+      if (r.status !== 402) return r
+      const code = await codeOf(r)
+      if (code === 'line_required' && w.state.channelId) { await l.open(); continue }
+      return r
+    }
+    throw new Error('prism: could not hold a line after three attempts')
+  }
+
+  const transport = http(door, { ...httpConfig, fetchFn })
+  transport.close = async () => { await l.off().catch(() => {}); l.drop('closed') }
+  // Stop buying, let the payment in flight settle, then ask. A refund while a
+  // voucher is still being verified is refused as a request still open.
+  transport.refund = async () => {
+    l.drop('refunding')
+    await w.oneAtATime(() => {})
+    let r
+    for (let i = 0; i < 6; i++) {
+      r = await l.refund()
+      if (r.op === 'refunded' || !/still open/.test(String(r.why ?? ''))) return r
+      await new Promise((res) => setTimeout(res, 1000))
+    }
+    return r
+  }
+  transport.state = () => ({ address: w.account.address, channelId: w.state.channelId, line: Boolean(l.s.credential),
+                             metering: l.s.metering, msRemaining: l.remaining() })
+  return transport
+}
+
+export { LINE_HEADER }