io.github.hifriendbot/agentwallet

One-time ERC-20 approval of a token to the Permit2 contract, needed before paying x402 "upto" endpoints with that token. A normal on-chain transaction (needs gas). Pass amount to grant a bounded allowance; with no amount it asks for the maximum, which is refused by default, under AGENTWALLET_MAX_TX_TOKEN, and always under a spend policy (where the allowance counts against the budgets). Only the operator can allow a maximum approval, with AGENTWALLET_ALLOW_UNLIMITED_APPROVAL=1 while no policy is set. Permit2 itself only moves what each signed authorization allows.

Approve a spender contract to transfer ERC-20 tokens on your behalf. Required before interacting with any DeFi protocol (DEXs, lending, etc.). Specify an exact amount. "max" (an unlimited allowance) is refused by default and always under a spend policy; only the operator can allow it, with AGENTWALLET_ALLOW_UNLIMITED_APPROVAL=1 while no policy is set. Under a spend policy an approval is a spend: it counts against the budgets and the spender is checked as a recipient.

Buy x402 verification credits with USDC on-chain. Paywall owners need credits to process verifications beyond the free tier (1,000/month) when they don't have Stripe billing configured. Returns 402 payment instructions — pay on-chain and retry with proof.

Execute a read-only call against a smart contract (eth_call). Returns the raw hex result. Does not cost gas or modify state. Useful for reading on-chain data like token balances, prices, positions.

Status of a payment approval created when pay_x402 exceeded the cap on a hosted wallet. Returns pending, approved, denied or expired. Once approved, call pay_x402 again with approval_id.

Assess an ERC-20 token before approving or swapping it: honeypot, taxes, owner powers, verified source, holder concentration, DEX liquidity. Uses GoPlus Security (free, no key) with an on-chain fallback. A warning for the caller to weigh, never a block.

Create an x402 paywall that charges agents/clients for accessing a resource. Returns a public access URL that returns HTTP 402 until paid. Agents pay on-chain, then retry with proof to get the content.

Create a new EVM or Solana wallet. Returns the wallet ID and address. Private key is encrypted server-side and never exposed.

Delete an x402 paywall. The access URL will return 404 after deletion.

Delete (soft-delete) a wallet. The wallet will no longer appear in listings and cannot be used for transactions. The wallet is read first and the delete names its address, so a wallet that cannot be read is never deleted.

Find x402-paid APIs by subject in the public x402 index (the Bazaar published by the CDP facilitator). Returns resources with their method, price and chain, re-priced from this client's own registry. Listings are sellers' own words. Nothing is paid; follow up with quote_x402 or pay_x402.

Every spend in the ledger as CSV or JSONL text (oldest first), for expense records. Returns the text; write it wherever it belongs.

Explain how to export the private key of a hosted (custodial) AgentWallet so it can be moved to self-custody or any other wallet. Export itself is deliberately human-gated and is not performed by this tool.

Check how many ERC-20 tokens a spender is approved to transfer. Returns the allowance in both raw and human-readable format. Use this to check if an approval is needed before a DeFi transaction.

Get the native token balance for a wallet on a specific chain. Returns balance in both wei (or lamports for Solana) and human-readable format.

List all supported chains (EVM + Solana) with their chain IDs, native tokens, stablecoins, and RPC configuration status.

Get details for a specific x402 paywall by ID. Returns pricing, access URL, payment stats, and configuration.

Get payment history for a specific x402 paywall. Returns verified payments with TX hashes, payer addresses, amounts, and timestamps.

Get the ERC-20 or SPL token balance for a wallet on a specific chain. Returns the raw balance and human-readable balance. Use get_chains to find stablecoin addresses for each chain.

Get the name, symbol, and decimals of any ERC-20 token by its contract address. Useful for discovering token details before transfers or approvals.

Get the current month's usage statistics. Returns operations count, tier info, remaining quota, and fees.

