SpendTree is a local, non-custodial budget tree and flight recorder for agents that make real x402 payments.
It is not a mock ledger or testnet demo. The payment path creates real EIP-3009 USDC authorizations for Base mainnet and sends them to real x402 merchants. The wallet belongs to the user, funds settle directly to the merchant, and SpendTree never holds either party's money.
Status: pre-alpha. Use only a dedicated, low-balance wallet while the security surface is being hardened.
- x402 v2
exactpayments - Base mainnet (
eip155:8453) - Canonical native USDC only
- A one-use signer that accepts only the reserved EIP-3009 typed data
- Exact HTTPS origin, path, HTTP method, and receiving-address policies
- Hierarchical, expiring agent quotas
- Atomic ancestor reservations that prevent concurrent overspend
- Root-scoped idempotency and conservative handling of ambiguous settlement
- A database-to-wallet binding that prevents accounting under the wrong signer
- SQLite audit trail containing the quote, signed payload, nonce, transaction hash, response hash, and agent ancestry
- Base receipt verification that checks both the exact canonical USDC
Transferand the signed EIP-3009AuthorizationUsednonce - A local Unix-socket daemon, mandate-bound MCP adapter, and CLI smoke path
Not in v0: arbitrary token transfers, swaps, upto, batch settlement,
subscriptions, fiat/card payments, onramping, refunds, custody, or merchant
delivery guarantees.
Agent
│ stdio MCP (scoped capability; no wallet key)
▼
SpendTree MCP adapter
│ authenticated JSON over a 0600 Unix socket
▼
SpendTree daemon
├─ policy + hierarchical budget engine
├─ SQLite reservation/attempt ledger
├─ constrained one-use EIP-3009 signer
└─ guarded x402 HTTP handshake
│
▼
Merchant facilitator ──▶ Base USDC settlement
The daemon moves a reservation to committed spend and persists the signed
payload before transmitting PAYMENT-SIGNATURE. A timeout, missing receipt,
or merchant error after that point never releases the budget: the merchant may
still settle the authorization until it expires.
Requirements: Node.js 24 or newer.
npm install --global github:bilalxashraf/spendtree
spendtree --helpThe GitHub install builds the CLI and MCP adapter locally. To develop from a
clone instead, run npm ci, npm run check, and npm run build. All
security-sensitive dependency versions are pinned in package.json and
package-lock.json.
This path calls Exa's live x402 web-search API on Base mainnet. On July 18,
2026, its unsigned quote was 0.007 USDC to
0x6d6E695b09861467c7d462f5AAF31cF3540B9192. The checked-in policy allows at
most 0.01 USDC per call and fails closed if the recipient or price changes.
Download the narrow example policy and create a mandate that expires in one hour:
curl --fail --output exa-policy.json \
https://raw.githubusercontent.com/bilalxashraf/spendtree/main/config/policy.exa.example.json
spendtree init exa-policy.json --ttl-minutes 60Save the capability printed by init. Create or export a dedicated EOA,
then print its address and fund it with a small amount of USDC on Base. Do not
use a primary wallet.
SPENDTREE_PRIVATE_KEY=0x... spendtree address
SPENDTREE_PRIVATE_KEY=0x... spendtree daemonKeep the daemon running. In another terminal, make a useful paid search with the capability but without exposing the wallet key to the client process:
SPENDTREE_CAPABILITY=st_cap_... \
spendtree pay \
'https://api.exa.ai/search' \
'exa-canary-001' \
'Find current primary sources about agent payment controls' \
--json '{"query":"agent payment controls x402","numResults":3}'Run the identical command again. SpendTree returns the stored response with
"replayed": true and does not sign or pay twice. Inspect the verified Base
transaction and remaining allowance with:
SPENDTREE_CAPABILITY=st_cap_... spendtree summaryThis is a real mainnet call funded by the user. The project maintainers do not subsidize the purchase, hold funds, or receive the merchant payment.
Copy config/policy.example.json, then replace the origin and payTo address
with a real x402 merchant. Amounts are atomic USDC units: 1000000 is 1 USDC.
cp config/policy.example.json config/policy.json
# Edit config/policy.json before continuing.
spendtree init config/policy.json --ttl-minutes 60init prints a root capability once. SpendTree stores only its SHA-256 hash;
save the raw capability in a password manager or other secret store.
Fund a dedicated EOA with USDC on Base. Standard EIP-3009 payments do not require that buyer wallet to hold ETH; the merchant's facilitator submits the transaction.
Start the daemon in a terminal or service environment that is separate from the agent. Do not place the wallet key in the MCP process:
SPENDTREE_PRIVATE_KEY=0x... spendtree daemonThe environment variable is the initial developer key provider. Keep daemon and MCP environments separate; example files are provided for each. An encrypted keystore/native keychain provider is planned before a stable release.
With the daemon running, use the root or child capability:
SPENDTREE_CAPABILITY=st_cap_... \
spendtree pay \
'https://merchant.example/paid/resource' \
'smoke-001' \
'Buy the merchant resource for the initial smoke test'For POST resources, append --json '{"key":"value"}'. --text and an
explicit --method GET|POST are also supported.
This is a mainnet operation. If the quote satisfies the mandate, real USDC can move from the configured wallet.
Inspect the quota and flight recorder:
SPENDTREE_CAPABILITY=st_cap_... spendtree summaryRun one adapter per agent/mandate. The adapter attaches its capability internally; the agent cannot choose a different mandate in tool arguments.
{
"mcpServers": {
"spendtree": {
"command": "spendtree-mcp",
"args": [],
"env": {
"SPENDTREE_SOCKET": "/absolute/path/to/home/.spendtree/spendtree.sock",
"SPENDTREE_CAPABILITY": "st_cap_..."
}
}
}
}Replace the socket path with the daemon's path; the default is
~/.spendtree/spendtree.sock. For a source-only install, set command to
node and args to the absolute path of dist/mcp.js instead.
The MCP surface exposes paid_fetch, get_spend_tree, delegate_budget, and
revoke_child. It exposes no generic signing or token-transfer operation.
- EIP-3009 cryptographically binds payer, receiver, amount, validity window, nonce, token, and chain. It does not bind the HTTP method, URL, body, or merchant delivery. SpendTree enforces and records that relationship locally.
PAYMENT-RESPONSEis a facilitator/merchant report, not itself a signed receipt. SpendTree verifies the Base transaction receipt, the exact USDCTransfer, and the matching EIP-3009AuthorizationUsednonce through an RPC. When the RPC is temporarily unavailable, the delivered result is retained asreported_settledwithonchainVerified: falseinstead of being mislabeled as confirmed.- A same-OS-user agent with unrestricted shell/filesystem access can bypass a Unix-socket capability boundary. Use a separate OS user/container for that threat model. The dedicated low-balance wallet is the hard v0 loss ceiling.
- Child limits are hierarchical quotas, not carved-out treasury allocations. Every payment consumes its leaf quota and all ancestor quotas.
See SECURITY.md before placing funds in a wallet.
npm run typecheck
npm test
npm run buildThe tests use a real EIP-3009 signing implementation against mocked HTTP transport. They do not broadcast transactions or use fake balances.
MIT