solverr-agent 0.0.0-stage → 0.1.0

package/dist/chains/chain-wallet.d.ts

@@ -0,0 +1,15 @@
+import type { WalletAsset } from "../assets.js";
+export interface TransferResult {
+    hash: string;
+}
+/** A key-holding wallet on one chain that can read balances and send exact token amounts. */
+export interface ChainWallet {
+    /** 1Click blockchain code. */
+    readonly blockchain: string;
+    readonly address: string;
+    balance(asset: WalletAsset): Promise<bigint>;
+    isValidRecipient(address: string): boolean;
+    /** Sends exactly `amount` base units of `asset` to `to`. Errors before broadcasting mean no funds left;
+        after broadcasting it throws only `PaymentError` with `fundsSent: true`. */
+    transfer(asset: WalletAsset, to: string, amount: bigint): Promise<TransferResult>;
+}

package/dist/chains/chain-wallet.js

@@ -0,0 +1 @@
+export {};

package/dist/chains/near.d.ts

@@ -0,0 +1,28 @@
+import type { WalletAsset } from "../assets.js";
+import type { ChainWallet, TransferResult } from "./chain-wallet.js";
+interface NearWalletOptions {
+    accountId: string;
+    /** `ed25519:…` private key. */
+    privateKey: string;
+    rpcUrl?: string;
+    requestTimeoutMs?: number;
+}
+/** NEAR wallet paying with NEP-141 tokens through `ft_transfer`, registering the recipient's token storage first when needed. */
+export declare class NearWallet implements ChainWallet {
+    readonly blockchain = "near";
+    readonly address: string;
+    private readonly provider;
+    private readonly account;
+    private readonly requestTimeoutMs;
+    private readonly rpcUrl;
+    constructor(options: NearWalletOptions);
+    isValidRecipient(address: string): boolean;
+    balance(asset: WalletAsset): Promise<bigint>;
+    transfer(asset: WalletAsset, to: string, amount: bigint): Promise<TransferResult>;
+    private contractOf;
+    private view;
+    /** Awaits an RPC call within `timeoutMs`; its error text names only the RPC origin, since the full URL may carry an API key. */
+    private rpc;
+    private assertGasBalance;
+}
+export {};

package/dist/chains/near.js

