solverr-agent 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Solverr
+
+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

@@ -1,3 +1,209 @@
-# Temporary Holding Version
+# <img src="https://github.com/forcequitx/solverr/raw/main/app/icon.svg" alt="Solverr" width="30" height="30"> solverr-agent
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**A wallet for AI agents that pays Solverr x402 paywalls from NEAR and Base, within the spending limits you set.**
+
+## <img src="https://github.com/forcequitx/solverr/raw/main/assets/icons/lightbulb.svg" width="24" height="24" style="vertical-align: middle; margin-right: 4px;"> Overview
+
+`solverr-agent` is a wallet for AI agents that pays [Solverr](https://www.npmjs.com/package/solverr-x402) x402 paywalls from NEAR and Base, always within the spending limits you set. It also runs as a local MCP server, so Claude Code, Cursor or any MCP client can pay for API calls.
+
+- **Keys:** the agent keeps them in memory on your machine and uses them only to sign transfers -> they are never logged.
+- **Limits:** the agent checks the per-payment limit, the rolling 24-hour limit and the allowed hosts before every quote and again before every transfer -> a payment outside them is refused.
+- **Spend log:** the agent writes every payment to a local JSON spend log -> the daily limit holds across restarts and across agents that share the same log file.
+
+## <img src="https://github.com/forcequitx/solverr/raw/main/assets/icons/package.svg" width="24" height="24" style="vertical-align: middle; margin-right: 4px;"> Install
+
+```bash
+npm install solverr-agent
+```
+
+The package needs Node 22.22.2 or later (required by `near-api-js` 7).
+
+## <img src="https://github.com/forcequitx/solverr/raw/main/assets/icons/code-xml.svg" width="24" height="24" style="vertical-align: middle; margin-right: 4px;"> Use It in Code
+
+```ts
+import { createAgentWallet } from "solverr-agent";
+
+const agent = createAgentWallet({
+  near: { accountId: process.env.AGENT_NEAR_ACCOUNT!, privateKey: process.env.AGENT_NEAR_KEY! },
+  base: { privateKey: process.env.AGENT_BASE_KEY! },
+  limits: { perPaymentUsd: 5, dailyUsd: 20, allow: ["api.example.com"] },
+  trustedGateways: ["https://pay.example.com"],
+});
+
+const res = await agent.fetch("https://api.example.com/premium-data"); // pays a 402 automatically
+console.log(res.status, await res.json());
+
+console.log(await agent.balances());
+console.log(await agent.spending());
+console.log(agent.limits());
+agent.setLimits({ dailyUsd: 10 });
+```
+
+### Options
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `near` | none | `{ accountId, privateKey: "ed25519:…", rpcUrl? }` |
+| `base` | none | `{ privateKey: "0x…", rpcUrl? }` |
+| `limits` | required | `{ perPaymentUsd, dailyUsd, allow }`. `allow` takes hosts such as `api.example.com` or `*.example.com`; an empty list allows nothing |
+| `spendLogPath` | `~/.solverr/agent-spend-log.json` | Local spend log |
+| `assets` | USDC, USDT, wNEAR on NEAR; USDC, ETH on Base | Coins to check and pay with |
+| `trustedGateways` | required | Solverr URLs the agent will pay through, such as `https://pay.example.com`. The gateway prices the invoice, so a paywall that names any other gateway is refused with `untrusted_gateway` |
+| `paymentTimeoutMs` | 180000 | How long to wait for the invoice to be paid after sending |
+| `requestTimeoutMs` | 15000 | Timeout of each RPC and gateway call |
+| `resourceTimeoutMs` | 30000 | Timeout of each paid request, and of the first request when you pass no `signal`, including reading the body. Raise it for endpoints that take longer to answer or stream their body |
+
+RPCs default to `https://free.rpc.fastnear.com` (NEAR) and `https://mainnet.base.org` (Base).
+
+## <img src="https://github.com/forcequitx/solverr/raw/main/assets/icons/triangle-alert.svg" width="24" height="24" style="vertical-align: middle; margin-right: 4px;"> Errors and Retries
+
+### Payment errors
+
+`agent.fetch` throws a `PaymentError` when it refuses or cannot finish a payment. Check `error.code` (`host_not_allowed`, `untrusted_gateway`, `per_payment_limit`, `daily_limit`, `test_invoice`, `no_funds`, `quote_unavailable`, `quote_mismatch`, `payment_timeout`, `payment_unconfirmed`, `paid_request_failed`, …) and `error.fundsSent`. When `fundsSent` is `true`, `error.invoiceId` names the invoice the money went to: read the message before you request that URL again.
+
+When the gateway or a wallet RPC fails before any transfer, `agent.fetch` throws that error (for example a `SolverrApiError`), and nothing was sent. A NEAR RPC error names only the RPC's origin, never its full URL, because that URL may carry an API key.
+
+### Abort signal
+
+A `signal` you pass in `init` covers the first request and the payment up to the transfer. Aborting before then throws the signal's reason, and nothing is sent. Once the transfer starts, the signal no longer applies: the agent always finishes the payment and the paid request, so a slow payment never costs you the response you paid for.
+
+### Retries of the paid request
+
+After paying, the agent sends the request with `PAYMENT-SIGNATURE`, always with the same payment and `resourceTimeoutMs` (30 seconds by default) per attempt. After a network error, 429 or 5xx, it tries again, up to 3 attempts in all. A `402` that follows an attempt with no answer also counts as a failure, because that earlier request may still be using the payment. It waits 1 second, then 2 seconds, between attempts. After a 429 or 503, it waits at least the `Retry-After` the site sends, up to 60 seconds. It stops early when the next wait would end more than `paymentTimeoutMs` after the first attempt. If it still fails, or the site answers `402` to the paid request, `agent.fetch` throws `paid_request_failed` with `fundsSent: true`.
+
+### Kept payments
+
+A site that answers the paid request with an error (400 or higher) does not use the payment, so the invoice can still be redeemed. The wallet keeps such a payment in memory for the same method, origin and path. It also keeps it after `paid_request_failed` from a 429, 5xx, network error, or a `402` that followed an attempt with no answer.
+
+The next time that URL answers `402`, the wallet sends the kept payment again before it pays anything new. This costs nothing and adds nothing to the spend log. The wallet drops the kept payment once the site accepts it. It also drops it when the site answers it with `402`, and then pays the new invoice.
+
+`agent.unusedInvoice(url, method?)` returns the invoice ID of a kept payment. Kept payments are lost when the process stops.
+
+## <img src="https://github.com/forcequitx/solverr/raw/main/assets/icons/server.svg" width="24" height="24" style="vertical-align: middle; margin-right: 4px;"> MCP Server
+
+Start the MCP server:
+
+```bash
+AGENT_BASE_KEY=0x… \
+AGENT_LIMIT_PER_PAYMENT_USD=1 \
+AGENT_LIMIT_DAILY_USD=5 \
+AGENT_ALLOW_HOSTS=api.example.com \
+AGENT_TRUSTED_GATEWAYS=https://pay.example.com \
+npx solverr-agent mcp
+```
+
+Add it to Claude Code:
+
+```bash
+claude mcp add solverr-agent \
+  -e AGENT_NEAR_ACCOUNT=agent.near -e AGENT_NEAR_KEY=ed25519:… \
+  -e AGENT_LIMIT_PER_PAYMENT_USD=1 -e AGENT_LIMIT_DAILY_USD=5 -e AGENT_ALLOW_HOSTS=api.example.com \
+  -e AGENT_TRUSTED_GATEWAYS=https://pay.example.com \
+  -- npx solverr-agent mcp
+```
+
+### Tools
+
+| Tool | What it does |
+| --- | --- |
+| `pay_url` | Fetches `url` on a host in the allow list, with optional `method` (`GET` by default, or `POST`, `PUT`, `PATCH`, `DELETE`), `headers` and `body`. It pays a 402 within the limits, then returns `status`, `content_type`, the receipt as `payment`, `body` and `body_truncated`. Redirects are returned with their `location`, not followed. When the site answers with an error and a paid invoice was not used, the result also has `invoice_id` and `payment_unused: true`. Calling `pay_url` again with the same method and URL sends that payment again |
+| `get_balances` | Balances of the coins the wallet can pay with |
+| `get_spending` | Limits, total of the last 24 hours, recent payments |
+| `set_limits` | Lowers `per_payment_usd` or `daily_usd`, or narrows the `allow` host list. It cannot raise them above the values the server started with, so text on a paid page cannot talk the model into spending more |
+
+### Environment variables
+
+| Variable | Required | Meaning |
+| --- | --- | --- |
+| `AGENT_NEAR_ACCOUNT`, `AGENT_NEAR_KEY` | one wallet | NEAR account and `ed25519:` key |
+| `AGENT_BASE_KEY` | one wallet | Base private key |
+| `AGENT_LIMIT_PER_PAYMENT_USD` | yes | Largest single payment |
+| `AGENT_LIMIT_DAILY_USD` | yes | Largest total over 24 hours |
+| `AGENT_ALLOW_HOSTS` | yes | Comma-separated hosts that `pay_url` may request and pay |
+| `AGENT_TRUSTED_GATEWAYS` | yes | Comma-separated Solverr URLs the agent may pay through |
+| `AGENT_NEAR_RPC_URL`, `AGENT_BASE_RPC_URL` | no | Custom RPCs |
+| `AGENT_SPEND_LOG` | no | Spend log path |
+| `AGENT_PAYMENT_TIMEOUT_MS` | no | Wait for payment, in ms |
+| `AGENT_RESOURCE_TIMEOUT_MS` | no | `resourceTimeoutMs`, in ms |
+
+## <img src="https://github.com/forcequitx/solverr/raw/main/assets/icons/workflow.svg" width="24" height="24" style="vertical-align: middle; margin-right: 4px;"> How a Payment Works
+
+```mermaid
+flowchart TD
+  A["Request url with the caller's method"] -->|not 402| Z[Return response]
+  A -->|402 without a readable solverr offer| Z
+  A -->|402 with solverr scheme| B{Host allowed? Trusted gateway? Live invoice?}
+  B -->|no| X[PaymentError, nothing sent]
+  B -->|yes| C[Price the invoice in USD from /tokens]
+  C --> D{Within per-payment and 24 h limits?}
+  D -->|no| X
+  D -->|yes| E[Reserve the amount in the spend log]
+  E --> F[Rank coins held: coin the business receives, same coin on another chain, stablecoins, others]
+  F --> G[POST quote with own refund address]
+  G -->|422| F
+  G --> H{Coin, refund address, deposit address, amount, deadline, limits all check out?}
+  H -->|no| X
+  H -->|yes| I[Send exact amount_in_base to deposit_address]
+  I --> J[POST deposit tx hash, poll status until paid]
+  J -->|paid| K[Send the same request with PAYMENT-SIGNATURE, up to 3 tries]
+  J -->|underpaid, refunded, failed, timeout, any other error| Y[PaymentError, fundsSent = true, invoiceId]
+  K -->|402, or still failing| Y
+```
+
+How each chain sends the transfer, and how payments take turns:
+
+- **Base:** ERC-20 `transfer`, or a plain ETH transfer for native ETH, signed with viem.
+- **NEAR:** NEP-141 `ft_transfer` with 1 yoctoNEAR. 1Click deposit addresses are usually fresh implicit accounts, so the agent checks `storage_balance_of` first. When the address is not registered with the token, the agent adds `storage_deposit` (the token's `storage_balance_bounds.min`) in the same transaction. Keep a little more than 0.01 NEAR available. The agent holds back 0.01 NEAR for gas, and it also needs the token's storage deposit when the deposit address is new.
+- **One payment at a time:** payments in one process run one at a time. Every spend log write re-reads the file while it holds `agent-spend-log.json.lock`. The limit check and the reservation happen in the same locked step, so two calls or two processes cannot both pass the daily limit. Quotes and transfers run outside the lock.
+
+## <img src="https://github.com/forcequitx/solverr/raw/main/assets/icons/circle-question-mark.svg" width="24" height="24" style="vertical-align: middle; margin-right: 4px;"> Points That Cause Confusion
+
+- **Test invoices are never paid on-chain.** Only the Solverr demo store issues `mode: "test"` invoices, and they have `TEST-` deposit addresses. The agent refuses them with `test_invoice` before it asks for a quote, and it refuses any quote with a `TEST-` address.
+- **Native NEAR is not used to pay.** NEAR Intents takes wNEAR (`wrap.near`). Hold wNEAR, USDC or USDT on NEAR.
+- **Route minimums.** 1Click can set a temporary minimum on a route, which makes the gateway refuse a quote for that coin. The agent prefers the exact coin the business receives, then the same coin on other chains, then other stablecoins. It tries up to three coins and moves on to the next one when a route is refused.
+- **The spend log counts money that may have left the wallet.** Entries that were `sent`, `paid` or `failed` count toward the daily limit. Only `aborted` entries (nothing sent) do not. A corrupt log stops payments instead of resetting the total.
+- **A stuck lock file.** A process that stops while writing can leave `<spend log>.lock` behind. The agent removes a lock older than 30 seconds. A younger one makes a payment wait up to 10 seconds and then fail.
+- **`pay_url` only reaches public addresses.** Besides the allow list, it resolves the host and refuses loopback, private, link-local (including cloud metadata such as `169.254.169.254`), multicast and reserved IPv4 and IPv6 addresses. To reach a local server, put its exact address in `AGENT_ALLOW_HOSTS` and use it in the URL: `127.0.0.1`, `[::1]` or `localhost`. The request then connects only to the addresses that passed this check, so a host whose DNS answer changes afterwards cannot send it to a private network.
+- **Give MCP tool calls enough time.** One `pay_url` call can take about 5 minutes with the default settings: up to 60 seconds to send the transfer, up to 3 minutes (`AGENT_PAYMENT_TIMEOUT_MS`) for the invoice to be paid, then the paid request. Many MCP clients stop waiting for a tool after 60 seconds. The payment still completes, but the model never sees the result and may pay again. Raise your client's tool timeout to at least 5 minutes; in Claude Code, set `MCP_TOOL_TIMEOUT=300000`.
+- **A timeout is not a refusal.** On `payment_timeout` the transfer was sent. Check the status URL in the message before paying again.
+- **`fundsSent: true` means the money left the wallet.** Every error after the transfer, including a spend log or gateway failure, carries `fundsSent: true` and the `invoiceId`. The MCP server returns them as `funds_sent` and `invoice_id`. An error that is not a `PaymentError` comes back with the code `request_failed` and `funds_sent: false`: a gateway or RPC failure before any transfer, a `set_limits` value above the starting one, or a host outside the starting allow list. A spend log write that fails after the transfer does not stop the payment. The entry still counts toward the daily limit.
+
+## <img src="https://github.com/forcequitx/solverr/raw/main/assets/icons/shield-check.svg" width="24" height="24" style="vertical-align: middle; margin-right: 4px;"> Tests
+
+The tests in `tests/` run with Vitest and never send a transaction or reach a network. Chains, wallets, the gateway, DNS and `fetch` are mocked, and spend logs are written to a fresh folder under the OS temp folder. They import `solverr-x402` from its `dist`, so build x402 first.
+
+```bash
+cd packages
+npm ci                                  # install the pinned dev dependencies of every package
+npm run build -w x402                   # the agent imports solverr-x402's build
+cd agent
+npx vitest run                          # run every test
+npx tsc --noEmit -p tests/tsconfig.json # type-check the tests
+```
+
+## <img src="https://github.com/forcequitx/solverr/raw/main/assets/icons/rocket.svg" width="24" height="24" style="vertical-align: middle; margin-right: 4px;"> Build and Publish
+
+### Build
+
+`solverr-agent` depends on `solverr-x402` at an exact version. Both are members of the npm workspace in `packages/` (`packages/package.json`, one `packages/package-lock.json`), so during development the dependency resolves to the local `packages/x402` folder. Build x402 first, because the agent compiles against its `dist`:
+
+```bash
+cd packages
+npm install
+npm run build -w x402
+npm run build -w agent
+```
+
+### Publish
+
+Publish `solverr-x402` before `solverr-agent`: the agent's `package.json` names the x402 version it needs (`"solverr-x402": "0.1.0"`), and npm can only install the agent once that version exists on the registry. When x402 gets a new version, set the same exact version in the agent's `dependencies` and run `npm install` in `packages/` to update the lockfile.
+
+```bash
+cd packages
+npm publish -w x402
+npm publish -w agent
+```
+
+## <img src="https://github.com/forcequitx/solverr/raw/main/assets/icons/file-text.svg" width="24" height="24" style="vertical-align: middle; margin-right: 4px;"> License
+
+Released under the **MIT License**.

package/dist/agent-wallet.d.ts

@@ -0,0 +1,64 @@
+import { type Dispatcher, type RequestInit, type Response } from "undici";
+import { type WalletAsset } from "./assets.js";
+import { type SpendingLimits } from "./limits.js";
+import { type SpendEntry } from "./spend-log.js";
+export interface AgentWalletOptions {
+    near?: {
+        accountId: string;
+        privateKey: string;
+        rpcUrl?: string;
+    };
+    base?: {
+        privateKey: string;
+        rpcUrl?: string;
+    };
+    limits: SpendingLimits;
+    /** Spend log file; defaults to `~/.solverr/agent-spend-log.json`. */
+    spendLogPath?: string;
+    /** Coins to check and pay with; defaults to USDC, USDT and wNEAR on NEAR, and USDC and ETH on Base. */
+    assets?: WalletAsset[];
+    /** Solverr gateway URLs the agent will pay through, such as `https://pay.example.com`. At least one is required. */
+    trustedGateways: string[];
+    /** How long to wait for an invoice to be paid after sending. Default 3 minutes. */
+    paymentTimeoutMs?: number;
+    /** Timeout of each RPC and gateway call. Default 15 seconds. */
+    requestTimeoutMs?: number;
+    /** Timeout of each paid request, and of the first request when no `signal` is passed, body included. Default 30 seconds; raise it for
+        endpoints that take longer to answer or stream their body. */
+    resourceTimeoutMs?: number;
+}
+export interface AssetBalance {
+    asset_id: string;
+    symbol: string;
+    blockchain: string;
+    address: string;
+    amount: string;
+    amount_base: string;
+}
+export interface SpendingSummary {
+    limits: SpendingLimits;
+    spent_last_24h_usd: number;
+    remaining_today_usd: number;
+    recent: SpendEntry[];
+}
+/** Init for undici's `fetch`: `dispatcher` may be an undici dispatcher pinned to approved addresses (Node's `fetch` refuses those). */
+export type AgentFetchInit = RequestInit & {
+    dispatcher?: Dispatcher;
+};
+export interface AgentWallet {
+    /** Like `fetch`, but pays `solverr` x402 challenges within the limits and then sends the request again with the payment. */
+    fetch(input: string | URL, init?: AgentFetchInit): Promise<Response>;
+    balances(): Promise<{
+        balances: AssetBalance[];
+        errors: string[];
+    }>;
+    spending(): Promise<SpendingSummary>;
+    /** The current spending limits, read without the spend log. */
+    limits(): SpendingLimits;
+    setLimits(limits: Partial<SpendingLimits>): SpendingLimits;
+    /** The invoice of a payment kept for `method` and `url` because the site answered the paid request with an error;
+        the next 402 there sends that payment again before anything new is paid. */
+    unusedInvoice(url: string | URL, method?: string): string | undefined;
+}
+/** Creates an agent wallet. Keys stay in memory and are only used to sign transfers on this machine. */
+export declare function createAgentWallet(options: AgentWalletOptions): AgentWallet;

package/dist/agent-wallet.js

@@ -0,0 +1,194 @@
+import { PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER, PAYMENT_SIGNATURE_HEADER, X402_VERSION, decodePaymentResponseHeader, encodePaymentSignatureHeader, readHeader, } from "solverr-x402";
+import { fetch, Headers } from "undici";
+import { formatUnits } from "viem";
+import { DEFAULT_ASSETS } from "./assets.js";
+import { BaseWallet } from "./chains/base.js";
+import { NearWallet } from "./chains/near.js";
+import { parseChallenge } from "./challenge.js";
+import { DEFAULT_PAYMENT_TIMEOUT_MS, DEFAULT_REQUEST_TIMEOUT_MS, DEFAULT_RESOURCE_TIMEOUT_MS, PAID_REQUEST_ATTEMPTS, PAID_REQUEST_MAX_WAIT_MS, PAID_REQUEST_RETRY_MS, } from "./config.js";
+import { PaymentError, errorSummary } from "./errors.js";
+import { GatewayClient } from "./gateway.js";
+import { isHostAllowed, normalizeLimits } from "./limits.js";
+import { Payer } from "./payer.js";
+import { SpendLog } from "./spend-log.js";
+import { sleep } from "./timeout.js";
+const RECENT_ENTRIES = 20;
+/** Whether a request body can be sent again after paying; streams and (async) iterables are used up by the first request. */
+function isReplayableBody(body) {
+    return (body === undefined ||
+        body === null ||
+        typeof body === "string" ||
+        body instanceof ArrayBuffer ||
+        ArrayBuffer.isView(body) ||
+        body instanceof Blob ||
+        body instanceof FormData ||
+        body instanceof URLSearchParams);
+}
+/** `Retry-After` in milliseconds, read as delay-seconds like `requestJson` in solverr-x402; 0 when it is missing or not a number. */
+const retryAfterMs = (response) => Number(response.headers.get("Retry-After") ?? 0) * 1000 || 0;
+/** The method, origin and path a kept payment belongs to; the paywall binds each invoice to the method and path it was issued for. */
+const paymentKey = (method, url) => `${(method ?? "GET").toUpperCase()} ${url.origin}${url.pathname}`;
+/** Sends a request carrying a paid invoice, retrying after a network error, 429, 5xx, or a 402 that follows an attempt with no answer (whose request
+    may still be using the payment); each attempt has `attemptTimeoutMs`. A 429 or 503 waits at least its `Retry-After`, capped at PAID_REQUEST_MAX_WAIT_MS,
+    and no wait ends later than `timeoutMs` after the first send. Returns any other response below 500; throws `PaymentError` with `fundsSent` at the end. */
+async function fetchPaid(url, init, invoiceId, timeoutMs, attemptTimeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    let failure = "no response";
+    let retryAfter = 0;
+    let unanswered = false;
+    for (let attempt = 1; attempt <= PAID_REQUEST_ATTEMPTS; attempt++) {
+        if (attempt > 1) {
+            const delay = Math.min(Math.max(PAID_REQUEST_RETRY_MS * (attempt - 1), retryAfter), PAID_REQUEST_MAX_WAIT_MS);
+            if (Date.now() + delay > deadline)
+                break;
+            await sleep(delay);
+        }
+        let response;
+        try {
+            response = await fetch(url, { ...init, signal: AbortSignal.timeout(attemptTimeoutMs) });
+        }
+        catch (error) {
+            failure = errorSummary(error, 120);
+            retryAfter = 0;
+            unanswered = true;
+            continue;
+        }
+        if (response.status === 402 && unanswered) {
+            failure = "HTTP 402 while an earlier attempt may still be using the payment";
+            retryAfter = 0;
+            await response.body?.cancel();
+            continue;
+        }
+        if (response.status !== 429 && response.status < 500)
+            return response;
+        failure = `HTTP ${response.status}`;
+        retryAfter = response.status === 429 || response.status === 503 ? retryAfterMs(response) : 0;
+        await response.body?.cancel();
+    }
+    throw new PaymentError("paid_request_failed", `Invoice ${invoiceId} is paid, but the request to ${url.host} with the payment failed (${failure}). The wallet keeps this payment and sends it again on the next request to the same URL instead of paying again.`, true, invoiceId);
+}
+/** Creates an agent wallet. Keys stay in memory and are only used to sign transfers on this machine. */
+export function createAgentWallet(options) {
+    const requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    const wallets = [];
+    if (options.near)
+        wallets.push(new NearWallet({ ...options.near, requestTimeoutMs }));
+    if (options.base)
+        wallets.push(new BaseWallet({ ...options.base, requestTimeoutMs }));
+    if (wallets.length === 0)
+        throw new Error("Configure at least one wallet: near or base.");
+    if (!options.trustedGateways?.length) {
+        throw new Error("Set trustedGateways to the Solverr URLs the agent may pay through, such as https://pay.example.com.");
+    }
+    const trustedGateways = options.trustedGateways.map((gateway) => new URL(gateway).origin);
+    const assets = (options.assets ?? DEFAULT_ASSETS).filter((asset) => wallets.some((wallet) => wallet.blockchain === asset.blockchain));
+    const spendLog = new SpendLog(options.spendLogPath);
+    let limits = normalizeLimits(options.limits);
+    const paymentTimeoutMs = options.paymentTimeoutMs ?? DEFAULT_PAYMENT_TIMEOUT_MS;
+    const resourceTimeoutMs = options.resourceTimeoutMs ?? DEFAULT_RESOURCE_TIMEOUT_MS;
+    const payer = new Payer({ wallets, assets, spendLog, gateway: new GatewayClient(requestTimeoutMs), limits: () => limits, paymentTimeoutMs });
+    /** Paid invoices a site answered with an error, by `paymentKey`. The paywall releases such a payment, so it is sent again instead of paying anew;
+        it is dropped once the site accepts it (below 400) or refuses it with 402. Nothing is reserved or logged for a resend, since nothing is spent. */
+    const unusedPayments = new Map();
+    /** Sends the request with `payment` and returns the response, 402 included; an error of 400 or more other than 402, or no response at all,
+        keeps the payment under `key`. */
+    async function sendPayment(url, init, payment, key) {
+        const headers = new Headers(init.headers);
+        headers.set(PAYMENT_SIGNATURE_HEADER, payment.signature);
+        let response;
+        try {
+            response = await fetchPaid(url, { ...init, headers }, payment.invoiceId, paymentTimeoutMs, resourceTimeoutMs);
+        }
+        catch (error) {
+            unusedPayments.set(key, payment);
+            throw error;
+        }
+        if (response.status >= 400 && response.status !== 402)
+            unusedPayments.set(key, payment);
+        return response;
+    }
+    async function paidFetch(input, init = {}) {
+        const request = { ...init, signal: init.signal ?? AbortSignal.timeout(resourceTimeoutMs) };
+        const first = await fetch(input, request);
+        if (first.status !== 402)
+            return first;
+        let challenge;
+        try {
+            challenge = parseChallenge(first.headers.get(PAYMENT_REQUIRED_HEADER), trustedGateways);
+            if (challenge && !isReplayableBody(init.body))
+                throw new PaymentError("body_not_replayable", "A streamed request body cannot be sent again after paying; pass a string or buffer.");
+        }
+        catch (error) {
+            await first.body?.cancel();
+            throw error;
+        }
+        if (!challenge)
+            return first;
+        /** The URL that answered 402 (after redirects) is the one checked against the allow list and retried. */
+        const resourceUrl = new URL(first.url || input.toString());
+        await first.body?.cancel();
+        const key = paymentKey(init.method, resourceUrl);
+        const unused = unusedPayments.get(key);
+        /** Taken out while it is sent once, so concurrent calls never send the same kept payment together. */
+        if (unused && isHostAllowed(resourceUrl.hostname, limits.allow)) {
+            unusedPayments.delete(key);
+            const resent = await sendPayment(resourceUrl, init, unused, key);
+            if (resent.status !== 402)
+                return resent;
+            await resent.body?.cancel();
+        }
+        /** The caller's signal can stop the payment up to the transfer; after that the paid request is always completed. */
+        await payer.pay(resourceUrl, challenge, init.signal ?? undefined);
+        const invoiceId = challenge.extra.invoice_id;
+        const payment = {
+            x402Version: X402_VERSION,
+            resource: challenge.paymentRequired.resource,
+            accepted: challenge.requirement,
+            payload: { invoice_id: invoiceId },
+        };
+        const response = await sendPayment(resourceUrl, init, { invoiceId, signature: encodePaymentSignatureHeader(payment) }, key);
+        if (response.status !== 402)
+            return response;
+        const settlement = readHeader(response.headers.get(PAYMENT_RESPONSE_HEADER), decodePaymentResponseHeader);
+        await response.body?.cancel();
+        throw new PaymentError("paid_request_failed", `Invoice ${invoiceId} is paid, but ${resourceUrl.host} refused the payment: ${settlement?.errorMessage ?? "402 Payment Required"}. Do not pay for this request again; ask the site about invoice ${invoiceId}.`, true, invoiceId);
+    }
+    return {
+        fetch: paidFetch,
+        async balances() {
+            const errors = [];
+            const results = await Promise.all(assets.map(async (asset) => {
+                const wallet = wallets.find((item) => item.blockchain === asset.blockchain);
+                try {
+                    const amount = await wallet.balance(asset);
+                    return { asset_id: asset.asset_id, symbol: asset.symbol, blockchain: asset.blockchain, address: wallet.address, amount: formatUnits(amount, asset.decimals), amount_base: amount.toString() };
+                }
+                catch (error) {
+                    errors.push(`${asset.symbol} on ${asset.blockchain}: ${errorSummary(error, 120)}`);
+                    return undefined;
+                }
+            }));
+            return { balances: results.filter((item) => item !== undefined), errors };
+        },
+        async spending() {
+            const spent = await spendLog.spentLast24hUsd();
+            const entries = await spendLog.entries();
+            return {
+                limits,
+                spent_last_24h_usd: spent,
+                remaining_today_usd: Math.max(0, limits.dailyUsd - spent),
+                recent: entries.slice(-RECENT_ENTRIES).reverse(),
+            };
+        },
+        limits() {
+            return limits;
+        },
+        setLimits(changes) {
+            limits = normalizeLimits({ ...limits, ...changes });
+            return limits;
+        },
+        unusedInvoice(url, method) {
+            return unusedPayments.get(paymentKey(method, new URL(url)))?.invoiceId;
+        },
+    };
+}

package/dist/assets.d.ts

@@ -0,0 +1,13 @@
+/** A coin the agent can hold and pay with, identified by its 1Click asset ID. */
+export interface WalletAsset {
+    asset_id: string;
+    symbol: string;
+    /** 1Click blockchain code: `near` or `base`. */
+    blockchain: string;
+    decimals: number;
+    /** NEP-141 contract on NEAR, ERC-20 contract on Base, or `null` for native ETH. */
+    contract_address: string | null;
+}
+/** Coins checked for balances and payments unless `assets` is set. */
+export declare const DEFAULT_ASSETS: readonly WalletAsset[];
+export declare function isUsdStablecoin(symbol: string): boolean;

package/dist/assets.js

@@ -0,0 +1,12 @@
+/** Coins checked for balances and payments unless `assets` is set. */
+export const DEFAULT_ASSETS = [
+    { asset_id: "nep141:17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1", symbol: "USDC", blockchain: "near", decimals: 6, contract_address: "17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1" },
+    { asset_id: "nep141:usdt.tether-token.near", symbol: "USDT", blockchain: "near", decimals: 6, contract_address: "usdt.tether-token.near" },
+    { asset_id: "nep141:wrap.near", symbol: "wNEAR", blockchain: "near", decimals: 24, contract_address: "wrap.near" },
+    { asset_id: "nep141:base-0x833589fcd6edb6e08f4c7c32d4f71b54bda02913.omft.near", symbol: "USDC", blockchain: "base", decimals: 6, contract_address: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913" },
+    { asset_id: "nep141:base.omft.near", symbol: "ETH", blockchain: "base", decimals: 18, contract_address: null },
+];
+const USD_STABLECOINS = new Set(["USDC", "USDT", "DAI"]);
+export function isUsdStablecoin(symbol) {
+    return USD_STABLECOINS.has(symbol.toUpperCase());
+}

package/dist/chains/base.d.ts

@@ -0,0 +1,24 @@
+import type { WalletAsset } from "../assets.js";
+import type { ChainWallet, TransferResult } from "./chain-wallet.js";
+interface BaseWalletOptions {
+    /** 32-byte hex private key, with or without `0x`. */
+    privateKey: string;
+    rpcUrl?: string;
+    requestTimeoutMs?: number;
+}
+/** Base wallet paying with ERC-20 `transfer` or native ETH. */
+export declare class BaseWallet implements ChainWallet {
+    readonly blockchain = "base";
+    readonly address: string;
+    private readonly publicClient;
+    private readonly walletClient;
+    constructor(options: BaseWalletOptions);
+    isValidRecipient(address: string): boolean;
+    balance(asset: WalletAsset): Promise<bigint>;
+    transfer(asset: WalletAsset, to: string, amount: bigint): Promise<TransferResult>;
+    /** Throws when the node answered the broadcast with an error and does not hold `hash`, so nothing was sent; returns when the
+        transaction may still have been accepted (no answer, "already known", or a lookup that could not tell). */
+    private throwIfRefused;
+    private tokenOf;
+}
+export {};

package/dist/chains/base.js

@@ -0,0 +1,96 @@
+import { BaseError, InsufficientFundsError, RpcRequestError, TransactionNotFoundError, WaitForTransactionReceiptTimeoutError, createPublicClient, createWalletClient, encodeFunctionData, erc20Abi, getAddress, http, isAddress, keccak256, zeroAddress, } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { base } from "viem/chains";
+import { DEFAULT_BASE_RPC_URL, DEFAULT_REQUEST_TIMEOUT_MS, DEFAULT_TRANSFER_TIMEOUT_MS } from "../config.js";
+import { PaymentError, errorSummary } from "../errors.js";
+const PRIVATE_KEY_PATTERN = /^(0x)?[0-9a-fA-F]{64}$/;
+/** Node answers to a broadcast that mean the node already holds this exact transaction. */
+const ALREADY_KNOWN = /already known|known transaction|already imported/i;
+/** Base wallet paying with ERC-20 `transfer` or native ETH. */
+export class BaseWallet {
+    blockchain = "base";
+    address;
+    publicClient;
+    walletClient;
+    constructor(options) {
+        if (!PRIVATE_KEY_PATTERN.test(options.privateKey))
+            throw new Error("base.privateKey must be a 32-byte hex private key.");
+        const key = (options.privateKey.startsWith("0x") ? options.privateKey : `0x${options.privateKey}`);
+        const account = privateKeyToAccount(key);
+        const transport = http(options.rpcUrl ?? DEFAULT_BASE_RPC_URL, { timeout: options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS, retryCount: 2 });
+        this.address = account.address;
+        this.publicClient = createPublicClient({ chain: base, transport });
+        this.walletClient = createWalletClient({ account, chain: base, transport });
+    }
+    isValidRecipient(address) {
+        return isAddress(address, { strict: false }) && getAddress(address) !== zeroAddress;
+    }
+    async balance(asset) {
+        const token = this.tokenOf(asset);
+        if (!token)
+            return this.publicClient.getBalance({ address: this.address });
+        return this.publicClient.readContract({ address: token, abi: erc20Abi, functionName: "balanceOf", args: [this.address] });
+    }
+    async transfer(asset, to, amount) {
+        if (!this.isValidRecipient(to))
+            throw new PaymentError("quote_mismatch", `The deposit address ${to} is not a valid Base address.`);
+        const recipient = getAddress(to);
+        const token = this.tokenOf(asset);
+        const call = token
+            ? { to: token, data: encodeFunctionData({ abi: erc20Abi, functionName: "transfer", args: [recipient, amount] }) }
+            : { to: recipient, value: amount };
+        let serialized;
+        try {
+            const request = await this.walletClient.prepareTransactionRequest(call);
+            serialized = await this.walletClient.signTransaction(request);
+        }
+        catch (error) {
+            throw new PaymentError("transfer_failed", `The Base transfer could not be prepared: ${errorSummary(error)}`);
+        }
+        const hash = keccak256(serialized);
+        try {
+            await this.publicClient.sendRawTransaction({ serializedTransaction: serialized });
+        }
+        catch (error) {
+            await this.throwIfRefused(error, hash);
+            /** Any other failure may have happened after the node accepted the transaction, so inclusion is checked below. */
+        }
+        try {
+            const receipt = await this.publicClient.waitForTransactionReceipt({ hash, timeout: DEFAULT_TRANSFER_TIMEOUT_MS });
+            if (receipt.status !== "success")
+                throw new PaymentError("transfer_failed", `The Base transfer ${hash} reverted.`, true);
+            return { hash };
+        }
+        catch (error) {
+            if (error instanceof WaitForTransactionReceiptTimeoutError)
+                return { hash };
+            if (error instanceof PaymentError)
+                throw error;
+            throw new PaymentError("transfer_failed", `The Base transfer ${hash} could not be confirmed: ${errorSummary(error)}`, true);
+        }
+    }
+    /** Throws when the node answered the broadcast with an error and does not hold `hash`, so nothing was sent; returns when the
+        transaction may still have been accepted (no answer, "already known", or a lookup that could not tell). */
+    async throwIfRefused(error, hash) {
+        const answer = error instanceof BaseError ? error.walk((cause) => cause instanceof RpcRequestError) : null;
+        const nodeMessage = answer instanceof RpcRequestError ? answer.details : "";
+        if (!answer || ALREADY_KNOWN.test(nodeMessage))
+            return;
+        const mayHoldIt = await this.publicClient.getTransaction({ hash }).then(() => true, (lookup) => !(lookup instanceof TransactionNotFoundError));
+        if (mayHoldIt)
+            return;
+        if (InsufficientFundsError.nodeMessage.test(nodeMessage)) {
+            throw new PaymentError("no_funds", `${this.address} does not have enough ETH on Base for this transfer and its gas.`);
+        }
+        throw new PaymentError("transfer_failed", `The Base node refused the transfer: ${nodeMessage.slice(0, 300)}`);
+    }
+    tokenOf(asset) {
+        if (asset.blockchain !== "base")
+            throw new Error(`${asset.symbol} is not a Base asset.`);
+        if (asset.contract_address === null)
+            return undefined;
+        if (!isAddress(asset.contract_address, { strict: false }))
+            throw new Error(`${asset.symbol} has an invalid Base contract address.`);
+        return getAddress(asset.contract_address);
+    }
+}