@bsvkey/x402-bsv-client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Embryo Space Inc. (DBA BSVKey)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,58 @@
+# @bsvkey/x402-bsv-client
+
+Pay an [x402](https://x402.org) `402 Payment Required` **in BSV**, in one line.
+
+x402 ships payment builders for EVM (EIP-3009) and Solana. This is the missing
+one for the **`bsv-p2pkh`** scheme — so an AI agent can pay a BSV-settled x402
+endpoint (like `inference.bsvkey.com`) with true sub-cent, per-call micropayments.
+
+```bash
+npm i @bsvkey/x402-bsv-client @bsv/sdk
+```
+
+## Use it
+
+```js
+import { fetchWithX402, readSettlement } from '@bsvkey/x402-bsv-client';
+
+const res = await fetchWithX402(
+  'https://inference.bsvkey.com/v1/x402/chat/completions',
+  {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ model: 'grok-4.3', messages: [{ role: 'user', content: 'Say hi in 3 words' }] }),
+  },
+  { wif: process.env.BSV_WIF } // a funded BSV private key (WIF)
+);
+
+const data = await res.json();
+console.log(data.choices[0].message.content);        // the answer
+console.log(readSettlement(res));                     // { success, transaction (on-chain txid), network, ... }
+```
+
+That's the whole x402 handshake, handled for you:
+
+1. `POST` the request → server replies **402** with the quoted price.
+2. This lib builds + signs a BSV tx paying the quoted amount to the server's `payTo`.
+3. Retries with the `X-PAYMENT` header → server settles on-chain and returns **200** + the answer.
+
+## Lower level
+
+```js
+import { buildX402Payment } from '@bsvkey/x402-bsv-client';
+
+// Given an x402 402 response body, produce the base64 X-PAYMENT header value:
+const xPayment = await buildX402Payment(body402, wif);
+```
+
+## Notes
+
+- **Funding:** the WIF's address must hold enough BSV to cover the quoted amount + a
+  small fee. Fund it like any BSV address (the `payTo`/QR flow on inference.bsvkey.com works).
+- **Back-to-back calls are safe:** the client chains each payment off its own change,
+  so a loop of paid calls won't double-spend while the mempool catches up.
+- **Non-custodial:** your key never leaves the process; the signed transaction pays the
+  server's address directly.
+- **Networks:** `bsv` (mainnet) and `bsv-testnet`. Testnet lets you dry-run for free.
+
+MIT.

package/example.js

@@ -0,0 +1,37 @@
+// Runnable example: pay for one inference in BSV via x402.
+//   BSV_WIF=<funded WIF> node example.js "your prompt here"
+//
+// Needs @bsv/sdk installed and a funded mainnet key. Without BSV_WIF it stops at
+// the 402 and just prints the quote (safe, no payment).
+
+import { fetchWithX402, buildX402Payment, readSettlement } from './index.js';
+
+const URL = process.env.X402_URL || 'https://inference.bsvkey.com/v1/x402/chat/completions';
+const prompt = process.argv[2] || 'In one sentence, why do AI agents want per-token billing?';
+const wif = process.env.BSV_WIF;
+
+const init = {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ model: process.env.X402_MODEL || 'grok-4.3', messages: [{ role: 'user', content: prompt }], max_tokens: 256 }),
+};
+
+if (!wif) {
+  // No key: just fetch the 402 quote so you can see the price without paying.
+  const r = await fetch(URL, init);
+  const body = await r.json();
+  const req = (body.accepts || [])[0];
+  console.log(`Quote: ${req?.maxAmountRequired} sat to ${req?.payTo} on ${req?.network} (model ${req?.extra?.model}).`);
+  console.log('Set BSV_WIF=<funded key> to actually pay and get the answer.');
+} else {
+  console.log('Paying and running…');
+  const res = await fetchWithX402(URL, init, { wif });
+  if (!res.ok) {
+    console.error('failed:', res.status, await res.text());
+  } else {
+    const data = await res.json();
+    console.log('\nAnswer:\n' + (data.choices?.[0]?.message?.content || '(none)'));
+    console.log('\nSettlement:', readSettlement(res));
+    console.log('Paid:', data.x_bsv?.paidSats, 'sat →', data.x_bsv?.payTo);
+  }
+}