Get details for a specific wallet by ID. Returns address, label, chain, spending limits, and pause status.

Get aggregate x402 revenue statistics across all your paywalls. Returns total payments and revenue broken down by chain and token.

Spends recorded in this wallet's ledger (x402 payments, transfers, auto-pay), newest first, each with its latest outcome (signed, settled, declined, unknown, broadcast, void). The ledger is a hash-chained append-only file when AGENTWALLET_LEDGER or a policy names one; otherwise this process only.

List all your x402 paywalls. Returns paywall IDs, names, pricing, access URLs, payment counts, and revenue totals.

List all wallets owned by the authenticated user. Returns wallet IDs, addresses, labels, chain IDs, and status.

Emergency pause a wallet. No transactions can be signed while paused.

Handle an x402 payment flow. Fetches a URL, and if the server returns HTTP 402 Payment Required, parses the payment requirements (v1 body or v2 PAYMENT-REQUIRED header), signs an EIP-3009 TransferWithAuthorization for the "exact" scheme (no gas, nothing broadcast by the payer), and retries the request with the payment header. AgentWallet paywalls are paid by on-chain transfer instead. The "upto" scheme is settled with a Permit2 authorization bounded by the cap. Returns the final response and the settlement receipt. Supports the x402 open payment standard (https://x402.org). max_payment can only lower the operator's cap for one call.

Ask what an x402 endpoint charges without paying: fetches the URL, parses the 402 requirements, says which option this wallet would pay (chain, asset, amount, recipient), whether the per-payment cap, the spend policy and the rolling budgets would allow it, and nothing is signed. Call it before pay_x402 when the price is unknown.

Sign and broadcast a transaction. Returns the transaction hash (EVM) or signature (Solana) on success. The transaction is signed server-side and broadcast via RPC.

Sign a transaction with a wallet's private key. For EVM: returns signed raw transaction hex. For Solana: returns base64 signed transaction. Does NOT broadcast. Use send_transaction for sign + broadcast. A signed transaction is a spend: under a spend policy it is checked, reserved on the ledger and counted against the budgets exactly as send_transaction is, because the caller can broadcast it.

Dry-run an EVM transaction with nothing signed: the local guards (native cap, token cap, fee cap), the spend policy, the node's gas estimate (which fails when the call would revert), the worst-case fee, whether the balance covers it, and the call's return data. Local mode runs the full check; hosted mode runs the policy and an eth_call.

The spend policy this server enforces (AGENTWALLET_POLICY), its sha256, the rolling budgets with what is spent and what remains, per-host spending, the ledger's path and integrity, and whether the connected client can answer approval questions. Read-only.

Send native tokens (ETH, AVAX, BNB, POL, PLS, SOL) to an address. Specify the amount in human-readable format (e.g. "0.1" for 0.1 ETH). The amount is converted to wei/lamports automatically. Signs and broadcasts the transaction.

Send ERC-20 tokens (EVM) or SPL tokens (Solana) to an address. Specify the amount in human-readable format (e.g. "100" for 100 USDC). Signs and broadcasts the transaction. Use get_chains to find stablecoin addresses.

Resume a paused wallet so transactions can be signed again.

Unwrap wrapped tokens (WETH, WAVAX, WBNB, etc.) back to native tokens. Specify amount in human-readable format (e.g. "0.5" for 0.5 WETH).

Update an x402 paywall configuration. Can change price, resource URL, active status, or any other field.

Report whether this server is signing locally (self-custody, the private key never leaves this machine) or through the hosted AgentWallet API (custodial). Use this to verify custody before moving funds.

Wrap native tokens (ETH, AVAX, BNB, POL, PLS) into their wrapped ERC-20 version (WETH, WAVAX, etc.). Required for most DeFi protocols that use ERC-20 tokens instead of raw native tokens. Specify amount in human-readable format (e.g. "0.5" for 0.5 ETH).