@xona-labs/xpay 0.1.0

package/dist/discover/payai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payai.js","sourceRoot":"","sources":["../../src/discover/payai.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,cAAc,EAAiB,MAAM,aAAa,CAAC;AAE5D,MAAM,gBAAgB,GAAG,uDAAuD,CAAC;AACjF;mCACmC;AACnC,MAAM,SAAS,GAAG,IAAI,CAAC;AAgBvB,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,OAA2B,EAAE;IACrE,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,gBAAgB,CAAC;IACnD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,SAAS,EAAE,SAAS,CAAC,CAAC;IAC3D,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC;IAC3C,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC;IAEtC,MAAM,GAAG,GAAe,EAAE,CAAC;IAC3B,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,KAAK,GAAG,QAAQ,CAAC;IAErB,yEAAyE;IACzE,qDAAqD;IACrD,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,GAAG,IAAI,MAAM,GAAG,KAAK,IAAI,GAAG,CAAC,MAAM,GAAG,QAAQ,EAAE,IAAI,EAAE,EAAE,CAAC;QACjF,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC9B,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAC7C,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;QAE/C,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE;YAC1C,OAAO,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE;SACxC,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,2BAA2B,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC;QAC7E,CAAC;QACD,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAkB,CAAC;QAEjD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;QAClC,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;YAC3B,MAAM,MAAM,GAAG,cAAc,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;YAC7C,IAAI,MAAM,CAAC,OAAO;gBAAE,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAC1C,IAAI,GAAG,CAAC,MAAM,IAAI,QAAQ;gBAAE,OAAO,GAAG,CAAC;QACzC,CAAC;QAED,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC;YAC9B,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;QACpD,CAAC;aAAM,CAAC;YACN,4CAA4C;YAC5C,MAAM;QACR,CAAC;QACD,+DAA+D;QAC/D,IAAI,QAAQ,CAAC,MAAM,GAAG,KAAK;YAAE,MAAM;IACrC,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/do/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Do — the thesis in one method. Discover by intent, pick the top result, use it.
+ *
+ * This is the API normies (and most agents) actually want. Power users compose
+ * {@link discover} + {@link use} manually when they need control over picking.
+ */
+import type { UseResult } from "../types.js";
+import type { Wallet } from "../wallet/index.js";
+import type { Guardrail } from "../guardrail/index.js";
+export interface DoArgs {
+    query: string;
+    wallet: Wallet;
+    guardrail: Guardrail;
+    body?: unknown;
+}
+export declare function doIt(args: DoArgs): Promise<UseResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/do/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/do/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAG7C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEvD,MAAM,WAAW,MAAM;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,SAAS,CAAC;IACrB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CA2B3D"}

package/dist/do/index.js

@@ -0,0 +1,32 @@
+/**
+ * Do — the thesis in one method. Discover by intent, pick the top result, use it.
+ *
+ * This is the API normies (and most agents) actually want. Power users compose
+ * {@link discover} + {@link use} manually when they need control over picking.
+ */
+import { discover } from "../discover/index.js";
+import { use } from "../use/index.js";
+export async function doIt(args) {
+    const candidates = await discover({
+        query: args.query,
+        networks: args.wallet.networks,
+        limit: 5,
+    });
+    if (candidates.length === 0) {
+        throw new Error(`xpay.do: no services found for "${args.query}"`);
+    }
+    // v0 picks the top-ranked match the wallet can actually pay. v0.2 should
+    // rerank by reliability + price; v1 should learn from user history.
+    for (const candidate of candidates) {
+        if (args.wallet.pickRequirement(candidate.accepts)) {
+            return use({
+                resource: candidate,
+                wallet: args.wallet,
+                guardrail: args.guardrail,
+                body: args.body,
+            });
+        }
+    }
+    throw new Error(`xpay.do: found ${candidates.length} services for "${args.query}" but none accept payment on configured networks (${args.wallet.networks.join(", ")})`);
+}
+//# sourceMappingURL=index.js.map

