whitemagic-pay 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WhiteMagic Labs
+
+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,105 @@
+# whitemagic-pay (TypeScript)
+
+Autonomous machine payment client, session lease caching, and cryptographic
+Proof-of-Context notarization for AI agents. A drop-in `fetch` wrapper that
+negotiates HTTP 402 challenges, signs EIP-3009 gasless permits on Base, caches
+session leases, and retries — no API key, no account.
+
+- Zero mandatory dependencies (global `fetch`); optional [`viem`](https://viem.sh) enables the paid signing path.
+- Session pass caching: one payment covers every call until the lease expires.
+- Faucet support: ephemeral agents can claim a free 10-minute pass with no wallet.
+- Works in Node.js 18+, Bun, Deno, and browsers (paid signing requires a key-capable runtime).
+
+## Install
+
+```bash
+npm install whitemagic-pay
+# optional, for the paid path:
+npm install viem
+```
+
+## Quickstart
+
+### 1. Free onboarding (no wallet, no API key)
+
+```ts
+import { X402Client } from "whitemagic-pay";
+
+const client = new X402Client();
+const faucet = await client.claimFaucet("https://mcp.whitemagic.dev");
+console.log("session pass acquired:", client.pass.tier);
+
+const { status, data } = await client.request(
+  "POST",
+  "https://mcp.whitemagic.dev/mcp",
+  {
+    jsonrpc: "2.0",
+    id: 1,
+    method: "tools/call",
+    params: { name: "memory.search", arguments: { query: "context continuity" } },
+  },
+);
+console.log(status, data);
+```
+
+### 2. Autonomous multi-tier micro-leases (x402 on Base)
+
+```ts
+import { X402Client } from "whitemagic-pay";
+
+const client = new X402Client({
+  privateKey: process.env.AGENT_WALLET_KEY as `0x${string}`,
+  preferredTier: "task",
+});
+
+// Negotiates the 402 challenge, signs EIP-3009, settles on Base, caches the
+// lease, and retries the call in one step.
+const { status, data } = await client.request("POST", "https://mcp.whitemagic.dev/mcp", { /* ... */ });
+```
+
+Or wrap `fetch` directly:
+
+```ts
+const res = await client.fetch("https://mcp.whitemagic.dev/mcp", {
+  method: "POST",
+  body: JSON.stringify({ /* ... */ }),
+});
+```
+
+### Tier menu
+
+| Tier | Price (USDC) | Atomic units | Duration | Best for |
+| :--- | :--- | :--- | :--- | :--- |
+| `call` | $0.002 | 2,000 | 60 s | Single tool call, health probe |
+| `task` | $0.010 | 10,000 | 300 s | Standard multi-step task |
+| `swarm` | $0.050 | 50,000 | 900 s | Multi-agent coordination |
+| `day` | $0.500 | 500,000 | 86,400 s | Continuous production worker |
+
+### 3. Proof-of-Context notarization
+
+```ts
+const receipt = await client.notarizeContext({
+  contextDigest: "sha256:b10b001a...",
+  action: "agent.decision",
+  model: "gemini-2.5-flash",
+  metadata: { epoch: 1 },
+});
+```
+
+## API
+
+- `new X402Client({ privateKey?, preferredTier?, autoLease? })`
+- `client.claimFaucet(baseUrl?)` — claim a free 10-minute trial pass.
+- `client.request(method, url, data?, headers?, timeoutMs?)` — full negotiation + pass reuse.
+- `client.fetch(input, init?)` — `fetch`-compatible wrapper.
+- `client.notarizeContext(input, baseUrl?)` — signed Proof-of-Context notarization.
+- `client.isPassActive()` / `client.pass` — lease state.
+- `client.address()` — payer address (async; resolves after signer load).
+
+## Links
+
+- Hosted lanes and x402 quickstart: https://www.whitemagic.dev/hosted
+- Receipt spec and verifiers: https://www.whitemagic.dev/receipts
+- Python package: https://pypi.org/project/whitemagic-pay/
+
+MIT — WhiteMagic Labs.

package/dist/index.d.ts

@@ -0,0 +1,82 @@
+/**
+ * whitemagic-pay (TypeScript) — autonomous x402 payment client, session lease
+ * caching, and Proof-of-Context notarization for AI agents.
+ *
+ * Mirrors the Python client's semantics: HTTP 402 challenge negotiation,
+ * EIP-3009 TransferWithAuthorization signing (via the optional `viem`
+ * dependency), session pass reuse, faucet claims, and context notarization.
+ */
+export type Tier = "call" | "task" | "swarm" | "day";
+export interface X402Accept {
+    network: string;
+    asset: string;
+    amount: string | number;
+    payTo: string;
+    extra?: {
+        name?: string;
+        version?: string;
+    };
+}
+export interface X402Challenge {
+    x402Version?: number;
+    resource?: string;
+    accepts: X402Accept[];
+    extensions?: Record<string, unknown>;
+}
+export interface X402ClientOptions {
+    privateKey?: string;
+    preferredTier?: Tier;
+    autoLease?: boolean;
+}
+export interface X402Response {
+    status: number;
+    data: Record<string, unknown>;
+    headers: Record<string, string>;
+}
+export interface NotarizeInput {
+    contextDigest?: string;
+    promptHash?: string;
+    action?: string;
+    model?: string;
+    metadata?: Record<string, unknown>;
+}
+export declare const TIER_PRICES: Record<Tier, number>;
+export declare class X402Client {
+    private signerPromise;
+    private preferredTier;
+    private autoLease;
+    private cachedPass;
+    private passExpiresAt;
+    private passTier;
+    constructor(options?: X402ClientOptions);
+    /** The payer address, when a private key was provided. */
+    address(): Promise<string | null>;
+    isPassActive(): boolean;
+    get pass(): {
+        token: string | null;
+        tier: string;
+        expiresAt: number;
+    };
+    /** Claim a 10-minute trial session pass from the hosted faucet (no wallet). */
+    claimFaucet(baseUrl?: string): Promise<Record<string, unknown>>;
+    /** Request a Proof-of-Context notarization from the hosted API lane. */
+    notarizeContext(input: NotarizeInput, baseUrl?: string): Promise<Record<string, unknown>>;
+    /** Build a signed EIP-3009 payment payload from an x402 challenge. */
+    createPaymentPayload(challenge: X402Challenge, tier?: Tier): Promise<{
+        payment: Record<string, unknown>;
+        header: string;
+    }>;
+    /** Execute a request with automatic 402 negotiation and session pass reuse. */
+    request(method: string, url: string, data?: unknown, headers?: Record<string, string>, timeoutMs?: number): Promise<X402Response>;
+    /**
+     * fetch()-style wrapper: same negotiation semantics for callers that want
+     * a drop-in replacement for global fetch.
+     */
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+    private raw;
+    private extractChallenge;
+    private extractChallengeFromResponse;
+    private cachePassFromHeaders;
+}
+/** Convenience helper mirroring the Python package's `wrap_session`. */
+export declare function createX402Client(options?: X402ClientOptions): X402Client;

package/dist/index.js

@@ -0,0 +1,328 @@
+/**
+ * whitemagic-pay (TypeScript) — autonomous x402 payment client, session lease
+ * caching, and Proof-of-Context notarization for AI agents.
+ *
+ * Mirrors the Python client's semantics: HTTP 402 challenge negotiation,
+ * EIP-3009 TransferWithAuthorization signing (via the optional `viem`
+ * dependency), session pass reuse, faucet claims, and context notarization.
+ */
+const CHAIN_MAP = {
+    "eip155:8453": 8453,
+    "eip155:84532": 84532,
+    "eip155:1": 1,
+};
+export const TIER_PRICES = {
+    call: 2000,
+    task: 10000,
+    swarm: 50000,
+    day: 500000,
+};
+const EIP3009_TYPES = {
+    TransferWithAuthorization: [
+        { name: "from", type: "address" },
+        { name: "to", type: "address" },
+        { name: "value", type: "uint256" },
+        { name: "validAfter", type: "uint256" },
+        { name: "validBefore", type: "uint256" },
+        { name: "nonce", type: "bytes32" },
+    ],
+};
+function b64encode(text) {
+    const g = globalThis;
+    if (typeof g.btoa === "function")
+        return g.btoa(text);
+    if (g.Buffer)
+        return g.Buffer.from(text, "utf8").toString("base64");
+    throw new Error("No base64 encoder available in this runtime.");
+}
+function b64decode(text) {
+    const g = globalThis;
+    if (typeof g.atob === "function")
+        return g.atob(text);
+    if (g.Buffer)
+        return g.Buffer.from(text, "base64").toString("utf8");
+    throw new Error("No base64 decoder available in this runtime.");
+}
+function randomNonce() {
+    const bytes = new Uint8Array(32);
+    const cryptoObj = globalThis.crypto;
+    if (cryptoObj?.getRandomValues) {
+        cryptoObj.getRandomValues(bytes);
+    }
+    else {
+        for (let i = 0; i < bytes.length; i++)
+            bytes[i] = Math.floor(Math.random() * 256);
+    }
+    return "0x" + Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+async function loadSigner(privateKey) {
+    let accounts;
+    try {
+        accounts = (await import("viem/accounts"));
+    }
+    catch {
+        throw new Error("The paid path requires the optional `viem` dependency. Install it with: npm install viem");
+    }
+    return accounts.privateKeyToAccount(privateKey);
+}
+export class X402Client {
+    signerPromise = null;
+    preferredTier;
+    autoLease;
+    cachedPass = null;
+    passExpiresAt = 0;
+    passTier = "";
+    constructor(options = {}) {
+        this.preferredTier = options.preferredTier ?? "task";
+        this.autoLease = options.autoLease !== false;
+        if (options.privateKey) {
+            this.signerPromise = loadSigner(options.privateKey);
+        }
+    }
+    /** The payer address, when a private key was provided. */
+    async address() {
+        if (!this.signerPromise)
+            return null;
+        return (await this.signerPromise).address;
+    }
+    isPassActive() {
+        return Boolean(this.cachedPass && Date.now() < this.passExpiresAt - 5000);
+    }
+    get pass() {
+        return { token: this.cachedPass, tier: this.passTier, expiresAt: this.passExpiresAt };
+    }
+    /** Claim a 10-minute trial session pass from the hosted faucet (no wallet). */
+    async claimFaucet(baseUrl = "https://mcp.whitemagic.dev") {
+        const address = await this.address();
+        const res = await this.raw("POST", `${baseUrl.replace(/\/$/, "")}/faucet`, {
+            payer: address ?? "agent",
+        });
+        const data = res.data;
+        if (data.session_pass) {
+            this.cachedPass = data.session_pass;
+            this.passExpiresAt = Date.now() + Number(data.expires_in ?? 600) * 1000;
+            this.passTier = "faucet";
+        }
+        return res.data;
+    }
+    /** Request a Proof-of-Context notarization from the hosted API lane. */
+    async notarizeContext(input, baseUrl = "https://api.whitemagic.dev") {
+        const payload = {};
+        if (input.contextDigest)
+            payload.context_digest = input.contextDigest;
+        if (input.promptHash)
+            payload.prompt_hash = input.promptHash;
+        if (input.action)
+            payload.action = input.action;
+        if (input.model)
+            payload.model = input.model;
+        if (input.metadata)
+            payload.metadata = input.metadata;
+        const address = await this.address();
+        if (address)
+            payload.agent_id = address;
+        const res = await this.request("POST", `${baseUrl.replace(/\/$/, "")}/notarize`, payload);
+        if (res.status !== 200) {
+            throw new Error(`Notarization failed with status ${res.status}: ${JSON.stringify(res.data)}`);
+        }
+        return res.data;
+    }
+    /** Build a signed EIP-3009 payment payload from an x402 challenge. */
+    async createPaymentPayload(challenge, tier) {
+        if (!this.signerPromise) {
+            throw new Error("No private key provided to X402Client to sign the payment challenge.");
+        }
+        const signer = await this.signerPromise;
+        const accepts = challenge.accepts ?? [];
+        if (accepts.length === 0) {
+            throw new Error("Challenge contains no 'accepts' requirements.");
+        }
+        const chosenTier = tier ?? this.preferredTier;
+        const targetAmount = TIER_PRICES[chosenTier];
+        let req = accepts.find((c) => Number(c.amount) === targetAmount);
+        if (!req) {
+            req = accepts.reduce((min, c) => (Number(c.amount) < Number(min.amount) ? c : min));
+        }
+        const network = req.network ?? "eip155:8453";
+        const chainId = CHAIN_MAP[network];
+        if (chainId === undefined) {
+            throw new Error(`Unsupported network rail: ${network}`);
+        }
+        const extra = req.extra ?? {};
+        const now = Math.floor(Date.now() / 1000);
+        const authorization = {
+            from: signer.address,
+            to: req.payTo,
+            value: Number(req.amount),
+            validAfter: now - 60,
+            validBefore: now + 600,
+            nonce: randomNonce(),
+        };
+        const domain = {
+            name: extra.name ?? "USD Coin",
+            version: String(extra.version ?? "2"),
+            chainId,
+            verifyingContract: req.asset,
+        };
+        const signature = await signer.signTypedData({
+            domain,
+            types: EIP3009_TYPES,
+            primaryType: "TransferWithAuthorization",
+            message: authorization,
+        });
+        const payloadAuthorization = {
+            from: authorization.from,
+            to: authorization.to,
+            value: String(authorization.value),
+            validAfter: String(authorization.validAfter),
+            validBefore: String(authorization.validBefore),
+            nonce: authorization.nonce,
+        };
+        const payment = {
+            x402Version: challenge.x402Version ?? 2,
+            resource: challenge.resource,
+            accepted: req,
+            payload: { signature, authorization: payloadAuthorization },
+            extensions: challenge.extensions ?? {},
+        };
+        return { payment, header: b64encode(JSON.stringify(payment)) };
+    }
+    /** Execute a request with automatic 402 negotiation and session pass reuse. */
+    async request(method, url, data, headers, timeoutMs = 30000) {
+        const reqHeaders = { "Content-Type": "application/json", ...(headers ?? {}) };
+        if (this.isPassActive() && this.cachedPass) {
+            reqHeaders["Authorization"] = `Bearer ${this.cachedPass}`;
+            reqHeaders["X-Session-Pass"] = this.cachedPass;
+        }
+        const body = data === undefined
+            ? undefined
+            : typeof data === "string"
+                ? data
+                : JSON.stringify(data);
+        let res = await this.raw(method, url, body, reqHeaders, timeoutMs);
+        if (res.status === 402 && this.signerPromise) {
+            const challenge = await this.extractChallenge(res);
+            if (challenge && Array.isArray(challenge.accepts) && challenge.accepts.length > 0) {
+                const { header } = await this.createPaymentPayload(challenge);
+                const retryHeaders = {
+                    ...reqHeaders,
+                    "PAYMENT-SIGNATURE": header,
+                    "X-Lease-Tier": this.preferredTier,
+                };
+                res = await this.raw(method, url, body, retryHeaders, timeoutMs);
+            }
+        }
+        this.cachePassFromHeaders(res.headers);
+        return res;
+    }
+    /**
+     * fetch()-style wrapper: same negotiation semantics for callers that want
+     * a drop-in replacement for global fetch.
+     */
+    async fetch(input, init) {
+        const headers = new Headers(init?.headers ?? {});
+        if (this.isPassActive() && this.cachedPass) {
+            headers.set("Authorization", `Bearer ${this.cachedPass}`);
+            headers.set("X-Session-Pass", this.cachedPass);
+        }
+        let response = await globalThis.fetch(input, { ...init, headers });
+        if (response.status === 402 && this.signerPromise) {
+            const challenge = await this.extractChallengeFromResponse(response);
+            if (challenge && Array.isArray(challenge.accepts) && challenge.accepts.length > 0) {
+                const { header } = await this.createPaymentPayload(challenge);
+                const retryHeaders = new Headers(headers);
+                retryHeaders.set("PAYMENT-SIGNATURE", header);
+                retryHeaders.set("X-Lease-Tier", this.preferredTier);
+                response = await globalThis.fetch(input, { ...init, headers: retryHeaders });
+            }
+        }
+        const headerRecord = {};
+        response.headers.forEach((value, key) => {
+            headerRecord[key] = value;
+        });
+        this.cachePassFromHeaders(headerRecord);
+        return response;
+    }
+    async raw(method, url, body, headers, timeoutMs = 30000) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        const payload = body === undefined ? undefined : typeof body === "string" ? body : JSON.stringify(body);
+        try {
+            const response = await globalThis.fetch(url, {
+                method,
+                headers: { "Content-Type": "application/json", ...(headers ?? {}) },
+                body: payload,
+                signal: controller.signal,
+            });
+            const headerRecord = {};
+            response.headers.forEach((value, key) => {
+                headerRecord[key] = value;
+            });
+            const text = await response.text();
+            let data = {};
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                data = { raw: text };
+            }
+            return { status: response.status, data, headers: headerRecord };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async extractChallenge(res) {
+        const body = res.data;
+        if (body && Array.isArray(body.accepts))
+            return body;
+        const header = res.headers["payment-required"] ?? res.headers["PAYMENT-REQUIRED"];
+        if (header) {
+            try {
+                return JSON.parse(b64decode(header));
+            }
+            catch {
+                return null;
+            }
+        }
+        return null;
+    }
+    async extractChallengeFromResponse(response) {
+        const header = response.headers.get("PAYMENT-REQUIRED");
+        if (header) {
+            try {
+                return JSON.parse(b64decode(header));
+            }
+            catch {
+                // fall through to the body
+            }
+        }
+        try {
+            const clone = response.clone();
+            const body = (await clone.json());
+            if (body && Array.isArray(body.accepts))
+                return body;
+        }
+        catch {
+            // not JSON
+        }
+        return null;
+    }
+    cachePassFromHeaders(headers) {
+        const sessionPass = headers["x-session-pass"];
+        const expiresIn = headers["x-session-expires-in"];
+        const tier = headers["x-session-tier"];
+        if (sessionPass && expiresIn) {
+            const secs = Number(expiresIn);
+            if (!Number.isNaN(secs)) {
+                this.cachedPass = sessionPass;
+                this.passExpiresAt = Date.now() + secs * 1000;
+                this.passTier = tier ?? this.preferredTier;
+            }
+        }
+    }
+}
+/** Convenience helper mirroring the Python package's `wrap_session`. */
+export function createX402Client(options = {}) {
+    return new X402Client(options);
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "whitemagic-pay",
+  "version": "0.1.0",
+  "description": "Autonomous x402 payment client, session lease caching, and Proof-of-Context notarization for AI agents.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "x402",
+    "agent",
+    "payments",
+    "usdc",
+    "base",
+    "eip-3009",
+    "notarization",
+    "whitemagic",
+    "mcp"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lbailey94/whitemagic-pay.git"
+  },
+  "homepage": "https://www.whitemagic.dev/hosted",
+  "peerDependencies": {
+    "viem": ">=2"
+  },
+  "peerDependenciesMeta": {
+    "viem": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "viem": "^2.21.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "smoke": "node scripts/smoke.mjs"
+  }
+}