# MoneyTools Spend Controls: Human Approval Relay + Spend Ledger

> Let an AI agent ask its human before it pays, and show where the agent's USDC went. Non-custodial: we never hold, move or sign funds.

## Human Approval Relay ($0.003/request via x402; 3 prepaid credits; MoneyTools monthly plan includes 20/day)
1. POST https://approve.moneytools.dev/v1/approvals  JSON {"title":"Pay api.example.com 0.50 USDC for a report","amountUsd":0.5,"host":"api.example.com","payTo":"0x...","ttlMinutes":30,"notify":{"webhook":"https://your.app/hook"}}
   -> {id, approveUrl, agentToken, statusUrl, channels}. Unpaid: HTTP 402 + PAYMENT-REQUIRED; or send X-API-Key.
2. Show approveUrl to your human (chat message). They open it and press Approve or Deny. Webhook (optional) gets signed events approval.created / approval.decided (header X-MoneyTools-Signature: t=..,v1=HMAC-SHA256(webhookSecret, "t.body")).
3. Poll GET https://approve.moneytools.dev/v1/approvals/{id} with Authorization: Bearer <agentToken> (free) -> pending | approved | denied | expired | cancelled. Approved responses include a signed proof (verify free: GET /v1/approvals/verify?proof=...).
4. Only if approved: pay with your own wallet, then POST /v1/approvals/{id}/consume (Bearer agentToken; optional JSON {amountUsd, host, payTo} must fit the approval) so it cannot be reused.
Channels: link (live), webhook (live), email (limited: only addresses our current sending plan can reach), Telegram (not enabled yet).

## Spend Ledger
- Pay Gateway users (free): GET https://ledger.moneytools.dev/v1/ledger?month=YYYY-MM (or ?days=30) with X-API-Key -> totals, by supplier, by day, exceptions (seller errors after payment), every receipt; &format=csv; &currency=EUR (default USD).
- Any Base wallet ($0.05 per report covering up to 30 days via x402; free with any MoneyTools API key): POST https://ledger.moneytools.dev/v1/ledger/wallet {"address":"0x...","days":30,"labels":{"0xseller":"Exa"}} (or "month":"YYYY-MM" for a month that started within the last 31 days; older history is not available yet) -> {reportId, reportToken, reportUrl}. Poll reportUrl (free) every 15-30 s until status=done (a few days: under a minute; a full month: typically 5-15 minutes, public RPC is rate-limited); &format=csv for the transaction list. Scans outgoing USDC transfers from public Base logs.

## MCP (streamable HTTP): https://approve.moneytools.dev/mcp
Tools: approval_request, approval_status, approval_consume, approval_cancel, approval_verify, ledger_gateway, ledger_wallet_start, ledger_wallet_report. Paid tools need header X-API-Key on the MCP connection (or use the HTTP x402 endpoints).

## Notes
- Run by MoneyTools (moneytools.dev). Non-custodial: approvals only record a human decision and ledgers only read receipts and public chain data; we never receive, hold, move or sign user funds or keys. Paid calls go to the MoneyTools team wallet via x402 (USDC on Base). Failed calls are not charged. Not financial, accounting or tax advice.
- OpenAPI: https://approve.moneytools.dev/openapi.json · x402 discovery: https://approve.moneytools.dev/.well-known/x402 · all products: https://moneytools.dev/products/
- Privacy: approval requests are deleted after 30 days and wallet reports after 90 days; ledgers read only your gateway receipts or public chain data. Support: support@moneytools.dev