package/dist/do/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/do/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAWtC,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,IAAY;IACrC,MAAM,UAAU,GAAG,MAAM,QAAQ,CAAC;QAChC,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ;QAC9B,KAAK,EAAE,CAAC;KACT,CAAC,CAAC;IAEH,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,mCAAmC,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;IACpE,CAAC;IAED,yEAAyE;IACzE,oEAAoE;IACpE,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;YACnD,OAAO,GAAG,CAAC;gBACT,QAAQ,EAAE,SAAS;gBACnB,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,IAAI,EAAE,IAAI,CAAC,IAAI;aAChB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,MAAM,IAAI,KAAK,CACb,kBAAkB,UAAU,CAAC,MAAM,kBAAkB,IAAI,CAAC,KAAK,qDAAqD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACvJ,CAAC;AACJ,CAAC"}

package/dist/guardrail/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Spending guardrail — enforced *before* signing so a hallucinating agent
+ * can't sneak past it. This is the security primitive that makes xPay
+ * "agentic" rather than just "an SDK with a wallet".
+ *
+ * v0 implements: per-tx cap, per-day cap, allowed host list. v0.2 adds
+ * per-counterparty caps and a biometric-required threshold.
+ */
+import type { PaymentRequirement, Resource } from "../types.js";
+export interface GuardrailConfig {
+    /** Max USD per single call. */
+    maxPerTx?: number;
+    /** Max USD across a rolling 24h window. */
+    maxPerDay?: number;
+    /** Glob-style host whitelist. `["*"]` allows everything. */
+    allowedHosts?: string[];
+    /** Calls above this USD threshold require an external approval hook. */
+    requireApprovalAbove?: number;
+    /**
+     * Optional callback invoked when {@link GuardrailConfig.requireApprovalAbove}
+     * is hit. Implementor decides how to surface the prompt (biometric, push,
+     * webhook). Resolve `true` to allow, `false` to deny.
+     */
+    onApprovalRequired?: (ctx: {
+        resource: Resource;
+        usd: number;
+    }) => Promise<boolean>;
+}
+export declare class Guardrail {
+    private readonly config;
+    private readonly history;
+    constructor(config?: GuardrailConfig);
+    /**
+     * Check a pending call. Throws if blocked.
+     * Called by {@link use} before any on-chain action.
+     */
+    check(args: {
+        resource: Resource;
+        requirement: PaymentRequirement;
+    }): Promise<void>;
+    /** Sum of recent spend, in USD, within the last 24h. */
+    recentSpend(): number;
+}
+export declare class GuardrailError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/guardrail/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/guardrail/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEhE,MAAM,WAAW,eAAe;IAC9B,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,wEAAwE;IACxE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,CAAC,GAAG,EAAE;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACrF;AAOD,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;gBAEhC,MAAM,GAAE,eAAoB;IAIxC;;;OAGG;IACG,KAAK,CAAC,IAAI,EAAE;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,WAAW,EAAE,kBAAkB,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAyDzF,wDAAwD;IACxD,WAAW,IAAI,MAAM;CAItB;AAED,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI5B"}

package/dist/guardrail/index.js