package/index.js

@@ -0,0 +1,122 @@
+// @bsvkey/x402-bsv-client — pay an x402 "402 Payment Required" in BSV.
+//
+// x402 ships EVM (EIP-3009) and Solana payment builders; this is the missing BSV
+// one for the `bsv-p2pkh` scheme. It turns an agent's paid API call into one line:
+//
+//   import { fetchWithX402 } from '@bsvkey/x402-bsv-client';
+//   const res = await fetchWithX402('https://inference.bsvkey.com/v1/x402/chat/completions',
+//     { method:'POST', headers:{'content-type':'application/json'},
+//       body: JSON.stringify({ model:'grok-4.3', messages:[{role:'user',content:'hi'}] }) },
+//     { wif: process.env.BSV_WIF });
+//   const answer = (await res.json()).choices[0].message.content;
+//
+// It does the whole handshake: request -> 402 -> build+sign a BSV payment paying the
+// quoted amount to payTo -> retry with the X-PAYMENT header -> return the 200 response
+// (whose X-PAYMENT-RESPONSE header carries the on-chain settlement txid).
+//
+// Peer dependency: @bsv/sdk (v1). Node 18+ (global fetch).
+
+import { PrivateKey, P2PKH, Transaction, Utils } from '@bsv/sdk';
+
+const NET = { bsv: 'main', 'bsv-testnet': 'test', 'bsv-dev': 'main' };
+const PREFIX = { main: [0x00], test: [0x6f] };
+
+// --- session UTXO tracker: chain each payment off our own change so back-to-back
+// paid calls don't double-spend while WhatsOnChain's unspent list catches up. ---
+const _sessions = new Map(); // addr -> { spent:Set, change:[{tx,vout,satoshis}] }
+function session(addr) {
+  let s = _sessions.get(addr);
+  if (!s) { s = { spent: new Set(), change: [] }; _sessions.set(addr, s); }
+  return s;
+}
+
+function pickRequirement(body) {
+  const accepts = (body && body.accepts) || [];
+  return accepts.find((a) => a.scheme === 'bsv-p2pkh') || accepts[0] || null;
+}
+
+// Build the base64 X-PAYMENT header value for a given x402 402 body, paying in BSV.
+export async function buildX402Payment(body402, wif, { wocBase } = {}) {
+  const req = pickRequirement(body402);
+  if (!req) throw new Error('no bsv-p2pkh payment requirement in the 402 response');
+  const amount = Number(req.maxAmountRequired || req.amount || 0);
+  if (!(amount > 0)) throw new Error('invalid amount in payment requirement');
+  const net = NET[req.network] || 'main';
+  const prefix = PREFIX[net];
+  const base = (wocBase || 'https://api.whatsonchain.com/v1/bsv') + '/' + net;
+
+  const priv = PrivateKey.fromWif(wif);
+  const pub = priv.toPublicKey();
+  const addr = pub.toAddress(prefix);
+  const sess = session(addr);
+
+  const tx = new Transaction();
+  tx.addOutput({ lockingScript: new P2PKH().lock(Utils.fromBase58Check(req.payTo).data), satoshis: amount });
+
+  const target = amount + 500; // amount + fee headroom
+  let got = 0;
+  const usedChange = [];
+
+  // spend our own unconfirmed change first
+  for (const c of sess.change) {
+    tx.addInput({ sourceTransaction: c.tx, sourceOutputIndex: c.vout, unlockingScriptTemplate: new P2PKH().unlock(priv) });
+    got += c.satoshis; usedChange.push(c);
+    if (got >= target) break;
+  }
+  // then confirmed UTXOs, skipping anything already spent this session
+  if (got < target) {
+    const unspent = await (await fetch(`${base}/address/${addr}/unspent`)).json();
+    if ((!unspent || !unspent.length) && !usedChange.length) throw new Error('wallet is unfunded: ' + addr);
+    for (const u of (unspent || []).sort((a, b) => b.value - a.value)) {
+      if (sess.spent.has(u.tx_hash + ':' + u.tx_pos)) continue;
+      let src;
+      try { const beef = await (await fetch(`${base}/tx/${u.tx_hash}/beef`)).text(); src = Transaction.fromBEEF(Utils.toArray(beef.trim(), 'hex')); }
+      catch { const hex = await (await fetch(`${base}/tx/${u.tx_hash}/hex`)).text(); src = Transaction.fromHex(hex.trim()); }
+      tx.addInput({ sourceTransaction: src, sourceOutputIndex: u.tx_pos, unlockingScriptTemplate: new P2PKH().unlock(priv) });
+      got += u.value; if (got >= target) break;
+    }
+  }
+  if (got < target) throw new Error(`wallet balance too low: have ${got}, need ${target} (${addr})`);
+
+  const changeIndex = tx.outputs.length;
+  tx.addOutput({ lockingScript: new P2PKH().lock(pub.toHash()), change: true });
+  await tx.fee();
+  await tx.sign();
+
+  // commit tracker (the payment is about to be submitted by the resource server)
+  for (const inp of tx.inputs) sess.spent.add((inp.sourceTransaction ? inp.sourceTransaction.id('hex') : inp.sourceTXID) + ':' + inp.sourceOutputIndex);
+  sess.change = sess.change.filter((c) => !usedChange.includes(c));
+  const chg = tx.outputs[changeIndex];
+  if (chg && chg.satoshis > 0) sess.change.push({ tx, vout: changeIndex, satoshis: chg.satoshis });
+
+  const envelope = {
+    x402Version: body402.x402Version || 1,
+    scheme: 'bsv-p2pkh',
+    network: req.network,
+    payload: { transaction: Utils.toHex(tx.toBEEF()), payer: addr },
+  };
+  return Buffer.from(JSON.stringify(envelope)).toString('base64');
+}
+
+// One-call paid fetch: run the request, auto-pay a 402 in BSV, return the final Response.
+// `paymentBuilder` is injectable for testing; defaults to buildX402Payment.
+export async function fetchWithX402(url, init = {}, { wif, wocBase, paymentBuilder } = {}) {
+  const first = await fetch(url, init);
+  if (first.status !== 402) return first;
+  if (!wif) throw new Error('402 received but no `wif` provided to pay it');
+
+  const body402 = await first.clone().json().catch(() => null);
+  if (!body402) throw new Error('402 response was not JSON x402');
+  const build = paymentBuilder || buildX402Payment;
+  const xpayment = await build(body402, wif, { wocBase });
+
+  const headers = Object.assign({}, init.headers || {}, { 'X-PAYMENT': xpayment });
+  return fetch(url, Object.assign({}, init, { headers }));
+}
+
+// Decode the settlement result from a paid 200 response (the on-chain txid, etc.).
+export function readSettlement(res) {
+  const h = res.headers.get('x-payment-response');
+  if (!h) return null;
+  try { return JSON.parse(Buffer.from(h, 'base64').toString('utf8')); } catch { return null; }
+}

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@bsvkey/x402-bsv-client",
+  "version": "0.1.0",
+  "description": "Pay an x402 HTTP 402 in BSV — the missing bsv-p2pkh payment builder for x402 agents.",
+  "type": "module",
+  "main": "index.js",
+  "exports": { ".": "./index.js" },
+  "files": ["index.js", "example.js", "README.md", "LICENSE"],
+  "author": "Embryo Space Inc. (DBA BSVKey)",
+  "homepage": "https://inference.bsvkey.com/v1/x402",
+  "engines": { "node": ">=18" },
+  "peerDependencies": { "@bsv/sdk": "^1" },
+  "keywords": ["x402", "bsv", "micropayments", "ai-agents", "402", "payments", "http-402"],
+  "license": "MIT",
+  "repository": { "type": "git", "url": "https://github.com/BSVKey/x402-bsv-client" }
+}