Agent kit

@solverr/agent lets an AI agent pay Solverr paywalls from NEAR and Base wallets, inside your code or as a local MCP server, and never spends past the limits you set. Its keys stay in memory on your machine, are used only to sign transfers, and are never logged.

InstallCopy Anchor Link

npm install @solverr/agent

The package needs Node 22.22.2 or later.

Use it in codeCopy Anchor Link

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 });

agent.fetch works like fetch. When the answer is a 402 with the solverr scheme, it pays and sends the request again. When it refuses a payment or cannot finish one, it throws a PaymentError.

A signal you pass in the second argument of agent.fetch 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.

Spending limitsCopy Anchor Link

Limits are checked before every quote and again before every transfer.

Every payment is written to a local JSON spend log, ~/.solverr/agent-spend-log.json by default, so the daily limit holds across restarts and across agents that share the log file. Entries that were sent, paid or failed count toward the daily limit, because money may have left the wallet. Only aborted entries, where nothing was sent, do not count.

The limit check and the reservation happen in one locked step on the spend log file, so two calls or two agent processes cannot both pass the daily limit. If the spend log is corrupt, the kit stops paying instead of resetting the total.

How it paysCopy Anchor Link

1. The agent calls the URL. If the answer is not a 402, it returns that answer.
2. It checks that the host is allowed, that the payment URLs point to a Solverr address in trustedGateways, and that the invoice is live. Test invoices are refused.
3. It prices the invoice in USD and checks the per-payment and 24-hour limits.
4. It reserves the amount in the spend log before anything is sent.
5. It ranks the coins it holds: the coin the paywall's business receives first, then the same coin on another chain, then stablecoins, then the rest. It tries up to three of them.
6. It asks for a quote with its own address as the refund address, then checks the coin, refund address, deposit address, amount, deadline and limits again.
7. It sends the exact amount to the deposit address, reports the transaction, and waits until the invoice is paid.
8. It sends the request again with the PAYMENT-SIGNATURE header. After a network error, 429 or 5xx, it makes up to 3 tries in total, always with the same payment and resourceTimeoutMs (30 seconds by default) per try. It waits 1 second, then 2 seconds, between tries. 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 try.

Payments the site did not useCopy Anchor Link

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, also after paid_request_failed from a 429, 5xx or network error. 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 kept payment is dropped once the site accepts it, or answers it with 402, after which the new invoice is paid.

agent.unusedInvoice(url, method?) returns the invoice id of a kept payment, with GET as the default method. Kept payments are lost when the process stops.

OptionsCopy Anchor Link

Unless you set rpcUrl, the kit uses https://free.rpc.fastnear.com for NEAR and https://mainnet.base.org for Base.

ErrorsCopy Anchor Link

Every PaymentError has a code and a fundsSent flag. When fundsSent is true, it also has invoiceId, the invoice the money went to.

When fundsSent is true, the money has left the wallet; do not pay for that request again. On payment_timeout and payment_unconfirmed, check the invoice's status before you do anything else. The MCP server returns the same fields as funds_sent and invoice_id. For any other error, such as a gateway or wallet RPC that fails before a transfer, a set_limits value above the starting one, or a host outside the starting allow list, the MCP server returns the code request_failed with funds_sent: false.

Run it as a local MCP serverCopy Anchor Link

The kit runs as an MCP server over stdio, so Claude Code, Cursor or another MCP client can pay for API calls. To add it to Claude Code, pass your wallet, limits and trusted gateways as environment variables:

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

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 before you start it.

MCP toolsCopy Anchor Link

Environment variablesCopy Anchor Link

Wallet and network rulesCopy Anchor Link

• Native NEAR is not used to pay. NEAR Intents takes wNEAR (wrap.near), so the agent pays with wNEAR, USDC or USDT on NEAR. Keep a little more than 0.01 NEAR available: 0.01 NEAR is held back for gas, plus the token's storage deposit when the deposit address is new.
• Route minimums. A NEAR Intents route can have a temporary minimum that changes without notice. When a route is refused, the kit moves on to the next coin in its ranking.
• pay_url only reaches public addresses. It resolves the host and refuses loopback, private, link-local (including cloud metadata such as 169.254.169.254), multicast and reserved addresses. To reach a local server, add its exact address to AGENT_ALLOW_HOSTS and use the same address in the URL: 127.0.0.1, [::1] or localhost.
• Keys are hot keys. The agent wallet is a hot wallet. Fund it with only what you are willing to let the agent spend.