# MoneyTools Settle

Call before your agent signs an x402 payment to ask "is this within my budget?" (advisory: complements your wallet's hard limits and cannot block a payment). Also verifies timed-out or unknown settlements and records spend by payer.

## When to call
- Verify a timed-out/unknown settlement on-chain: POST https://settle.moneytools.dev/v1/verify — 0.005 USDC
- Ask if a payment is within the cap: POST https://settle.moneytools.dev/v1/spend/check — 0.005 USDC
- Set an advisory spend cap: POST https://settle.moneytools.dev/v1/spend/cap — 0.005 USDC
- Read the current advisory cap: POST https://settle.moneytools.dev/v1/spend/cap/get — 0.005 USDC
- Record a payment after you pay: POST https://settle.moneytools.dev/v1/spend/record — 0.005 USDC
- Read the spend log by payer: POST https://settle.moneytools.dev/v1/spend/log — 0.005 USDC
- Optional 30-day key: POST https://settle.moneytools.dev/v1/subscribe — 1 USDC / 30 days incl. 1000 calls (not auto-renewing).

## When you are not charged
- Invalid input, not found, locked, or upstream errors are not charged.
- Empty POST / {} / GET on a paid route returns HTTP 402 (the offer), not a charge.
- Invalid input after a payment header is HTTP 400 (not charged). Failed calls are not settled.

## Pricing — pay per call (x402, no key)
- 0.005 USDC — settle_verify (POST https://settle.moneytools.dev/v1/verify)
- 0.005 USDC — spend_check (POST https://settle.moneytools.dev/v1/spend/check)
- 0.005 USDC — spend_cap_set (POST https://settle.moneytools.dev/v1/spend/cap)
- 0.005 USDC — spend_cap_get (POST https://settle.moneytools.dev/v1/spend/cap/get)
- 0.005 USDC — spend_record (POST https://settle.moneytools.dev/v1/spend/record)
- 0.005 USDC — spend_log (POST https://settle.moneytools.dev/v1/spend/log)
- Optional upgrade: 1 USDC / 30 days incl. 1000 calls (API key, not auto-renewing) — only worth it above ~200 calls/month.

## Start in 30 seconds (free)
1. Get a trial key: POST https://settle.moneytools.dev/v1/trial (REST) or MCP tool settle_trial_key → apiKey mts_… (50 calls / 7 days, 1 per client per day). The response includes copy-paste first calls and an MCP config.
2. First call: POST https://settle.moneytools.dev/v1/spend/check -H 'X-API-Key: mts_…' {"payer":"0xYourAgentWallet","amountUsd":"0.25","host":"api.example.com"} → allow/deny.
3. MCP (streamable HTTP): https://settle.moneytools.dev/mcp — send X-API-Key as a header, or pass apiKey as a tool argument (works in clients that cannot set headers).

## How to pay (x402 v2, USDC on Base) — 0.005 USDC/call
1. Call without payment: curl -i -X POST 'https://settle.moneytools.dev/v1/spend/check' -H 'content-type: application/json' -d '{"payer":"0xYourAgentWallet","amountUsd":"0.25","host":"api.example.com"}'  → HTTP 402, header PAYMENT-REQUIRED (base64 JSON; same JSON in the body: accepts[] with scheme exact, network eip155:8453, asset USDC, amount, payTo).
2. Sign one accepts[] entry (EIP-3009 TransferWithAuthorization) with your wallet and resend the same request with header PAYMENT-SIGNATURE: base64({"x402Version":2,"accepted":{…},"payload":{"signature":"0x…","authorization":{"from","to","value","validAfter","validBefore","nonce"}}}).  (v1 clients: X-PAYMENT.)
3. 200 + PAYMENT-RESPONSE header = paid. Failed calls are not settled. Malformed payment header → HTTP 400 {error: invalid_payload | invalid_exact_evm_payload_signature | …}.
JS (any x402 client works):
  import { wrapFetchWithPayment } from "@x402/fetch";   // + your viem/CDP signer
  const pay = wrapFetchWithPayment(fetch, signer);
  const r = await pay("https://settle.moneytools.dev/v1/spend/check", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({"payer":"0xYourAgentWallet","amountUsd":"0.25","host":"api.example.com"}) });
Python: x402 package (x402.clients.requests / httpx) wraps requests the same way.
MCP: an unpaid paid-tool call returns isError + structuredContent = PaymentRequired; resend tools/call with params._meta["x402/payment"] = the PaymentPayload object; receipt in result._meta["x402/payment-response"].

## Pay per call (x402, no key)
- POST https://settle.moneytools.dev/v1/verify — 0.005 USDC/call
- POST https://settle.moneytools.dev/v1/spend/check — 0.005 USDC/call
- POST https://settle.moneytools.dev/v1/spend/cap — 0.005 USDC/call
- POST https://settle.moneytools.dev/v1/spend/cap/get — 0.005 USDC/call
- POST https://settle.moneytools.dev/v1/spend/record — 0.005 USDC/call
- POST https://settle.moneytools.dev/v1/spend/log — 0.005 USDC/call
Without X-API-Key these endpoints (and the matching MCP tools) answer HTTP 402 / MCP PaymentRequired; pay and resend. Caps, spend log and receipts are kept under the paying wallet. Empty POST / {} / GET = 402 offer; invalid input = 400 (not charged).

## Optional upgrade: subscription (x402)
POST https://settle.moneytools.dev/v1/subscribe → HTTP 402 + PAYMENT-REQUIRED (x402 v2, exact, Base eip155:8453, USDC, payTo 0x64eB63904Cf9688AC5B3087A72AcF9C31a273169, CDP facilitator + PayAI fallback). Retry with PAYMENT-SIGNATURE → apiKey mts_… (shown once). 1 USDC = 30 days incl. 1000 calls. Not auto-renewing. Successful trial responses carry _settle.upgrade with the same offer.

Auth: header X-API-Key: mts_… (or Authorization: Bearer mts_…; MCP: apiKey tool argument). Failed calls (invalid input, not found, locked, upstream errors) are not charged. Upgrading: send your trial X-API-Key on the /v1/subscribe purchase and your caps, owner lock, spend log, receipts, watches and gates move to the new key; the old key is then retired (HTTP 409 key_upgraded) so it cannot keep working with empty caps.

## Endpoints (POST JSON)
- /v1/spend/cap — Advisory spend caps that complement your wallet's enforced hard limits (Coinbase Agentic Wallet / CDP spendControls); cannot block payments. Set per-call / per-day (rolling 24h) / per-session USD limits and optional allow-lists (payTo, hosts, networks) for a payer wallet address (replaces the previous policy for that payer). Optional ownerLock secret so the agent cannot loosen the caps later. Advisory and non-custodial.
- /v1/spend/cap/get — Advisory (complements your wallet's enforced hard limits): read the spend caps of a payer address plus what it spent in the last 24h (and in a session).
- /v1/spend/check — Advisory pre-sign check (your wallet's own hard limits still apply; we cannot block a payment): 'would this payment exceed my cap?'. Pass the 402 PAYMENT-REQUIRED (header or body) or amountUsd, plus payer and optional sessionId/host. Returns allow|deny with reasons and remaining budget; reserve:true also logs it as pending.
- /v1/spend/record — Record an x402 payment the agent made (or update a reserved one by spendId/ref): status settled|failed|pending|refunded, tx; verify:true checks a Base tx on-chain (read-only). Builds the spend log / receipts.
- /v1/spend/log — Spend log / receipts for a payer address: totals (settled, pending, refunded), top sellers and the latest receipts over the last N days (1-31; read from Settle's own receipt records, not from Base RPC history).
- /v1/verify — Verify an x402 settlement on Base USDC right now (by tx hash, or payer+nonce / paymentPayload via USDC.authorizationState). Returns settled|failed|pending|not_settled|expired|unknown.
- /v1/watch — Watch a timed-out/unknown x402 settlement: re-checked on-chain for up to 24h; POSTs your webhook when it becomes settled/failed/expired.
- /v1/watch/status — Status of a settlement watch.
- /v1/gate/claim — Idempotency gate: claim an EIP-3009 authorization (payer+nonce) before settling. claimed:false means duplicate — do not settle again.
- /v1/gate/complete — Mark a claimed authorization settled or failed (failed allows a retry).
- /v1/receipts — Create a delivery receipt (status paid) for an order/request ref; idempotent per ref.
- /v1/receipts/update — Move a receipt paid -> delivered | failed | refunded (refundTx optional).
- /v1/receipts/get — Read a delivery receipt and its history.
- /v1/key — Show remaining calls/expiry of your MoneyTools Settle key.

## Agent spend caps — advisory, complements your wallet's hard limits
Advisory layer: your wallet signs; we never hold funds or keys and cannot move, stop or block a payment. The agent asks us before it signs, and records what it paid. Hard enforcement stays with your wallet (Coinbase Agentic Wallet / CDP x402 spendControls) — Settle complements it.
1. Owner sets limits once per payer address: POST /v1/spend/cap {"payer":"0x…","perCallUsd":"0.05","perDayUsd":"5","perSessionUsd":"2","allowHosts":["api.example.com"],"ownerLock":"<secret ≥12 chars, optional>"}. With ownerLock set, the agent (holding only the API key) cannot loosen the caps.
2. On every HTTP 402: POST /v1/spend/check {"payer":"0x…","paymentRequired":"<PAYMENT-REQUIRED header (base64) or 402 JSON>","sessionId":"run-42","host":"api.example.com","reserve":true} → {"allow":false,"reasons":[{"code":"per_day_cap",…}],"remaining":{…}}. Do not sign when allow=false.
3. After paying: POST /v1/spend/record {"spendId":"sp_…","status":"settled","tx":"0x…","verify":true} (verify = read-only on-chain check on Base).
4. Receipts / spend log: POST /v1/spend/log {"payer":"0x…","days":7} → totals, top sellers, receipts.
Pairing with Coinbase Agentic Wallet (or CDP x402 client spendControls): those wallets enforce their own max-per-call / max-per-session or rolling caps inside the wallet. Keep them as the hard backstop and use Settle for what they don't cover: one policy shared by several agents/wallets, per-day + per-session + per-seller allow-lists, an owner lock, a pre-sign "why denied" answer the agent can act on, and a spend log with on-chain-verified receipts for the owner. Order: 402 → spend_check → (allow) wallet signs/pays → spend_record.

## Typical seller flow
1. On PAYMENT-SIGNATURE: POST /v1/gate/claim {paymentPayload} → claimed:false = duplicate, stop.
2. Settle via your facilitator. On timeout/unknown: POST /v1/watch {paymentPayload or tx, webhook} — we verify on-chain and POST your webhook.
3. POST /v1/gate/complete {gateId, status}. 4. POST /v1/receipts {ref, tx}; then /v1/receipts/update {ref, status: delivered|failed|refunded}.

## Agent payment-safety suite
Recommended path when an agent is about to pay: (1) Pay Precheck https://api.moneytools.dev/v1/precheck (HTTP: 5 free/IP/endpoint/day; MCP: 20 free/client/day) (2) Settle spend/check https://settle.moneytools.dev/v1/spend/check (advisory; free trial 50 calls / 7 days, or 0.005 USDC) (3) if high-risk or over a threshold, Approval Relay https://relay.moneytools.dev/v1/approvals (0.005 USDC, 3 free/day) (4) pay, then Spend Ledger https://ledger.moneytools.dev/ . Suite docs and examples: https://moneytools.dev/products/payment-safety/
MCP (streamable HTTP): https://settle.moneytools.dev/mcp · OpenAPI: https://settle.moneytools.dev/openapi.json · x402 discovery: https://settle.moneytools.dev/.well-known/x402 · Spend caps guide: https://settle.moneytools.dev/docs/spend-caps

## MCP-paid tool
settle_report (read-only, no arguments, $0.005 USDC/call) uses the x402 MCP transport: an unpaid call returns an isError result whose structuredContent is PaymentRequired {x402Version:2, accepts[]} (same JSON in content[0].text); retry with params._meta["x402/payment"]; settlement in result._meta["x402/payment-response"]. With a Settle key it costs 1 call instead.

Read-only: we never sign, send or hold funds or keys. Support: support@moneytools.dev