@@ -0,0 +1,96 @@
+import { createHash } from "node:crypto";
+import { Account, JsonRpcProvider, actions, baseEncode, teraToGas, yoctoToNear } from "near-api-js";
+import { DEFAULT_NEAR_RPC_URL, DEFAULT_REQUEST_TIMEOUT_MS, DEFAULT_TRANSFER_TIMEOUT_MS } from "../config.js";
+import { PaymentError, errorSummary } from "../errors.js";
+import { TimeoutError, withTimeout } from "../timeout.js";
+const ACCOUNT_ID_PATTERN = /^(([a-z\d]+[-_])*[a-z\d]+\.)*([a-z\d]+[-_])*[a-z\d]+$/;
+const FUNCTION_CALL_GAS = teraToGas("30");
+const ONE_YOCTO = 1n;
+/** Native NEAR kept back for gas (two 30 TGas calls cost well under 0.01 NEAR). */
+const GAS_RESERVE_YOCTO = 10n ** 22n;
+const STORAGE_PRICE_PER_BYTE = 10n ** 19n;
+const RPC_RETRIES = { retries: 2, wait: 500, backoff: 2 };
+function isNearAccountId(value) {
+    return value.length >= 2 && value.length <= 64 && ACCOUNT_ID_PATTERN.test(value);
+}
+/** NEAR wallet paying with NEP-141 tokens through `ft_transfer`, registering the recipient's token storage first when needed. */
+export class NearWallet {
+    blockchain = "near";
+    address;
+    provider;
+    account;
+    requestTimeoutMs;
+    rpcUrl;
+    constructor(options) {
+        if (!isNearAccountId(options.accountId))
+            throw new Error("near.accountId is not a valid NEAR account ID.");
+        if (!/^(ed25519|secp256k1):/.test(options.privateKey))
+            throw new Error("near.privateKey must start with ed25519: or secp256k1:.");
+        this.address = options.accountId;
+        this.rpcUrl = options.rpcUrl ?? DEFAULT_NEAR_RPC_URL;
+        this.provider = new JsonRpcProvider({ url: this.rpcUrl }, RPC_RETRIES);
+        this.account = new Account(options.accountId, this.provider, options.privateKey);
+        this.requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    }
+    isValidRecipient(address) {
+        return isNearAccountId(address);
+    }
+    async balance(asset) {
+        const balance = await this.view(this.contractOf(asset), "ft_balance_of", { account_id: this.address });
+        return BigInt(balance ?? "0");
+    }
+    async transfer(asset, to, amount) {
+        if (!this.isValidRecipient(to))
+            throw new PaymentError("quote_mismatch", `The deposit address ${to} is not a valid NEAR account.`);
+        const contract = this.contractOf(asset);
+        const registered = await this.view(contract, "storage_balance_of", { account_id: to });
+        const transferActions = [];
+        let storageCost = 0n;
+        if (registered == null) {
+            const bounds = await this.view(contract, "storage_balance_bounds", {});
+            storageCost = BigInt(bounds?.min ?? "0");
+            transferActions.push(actions.functionCall("storage_deposit", { account_id: to, registration_only: true }, FUNCTION_CALL_GAS, storageCost));
+        }
+        transferActions.push(actions.functionCall("ft_transfer", { receiver_id: to, amount: amount.toString() }, FUNCTION_CALL_GAS, ONE_YOCTO));
+        await this.assertGasBalance(storageCost);
+        const signed = await this.rpc(this.account.createSignedTransaction({ receiverId: contract, actions: transferActions }), this.requestTimeoutMs, "Preparing the NEAR transaction");
+        const hash = baseEncode(createHash("sha256").update(signed.transaction.encode()).digest());
+        try {
+            const outcome = await this.rpc(this.provider.sendTransactionUntil(signed, "EXECUTED_OPTIMISTIC"), DEFAULT_TRANSFER_TIMEOUT_MS, "The NEAR transfer");
+            if (typeof outcome.status === "object" && "Failure" in outcome.status) {
+                throw new PaymentError("transfer_failed", `The NEAR transfer ${hash} failed on-chain.`, true);
+            }
+            return { hash };
+        }
+        catch (error) {
+            if (error instanceof TimeoutError)
+                return { hash };
+            if (error instanceof PaymentError)
+                throw error;
+            throw new PaymentError("transfer_failed", `The NEAR transfer ${hash} was not accepted: ${errorSummary(error)}`, true);
+        }
+    }
+    contractOf(asset) {
+        if (asset.blockchain !== "near" || !asset.contract_address)
+            throw new Error(`${asset.symbol} is not a NEP-141 token on NEAR.`);
+        return asset.contract_address;
+    }
+    view(contractId, method, args) {
+        return this.rpc(this.provider.callFunction({ contractId, method, args }), this.requestTimeoutMs, `NEAR ${method}`);
+    }
+    /** Awaits an RPC call within `timeoutMs`; its error text names only the RPC origin, since the full URL may carry an API key. */
+    rpc(call, timeoutMs, label) {
+        return withTimeout(call, timeoutMs, label).catch((error) => {
+            if (!(error instanceof Error) || !error.message.includes(this.rpcUrl))
+                throw error;
+            throw new Error(error.message.replaceAll(this.rpcUrl, URL.canParse(this.rpcUrl) ? new URL(this.rpcUrl).origin : "the NEAR RPC"));
+        });
+    }
+    async assertGasBalance(storageCost) {
+        const account = await this.rpc(this.provider.viewAccount({ accountId: this.address }), this.requestTimeoutMs, "NEAR account lookup");
+        const available = account.amount - BigInt(account.storage_usage) * STORAGE_PRICE_PER_BYTE;
+        if (available < storageCost + GAS_RESERVE_YOCTO) {
+            throw new PaymentError("no_funds", `${this.address} needs at least ${yoctoToNear(storageCost + GAS_RESERVE_YOCTO, 4)} NEAR available for gas and token storage.`);
+        }
+    }
+}

package/dist/challenge.d.ts

@@ -0,0 +1,11 @@
+import { type SolverrRequirementExtra, type PaymentRequired, type PaymentRequirements } from "solverr-x402";
+/** A validated `solverr` payment requirement from a 402 response. */
+export interface SolverrChallenge {
+    paymentRequired: PaymentRequired;
+    requirement: PaymentRequirements;
+    extra: SolverrRequirementExtra;
+    tokensUrl: string;
+}
+/** Returns the `solverr` requirement of a `PAYMENT-REQUIRED` header; `undefined` when the header is missing, undecodable or offers none.
+    An incomplete requirement, bad endpoint URLs or an untrusted gateway throw `PaymentError`. */
+export declare function parseChallenge(header: string | null, trustedGateways: readonly string[]): SolverrChallenge | undefined;

package/dist/challenge.js