@@ -0,0 +1,99 @@
+/**
+ * Spending guardrail — enforced *before* signing so a hallucinating agent
+ * can't sneak past it. This is the security primitive that makes xPay
+ * "agentic" rather than just "an SDK with a wallet".
+ *
+ * v0 implements: per-tx cap, per-day cap, allowed host list. v0.2 adds
+ * per-counterparty caps and a biometric-required threshold.
+ */
+export class Guardrail {
+    config;
+    history = [];
+    constructor(config = {}) {
+        this.config = config;
+    }
+    /**
+     * Check a pending call. Throws if blocked.
+     * Called by {@link use} before any on-chain action.
+     */
+    async check(args) {
+        const usd = estimateUsd(args.requirement);
+        // Host whitelist. Skipped for direct transfers (they target addresses, not
+        // hosts) — amount caps still apply, so a leaked CLI can't drain the wallet.
+        if (args.resource.type !== "transfer" &&
+            this.config.allowedHosts &&
+            this.config.allowedHosts.length > 0) {
+            const allowed = this.config.allowedHosts;
+            if (!allowed.includes("*")) {
+                const host = safeHost(args.resource.resource);
+                const ok = allowed.some((pattern) => hostMatches(host, pattern));
+                if (!ok) {
+                    throw new GuardrailError(`Host "${host}" is not in the allowed list`);
+                }
+            }
+        }
+        // Per-tx cap.
+        if (this.config.maxPerTx !== undefined && usd > this.config.maxPerTx) {
+            throw new GuardrailError(`Single call would spend $${usd.toFixed(4)}, exceeds maxPerTx $${this.config.maxPerTx}`);
+        }
+        // Per-day cap.
+        if (this.config.maxPerDay !== undefined) {
+            const dayAgo = Date.now() - 24 * 60 * 60 * 1000;
+            const spent = this.history.filter((h) => h.at >= dayAgo).reduce((s, h) => s + h.usd, 0);
+            if (spent + usd > this.config.maxPerDay) {
+                throw new GuardrailError(`Daily spend $${(spent + usd).toFixed(4)} would exceed maxPerDay $${this.config.maxPerDay}`);
+            }
+        }
+        // Approval gate.
+        if (this.config.requireApprovalAbove !== undefined &&
+            usd >= this.config.requireApprovalAbove) {
+            if (!this.config.onApprovalRequired) {
+                throw new GuardrailError(`Call requires approval ($${usd.toFixed(4)} >= $${this.config.requireApprovalAbove}) but no onApprovalRequired hook is configured`);
+            }
+            const approved = await this.config.onApprovalRequired({ resource: args.resource, usd });
+            if (!approved) {
+                throw new GuardrailError(`Call denied by approval hook`);
+            }
+        }
+        this.history.push({ at: Date.now(), usd });
+    }
+    /** Sum of recent spend, in USD, within the last 24h. */
+    recentSpend() {
+        const dayAgo = Date.now() - 24 * 60 * 60 * 1000;
+        return this.history.filter((h) => h.at >= dayAgo).reduce((s, h) => s + h.usd, 0);
+    }
+}
+export class GuardrailError extends Error {
+    constructor(message) {
+        super(`xpay guardrail: ${message}`);
+        this.name = "GuardrailError";
+    }
+}
+/**
+ * Best-effort USD estimate. Assumes USDC (6 decimals) on Solana, USDC (6) on
+ * Base/EVM. Future versions should consult a price oracle for non-USDC assets.
+ */
+function estimateUsd(req) {
+    if (!req.amount)
+        return 0;
+    // USDC has 6 decimals on every chain we currently support.
+    return Number(req.amount) / 1_000_000;
+}
+function safeHost(url) {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return "";
+    }
+}
+function hostMatches(host, pattern) {
+    if (pattern === host)
+        return true;
+    if (pattern.startsWith("*.")) {
+        const suffix = pattern.slice(1); // ".example.com"
+        return host.endsWith(suffix);
+    }
+    return false;
+}
+//# sourceMappingURL=index.js.map

package/dist/guardrail/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/guardrail/index.ts"],"names":[],"mappings":"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"}

package/dist/history/evm.d.ts

@@ -0,0 +1,21 @@
+/**
+ * EVM USDC history via ERC-20 Transfer event logs.
+ *
+ * Strategy: scan a recent block window for `Transfer` events on the USDC
+ * contract where `from` or `to` is the wallet. Public RPCs typically allow a
+ * window of ~5k–10k blocks per `eth_getLogs` call; we paginate if needed.
+ *
+ * Good enough for the v1 history view. For production / large windows, swap
+ * the RPC for an indexer (Basescan/Alchemy/Covalent) by passing `rpcUrl`.
+ */
+import type { HistoryEntry } from "./types.js";
+import type { Network } from "../types.js";
+export interface EvmHistoryOptions {
+    address: string;
+    network: Network;
+    limit?: number;
+    blockWindow?: number;
+    rpcUrl?: string;
+}
+export declare function fetchEvmHistory(opts: EvmHistoryOptions): Promise<HistoryEntry[]>;
+//# sourceMappingURL=evm.d.ts.map

package/dist/history/evm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evm.d.ts","sourceRoot":"","sources":["../../src/history/evm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAsB3C,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAID,wBAAsB,eAAe,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAyFtF"}

package/dist/history/evm.js

