@agentkv/client 0.1.0

package/dist/index.cjs

@@ -0,0 +1,1263 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ACCOUNT_READ_USD: () => ACCOUNT_READ_USD,
+  ACCOUNT_WRITE_USD: () => ACCOUNT_WRITE_USD,
+  AgentKV: () => AgentKV,
+  AgentKVError: () => import_core2.AgentKVError,
+  CREDIT_VALUE_USD: () => CREDIT_VALUE_USD,
+  DEFAULT_MAX_OP_USD: () => DEFAULT_MAX_OP_USD,
+  SpendCapError: () => import_core2.SpendCapError,
+  VERSION: () => VERSION,
+  decrypt: () => decrypt,
+  deriveKeyMaterial: () => deriveKeyMaterial,
+  encrypt: () => encrypt,
+  generateAccountKey: () => generateAccountKey,
+  hashKey: () => hashKey,
+  isAccountKeyFormat: () => isAccountKeyFormat
+});
+module.exports = __toCommonJS(index_exports);
+var import_core3 = require("@agentx402-ai/core");
+var import_viem3 = require("viem");
+var import_accounts = require("viem/accounts");
+
+// src/account.ts
+var import_viem = require("viem");
+var AK_PREFIX = "ak_";
+var AK_RANDOM_BYTES = 32;
+var AK_FORMAT_RE = /^ak_[0-9a-f]{64}$/;
+function generateAccountKey() {
+  const bytes = crypto.getRandomValues(new Uint8Array(AK_RANDOM_BYTES));
+  return AK_PREFIX + (0, import_viem.bytesToHex)(bytes).slice(2);
+}
+function isAccountKeyFormat(s) {
+  return typeof s === "string" && AK_FORMAT_RE.test(s);
+}
+
+// src/crypto.ts
+var import_hkdf = require("@noble/hashes/hkdf");
+var import_hmac = require("@noble/hashes/hmac");
+var import_sha2 = require("@noble/hashes/sha2");
+var import_viem2 = require("viem");
+var KEY_LENGTH = 32;
+var IV_LENGTH = 12;
+var TAG_LENGTH = 16;
+var utf8 = (s) => new TextEncoder().encode(s);
+var MAGIC0 = 97;
+var MAGIC1 = 107;
+var ENVELOPE_VER = 1;
+var SUITE_AES256GCM = 1;
+var KDF_V1 = 1;
+var DIGEST_SCHEME_V1 = 1;
+var HEADER = Uint8Array.of(MAGIC0, MAGIC1, ENVELOPE_VER, SUITE_AES256GCM, KDF_V1);
+var HEADER_LEN = HEADER.length;
+function normalizeEncryptionKey(key) {
+  const bytes = typeof key === "string" ? (0, import_viem2.hexToBytes)(key) : key;
+  if (bytes.length !== KEY_LENGTH) {
+    throw new Error(`encryption key must be 32 bytes, got ${bytes.length}`);
+  }
+  return bytes;
+}
+function deriveKeyMaterial(ikm) {
+  return {
+    value: (0, import_hkdf.hkdf)(import_sha2.sha256, ikm, utf8("agentkv/v1/enc"), utf8("value"), KEY_LENGTH),
+    keyName: (0, import_hkdf.hkdf)(import_sha2.sha256, ikm, utf8("agentkv/v1/enc"), utf8("keyname"), KEY_LENGTH),
+    mac: (0, import_hkdf.hkdf)(import_sha2.sha256, ikm, utf8("agentkv/v1/mac"), utf8("lookup"), KEY_LENGTH)
+  };
+}
+function hashKey(macKey, name) {
+  const mac = (0, import_hmac.hmac)(import_sha2.sha256, macKey, utf8(name.normalize("NFC")));
+  const tagged = new Uint8Array(1 + mac.length);
+  tagged[0] = DIGEST_SCHEME_V1;
+  tagged.set(mac, 1);
+  return toBase64Url(tagged);
+}
+function toBase64(bytes) {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+  return btoa(binary);
+}
+function toBase64Url(bytes) {
+  return toBase64(bytes).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromBase64(b64) {
+  const binary = atob(b64);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+  return out;
+}
+function aadBytes(aad) {
+  if (!aad) return HEADER;
+  const extra = utf8(aad);
+  const out = new Uint8Array(HEADER_LEN + extra.length);
+  out.set(HEADER, 0);
+  out.set(extra, HEADER_LEN);
+  return out;
+}
+async function importAesKey(key) {
+  return crypto.subtle.importKey(
+    "raw",
+    key.buffer.slice(key.byteOffset, key.byteOffset + key.byteLength),
+    { name: "AES-GCM" },
+    false,
+    ["encrypt", "decrypt"]
+  );
+}
+async function gcmDecrypt(key, iv, ct, aad) {
+  const cryptoKey = await importAesKey(key);
+  const plaintext = await crypto.subtle.decrypt(
+    { name: "AES-GCM", iv, additionalData: aad },
+    cryptoKey,
+    ct
+  );
+  return new TextDecoder().decode(plaintext);
+}
+async function encrypt(key, plaintext, aad) {
+  const cryptoKey = await importAesKey(key);
+  const iv = crypto.getRandomValues(new Uint8Array(IV_LENGTH));
+  const data = utf8(plaintext);
+  const ct = new Uint8Array(
+    await crypto.subtle.encrypt(
+      { name: "AES-GCM", iv, additionalData: aadBytes(aad) },
+      cryptoKey,
+      data
+    )
+  );
+  const packed = new Uint8Array(HEADER_LEN + iv.length + ct.length);
+  packed.set(HEADER, 0);
+  packed.set(iv, HEADER_LEN);
+  packed.set(ct, HEADER_LEN + iv.length);
+  return toBase64(packed);
+}
+async function decrypt(key, packed, aad) {
+  const bytes = fromBase64(packed);
+  const known = bytes.length >= HEADER_LEN + IV_LENGTH + TAG_LENGTH && bytes[0] === MAGIC0 && bytes[1] === MAGIC1 && bytes[2] === ENVELOPE_VER && bytes[3] === SUITE_AES256GCM && bytes[4] === KDF_V1;
+  if (!known) {
+    throw new Error(
+      `decryption failed: not a recognized AgentKV envelope (ver=${bytes[2]}, suite=${bytes[3]}, kdf=${bytes[4]}) \u2014 upgrade @agentkv/client, or the encryption key is wrong / the blob is corrupted`
+    );
+  }
+  try {
+    return await gcmDecrypt(
+      key,
+      bytes.slice(HEADER_LEN, HEADER_LEN + IV_LENGTH),
+      bytes.slice(HEADER_LEN + IV_LENGTH),
+      aadBytes(aad)
+    );
+  } catch {
+    throw new Error(
+      "decryption failed: wrong encryption key, corrupted blob, or a value served for a different key"
+    );
+  }
+}
+
+// src/payment.ts
+var import_core = require("@agentx402-ai/core");
+
+// src/types.ts
+var import_core2 = require("@agentx402-ai/core");
+var DEFAULT_NETWORK = "eip155:8453";
+
+// src/index.ts
+var VERSION = "0.1.0";
+var V1 = "/v1";
+var ENC_DERIVATION_DOMAIN = { name: "AgentKV Encryption", version: "1" };
+var ENC_DERIVATION_TYPES = {
+  Derive: [
+    { name: "purpose", type: "string" },
+    { name: "version", type: "string" }
+  ]
+};
+var ENC_DERIVATION_MESSAGE = { purpose: "encryption-key", version: "v1" };
+var CREDIT_VALUE_USD = 1e-4;
+var ACCOUNT_READ_USD = 3e-4;
+var ACCOUNT_WRITE_USD = 5e-4;
+var DEFAULT_MAX_OP_USD = 0.05;
+function toWholeAtomicUsd(amountUsd) {
+  if (!Number.isFinite(amountUsd)) return null;
+  const atomic = Math.round(amountUsd * 1e6);
+  if (!Number.isInteger(atomic) || atomic <= 0) return null;
+  if (Math.abs(amountUsd * 1e6 - atomic) > atomic * 1e-9) return null;
+  return atomic;
+}
+var AgentKV = class {
+  /**
+   * The signing wallet. `undefined` in account-key mode (a managed account has no
+   * wallet that can sign) — the `ak_…` bearer token is the identity instead.
+   */
+  signer;
+  /**
+   * The wallet address, the per-wallet namespace. In account-key mode there is no
+   * wallet, so this is the zero address (a documented sentinel: the account key —
+   * not an address — is the identity; the server names storage by the key's hash).
+   */
+  /** The wallet address (its namespace) in wallet/signer mode; `undefined` in account-key mode. */
+  address;
+  /** The raw `ak_…` bearer token in account-key mode; `undefined` otherwise. */
+  accountKey;
+  endpoint;
+  network;
+  maxSpendUsd;
+  maxSessionSpendUsd;
+  /** Bounded internal retries on transient failures (network error / 5xx). */
+  maxRetries;
+  timeoutMs;
+  fetchImpl;
+  _ikm;
+  _km;
+  _kmPromise;
+  sessionSpentUsd = 0;
+  // --- Discounted Prepay state (opt-in; undefined => Pay-as-you-go, unchanged) ---
+  prepay;
+  /** Top-off amount in atomic USDC units (1e6), computed once in the constructor. */
+  topoffAtomic = 0;
+  /** Account-key top-off hook (account-key mode only; validated in the constructor). */
+  topoffPayer;
+  /**
+   * Account-key inline x402 transport hook (account-key mode only; validated in
+   * the constructor). Mutually exclusive with `topoffPayer` PER OP — `topoffPayer`
+   * always takes precedence when both are configured (see the call sites in
+   * set()/get(), which gate on `!this.topoffPayer`).
+   */
+  opInlinePayer;
+  /** Last-known credit balance as an EXACT integer credit count (never USD floats). */
+  knownCredits;
+  /** Synchronous single-flight guard: at most one in-flight top-off at a time. */
+  topoffInFlight = false;
+  /**
+   * The in-flight SYNCHRONOUS top-off deposit (account mode), published so a concurrent op
+   * that hits a hard 402 but can't claim the single-flight can await it and retry.
+   */
+  topoffPromise;
+  /** Cached last `PAYMENT-REQUIRED` header — the template for a proactive single-shot. */
+  challengeTemplate;
+  constructor(opts) {
+    this.endpoint = opts.endpoint.replace(/\/+$/, "");
+    this.network = opts.network ?? DEFAULT_NETWORK;
+    this.maxSpendUsd = opts.maxSpendUsd;
+    this.maxSessionSpendUsd = opts.maxSessionSpendUsd;
+    this.maxRetries = Math.max(0, Math.floor(opts.retries ?? 2));
+    this.timeoutMs = opts.timeoutMs;
+    this.fetchImpl = opts.fetch;
+    const isAccountMode = "accountKey" in opts && opts.accountKey != null;
+    if (opts.topoffPayer !== void 0) {
+      if (typeof opts.topoffPayer !== "function") {
+        throw new import_core2.AgentKVError("topoffPayer must be a function", "invalid_config", 0);
+      }
+      if (!isAccountMode) {
+        throw new import_core2.AgentKVError(
+          "topoffPayer is account-key-mode only; wallet mode pays its own top-offs",
+          "invalid_config",
+          0
+        );
+      }
+      if (!opts.prepay) {
+        throw new import_core2.AgentKVError(
+          "topoffPayer requires prepay ({ watermark, topoff }) to control when it fires",
+          "invalid_config",
+          0
+        );
+      }
+      this.topoffPayer = opts.topoffPayer;
+    }
+    if (opts.opInlinePayer !== void 0) {
+      if (typeof opts.opInlinePayer !== "function") {
+        throw new import_core2.AgentKVError("opInlinePayer must be a function", "invalid_config", 0);
+      }
+      if (!isAccountMode) {
+        throw new import_core2.AgentKVError(
+          "opInlinePayer is account-key-mode only; wallet mode pays its own x402 challenges",
+          "invalid_config",
+          0
+        );
+      }
+      this.opInlinePayer = opts.opInlinePayer;
+    }
+    if (opts.prepay) {
+      if (isAccountMode && !opts.topoffPayer) {
+        throw new import_core2.AgentKVError(
+          "prepay in account-key mode requires a topoffPayer hook (or fund via fundAccount() / 'agentkv fund')",
+          "invalid_config",
+          0
+        );
+      }
+      const topoffAtomic = toWholeAtomicUsd(opts.prepay.topoff);
+      if (topoffAtomic === null || !(opts.prepay.topoff >= 1)) {
+        throw new import_core2.AgentKVError(
+          "prepay.topoff must be >= $1 (a whole number of atomic USDC units)",
+          "invalid_config",
+          0
+        );
+      }
+      if (!(opts.prepay.watermark >= 0)) {
+        throw new import_core2.AgentKVError("prepay.watermark must be >= 0", "invalid_config", 0);
+      }
+      this.prepay = opts.prepay;
+      this.topoffAtomic = topoffAtomic;
+    }
+    if (isAccountMode) {
+      if (!isAccountKeyFormat(opts.accountKey)) {
+        throw new import_core2.AgentKVError(
+          "accountKey must be a string of the form ak_<64 lowercase hex>",
+          "invalid_config",
+          0
+        );
+      }
+      if (!opts.encryptionKey) {
+        throw new import_core2.AgentKVError(
+          "account-key mode requires an explicit encryptionKey (there is no wallet to derive one from)",
+          "invalid_config",
+          0
+        );
+      }
+      this.accountKey = opts.accountKey;
+      this.signer = void 0;
+      this.address = void 0;
+      this._ikm = normalizeEncryptionKey(opts.encryptionKey);
+    } else if ("privateKey" in opts && opts.privateKey != null) {
+      if ("encryptionKey" in opts && opts.encryptionKey) {
+        throw new import_core2.AgentKVError(
+          "privateKey mode derives its encryption key from the wallet key; do not also pass encryptionKey \u2014 use { signer, encryptionKey } for an explicit AES key",
+          "invalid_config",
+          0
+        );
+      }
+      this.signer = (0, import_accounts.privateKeyToAccount)(opts.privateKey);
+      this._ikm = (0, import_viem3.hexToBytes)(opts.privateKey);
+      this.address = this.signer.address;
+    } else if ("signer" in opts && opts.signer != null) {
+      this.signer = opts.signer;
+      if ("encryptionKey" in opts && opts.encryptionKey) {
+        this._ikm = normalizeEncryptionKey(opts.encryptionKey);
+      }
+      this.address = this.signer.address;
+    } else {
+      throw new import_core2.AgentKVError(
+        "invalid auth config: provide one of { privateKey } | { signer } | { accountKey, encryptionKey }",
+        "invalid_config",
+        0
+      );
+    }
+  }
+  /**
+   * Resolve (and memoize) the AES key. Async only for the sign-to-derive shape
+   * (`{signer}` with no encryptionKey): the key is `HKDF` over a fixed-message
+   * signature, which is stable ONLY for deterministic ECDSA signers (local keys /
+   * RFC-6979). Non-deterministic signers (some MPC/threshold backends) would
+   * derive a different key each run and fail to decrypt — those must pass an
+   * explicit `encryptionKey`.
+   */
+  getKeyMaterial() {
+    if (this._km) return Promise.resolve(this._km);
+    if (!this._kmPromise) {
+      this._kmPromise = (async () => {
+        let ikm = this._ikm;
+        if (!ikm) {
+          if (!this.signer) {
+            throw new import_core2.AgentKVError(
+              "no encryption key material: account-key mode requires an explicit encryptionKey",
+              "invalid_config",
+              0
+            );
+          }
+          const sig = await this.signer.signTypedData({
+            domain: ENC_DERIVATION_DOMAIN,
+            types: ENC_DERIVATION_TYPES,
+            primaryType: "Derive",
+            message: ENC_DERIVATION_MESSAGE
+          });
+          const sigBytes = (0, import_viem3.hexToBytes)(sig);
+          if (sigBytes.length !== 65) {
+            throw new import_core2.AgentKVError(
+              `sign-to-derive expected a 65-byte EIP-712 signature but got ${sigBytes.length} bytes; this signer's format is unstable for key derivation \u2014 construct with an explicit encryptionKey`,
+              "invalid_config",
+              0
+            );
+          }
+          ikm = sigBytes;
+        }
+        const km = deriveKeyMaterial(ikm);
+        this._km = km;
+        return km;
+      })().catch((err) => {
+        this._kmPromise = void 0;
+        throw err;
+      });
+    }
+    return this._kmPromise;
+  }
+  /**
+   * Decrypt a value envelope with the current value key, binding the key's blind-index
+   * digest into the AAD so a value the server serves for the wrong key fails the auth tag.
+   */
+  async decryptValue(packed, key) {
+    const km = await this.getKeyMaterial();
+    return decrypt(km.value, packed, hashKey(km.mac, key));
+  }
+  assertSpend(usd, opts = {}) {
+    if (!opts.bypassPerOpCap && this.maxSpendUsd !== void 0 && usd > this.maxSpendUsd) {
+      throw new import_core2.SpendCapError(`spend $${usd} exceeds per-call cap $${this.maxSpendUsd}`);
+    }
+    if (this.maxSessionSpendUsd !== void 0 && this.sessionSpentUsd + usd > this.maxSessionSpendUsd) {
+      throw new import_core2.SpendCapError(
+        `spend $${usd} would exceed session cap $${this.maxSessionSpendUsd} (spent $${this.sessionSpentUsd})`
+      );
+    }
+  }
+  recordSpend(usd) {
+    this.sessionSpentUsd += usd;
+  }
+  /**
+   * Reject a SERVER-QUOTED per-op price above a sane ceiling in the DEFAULT (cap-less) config.
+   * When `maxSpendUsd` is set, `assertSpend` already bounds the op price; when it is NOT set,
+   * a compromised or spoofed worker could otherwise answer a routine $0.005 read with a 402
+   * challenge for the wallet's whole balance and the client would sign the EIP-3009
+   * authorization. Callers who genuinely need a pricier op opt in via `maxSpendUsd`.
+   */
+  assertOpPriceCeiling(usd) {
+    if (this.maxSpendUsd === void 0 && usd > DEFAULT_MAX_OP_USD) {
+      throw new import_core2.SpendCapError(
+        `server-quoted op price $${usd} exceeds the built-in $${DEFAULT_MAX_OP_USD} op ceiling; set maxSpendUsd to allow a higher per-op charge`
+      );
+    }
+  }
+  /**
+   * The effective per-op ceiling (USD) for an inline-payer op: the caller's `maxSpendUsd`
+   * when set (they opted into that bound), else the built-in default ceiling. Handed to the
+   * hook as its hard `maxAmountAtomic`, and pre-reserved against the session cap before paying.
+   */
+  inlineOpCeilingUsd() {
+    return this.maxSpendUsd ?? DEFAULT_MAX_OP_USD;
+  }
+  /**
+   * The on-chain settlement txHash from a response's PAYMENT-RESPONSE header, or ""
+   * when the server served the op from existing credits (so the attached top-off
+   * authorization was NEVER settled — it just expires) or the header is absent. The
+   * worker emits PAYMENT-RESPONSE = base64(JSON `{ success, payer, amount, txHash }`)
+   * on any paid 200, with `txHash: ""` on the credit hot path. A proactive single-shot
+   * top-off must only count toward session spend when this is non-empty — otherwise no
+   * USDC moved and recording it inflates sessionSpentUsd, prematurely tripping the cap.
+   *
+   * Accepted trade-off: in a doubly-rare crash window (the server's settle mined on-chain
+   * but its ledger row was lost, AND the response was lost so the client retries), the
+   * worker's already-used-authorization recovery returns success with txHash "" even
+   * though USDC did move. The client then under-counts that top-off by one, making the
+   * local session cap marginally lenient — no funds are lost (the amount is still minted
+   * as credits). This is unavoidable (the worker cannot distinguish that case from a
+   * plain credit-served op) and far cheaper than the systematic L3 over-count it replaces.
+   */
+  settledTxHash(res) {
+    const header = res.headers.get("PAYMENT-RESPONSE");
+    if (!header) return "";
+    try {
+      const parsed = JSON.parse((0, import_core.decodeBase64Utf8)(header));
+      return typeof parsed.txHash === "string" ? parsed.txHash : "";
+    } catch {
+      return "";
+    }
+  }
+  /**
+   * Issue a request with bounded internal retry on TRANSIENT failures only: a
+   * thrown fetch (network error / lost response) or a 5xx. `build()` is re-invoked
+   * per attempt so the credit path can re-sign identity with a FRESH nonce each
+   * time, while the op's stable Idempotency-Key (and pinned EIP-3009 nonce on paid
+   * ops) makes a retry of an already-processed request dedupe server-side — so a
+   * lost response that the server already charged is recovered without a second
+   * charge. NOT retried: any 2xx/4xx (incl. the 402 credit->pay handoff, 401, 404)
+   * — those are returned as-is for the caller's normal handling. The bound is kept
+   * small so a re-sent paid authorization cannot outlive its validBefore.
+   *
+   * The retry MECHANICS (transient-status detection, backoff,
+   * Retry-After honoring) were extracted to `@agentx402-ai/core`'s `fetchWithRetry`
+   * as a pure function parameterized by `maxRetries` — this method is now a
+   * thin delegating wrapper so every existing `this.fetchWithRetry(...)` call
+   * site above is unchanged.
+   */
+  fetchWithRetry(url, build) {
+    return (0, import_core3.fetchWithRetry)(url, build, this.maxRetries, {
+      timeoutMs: this.timeoutMs,
+      fetchImpl: this.fetchImpl
+    });
+  }
+  // --- Discounted Prepay helpers -------------------------------------------
+  /**
+   * Update prepay tracking from any server response. Reads the exact integer
+   * credit balance (`X-AgentKV-Credits-Remaining`) and caches the most recent
+   * `PAYMENT-REQUIRED` challenge as the proactive single-shot template (so a
+   * top-off needs no preflight request). Safe to call when prepay is disabled.
+   */
+  trackBalance(res) {
+    const credits = res.headers.get("X-AgentKV-Credits-Remaining");
+    if (credits !== null && credits !== "") {
+      const n = Number(credits);
+      if (Number.isFinite(n)) this.knownCredits = n;
+    }
+    const challenge = res.headers.get("PAYMENT-REQUIRED");
+    if (challenge) this.challengeTemplate = challenge;
+  }
+  /** Watermark (USD) expressed in EXACT integer credits (1 credit = CREDIT_VALUE_USD = $0.0001,
+   *  so $1 = 10,000 credits — matching the worker's mint rate). */
+  watermarkCredits() {
+    return Math.round(this.prepay.watermark / CREDIT_VALUE_USD);
+  }
+  /**
+   * Synchronous single-flight claim for a proactive top-off. CRITICAL: there is
+   * NO `await` between the watermark check and setting `topoffInFlight = true`,
+   * and this must be called at the very top of set/get before any await.
+   * Otherwise two concurrent ops both pass the check and each fire a separate
+   * top-off with distinct fresh nonces the server can't dedupe (double charge).
+   * Returns true for exactly one concurrent op below the watermark; the caller
+   * MUST clear `topoffInFlight` in a `finally`. Losers take the identity path.
+   */
+  tryClaimTopoff() {
+    if (!this.prepay || this.prepay.async || this.topoffInFlight || this.knownCredits === void 0 || this.knownCredits >= this.watermarkCredits()) {
+      return false;
+    }
+    this.topoffInFlight = true;
+    return true;
+  }
+  /**
+   * Single-flight claim at a hard 402 (insufficient credits). Unlike
+   * `tryClaimTopoff` this ignores the watermark — a 402 already proves credits
+   * are short — but still claims the flag synchronously so concurrent 402s don't
+   * each fire a top-off. Returns true only if the flag was free; the caller MUST
+   * clear it in a `finally`. In `async` mode we leave the 402 to be paid at the
+   * op price (the background deposit replenishes credits separately).
+   */
+  tryClaimTopoffOnFault() {
+    if (!this.prepay || this.prepay.async || this.topoffInFlight) return false;
+    this.topoffInFlight = true;
+    return true;
+  }
+  /**
+   * Run a synchronous account-mode top-off while PUBLISHING its in-flight promise, so a
+   * concurrent op that hits a hard 402 (and can't claim the single-flight) can await THIS
+   * deposit and retry rather than surfacing the 402. The caller holds the single-flight claim.
+   */
+  async runSharedTopoff() {
+    const p = this.runAccountTopoff();
+    this.topoffPromise = p;
+    try {
+      await p;
+    } finally {
+      if (this.topoffPromise === p) this.topoffPromise = void 0;
+    }
+  }
+  /**
+   * Detached async top-off (opt-in via `prepay.async`). When below the watermark
+   * and no top-off is in flight, fire a deposit WITHOUT awaiting it in the op
+   * path. Documented races: the balance read is point-in-time so the trigger can
+   * be stale, and a deposit settling between an op's read and this check can make
+   * the top-off redundant; the single-flight flag bounds these to at most one
+   * outstanding deposit, but cannot serialize against an op already past its own
+   * check. Use the (default) synchronous single-shot for exactly-bounded spend.
+   *
+   * Account-key mode: there is no signing wallet, so the detached
+   * deposit is dispatched through `runAccountTopoff()` (the `topoffPayer` hook)
+   * instead of `runDeposit` (which throws `no_signer` in account mode). Wallet
+   * mode is completely unchanged below.
+   */
+  maybeAsyncTopoff() {
+    if (!this.prepay?.async || this.topoffInFlight || this.knownCredits === void 0 || this.knownCredits >= this.watermarkCredits()) {
+      return;
+    }
+    if (this.maxSessionSpendUsd !== void 0 && this.sessionSpentUsd + this.prepay.topoff > this.maxSessionSpendUsd) {
+      return;
+    }
+    this.topoffInFlight = true;
+    if (this.accountKey) {
+      void this.runAccountTopoff().catch(() => {
+      }).finally(() => {
+        this.topoffInFlight = false;
+      });
+      return;
+    }
+    void this.runDeposit(this.prepay.topoff, { bypassPerOpCap: true }).catch(() => {
+    }).finally(() => {
+      this.topoffInFlight = false;
+    });
+  }
+  /**
+   * Whether a top-off of `prepay.topoff` fits under the cumulative SESSION cap.
+   * Top-offs are deliberately NOT gated on the per-op `maxSpendUsd` (which bounds
+   * individual pay-per-op charges); when over the session cap we downgrade to
+   * pay-per-op rather than throwing.
+   */
+  topoffFitsSessionCap() {
+    if (this.maxSessionSpendUsd === void 0) return true;
+    return this.sessionSpentUsd + this.prepay.topoff <= this.maxSessionSpendUsd;
+  }
+  /**
+   * Single source of truth for BOTH the EIP-712-signed pathname (`path`) and the
+   * URL to fetch (`url`), so they can never diverge — a divergence silently
+   * breaks identity auth: the worker verifies over the RECEIVED path and
+   * recovers a phantom address if it differs from what the client signed.
+   * `base` is the un-prefixed pathname; the fetched/signed path is `/v1` + `base`
+   * (list-keys overrides it to `/v1/kv`). `query` is appended to `url`
+   * ONLY — EIP-712 binds the pathname, never the query string.
+   */
+  route(spec) {
+    const path = spec.versioned ?? `${V1}${spec.base}`;
+    const q = spec.query ? `?${spec.query}` : "";
+    return { path, url: `${this.endpoint}${path}${q}` };
+  }
+  // kv entry route (set/get/delete). `digest` is base64url (from hashKey(), which
+  // returns toBase64Url output — URL-safe [A-Za-z0-9_-], not hex), so no extra
+  // encoding is needed and the signed path matches the fetched path byte-for-byte.
+  kvRoute(digest) {
+    return this.route({ base: `/kv/${digest}` });
+  }
+  /**
+   * Per-op auth headers. In account-key mode this is the `Authorization: Bearer
+   * ak_…` header (server hashes it to name storage + debit credits); in wallet
+   * mode it is the EIP-712 identity signature. Used by every op so the same call
+   * site picks the right scheme. Async to share the signature of `identityHeaders`.
+   */
+  async authHeaders(method, path) {
+    if (this.accountKey) return (0, import_core.buildBearerHeaders)(this.accountKey);
+    return { ...await this.identityHeaders(method, path) };
+  }
+  /**
+   * The signing wallet, asserted present. Every x402 path (set/get top-off + 402
+   * fallback, deposit) is gated behind `!this.accountKey` and so always has a
+   * signer; this narrows the optional type at those call sites (and fails loudly
+   * if that invariant is ever broken).
+   */
+  requireSigner() {
+    if (!this.signer) {
+      throw new import_core2.AgentKVError(
+        "no signer: this operation requires a signing wallet",
+        "invalid_config",
+        0
+      );
+    }
+    return this.signer;
+  }
+  /** EIP-712 identity headers with the deployment host bound into the signature (prevents cross-deployment signature replay). */
+  identityHeaders(method, path) {
+    if (!this.signer) {
+      throw new import_core2.AgentKVError(
+        "no signer: this operation requires a signing wallet",
+        "invalid_config",
+        0
+      );
+    }
+    return (0, import_core.buildIdentityHeaders)(this.signer, {
+      method,
+      path,
+      host: new URL(this.endpoint).host,
+      network: this.network
+    });
+  }
+  /**
+   * Shared money/transport orchestrator behind set() and getInternal() — the single copy of
+   * the flow both share: account-key (bearer) mode with proactive + hard-402 top-off and the
+   * inline-payer path; wallet mode with the proactive single-shot, credit path, and 402
+   * pay-and-retry — including the single-flight top-off accounting and settled-txHash spend
+   * gating. Per-op differences (method/body, credit cost, 404 handling, success/inline
+   * parsing) come from `spec`. The CALLER must claim the single-flight top-off SYNCHRONOUSLY
+   * (before any await) and pass it in `flight`; it may be re-claimed here on a cold-start hard
+   * 402, and the caller's `finally` releases it.
+   */
+  async performOp(flight, spec) {
+    const { path, url, idempotencyKey, creditCostUsd, label } = spec;
+    if (this.accountKey) {
+      let toppedOff = false;
+      if (flight.claimed && this.topoffPayer && this.topoffFitsSessionCap()) {
+        try {
+          await this.runSharedTopoff();
+          toppedOff = true;
+        } catch {
+        }
+      }
+      this.maybeAsyncTopoff();
+      this.assertSpend(creditCostUsd);
+      const sendBearer = () => this.fetchWithRetry(
+        url,
+        () => spec.buildRequest({
+          "Idempotency-Key": idempotencyKey,
+          ...(0, import_core.buildBearerHeaders)(this.accountKey)
+        })
+      );
+      let res2 = await sendBearer();
+      this.trackBalance(res2);
+      if (res2.status === 402 && this.topoffPayer && !toppedOff) {
+        if (!flight.claimed) flight.claimed = this.tryClaimTopoffOnFault();
+        if (flight.claimed && this.topoffFitsSessionCap()) {
+          await this.runSharedTopoff();
+          res2 = await sendBearer();
+          this.trackBalance(res2);
+        } else if (this.topoffPromise) {
+          await this.topoffPromise.catch(() => {
+          });
+          res2 = await sendBearer();
+          this.trackBalance(res2);
+        }
+      }
+      if (res2.status === 402 && this.opInlinePayer && !this.topoffPayer) {
+        const inlineCeilingUsd = this.inlineOpCeilingUsd();
+        this.assertSpend(inlineCeilingUsd);
+        const reqInit = spec.buildRequest({
+          "Idempotency-Key": idempotencyKey,
+          ...(0, import_core.buildBearerHeaders)(this.accountKey)
+        });
+        const inlineRes = await this.opInlinePayer({
+          url,
+          method: spec.method,
+          body: reqInit.body,
+          headers: reqInit.headers,
+          // The hook MUST NOT settle more than the effective per-op ceiling.
+          maxAmountAtomic: Math.round(inlineCeilingUsd * 1e6)
+        });
+        if (inlineRes.status === 404 && spec.notFound) return spec.notFound();
+        if (inlineRes.status < 200 || inlineRes.status >= 300) {
+          throw this.errorFromBody(inlineRes.status, inlineRes.body, label);
+        }
+        this.recordSpend(this.inlineSettledAmountUsd(inlineRes.headers) ?? creditCostUsd);
+        return spec.parseInline(inlineRes);
+      }
+      if (res2.status === 404 && spec.notFound) return spec.notFound();
+      if (!res2.ok) throw await this.asError(res2, label);
+      this.recordSpend(creditCostUsd);
+      return spec.parseSuccess(res2);
+    }
+    if (flight.claimed && this.challengeTemplate && this.topoffFitsSessionCap()) {
+      let paymentSignature;
+      try {
+        paymentSignature = await (0, import_core.buildPaymentHeader)(this.requireSigner(), this.challengeTemplate, {
+          amountAtomic: this.topoffAtomic,
+          expectedNetwork: this.network,
+          // Pin the nonce to the op's idempotency key so a retry reuses the auth and the
+          // server dedupes the mint + the op.
+          nonce: (0, import_core.nonceFromIdempotencyKey)(idempotencyKey)
+        });
+      } catch {
+        this.challengeTemplate = void 0;
+      }
+      if (paymentSignature !== void 0) {
+        const res2 = await this.fetchWithRetry(
+          url,
+          () => spec.buildRequest({
+            "Idempotency-Key": idempotencyKey,
+            "PAYMENT-SIGNATURE": paymentSignature
+          })
+        );
+        this.trackBalance(res2);
+        if (res2.status === 404 && spec.notFound) return spec.notFound();
+        if (res2.status !== 402) {
+          if (!res2.ok) throw await this.asError(res2, label);
+          if (this.settledTxHash(res2)) this.recordSpend(this.prepay.topoff);
+          return spec.parseSuccess(res2);
+        }
+      }
+    }
+    this.maybeAsyncTopoff();
+    let res = await this.fetchWithRetry(
+      url,
+      async () => spec.buildRequest({
+        "Idempotency-Key": idempotencyKey,
+        ...await this.identityHeaders(spec.method, path)
+      })
+    );
+    this.trackBalance(res);
+    if (res.status === 402) {
+      const challenge = res.headers.get("PAYMENT-REQUIRED");
+      if (!challenge) {
+        throw await this.asError(res, "payment required but no PAYMENT-REQUIRED challenge");
+      }
+      if (!flight.claimed) flight.claimed = this.tryClaimTopoffOnFault();
+      const topoffHere = flight.claimed && this.topoffFitsSessionCap();
+      const usd = topoffHere ? this.prepay.topoff : (0, import_core.challengePriceUsd)(challenge, void 0, this.network);
+      if (!topoffHere) {
+        this.assertOpPriceCeiling(usd);
+        this.assertSpend(usd);
+      }
+      const paymentSignature = await (0, import_core.buildPaymentHeader)(this.requireSigner(), challenge, {
+        amountAtomic: topoffHere ? this.topoffAtomic : void 0,
+        expectedNetwork: this.network,
+        nonce: (0, import_core.nonceFromIdempotencyKey)(idempotencyKey)
+      });
+      res = await this.fetchWithRetry(
+        url,
+        () => spec.buildRequest({
+          "Idempotency-Key": idempotencyKey,
+          "PAYMENT-SIGNATURE": paymentSignature
+        })
+      );
+      this.trackBalance(res);
+      if (res.ok && (!topoffHere || this.settledTxHash(res))) this.recordSpend(usd);
+    }
+    if (res.status === 404 && spec.notFound) return spec.notFound();
+    if (!res.ok) throw await this.asError(res, label);
+    return spec.parseSuccess(res);
+  }
+  /**
+   * Write an encrypted value. The value is JSON-stringified and AES-256-GCM
+   * encrypted client-side; the server only ever stores ciphertext. `null` and
+   * `undefined` are rejected (`invalid_value`) so a `null` from get() unambiguously
+   * means "missing key" — use delete() to remove a key. Tries the credit path first
+   * (EIP-712 identity signature); if credits are insufficient the server returns a 402
+   * x402 challenge and the client pays. A stable Idempotency-Key is reused across that
+   * retry so the write is exactly-once.
+   */
+  async set(key, value, opts = {}) {
+    const flight = { claimed: this.tryClaimTopoff() };
+    try {
+      const plaintext = JSON.stringify(value);
+      if (value === null || plaintext === void 0) {
+        throw new import_core2.AgentKVError(
+          "cannot store null or undefined; use delete() to remove a key",
+          "invalid_value",
+          0
+        );
+      }
+      const km = await this.getKeyMaterial();
+      const digest = hashKey(km.mac, key);
+      const ciphertext = await encrypt(km.value, plaintext, digest);
+      const body = {
+        value: ciphertext,
+        key_name: await encrypt(km.keyName, key)
+      };
+      if (opts.ttlDays !== void 0) body.ttl_days = opts.ttlDays;
+      if (opts.strictTtl !== void 0) body.strict_ttl = opts.strictTtl;
+      const payload = JSON.stringify(body);
+      const idempotencyKey = opts.idempotencyKey ?? (0, import_core.freshNonce)();
+      const { path, url } = this.kvRoute(digest);
+      return await this.performOp(flight, {
+        method: "POST",
+        path,
+        url,
+        idempotencyKey,
+        creditCostUsd: ACCOUNT_WRITE_USD,
+        label: "set failed",
+        buildRequest: (headers) => ({
+          method: "POST",
+          headers: { "content-type": "application/json", ...headers },
+          body: payload
+        }),
+        parseSuccess: async (res) => await res.json(),
+        parseInline: async (inlineRes) => JSON.parse(inlineRes.body)
+      });
+    } finally {
+      if (flight.claimed) this.topoffInFlight = false;
+    }
+  }
+  /**
+   * Read and decrypt a value. Tries the credit path first (EIP-712 identity);
+   * if credits are insufficient the server returns a 402 x402 challenge and the
+   * client pays, then retries. Returns null if the key is missing or expired (404);
+   * stored values are never null (set rejects it), so null unambiguously means absent.
+   */
+  async get(key, opts = {}) {
+    const { value } = await this.getInternal(key, opts);
+    return value;
+  }
+  /**
+   * Like `get`, but ALSO surfaces the machine-readable usage envelope the server
+   * attaches to a paid read's success body — a separate, additive
+   * accessor so `get()` keeps its narrower `T | null` signature (no existing
+   * caller breaks). `usage` is absent when the key was missing/expired (404 —
+   * the read op itself is never charged on a miss, see the DO's 404-before-charge
+   * precheck — though a proactive top-off, if one was triggered for this call,
+   * is a separate deposit charge and can still happen alongside a miss) or when
+   * talking to a server that predates the usage envelope.
+   */
+  async getWithUsage(key, opts = {}) {
+    return this.getInternal(key, opts);
+  }
+  /**
+   * Shared implementation behind `get`/`getWithUsage`. Tries the credit path
+   * first (EIP-712 identity); if credits are insufficient the server returns a
+   * 402 x402 challenge and the client pays, then retries. `value` is null if
+   * the key is missing or expired (404); stored values are never null (set
+   * rejects it), so null unambiguously means absent.
+   */
+  async getInternal(key, opts = {}) {
+    const flight = { claimed: this.tryClaimTopoff() };
+    try {
+      const digest = hashKey((await this.getKeyMaterial()).mac, key);
+      const { path, url } = this.kvRoute(digest);
+      const idempotencyKey = opts.idempotencyKey ?? (0, import_core.freshNonce)();
+      const parseBody = async (raw) => {
+        const data = JSON.parse(raw);
+        const decryptedText = await this.decryptValue(data.value, key);
+        return { value: JSON.parse(decryptedText), usage: data.usage };
+      };
+      return await this.performOp(flight, {
+        method: "GET",
+        path,
+        url,
+        idempotencyKey,
+        creditCostUsd: ACCOUNT_READ_USD,
+        label: "get failed",
+        buildRequest: (headers) => ({ method: "GET", headers }),
+        parseSuccess: async (res) => parseBody(await res.text()),
+        parseInline: async (inlineRes) => parseBody(inlineRes.body),
+        notFound: () => ({ value: null })
+      });
+    } finally {
+      if (flight.claimed) this.topoffInFlight = false;
+    }
+  }
+  /**
+   * Delete a key. Free operation. Authenticated with the account-key bearer in
+   * account mode, else an EIP-712 identity signature (fresh nonce + timestamp).
+   * The digest is computed from the local key material either way.
+   */
+  async delete(key) {
+    const digest = hashKey((await this.getKeyMaterial()).mac, key);
+    const { path, url } = this.kvRoute(digest);
+    const res = await this.fetchWithRetry(url, async () => ({
+      method: "DELETE",
+      headers: { ...await this.authHeaders("DELETE", path) }
+    }));
+    if (!res.ok) {
+      throw await this.asError(res, "delete failed");
+    }
+    return await res.json();
+  }
+  /**
+   * List the wallet's keys. The server returns opaque per-wallet digests plus each key's
+   * ENCRYPTED name; this decrypts the names locally and returns them — the server never
+   * sees a plaintext key name. Free (EIP-712 identity signed). Paginated: pass the returned
+   * `cursor` to fetch the next page; `cursor` is null once exhausted.
+   */
+  async listKeys(opts = {}) {
+    const km = await this.getKeyMaterial();
+    const params = new URLSearchParams();
+    if (opts.cursor) params.set("cursor", opts.cursor);
+    if (opts.limit !== void 0) params.set("limit", String(opts.limit));
+    const qs = params.toString();
+    const { path, url } = this.route({
+      base: "/list-keys",
+      versioned: `${V1}/kv`,
+      query: qs || void 0
+    });
+    const res = await this.fetchWithRetry(url, async () => ({
+      method: "GET",
+      headers: { ...await this.authHeaders("GET", path) }
+    }));
+    if (!res.ok) throw await this.asError(res, "list-keys failed");
+    const data = await res.json();
+    const keys = (await Promise.all(
+      data.items.filter((i) => i.key_name != null).map(async (i) => {
+        try {
+          return await decrypt(km.keyName, i.key_name);
+        } catch {
+          return null;
+        }
+      })
+    )).filter((k) => k !== null);
+    return { keys, cursor: data.cursor };
+  }
+  /**
+   * Read the pre-paid credit balance. Free. Account-key bearer in account mode,
+   * else an EIP-712 identity signature.
+   */
+  async balance() {
+    const { path, url } = this.route({ base: "/credits/balance" });
+    const res = await this.fetchWithRetry(url, async () => ({
+      method: "GET",
+      headers: { ...await this.authHeaders("GET", path) }
+    }));
+    this.trackBalance(res);
+    if (!res.ok) {
+      throw await this.asError(res, "balance failed");
+    }
+    const body = await res.json();
+    if (this.prepay && Number.isFinite(body.balance)) this.knownCredits = body.balance;
+    return body.balance;
+  }
+  /**
+   * Buy credits with an x402 payment. `amountUsd` must be at least $1; any
+   * amount is accepted (no fixed tiers). This settles on-chain once via the
+   * facilitator; the returned credits are then spendable by set/get with no
+   * further payment.
+   */
+  async deposit(amountUsd, opts = {}) {
+    if (this.accountKey && this.topoffPayer) {
+      const runAccountDeposit = async () => {
+        this.assertSpend(amountUsd);
+        await this.runAccountTopoff(amountUsd);
+        const balance = await this.balance();
+        return { credits_added: Math.round(amountUsd / CREDIT_VALUE_USD), balance };
+      };
+      if (this.topoffInFlight) {
+        return runAccountDeposit();
+      }
+      this.topoffInFlight = true;
+      try {
+        return await runAccountDeposit();
+      } finally {
+        this.topoffInFlight = false;
+      }
+    }
+    if (!this.prepay || this.topoffInFlight) {
+      return this.runDeposit(amountUsd, opts);
+    }
+    this.topoffInFlight = true;
+    try {
+      return await this.runDeposit(amountUsd, opts);
+    } finally {
+      this.topoffInFlight = false;
+    }
+  }
+  /**
+   * Account-key top-off: delegate payment of `${endpoint}/account/deposit` to the
+   * configured `topoffPayer` (a managed account has no signing wallet to sign an
+   * x402 payment). The caller must hold the single-flight claim and have checked
+   * `topoffFitsSessionCap()`. On resolve (= the deposit SETTLED) the top-off is
+   * recorded against the session budget only — top-offs are credit purchases, not
+   * per-op charges, so the per-op cap is deliberately not consulted (mirrors the
+   * wallet-mode top-off budget rules). A rejection is wrapped as
+   * `account_topoff_failed`; the ak_ bearer is never included in the message.
+   */
+  /**
+   * `amountUsd` generalizes this beyond the fixed `prepay.topoff` amount
+   * so `deposit()` can reuse it for a caller-chosen amount. OMITTED (the no-arg
+   * call from the proactive/hard-402/async paths above), it defaults to
+   * `prepay.topoff` and its precomputed `topoffAtomic` ceiling — BYTE-FOR-BYTE the
+   * stage-1 behavior. An EXPLICIT `amountUsd` (from `deposit()`, which may be
+   * called with no `prepay` configured at all) is validated here the same way
+   * `runDeposit` validates its wallet-mode amount, since it never passed through
+   * the constructor's `prepay.topoff` guard.
+   */
+  async runAccountTopoff(amountUsd) {
+    let amount;
+    let maxAmountAtomic;
+    if (amountUsd === void 0) {
+      amount = this.prepay.topoff;
+      maxAmountAtomic = this.topoffAtomic;
+    } else {
+      const atomic = toWholeAtomicUsd(amountUsd);
+      if (atomic === null || !(amountUsd >= 1)) {
+        throw new import_core2.AgentKVError(
+          "amountUsd must be >= $1 and a whole number of atomic USDC units",
+          "invalid_config",
+          0
+        );
+      }
+      amount = amountUsd;
+      maxAmountAtomic = atomic;
+    }
+    try {
+      await this.topoffPayer({
+        depositUrl: this.route({ base: "/account/deposit" }).url,
+        accountKey: this.accountKey,
+        amountUsd: amount,
+        maxAmountAtomic
+      });
+    } catch (e) {
+      const detail = e instanceof Error ? e.message : String(e);
+      throw new import_core2.AgentKVError(
+        `account top-off failed: ${detail} \u2014 check the payer wallet's USDC balance (e.g. 'awal balance'; fund by sending USDC to its address)`,
+        "account_topoff_failed",
+        0
+      );
+    }
+    this.recordSpend(amount);
+  }
+  async runDeposit(amountUsd, opts) {
+    if (this.accountKey) {
+      throw new import_core2.AgentKVError(
+        `Account-key mode has no signing wallet. Fund this account with fundAccount(payerKeyOrSigner, amountUsd), or via 'agentkv fund', or awal: awal x402 pay ${this.route({ base: "/account/deposit" }).url} --headers '{"Authorization":"Bearer <ak>"}'.`,
+        "no_signer",
+        0
+      );
+    }
+    const amountAtomic = toWholeAtomicUsd(amountUsd);
+    if (amountAtomic === null || !(amountUsd >= 1)) {
+      throw new import_core2.AgentKVError(
+        "deposit amountUsd must be >= $1 and a whole number of atomic USDC units",
+        "invalid_config",
+        0
+      );
+    }
+    this.assertSpend(amountUsd, opts);
+    const opKey = opts.idempotencyKey ?? (0, import_core.freshNonce)();
+    const { url } = this.route({ base: "/credits/deposit" });
+    let res = await this.fetchWithRetry(url, () => ({
+      method: "POST",
+      headers: { "Idempotency-Key": opKey }
+    }));
+    this.trackBalance(res);
+    if (res.status === 402) {
+      const challenge = res.headers.get("PAYMENT-REQUIRED");
+      if (!challenge) {
+        throw await this.asError(res, "payment required but no PAYMENT-REQUIRED challenge");
+      }
+      const paymentSignature = await (0, import_core.buildPaymentHeader)(this.requireSigner(), challenge, {
+        amountAtomic,
+        expectedNetwork: this.network,
+        expectedPayTo: opts.expectedPayTo,
+        nonce: (0, import_core.nonceFromIdempotencyKey)(opKey)
+      });
+      res = await this.fetchWithRetry(url, () => ({
+        method: "POST",
+        headers: { "Idempotency-Key": opKey, "PAYMENT-SIGNATURE": paymentSignature }
+      }));
+      this.trackBalance(res);
+    }
+    if (!res.ok) {
+      throw await this.asError(res, "deposit failed");
+    }
+    this.recordSpend(amountUsd);
+    const result = await res.json();
+    if (this.prepay && Number.isFinite(result.balance)) this.knownCredits = result.balance;
+    return result;
+  }
+  /**
+   * Fund an ACCOUNT-KEY namespace — "payer funds, bearer owns". A CALLER-supplied
+   * `signer` pays via x402 to add prepaid credits to THIS client's account (the
+   * one named by its `ak_…` bearer). The payer and the owner are deliberately
+   * DECOUPLED: the payer wallet signs the on-chain EIP-3009 authorization, while
+   * the bearer — not the payer's address — owns the credited namespace. This is the
+   * SDK counterpart of the server's `/account/deposit` route.
+   *
+   * Account-key mode ONLY. In WALLET mode the paying wallet IS the namespace, so
+   * use `deposit()` instead — calling this throws `wrong_mode` before any network.
+   *
+   * `signer` is the PAYER: a viem account (must expose `address` + `signTypedData`)
+   * or a raw `0x` private key (built into a viem account internally, mirroring the
+   * constructor). `amountUsd` must be a whole number of dollars >= $1. UNLIKE
+   * `deposit()` (which IS gated by both spend caps and counts toward session spend),
+   * this explicit funding call is NOT gated by `maxSpendUsd`/`maxSessionSpendUsd` and
+   * does not count toward session spend — the payer is an EXTERNAL wallet, not this
+   * client's tracked budget. The local encryption key is never touched (funding does not encrypt).
+   */
+  async fundAccount(signer, amountUsd, opts = {}) {
+    if (!this.accountKey) {
+      throw new import_core2.AgentKVError(
+        "fundAccount funds an account-key namespace; in wallet mode use deposit()",
+        "wrong_mode",
+        0
+      );
+    }
+    const payer = typeof signer === "string" ? (0, import_accounts.privateKeyToAccount)(signer) : signer;
+    if (!payer?.address || typeof payer.signTypedData !== "function") {
+      throw new import_core2.AgentKVError(
+        "fundAccount: signer must be a 0x private key or a viem account (with address + signTypedData)",
+        "invalid_config",
+        0
+      );
+    }
+    if (!Number.isInteger(amountUsd) || amountUsd < 1) {
+      throw new import_core2.AgentKVError(
+        "fundAccount amountUsd must be a whole number of US dollars >= $1",
+        "invalid_config",
+        0
+      );
+    }
+    const amountAtomic = amountUsd * 1e6;
+    const { url } = this.route({ base: "/account/deposit" });
+    const bearer = (0, import_core.buildBearerHeaders)(this.accountKey);
+    const idempotencyKey = opts.idempotencyKey ?? (0, import_core.freshNonce)();
+    const nonce = (0, import_core.nonceFromIdempotencyKey)(idempotencyKey);
+    let res = await this.fetchWithRetry(url, () => ({
+      method: "POST",
+      headers: { ...bearer, "Idempotency-Key": idempotencyKey }
+    }));
+    this.trackBalance(res);
+    if (res.status === 402) {
+      const challenge = res.headers.get("PAYMENT-REQUIRED");
+      if (!challenge) {
+        throw await this.asError(res, "payment required but no PAYMENT-REQUIRED challenge");
+      }
+      const paymentSignature = await (0, import_core.buildPaymentHeader)(payer, challenge, {
+        amountAtomic,
+        expectedNetwork: this.network,
+        expectedPayTo: opts.expectedPayTo,
+        nonce
+      });
+      res = await this.fetchWithRetry(url, () => ({
+        method: "POST",
+        headers: {
+          ...bearer,
+          "Idempotency-Key": idempotencyKey,
+          "PAYMENT-SIGNATURE": paymentSignature
+        }
+      }));
+      this.trackBalance(res);
+    }
+    if (!res.ok) {
+      throw await this.asError(res, "fundAccount failed");
+    }
+    const result = await res.json();
+    if (this.prepay && Number.isFinite(result.balance)) this.knownCredits = result.balance;
+    return result;
+  }
+  /** Shared by `asError` (a real `Response`) and the `opInlinePayer` path (a plain `{status,body}`). */
+  errorFromBody(status, bodyText, fallback) {
+    let detail = fallback, code = "request_failed";
+    try {
+      const body = JSON.parse(bodyText);
+      if (body?.error) detail = body.error;
+      if (body?.code) code = body.code;
+    } catch {
+    }
+    return new import_core2.AgentKVError(`AgentKV ${status}: ${detail}`, code, status);
+  }
+  async asError(res, fallback) {
+    return this.errorFromBody(res.status, await res.text(), fallback);
+  }
+  /**
+   * The settled amount (USD) from an `opInlinePayer` response's PAYMENT-RESPONSE
+   * header — the inline-path mirror of `settledTxHash()` above, but reading a
+   * plain `Record<string,string>` (the hook's own headers, not a `Response`) and
+   * returning the `amount` field instead of the `txHash`. Case-insensitive header
+   * lookup: an external transport (e.g. awal) is not guaranteed to preserve the
+   * worker's exact `PAYMENT-RESPONSE` casing. Returns `undefined` when the header
+   * is absent/unparsable OR the op settled nothing (served from existing credits,
+   * `txHash: ""`) — callers fall back to the credit-equivalent op price.
+   */
+  inlineSettledAmountUsd(headers) {
+    const key = Object.keys(headers).find((k) => k.toLowerCase() === "payment-response");
+    const header = key ? headers[key] : void 0;
+    if (!header) return void 0;
+    try {
+      const parsed = JSON.parse((0, import_core.decodeBase64Utf8)(header));
+      if (typeof parsed.txHash !== "string" || parsed.txHash === "") return void 0;
+      const atomic = Number(parsed.amount);
+      return Number.isFinite(atomic) && atomic > 0 ? atomic / 1e6 : void 0;
+    } catch {
+      return void 0;
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ACCOUNT_READ_USD,
+  ACCOUNT_WRITE_USD,
+  AgentKV,
+  AgentKVError,
+  CREDIT_VALUE_USD,
+  DEFAULT_MAX_OP_USD,
+  SpendCapError,
+  VERSION,
+  decrypt,
+  deriveKeyMaterial,
+  encrypt,
+  generateAccountKey,
+  hashKey,
+  isAccountKeyFormat
+});
+//# sourceMappingURL=index.cjs.map