@@ -0,0 +1,75 @@
+import { SOLVERR_SCHEME, X402_VERSION, decodePaymentRequiredHeader, readHeader, secureUrl, } from "solverr-x402";
+import { PaymentError } from "./errors.js";
+const INVOICE_ENDPOINT = /^(?<root>(?:\/[^/]+)*?\/api\/v1)\/invoices\/(?<id>[^/]+)\/(?<action>quote|deposit|status)$/;
+const isText = (value) => typeof value === "string" && value.length > 0;
+/** A percent-decoded path segment, or `undefined` when its escapes are malformed. */
+function decodedSegment(segment) {
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseEndpoint(value, invoiceId, action) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new PaymentError("invalid_challenge", `The payment challenge has an invalid ${action} URL.`);
+    }
+    try {
+        secureUrl(url.href, `${action} URL`);
+    }
+    catch {
+        throw new PaymentError("untrusted_gateway", `The payment challenge's ${action} URL must use https.`);
+    }
+    const match = INVOICE_ENDPOINT.exec(url.pathname);
+    if (!match?.groups || decodedSegment(match.groups.id) !== invoiceId || match.groups.action !== action || url.search || url.hash) {
+        throw new PaymentError("invalid_challenge", `The payment challenge's ${action} URL does not point to invoice ${invoiceId}.`);
+    }
+    return { origin: url.origin, root: `${url.origin}${match.groups.root}` };
+}
+/** Returns the `solverr` requirement of a `PAYMENT-REQUIRED` header; `undefined` when the header is missing, undecodable or offers none.
+    An incomplete requirement, bad endpoint URLs or an untrusted gateway throw `PaymentError`. */
+export function parseChallenge(header, trustedGateways) {
+    const paymentRequired = readHeader(header, decodePaymentRequiredHeader);
+    if (!paymentRequired || paymentRequired.x402Version !== X402_VERSION || !Array.isArray(paymentRequired.accepts))
+        return undefined;
+    const requirement = paymentRequired.accepts.find((entry) => entry?.scheme === SOLVERR_SCHEME);
+    if (!requirement)
+        return undefined;
+    const extra = requirement.extra;
+    const settlement = extra?.settlement;
+    if (!extra ||
+        !isText(extra.invoice_id) ||
+        !isText(extra.mode) ||
+        !isText(extra.quote_url) ||
+        !isText(extra.deposit_url) ||
+        !isText(extra.status_url) ||
+        !isText(extra.price) ||
+        !isText(extra.currency) ||
+        !isText(extra.expires_at) ||
+        Number.isNaN(Date.parse(extra.expires_at)) ||
+        !settlement ||
+        !isText(settlement.asset_id) ||
+        !isText(settlement.symbol) ||
+        !isText(settlement.blockchain) ||
+        !isText(settlement.amount)) {
+        throw new PaymentError("invalid_challenge", "The payment challenge is missing invoice details.");
+    }
+    const endpoints = [
+        parseEndpoint(extra.quote_url, extra.invoice_id, "quote"),
+        parseEndpoint(extra.deposit_url, extra.invoice_id, "deposit"),
+        parseEndpoint(extra.status_url, extra.invoice_id, "status"),
+    ];
+    if (endpoints.some((endpoint) => endpoint.root !== endpoints[0].root)) {
+        throw new PaymentError("invalid_challenge", "The payment challenge's URLs point to different servers.");
+    }
+    const gatewayOrigin = endpoints[0].origin;
+    if (!trustedGateways.some((trusted) => new URL(trusted).origin === gatewayOrigin)) {
+        throw new PaymentError("untrusted_gateway", `The payment gateway ${gatewayOrigin} is not in the trusted gateway list.`);
+    }
+    return { paymentRequired, requirement, extra: extra, tokensUrl: `${endpoints[0].root}/tokens` };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { createAgentWallet } from "./agent-wallet.js";
+import { agentOptionsFromEnv } from "./env.js";
+import { errorSummary } from "./errors.js";
+import { normalizeLimits } from "./limits.js";
+import { serveAgentMcp } from "./mcp-server.js";
+const USAGE = `Usage: solverr-agent mcp
+
+Starts a local MCP server on stdin/stdout with the tools pay_url, get_balances, get_spending and set_limits.
+
+Environment:
+  AGENT_NEAR_ACCOUNT, AGENT_NEAR_KEY   NEAR account and ed25519: private key
+  AGENT_BASE_KEY                       Base private key (0x…)
+  AGENT_LIMIT_PER_PAYMENT_USD          Largest single payment in USD (required)
+  AGENT_LIMIT_DAILY_USD                Largest total over 24 hours in USD (required)
+  AGENT_ALLOW_HOSTS                    Comma-separated hosts the agent may request and pay (required)
+  AGENT_TRUSTED_GATEWAYS               Comma-separated Solverr URLs to pay through (required)
+  AGENT_NEAR_RPC_URL, AGENT_BASE_RPC_URL, AGENT_SPEND_LOG   Optional
+  AGENT_PAYMENT_TIMEOUT_MS, AGENT_RESOURCE_TIMEOUT_MS      Optional timeouts in ms
+`;
+function packageVersion() {
+    const manifest = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    return manifest.version;
+}
+function main(argv) {
+    const [command] = argv;
+    if (command !== "mcp") {
+        process.stderr.write(USAGE);
+        process.exitCode = command === "--help" || command === "-h" ? 0 : 1;
+        return;
+    }
+    const options = agentOptionsFromEnv();
+    const agent = createAgentWallet(options);
+    serveAgentMcp(agent, { name: "solverr-agent", version: packageVersion(), ceiling: normalizeLimits(options.limits) });
+}
+try {
+    main(process.argv.slice(2));
+}
+catch (error) {
+    process.stderr.write(`solverr-agent: ${errorSummary(error)}\n`);
+    process.exitCode = 1;
+}

package/dist/coin-selection.d.ts

@@ -0,0 +1,29 @@
+import { type WalletAsset } from "./assets.js";
+import type { ChainWallet } from "./chains/chain-wallet.js";
+import type { GatewayToken } from "./gateway.js";
+/** A coin the agent holds enough of to try paying with. Lower `tier` is preferred. */
+export interface PaymentOption {
+    asset: WalletAsset;
+    wallet: ChainWallet;
+    priceUsd: number;
+    balance: bigint;
+    /** Expected amount in base units, with headroom for fees and slippage. */
+    estimatedAmount: bigint;
+    /** 0: the settlement coin itself, 1: the same coin on another chain, 2: another USD stablecoin, 3: any other coin. */
+    tier: number;
+}
+export interface SelectionInput {
+    wallets: readonly ChainWallet[];
+    assets: readonly WalletAsset[];
+    tokens: readonly GatewayToken[];
+    settlement: {
+        asset_id: string;
+        symbol: string;
+    };
+    amountUsd: number;
+}
+/** Ranks held coins for paying `amountUsd`: same-coin routes first (no swap minimum, lowest fee), then stablecoins, then others. */
+export declare function rankPaymentOptions(input: SelectionInput): Promise<{
+    options: PaymentOption[];
+    skipped: string[];
+}>;

package/dist/coin-selection.js

@@ -0,0 +1,60 @@
+import { parseUnits } from "viem";
+import { isUsdStablecoin } from "./assets.js";
+import { ESTIMATE_BUFFER } from "./config.js";
+import { errorSummary } from "./errors.js";
+function tierOf(asset, settlement) {
+    if (asset.asset_id === settlement.asset_id)
+        return 0;
+    if (asset.symbol.toUpperCase() === settlement.symbol.toUpperCase())
+        return 1;
+    return isUsdStablecoin(asset.symbol) ? 2 : 3;
+}
+/** Converts a USD amount to base units of a coin at `priceUsd`, rounded up. */
+function usdToBaseUnits(amountUsd, priceUsd, decimals) {
+    return parseUnits((amountUsd / priceUsd).toFixed(decimals), decimals) + 1n;
+}
+/** Ranks held coins for paying `amountUsd`: same-coin routes first (no swap minimum, lowest fee), then stablecoins, then others. */
+export async function rankPaymentOptions(input) {
+    const walletByChain = new Map(input.wallets.map((wallet) => [wallet.blockchain, wallet]));
+    const prices = new Map(input.tokens.map((token) => [token.asset_id, token]));
+    const candidates = [...input.assets];
+    const settlementToken = prices.get(input.settlement.asset_id);
+    if (settlementToken && walletByChain.has(settlementToken.blockchain) && !candidates.some((asset) => asset.asset_id === settlementToken.asset_id)) {
+        const { asset_id, symbol, blockchain, decimals, contract_address } = settlementToken;
+        candidates.push({ asset_id, symbol, blockchain, decimals, contract_address });
+    }
+    const skipped = [];
+    const checks = candidates.map(async (asset) => {
+        const wallet = walletByChain.get(asset.blockchain);
+        const listed = prices.get(asset.asset_id);
+        const priceUsd = listed?.price_usd;
+        if (!wallet)
+            return undefined;
+        if (!listed || !priceUsd || priceUsd <= 0) {
+            skipped.push(`${asset.symbol} on ${asset.blockchain}: no price from the gateway`);
+            return undefined;
+        }
+        /** Amounts and spending limits are worked out with the configured decimals, so a coin set up with the wrong ones is never used. */
+        if (listed.decimals !== asset.decimals) {
+            skipped.push(`${asset.symbol} on ${asset.blockchain}: set to ${asset.decimals} decimals, but the gateway lists ${listed.decimals}`);
+            return undefined;
+        }
+        const estimatedAmount = usdToBaseUnits(input.amountUsd * (1 + ESTIMATE_BUFFER), priceUsd, asset.decimals);
+        let balance;
+        try {
+            balance = await wallet.balance(asset);
+        }
+        catch (error) {
+            skipped.push(`${asset.symbol} on ${asset.blockchain}: balance unavailable (${errorSummary(error, 120)})`);
+            return undefined;
+        }
+        if (balance < estimatedAmount) {
+            skipped.push(`${asset.symbol} on ${asset.blockchain}: balance too low`);
+            return undefined;
+        }
+        return { asset, wallet, priceUsd, balance, estimatedAmount, tier: tierOf(asset, input.settlement) };
+    });
+    const options = (await Promise.all(checks)).filter((option) => option !== undefined);
+    options.sort((a, b) => a.tier - b.tier);
+    return { options, skipped };
+}

package/dist/config.d.ts

@@ -0,0 +1,33 @@
+export declare const DEFAULT_NEAR_RPC_URL = "https://free.rpc.fastnear.com";
+export declare const DEFAULT_BASE_RPC_URL = "https://mainnet.base.org";
+/** Timeout for one RPC or Solverr API call. */
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 15000;
+/** Default `resourceTimeoutMs`: the first resource request when the caller passes no `signal`, and every paid attempt, which ignores the
+    caller's signal; each includes reading the body. */
+export declare const DEFAULT_RESOURCE_TIMEOUT_MS = 30000;
+/** Total sends of the paid request, the first included (repeated after network errors, 429 or 5xx), and the delay step between them. */
+export declare const PAID_REQUEST_ATTEMPTS = 3;
+export declare const PAID_REQUEST_RETRY_MS = 1000;
+/** Longest wait between paid attempts, even when a 429 or 503 asks for more in `Retry-After`; a paywall's challenge limit counts per minute. */
+export declare const PAID_REQUEST_MAX_WAIT_MS = 60000;
+/** How long to wait for an invoice to become paid after the transfer. */
+export declare const DEFAULT_PAYMENT_TIMEOUT_MS = 180000;
+/** How long to wait for a transfer to be included on-chain before relying on the gateway to detect it. */
+export declare const DEFAULT_TRANSFER_TIMEOUT_MS = 60000;
+export declare const STATUS_POLL_INTERVAL_MS = 3000;
+/** Different coins are tried in turn when a quote is refused, up to this many. */
+export declare const MAX_QUOTE_ATTEMPTS = 3;
+/** Headroom over the settlement value when estimating the amount a coin must cover (fees and slippage). */
+export declare const ESTIMATE_BUFFER = 0.03;
+/** A quote may cost at most this share more than the invoice's USD value (not the buffered estimate) before the payment is refused. */
+export declare const MAX_QUOTE_OVER_ESTIMATE = 0.1;
+/** A quote must stay valid at least this long after it is received. */
+export declare const MIN_QUOTE_VALIDITY_MS = 60000;
+/** Entries older than this are dropped from the spend log. */
+export declare const SPEND_LOG_RETENTION_MS: number;
+/** How often a busy spend log lock is retried, and how long to wait for it in total. */
+export declare const SPEND_LOG_LOCK_RETRY_MS = 50;
+export declare const SPEND_LOG_LOCK_TIMEOUT_MS = 10000;
+/** A lock file older than this was left by a process that stopped while holding it. */
+export declare const SPEND_LOG_STALE_LOCK_MS = 30000;
+export declare const DAY_MS: number;

package/dist/config.js

@@ -0,0 +1,33 @@
+export const DEFAULT_NEAR_RPC_URL = "https://free.rpc.fastnear.com";
+export const DEFAULT_BASE_RPC_URL = "https://mainnet.base.org";
+/** Timeout for one RPC or Solverr API call. */
+export const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
+/** Default `resourceTimeoutMs`: the first resource request when the caller passes no `signal`, and every paid attempt, which ignores the
+    caller's signal; each includes reading the body. */
+export const DEFAULT_RESOURCE_TIMEOUT_MS = 30_000;
+/** Total sends of the paid request, the first included (repeated after network errors, 429 or 5xx), and the delay step between them. */
+export const PAID_REQUEST_ATTEMPTS = 3;
+export const PAID_REQUEST_RETRY_MS = 1_000;
+/** Longest wait between paid attempts, even when a 429 or 503 asks for more in `Retry-After`; a paywall's challenge limit counts per minute. */
+export const PAID_REQUEST_MAX_WAIT_MS = 60_000;
+/** How long to wait for an invoice to become paid after the transfer. */
+export const DEFAULT_PAYMENT_TIMEOUT_MS = 180_000;
+/** How long to wait for a transfer to be included on-chain before relying on the gateway to detect it. */
+export const DEFAULT_TRANSFER_TIMEOUT_MS = 60_000;
+export const STATUS_POLL_INTERVAL_MS = 3_000;
+/** Different coins are tried in turn when a quote is refused, up to this many. */
+export const MAX_QUOTE_ATTEMPTS = 3;
+/** Headroom over the settlement value when estimating the amount a coin must cover (fees and slippage). */
+export const ESTIMATE_BUFFER = 0.03;
+/** A quote may cost at most this share more than the invoice's USD value (not the buffered estimate) before the payment is refused. */
+export const MAX_QUOTE_OVER_ESTIMATE = 0.1;
+/** A quote must stay valid at least this long after it is received. */
+export const MIN_QUOTE_VALIDITY_MS = 60_000;
+/** Entries older than this are dropped from the spend log. */
+export const SPEND_LOG_RETENTION_MS = 30 * 24 * 60 * 60_000;
+/** How often a busy spend log lock is retried, and how long to wait for it in total. */
+export const SPEND_LOG_LOCK_RETRY_MS = 50;
+export const SPEND_LOG_LOCK_TIMEOUT_MS = 10_000;
+/** A lock file older than this was left by a process that stopped while holding it. */
+export const SPEND_LOG_STALE_LOCK_MS = 30_000;
+export const DAY_MS = 24 * 60 * 60_000;

package/dist/env.d.ts

@@ -0,0 +1,4 @@
+import type { AgentWalletOptions } from "./agent-wallet.js";
+/** Reads AGENT_* variables. Required: AGENT_NEAR_ACCOUNT + AGENT_NEAR_KEY or AGENT_BASE_KEY, AGENT_LIMIT_PER_PAYMENT_USD, AGENT_LIMIT_DAILY_USD,
+    AGENT_ALLOW_HOSTS, AGENT_TRUSTED_GATEWAYS; optional: AGENT_NEAR_RPC_URL, AGENT_BASE_RPC_URL, AGENT_SPEND_LOG, AGENT_PAYMENT_TIMEOUT_MS, AGENT_RESOURCE_TIMEOUT_MS. */
+export declare function agentOptionsFromEnv(env?: NodeJS.ProcessEnv): AgentWalletOptions;

package/dist/env.js

@@ -0,0 +1,49 @@
+function required(env, name) {
+    const value = env[name]?.trim();
+    if (!value)
+        throw new Error(`${name} is required.`);
+    return value;
+}
+function usd(env, name) {
+    const value = Number(required(env, name));
+    if (!Number.isFinite(value) || value < 0)
+        throw new Error(`${name} must be a USD amount, such as 5.`);
+    return value;
+}
+function milliseconds(env, name) {
+    const value = env[name]?.trim();
+    if (!value)
+        return undefined;
+    const ms = Number(value);
+    if (!Number.isInteger(ms) || ms <= 0)
+        throw new Error(`${name} must be a whole number of milliseconds.`);
+    return ms;
+}
+const list = (value) => (value ?? "").split(",").map((item) => item.trim()).filter(Boolean);
+/** Reads AGENT_* variables. Required: AGENT_NEAR_ACCOUNT + AGENT_NEAR_KEY or AGENT_BASE_KEY, AGENT_LIMIT_PER_PAYMENT_USD, AGENT_LIMIT_DAILY_USD,
+    AGENT_ALLOW_HOSTS, AGENT_TRUSTED_GATEWAYS; optional: AGENT_NEAR_RPC_URL, AGENT_BASE_RPC_URL, AGENT_SPEND_LOG, AGENT_PAYMENT_TIMEOUT_MS, AGENT_RESOURCE_TIMEOUT_MS. */
+export function agentOptionsFromEnv(env = process.env) {
+    const nearAccount = env.AGENT_NEAR_ACCOUNT?.trim();
+    const nearKey = env.AGENT_NEAR_KEY?.trim();
+    if (!!nearAccount !== !!nearKey)
+        throw new Error("Set both AGENT_NEAR_ACCOUNT and AGENT_NEAR_KEY to use a NEAR wallet.");
+    const baseKey = env.AGENT_BASE_KEY?.trim();
+    if (!nearAccount && !baseKey)
+        throw new Error("Set AGENT_NEAR_ACCOUNT and AGENT_NEAR_KEY, or AGENT_BASE_KEY.");
+    const allow = list(env.AGENT_ALLOW_HOSTS);
+    if (allow.length === 0)
+        throw new Error("AGENT_ALLOW_HOSTS is required: a comma-separated list of hosts the agent may pay.");
+    const trustedGateways = list(env.AGENT_TRUSTED_GATEWAYS);
+    if (trustedGateways.length === 0) {
+        throw new Error("AGENT_TRUSTED_GATEWAYS is required: a comma-separated list of Solverr URLs the agent may pay through, such as https://pay.example.com.");
+    }
+    return {
+        ...(nearAccount && nearKey ? { near: { accountId: nearAccount, privateKey: nearKey, rpcUrl: env.AGENT_NEAR_RPC_URL?.trim() || undefined } } : {}),
+        ...(baseKey ? { base: { privateKey: baseKey, rpcUrl: env.AGENT_BASE_RPC_URL?.trim() || undefined } } : {}),
+        limits: { perPaymentUsd: usd(env, "AGENT_LIMIT_PER_PAYMENT_USD"), dailyUsd: usd(env, "AGENT_LIMIT_DAILY_USD"), allow },
+        spendLogPath: env.AGENT_SPEND_LOG?.trim() || undefined,
+        trustedGateways,
+        paymentTimeoutMs: milliseconds(env, "AGENT_PAYMENT_TIMEOUT_MS"),
+        resourceTimeoutMs: milliseconds(env, "AGENT_RESOURCE_TIMEOUT_MS"),
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,10 @@
+export type PaymentErrorCode = "host_not_allowed" | "per_payment_limit" | "daily_limit" | "invalid_challenge" | "untrusted_gateway" | "test_invoice" | "invoice_expired" | "no_funds" | "quote_unavailable" | "quote_mismatch" | "transfer_failed" | "payment_failed" | "payment_timeout" | "payment_unconfirmed" | "paid_request_failed" | "body_not_replayable";
+/** First line of an error message, bounded, for logs and tool output. */
+export declare function errorSummary(error: unknown, maxLength?: number): string;
+/** A payment the agent refused or could not complete; `fundsSent` is true once a transfer was broadcast, and `invoiceId` then names its invoice. */
+export declare class PaymentError extends Error {
+    readonly code: PaymentErrorCode;
+    readonly fundsSent: boolean;
+    readonly invoiceId?: string | undefined;
+    constructor(code: PaymentErrorCode, message: string, fundsSent?: boolean, invoiceId?: string | undefined);
+}

package/dist/errors.js

@@ -0,0 +1,17 @@
+/** First line of an error message, bounded, for logs and tool output. */
+export function errorSummary(error, maxLength = 300) {
+    return (error instanceof Error ? error.message : String(error)).split("\n")[0].slice(0, maxLength);
+}
+/** A payment the agent refused or could not complete; `fundsSent` is true once a transfer was broadcast, and `invoiceId` then names its invoice. */
+export class PaymentError extends Error {
+    code;
+    fundsSent;
+    invoiceId;
+    constructor(code, message, fundsSent = false, invoiceId) {
+        super(message);
+        this.code = code;
+        this.fundsSent = fundsSent;
+        this.invoiceId = invoiceId;
+        this.name = "PaymentError";
+    }
+}

package/dist/gateway.d.ts

@@ -0,0 +1,43 @@
+/** One coin from `GET /api/v1/tokens`. */
+export interface GatewayToken {
+    asset_id: string;
+    symbol: string;
+    blockchain: string;
+    decimals: number;
+    price_usd: number;
+    contract_address: string | null;
+}
+/** Payment attempt returned by `POST /api/v1/invoices/:id/quote`. */
+export interface GatewayQuote {
+    id: string;
+    coin: {
+        asset_id: string;
+        symbol: string;
+        blockchain: string;
+        decimals: number;
+    };
+    amount_in: string;
+    amount_in_base: string;
+    deposit_address: string;
+    deposit_memo: string | null;
+    refund_address: string;
+    deadline: string;
+}
+/** Public checkout status from `GET /api/v1/invoices/:id/status`. */
+export interface GatewayStatus {
+    status: string;
+    payment: (GatewayQuote & {
+        status: string;
+    }) | null;
+}
+/** Public Solverr API calls the agent makes for one invoice. URLs come from a validated challenge. */
+export declare class GatewayClient {
+    private readonly timeoutMs;
+    constructor(timeoutMs: number);
+    listTokens(tokensUrl: string): Promise<GatewayToken[]>;
+    /** Asks for a deposit address; retried once, since the server returns the same open quote for the same coin and refund address. */
+    requestQuote(quoteUrl: string, originAsset: string, refundAddress: string): Promise<GatewayQuote>;
+    /** Reports the transfer for the payment it was sent to, so a newer address on the invoice cannot take the report. */
+    reportDeposit(depositUrl: string, txHash: string, paymentId: string): Promise<GatewayStatus>;
+    getStatus(statusUrl: string): Promise<GatewayStatus>;
+}

package/dist/gateway.js

@@ -0,0 +1,24 @@
+import { requestJson } from "solverr-x402";
+const RETRIES = 2;
+/** Public Solverr API calls the agent makes for one invoice. URLs come from a validated challenge. */
+export class GatewayClient {
+    timeoutMs;
+    constructor(timeoutMs) {
+        this.timeoutMs = timeoutMs;
+    }
+    async listTokens(tokensUrl) {
+        const body = await requestJson({ method: "GET", url: tokensUrl, timeoutMs: this.timeoutMs, retries: RETRIES });
+        return body.data;
+    }
+    /** Asks for a deposit address; retried once, since the server returns the same open quote for the same coin and refund address. */
+    requestQuote(quoteUrl, originAsset, refundAddress) {
+        return requestJson({ method: "POST", url: quoteUrl, body: { origin_asset: originAsset, refund_address: refundAddress }, timeoutMs: this.timeoutMs, retries: 1 });
+    }
+    /** Reports the transfer for the payment it was sent to, so a newer address on the invoice cannot take the report. */
+    reportDeposit(depositUrl, txHash, paymentId) {
+        return requestJson({ method: "POST", url: depositUrl, body: { tx_hash: txHash, payment_id: paymentId }, timeoutMs: this.timeoutMs, retries: RETRIES });
+    }
+    getStatus(statusUrl) {
+        return requestJson({ method: "GET", url: statusUrl, timeoutMs: this.timeoutMs, retries: RETRIES });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { createAgentWallet } from "./agent-wallet.js";
+export type { AgentFetchInit, AgentWallet, AgentWalletOptions, AssetBalance, SpendingSummary } from "./agent-wallet.js";
+export { agentOptionsFromEnv } from "./env.js";
+export { serveAgentMcp } from "./mcp-server.js";
+export type { McpServerOptions } from "./mcp-server.js";
+export { PaymentError } from "./errors.js";
+export type { PaymentErrorCode } from "./errors.js";
+export type { SpendingLimits } from "./limits.js";
+export type { SpendEntry, SpendStatus } from "./spend-log.js";
+export { DEFAULT_ASSETS } from "./assets.js";
+export type { WalletAsset } from "./assets.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { createAgentWallet } from "./agent-wallet.js";
+export { agentOptionsFromEnv } from "./env.js";
+export { serveAgentMcp } from "./mcp-server.js";
+export { PaymentError } from "./errors.js";
+export { DEFAULT_ASSETS } from "./assets.js";

package/dist/limits.d.ts

@@ -0,0 +1,18 @@
+export interface SpendingLimits {
+    /** Largest single payment in USD. */
+    perPaymentUsd: number;
+    /** Largest total in USD over any rolling 24 hours. */
+    dailyUsd: number;
+    /** Hosts the agent may pay: `api.example.com`, or `*.example.com` for its subdomains. An empty list allows none. */
+    allow: string[];
+}
+/** Validates limits and normalizes host patterns to lowercase. */
+export declare function normalizeLimits(limits: SpendingLimits): SpendingLimits;
+export declare function isHostAllowed(hostname: string, allow: readonly string[]): boolean;
+export declare function assertHostAllowed(limits: SpendingLimits, hostname: string): void;
+/** Throws a `PaymentError` when paying `amountUsd` to `hostname` would break a limit. */
+export declare function enforceLimits(limits: SpendingLimits, payment: {
+    hostname: string;
+    amountUsd: number;
+    spentLast24hUsd: number;
+}): void;