@@ -0,0 +1,118 @@
+/**
+ * EVM USDC history via ERC-20 Transfer event logs.
+ *
+ * Strategy: scan a recent block window for `Transfer` events on the USDC
+ * contract where `from` or `to` is the wallet. Public RPCs typically allow a
+ * window of ~5k–10k blocks per `eth_getLogs` call; we paginate if needed.
+ *
+ * Good enough for the v1 history view. For production / large windows, swap
+ * the RPC for an indexer (Basescan/Alchemy/Covalent) by passing `rpcUrl`.
+ */
+import { Contract, JsonRpcProvider, ZeroAddress, hexlify, toBeHex, zeroPadValue } from "ethers";
+const USDC_CONTRACTS = {
+    base: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+    ethereum: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+    arbitrum: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
+    optimism: "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
+};
+const DEFAULT_RPCS = {
+    base: "https://mainnet.base.org",
+    ethereum: "https://eth.llamarpc.com",
+    arbitrum: "https://arb1.arbitrum.io/rpc",
+    optimism: "https://mainnet.optimism.io",
+};
+/** Window (in blocks) scanned for transfer history. ~2 days at 2s block times. */
+const DEFAULT_BLOCK_WINDOW = 100_000;
+/** Public RPCs commonly cap getLogs at 10k blocks. Stay under it. */
+const MAX_LOG_RANGE = 9_500;
+const TRANSFER_TOPIC = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
+const TRANSFER_IFACE = ["event Transfer(address indexed from, address indexed to, uint256 value)"];
+export async function fetchEvmHistory(opts) {
+    const usdc = USDC_CONTRACTS[opts.network];
+    const rpc = opts.rpcUrl ?? DEFAULT_RPCS[opts.network];
+    if (!usdc || !rpc) {
+        throw new Error(`fetchEvmHistory: no USDC contract / RPC for network "${opts.network}"`);
+    }
+    const provider = new JsonRpcProvider(rpc);
+    const latest = await provider.getBlockNumber();
+    const from = Math.max(0, latest - (opts.blockWindow ?? DEFAULT_BLOCK_WINDOW));
+    const padded = zeroPadValue(opts.address, 32);
+    /** Chunked getLogs — public RPCs cap range, so we walk backwards in MAX_LOG_RANGE
+     *  windows and stop early once we have enough hits for the requested limit. */
+    async function chunkedLogs(topics) {
+        const all = [];
+        let end = latest;
+        while (end > from) {
+            const start = Math.max(from, end - MAX_LOG_RANGE);
+            try {
+                const batch = await provider.getLogs({
+                    address: usdc,
+                    topics,
+                    fromBlock: start,
+                    toBlock: end,
+                });
+                all.push(...batch);
+            }
+            catch (err) {
+                // Tolerate per-chunk failures (rate limits) — keep what we have.
+                // eslint-disable-next-line no-console
+                console.warn(`[xpay] evm history chunk ${start}-${end} failed:`, err.message);
+            }
+            if (opts.limit && all.length >= opts.limit)
+                break;
+            end = start - 1;
+        }
+        return all;
+    }
+    const [outgoing, incoming] = await Promise.all([
+        chunkedLogs([TRANSFER_TOPIC, padded, null]),
+        chunkedLogs([TRANSFER_TOPIC, null, padded]),
+    ]);
+    const erc20 = new Contract(usdc, TRANSFER_IFACE, provider);
+    const logs = [...outgoing, ...incoming];
+    const seen = new Set();
+    // Pull block timestamps for each unique block in the result.
+    const blockNumbers = [...new Set(logs.map((l) => l.blockNumber))];
+    const blocks = new Map();
+    await Promise.all(blockNumbers.map(async (bn) => {
+        try {
+            const b = await provider.getBlock(bn);
+            if (b?.timestamp)
+                blocks.set(bn, b.timestamp * 1000);
+        }
+        catch {
+            /* skip */
+        }
+    }));
+    const out = [];
+    for (const log of logs) {
+        const key = `${log.transactionHash}:${log.index}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const parsed = erc20.interface.parseLog({ topics: [...log.topics], data: log.data });
+        if (!parsed)
+            continue;
+        const fromAddr = parsed.args[0].toLowerCase();
+        const toAddr = parsed.args[1].toLowerCase();
+        const value = parsed.args[2];
+        const isSend = fromAddr === opts.address.toLowerCase();
+        out.push({
+            timestamp: blocks.get(log.blockNumber) ?? null,
+            network: opts.network,
+            signature: log.transactionHash,
+            direction: isSend ? "send" : "receive",
+            counterparty: isSend ? toAddr : fromAddr,
+            amountUsdc: Number(value) / 1_000_000,
+        });
+    }
+    out.sort((a, b) => (b.timestamp ?? 0) - (a.timestamp ?? 0));
+    if (opts.limit)
+        return out.slice(0, opts.limit);
+    return out;
+}
+// hint to tree-shakers: keep this import live (used in JSDoc only otherwise)
+void hexlify;
+void toBeHex;
+void ZeroAddress;
+//# sourceMappingURL=evm.js.map

package/dist/history/evm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evm.js","sourceRoot":"","sources":["../../src/history/evm.ts"],"names":[],"mappings":"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"}

package/dist/history/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Unified history — merges Solana + EVM USDC activity into a single sorted feed.
+ */
+import type { Network } from "../types.js";
+import type { Wallet } from "../wallet/index.js";
+import type { HistoryEntry } from "./types.js";
+export * from "./types.js";
+export interface HistoryOptions {
+    /** Restrict to specific networks. Defaults to all the wallet supports. */
+    networks?: Network[];
+    /** Max entries to return (after merge + sort). */
+    limit?: number;
+    /** Per-network block window for EVM scans. */
+    evmBlockWindow?: number;
+    /** Per-network RPC overrides. */
+    rpcs?: Partial<Record<Network, string>>;
+}
+export declare function getHistory(wallet: Wallet, opts?: HistoryOptions): Promise<HistoryEntry[]>;
+//# sourceMappingURL=index.d.ts.map

package/dist/history/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/history/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAGjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,cAAc,YAAY,CAAC;AAE3B,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IACrB,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iCAAiC;IACjC,IAAI,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;CACzC;AAID,wBAAsB,UAAU,CAC9B,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,YAAY,EAAE,CAAC,CAqCzB"}

package/dist/history/index.js

@@ -0,0 +1,45 @@
+/**
+ * Unified history — merges Solana + EVM USDC activity into a single sorted feed.
+ */
+import { fetchSolanaHistory } from "./solana.js";
+import { fetchEvmHistory } from "./evm.js";
+export * from "./types.js";
+const EVM_NETWORKS = ["base", "ethereum", "arbitrum", "optimism"];
+export async function getHistory(wallet, opts = {}) {
+    const networks = opts.networks ?? wallet.networks;
+    const perNetwork = Math.max(opts.limit ?? 25, 25);
+    const results = await Promise.all(networks.map(async (net) => {
+        if (!wallet.has(net))
+            return [];
+        const address = wallet.address(net);
+        try {
+            if (net === "solana") {
+                return await fetchSolanaHistory({
+                    address,
+                    limit: perNetwork,
+                    rpcUrl: opts.rpcs?.solana,
+                });
+            }
+            if (EVM_NETWORKS.includes(net)) {
+                return await fetchEvmHistory({
+                    address,
+                    network: net,
+                    limit: perNetwork,
+                    blockWindow: opts.evmBlockWindow,
+                    rpcUrl: opts.rpcs?.[net],
+                });
+            }
+        }
+        catch (err) {
+            // One bad network shouldn't kill history. Log and continue.
+            // eslint-disable-next-line no-console
+            console.warn(`[xpay] history fetch failed for ${net}:`, err.message);
+        }
+        return [];
+    }));
+    const merged = results.flat().sort((a, b) => (b.timestamp ?? 0) - (a.timestamp ?? 0));
+    if (opts.limit)
+        return merged.slice(0, opts.limit);
+    return merged;
+}
+//# sourceMappingURL=index.js.map

package/dist/history/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/history/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAG3C,cAAc,YAAY,CAAC;AAa3B,MAAM,YAAY,GAAc,CAAC,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;AAE7E,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,MAAc,EACd,OAAuB,EAAE;IAEzB,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC;IAClD,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;IAElD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAC/B,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;QACzB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO,EAAE,CAAC;QAChC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACpC,IAAI,CAAC;YACH,IAAI,GAAG,KAAK,QAAQ,EAAE,CAAC;gBACrB,OAAO,MAAM,kBAAkB,CAAC;oBAC9B,OAAO;oBACP,KAAK,EAAE,UAAU;oBACjB,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM;iBAC1B,CAAC,CAAC;YACL,CAAC;YACD,IAAI,YAAY,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC/B,OAAO,MAAM,eAAe,CAAC;oBAC3B,OAAO;oBACP,OAAO,EAAE,GAAG;oBACZ,KAAK,EAAE,UAAU;oBACjB,WAAW,EAAE,IAAI,CAAC,cAAc;oBAChC,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC;iBACzB,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,4DAA4D;YAC5D,sCAAsC;YACtC,OAAO,CAAC,IAAI,CAAC,mCAAmC,GAAG,GAAG,EAAG,GAAa,CAAC,OAAO,CAAC,CAAC;QAClF,CAAC;QACD,OAAO,EAAE,CAAC;IACZ,CAAC,CAAC,CACH,CAAC;IAEF,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,CAAC,CAAC;IACtF,IAAI,IAAI,CAAC,KAAK;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IACnD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/history/solana.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Solana USDC history via standard JSON-RPC.
+ *
+ * Strategy:
+ *   1. `getSignaturesForAddress` on the wallet's USDC associated token account
+ *      (ATA), not the wallet itself — token-program txs are addressed to the
+ *      ATA, not the owner.
+ *   2. `getParsedTransactions` (batched) to extract amounts + counterparties.
+ *
+ * Works on free public RPC for small `limit` values. For prod scale, drop in
+ * a Helius / Triton RPC via the `rpcUrl` arg.
+ */
+import type { HistoryEntry } from "./types.js";
+export interface SolanaHistoryOptions {
+    address: string;
+    limit?: number;
+    rpcUrl?: string;
+}
+export declare function fetchSolanaHistory(opts: SolanaHistoryOptions): Promise<HistoryEntry[]>;
+//# sourceMappingURL=solana.d.ts.map

package/dist/history/solana.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"solana.d.ts","sourceRoot":"","sources":["../../src/history/solana.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AASH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAK/C,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAgC5F"}

package/dist/history/solana.js

@@ -0,0 +1,97 @@
+/**
+ * Solana USDC history via standard JSON-RPC.
+ *
+ * Strategy:
+ *   1. `getSignaturesForAddress` on the wallet's USDC associated token account
+ *      (ATA), not the wallet itself — token-program txs are addressed to the
+ *      ATA, not the owner.
+ *   2. `getParsedTransactions` (batched) to extract amounts + counterparties.
+ *
+ * Works on free public RPC for small `limit` values. For prod scale, drop in
+ * a Helius / Triton RPC via the `rpcUrl` arg.
+ */
+import { Connection, PublicKey, } from "@solana/web3.js";
+import { getAssociatedTokenAddress } from "@solana/spl-token";
+const USDC_MINT = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+const DEFAULT_RPC = "https://api.mainnet-beta.solana.com";
+export async function fetchSolanaHistory(opts) {
+    const limit = Math.min(opts.limit ?? 25, 1000);
+    const connection = new Connection(opts.rpcUrl ?? DEFAULT_RPC, "confirmed");
+    const owner = new PublicKey(opts.address);
+    const ata = await getAssociatedTokenAddress(new PublicKey(USDC_MINT), owner);
+    const sigs = await connection.getSignaturesForAddress(ata, { limit });
+    if (sigs.length === 0)
+        return [];
+    // Batch-fetch parsed txs (RPC supports up to ~100 per batch via single calls,
+    // but the helper here just fires Promise.all on individual calls — public RPC
+    // tolerates this at small limits).
+    const parsed = await Promise.all(sigs.map((s) => connection
+        .getParsedTransaction(s.signature, { maxSupportedTransactionVersion: 0 })
+        .catch(() => null)));
+    const out = [];
+    for (let i = 0; i < sigs.length; i++) {
+        const sig = sigs[i];
+        const tx = parsed[i];
+        const entry = extractTransferEntry(tx, sig.signature, opts.address);
+        if (!entry)
+            continue;
+        entry.timestamp = sig.blockTime ? sig.blockTime * 1000 : null;
+        entry.status = sig.err ? "failed" : sig.confirmationStatus ?? "confirmed";
+        out.push(entry);
+    }
+    return out;
+}
+function extractTransferEntry(tx, signature, ownerAddress) {
+    if (!tx?.meta || tx.meta.err) {
+        // Still emit failed tx so users can see them.
+        return tx
+            ? {
+                timestamp: null,
+                network: "solana",
+                signature,
+                direction: "send",
+                counterparty: "",
+                amountUsdc: 0,
+            }
+            : null;
+    }
+    for (const ix of tx.transaction.message.instructions) {
+        const parsed = ix;
+        if (parsed.program !== "spl-token")
+            continue;
+        const info = parsed.parsed?.info;
+        if (!info)
+            continue;
+        const type = parsed.parsed?.type;
+        if (type !== "transfer" && type !== "transferChecked")
+            continue;
+        // For SPL transfers we need to map source/dest token accounts back to owners.
+        // The pre/post token balances expose this cleanly.
+        const owners = (tx.meta.postTokenBalances ?? []).reduce((acc, b) => {
+            if (b.owner)
+                acc[b.accountIndex] = b.owner;
+            return acc;
+        }, {});
+        const sourceIdx = tx.transaction.message.accountKeys.findIndex((k) => k.pubkey.toBase58() === info.source);
+        const destIdx = tx.transaction.message.accountKeys.findIndex((k) => k.pubkey.toBase58() === info.destination);
+        const sourceOwner = sourceIdx >= 0 ? owners[sourceIdx] ?? info.source : info.source;
+        const destOwner = destIdx >= 0 ? owners[destIdx] ?? info.destination : info.destination;
+        const isSend = info.authority === ownerAddress || sourceOwner === ownerAddress;
+        const isReceive = destOwner === ownerAddress;
+        if (!isSend && !isReceive)
+            continue;
+        const rawAmount = info.tokenAmount?.amount ?? info.amount ?? "0";
+        const decimals = info.tokenAmount?.decimals ?? 6;
+        const amount = Number(rawAmount) / 10 ** decimals;
+        return {
+            timestamp: null, // filled in by caller
+            network: "solana",
+            signature,
+            direction: isSend ? "send" : "receive",
+            counterparty: isSend ? destOwner ?? "" : sourceOwner ?? "",
+            amountUsdc: amount,
+        };
+    }
+    return null;
+}
+//# sourceMappingURL=solana.js.map

package/dist/history/solana.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"solana.js","sourceRoot":"","sources":["../../src/history/solana.ts"],"names":[],"mappings":"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"}

package/dist/history/types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Unified history shape across networks. One entry per USDC transfer in or
+ * out of the wallet.
+ *
+ * v1 only surfaces USDC because that's what xPay actually transacts in
+ * (x402 is USDC-denominated). Future versions can extend `asset` to other
+ * tokens or even non-fungible payments.
+ */
+import type { Network } from "../types.js";
+export interface HistoryEntry {
+    /** Unix ms timestamp the tx was confirmed (best-effort). */
+    timestamp: number | null;
+    /** Network the tx happened on. */
+    network: Network;
+    /** Settlement signature / tx hash. */
+    signature: string;
+    /** "send" when wallet was the sender, "receive" when the receiver. */
+    direction: "send" | "receive";
+    /** Other side of the transfer. */
+    counterparty: string;
+    /** Human USDC amount (positive, with 6-decimal precision). */
+    amountUsdc: number;
+    /** "confirmed" / "finalized" / "failed" — best-effort, may be undefined. */
+    status?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/history/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/history/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,WAAW,YAAY;IAC3B,4DAA4D;IAC5D,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,kCAAkC;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,kCAAkC;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,8DAA8D;IAC9D,UAAU,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/dist/history/types.js

@@ -0,0 +1,10 @@
+/**
+ * Unified history shape across networks. One entry per USDC transfer in or
+ * out of the wallet.
+ *
+ * v1 only surfaces USDC because that's what xPay actually transacts in
+ * (x402 is USDC-denominated). Future versions can extend `asset` to other
+ * tokens or even non-fungible payments.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/history/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/history/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}