x402 Agentic Payments

Call Madhouse's compliance, payout, and KYC APIs from an AI agent — paying per request in USDC with no API keys, via x402 and the AgentCash MCP.

Madhouse exposes three production APIs that an autonomous agent can call and pay for per request, in USDC, with no API key, no signup, and no invoice. Each endpoint is gated by the x402 protocol: the first request returns 402 Payment Required with payment terms, the client signs a USDC micropayment, retries, and gets the data.

You don't implement x402 by hand. The AgentCash MCP server holds a USDC wallet and handles the 402 → sign → settle → retry loop for you. From the agent's side, it's a single fetch call.

Service	Base URL	What it does
Scanner	scan.madhousewallet.com	Wallet risk scoring + sanctions name screening
Payouts	try.madhousewallet.com	Quote and send cross-border fiat payouts (80+ currencies)
KYC	kyc.madhousewallet.com	On-chain identity attestation (EAS / SAS) + wallet sanctions screening

All three accept USDC on Base, Polygon, Arbitrum (EVM) and Solana. Payment settles through the Coinbase CDP facilitator, which sponsors gas — you only pay the listed price.

---

How payment works

Agent ──fetch──▶ endpoint
        ◀── 402 Payment Required (price, network, payTo, asset)
AgentCash signs an EIP-3009 / SPL USDC transfer for the exact amount
Agent ──fetch (X-PAYMENT header)──▶ endpoint
        ◀── 200 OK + JSON body

There are no refunds — the exact scheme moves funds on-chain before the handler runs. Endpoints that mutate state (transfers, KYC sessions) are idempotent upstream, so a retry after a network blip does not double-charge the business logic, but each HTTP attempt that reaches a 402 and pays is a separate USDC charge. Cache successful responses; don't poll paid endpoints in a tight loop.

---

Using AgentCash (the fast path)

AgentCash is already wired into this environment as an MCP server. The workflow is three tool calls:

1. Check / fund the wallet. Paid calls need a balance; the free endpoints don't.

get_balance()                 → { "usdc": "4.92", ... }
list_accounts()               → deposit addresses + funding link (if balance is low)

2. Discover the endpoints for a base URL. This pulls the live OpenAPI + price for every route — you don't hardcode paths.

discover_api_endpoints("https://scan.madhousewallet.com")
discover_api_endpoints("https://try.madhousewallet.com")
discover_api_endpoints("https://kyc.madhousewallet.com")

3. Call the endpoint. fetch handles the 402 automatically and returns the final body.

fetch({
  url: "https://scan.madhousewallet.com/api/public/quick-scan?address=vitalik.eth",
  method: "GET"
})

Pick the network with fetch's payment options if you want to pay on Polygon/Arbitrum/Solana instead of Base — otherwise it defaults to the first accepted network (Base). Use check_endpoint_schema before a POST if you're unsure of the body shape.

If you're not running AgentCash, any x402 client works — see Calling raw x402 at the bottom.

---

Pricing

Prices are fixed per call, charged in USDC regardless of which chain you pay on. The /solana variant of any endpoint is the same price as its EVM sibling — it just settles on Solana.

scan.madhousewallet.com

Endpoint	Method	Price	Notes
/api/public/quick-scan	GET	$0.01	~350 ms. Risk score + traits only.
/api/public/scan	GET	$0.01	~9 s. Full metrics incl. USD volumes, ENS, contract flag.
/api/public/sanctions-check	GET	$0.04	OpenSanctions name/entity screening.
/api/public/quick-scan/solana, /scan/solana, /sanctions-check/solana	GET	same as above	Pay on Solana.

try.madhousewallet.com

Endpoint	Method	Price
/api/public/quote	GET	$0.01
/api/public/requirements	GET	$0.01
/api/public/requirements/refresh	POST	$0.01
/api/public/recipients	POST	$0.01
/api/public/transfer	POST	$0.01
/api/public/confirm-transfer	POST	$0.01
/api/public/transfer-status	GET	$0.01

A complete payout costs ~$0.05–0.06 in x402 fees (quote → requirements → recipient → transfer → confirm), separate from the FX/payout fees on the money itself.

kyc.madhousewallet.com

Endpoint	Method	Price
/api/public/kyc/start	POST	$0.05
/api/public/kyc/status	GET	$0.01
/api/public/kyc/sanctions	GET	$0.02
/api/public/kyc/verified	GET	Free (60 req/min/IP)
/api/public/kyc/start-eoa	POST	Free (wallet-signature gated, 5 req/min/IP)

Each paid endpoint has a /solana twin at the same price.

---

Scanner — wallet risk & sanctions

scan.madhousewallet.com

Quick scan (cheapest, real-time)

Best for pre-transaction screening. Accepts a 0x address or an ENS name.

Request

GET /api/public/quick-scan?address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

Response — flagged

{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "toxicScore": 0.95,
  "riskLevel": "CRITICAL",
  "shouldFlag": true,
  "traits": [
    {
      "name": "initiator_scam_transactions",
      "risk": 0.95,
      "txsCount": 1,
      "description": "The address has initiated scam airdrops or poisoning attacks."
    }
  ]
}

Response — clean

{ "address": "0x1234…", "toxicScore": 0, "riskLevel": "PASS", "shouldFlag": false, "traits": [] }

riskLevel: PASS (0) · LOW (0–0.40) · MIDDLE (0.41–0.80) · CRITICAL (≥0.81).

Full scan

Same input, slower (~9 s), richer output: flaggedMetrics[] carries type (absolute | volume), incomingMoneyUSD, outgoingMoneyUSD, plus ens, isContract, addressExists.

{
  "address": "0xd8dA…", "toxicScore": 0.04, "riskLevel": "LOW", "shouldFlag": true,
  "flaggedMetrics": [
    { "name": "non_kyc_transfers", "risk": 0.03, "type": "volume",
      "description": "Transacted with non-KYC exchanges",
      "txsCount": 344, "incomingMoneyUSD": 15722.47, "outgoingMoneyUSD": 2484.15 }
  ],
  "ens": "vitalik.eth", "isContract": false, "addressExists": true
}

Sanctions name check ($0.04)

Screens a person/company name against OpenSanctions (EU, UN + 330 lists).

Request

GET /api/public/sanctions-check?name=Viktor%20Bout&country=ru&birthDate=1967-01-13

name is required; country (ISO-2), address, and birthDate (YYYY or YYYY-MM-DD) are optional filters that cut false positives.

Response

{
  "sanctioned": true,
  "name": "Viktor Bout",
  "matchCount": 1,
  "matches": [
    {
      "entityId": "Q314650",
      "caption": "Viktor Anatolijevitch BOUT",
      "entityType": "Person",
      "topics": ["role.pep", "sanction", "debarment"],
      "matchedOn": ["name", "country", "birthDate"],
      "datasets": ["us_ofac_sdn", "us_trade_csl", "eu_financial_sanctions_files"]
    }
  ]
}

Edge cases

• Score normalization. toxicScore is 0–1, but the upstream may return 0–100 for confirmed bad actors. The API normalizes (s > 1 ? s/100 : s) — trust the returned 0–1 value.

• Off-ramp rule: only toxicScore === 0 is truly clean. shouldFlag is true for any non-zero score.

• Sparse sanctions matching is AND-logic with fallback: a name-only query (e.g. John Smith) returns many matches because country/birthDate filters are skipped when absent. Read matchedOn[] per match to judge confidence — a hit on ["name","country","birthDate"] is high-confidence; ["name"] alone is weak.

• 503 from sanctions = MongoDB blip; retry with backoff. 400 = missing name or bad address format.

---

Payouts — cross-border fiat

try.madhousewallet.com

KYC and sanctions screening on the funding wallet and recipient are enforced upstream, so these endpoints are safe to drive from an agent. The flow is six paid calls:

1. GET  /api/public/quote                 → quoteId + FX rate + fees
2. GET  /api/public/requirements?currency=NGN   → dynamic bank-detail fields
3. POST /api/public/requirements/refresh  → (only if a field has refreshRequirementsOnChange)
4. POST /api/public/recipients            → recipientId
5. POST /api/public/transfer              → transfer_id + deposit_address
   (user sends USDC to deposit_address on Base)
6. POST /api/public/confirm-transfer      → status: processing
   GET  /api/public/transfer-status?id=…  → poll to completed

Quote

GET /api/public/quote?targetCurrency=NGN&sourceAmount=100

{
  "quoteId": "7f3c1a2b-0d9e-4a6f-8c11-2b9d4e5f6a7b",
  "sourceAmount": 100,
  "targetCurrency": "NGN",
  "usdToTargetRate": 1580.42,
  "serviceFeePercent": 1.5,
  "quote": {
    "targetAmount": 155661.4, "transferFee": 0.5,
    "feeFxPercent": 0.47, "feeFxAmount": 0.32, "feePayoutAmount": 0.18,
    "estimatedDelivery": "2026-06-01T12:00:00.000Z"
  }
}

Requirements return field descriptors that vary per currency (Nigeria needs bankCode + 10-digit accountNumber; an IBAN country needs IBAN, etc.). If any field has refreshRequirementsOnChange: true, call requirements/refresh with the values chosen so far to reveal the conditional fields.

Create recipient → transfer

POST /api/public/recipients
{ "currency":"NGN", "type":"nigeria_bank_account", "accountHolderName":"Ada Lovelace",
  "details":{ "bankCode":"058", "accountNumber":"0123456789" },
  "wallet":"0x1234…" }
→ { "id": 12345, "active": true, ... }

POST /api/public/transfer
{ "quote_id":"7f3c…", "amount":100, "recipientId":12345,
  "customer_uuid":"2b9d…", "customer_email":"[e-mail]",
  "source_token":"usdc", "source_network":"base", "wallet_address":"0x1234…" }
→ { "transfer_id":"6650f1a2b3c4d5e6f7a8b9c0",
    "deposit_address":"0x…", "amount":100, "currency":"NGN",
    "instructions": { "send_amount":100, "send_token":"usdc", "send_network":"base", ... } }

After the user sends USDC to deposit_address, confirm with the on-chain tx hash:

POST /api/public/confirm-transfer
{ "transfer_id":"6650f1a2b3c4d5e6f7a8b9c0", "tx_hash":"0xabc…def" }
→ { "transfer_id":"6650…", "status":"processing", "message":"Transfer confirmed and queued for payout." }

transfer-status cycles through pending → awaiting_deposit → deposit_sent → processing → completed (or failed).

Edge cases

• Quotes expire (~5 min). A stale quote_id fails at /transfer — re-quote and retry.

• amount must equal the quote's sourceAmount. Validation rejects mismatches; max is 1,000,000.

• Idempotency: confirm-transfer is idempotent on tx_hash — re-submitting the same hash won't double-pay out. Generate one customer_uuid per logical transfer.

• Conditional fields: skipping requirements/refresh when required leaves you with an incomplete recipient body → 400.

• Recipient/wallet rejected by upstream sanctions screening surfaces as a 4xx with a message — don't retry, surface it.

---

KYC — on-chain identity attestation

kyc.madhousewallet.com

Verifies a real person via Stripe Identity (document + selfie) and writes a permanent attestation on-chain — EAS on Base/Polygon/Arbitrum, SAS on Solana. The wallet that pays the x402 charge is the wallet that gets bound to the attestation.

Start a session ($0.05). Body is empty — the payer wallet comes from the payment header.

POST /api/public/kyc/start      body: {}
→ { "kycUrl": "https://kyc.madhousewallet.com/verify/vs_1Taj…",
    "walletAddress": "0xef61…73f7" }

Open kycUrl in a browser to finish verification. A Stripe webhook then writes the attestation on-chain automatically — no further call needed from you.

Check status ($0.01). Authoritative: reads on-chain and checks revocation.

GET /api/public/kyc/status?wallet=0xef61…73f7
→ {
    "walletAddress": "0xef61…73f7", "verified": true, "chain": "base",
    "easUID": "0x9f8e…0100", "txHash": "0xa1b2…a1b2",
    "sasAttestationAddress": null, "verifiedAt": 1716500000,
    "verificationMethods": { "documentType": "passport", "selfieCheck": "verified" },
    "riskScore": "low"
  }

Free verification check — for gating logic at scale. DB-only, no on-chain read, no revocation check, rate-limited 60/min/IP.

GET /api/public/kyc/verified?wallet=0xef61…73f7
→ { "wallet": "0xef61…73f7", "verified": true }

Wallet sanctions ($0.02). Screens the verified person behind a wallet against OpenSanctions. PII is pulled transiently from Stripe and never stored or returned — only the match metadata comes back.

GET /api/public/kyc/sanctions?wallet=0xef61…73f7
→ { "walletAddress":"0xef61…73f7", "sanctioned": false, "matchCount": 0, "matches": [] }

Edge cases

• verified: true requires the attestation to be on-chain AND not revoked. A wallet mid-flow (awaiting_stripe / attesting) returns verified: false, not an error.

• /verified (free) vs /status (paid): use free for cheap gating; use paid /status when you need the revocation-checked source of truth.

• /sanctions needs a completed attestation first — screening a wallet with no on-chain KYC record returns 404.

• Pay-network ≠ attestation-chain. The attestation chain is fixed at /start (EVM → Base by default; the /solana route → SAS on Solana). Paying /status on Polygon doesn't move the attestation.

• start-eoa is the free, signature-gated entry point: prove wallet ownership with a signed nonce (valid 60 s) instead of paying. Recovered signer must match walletAddress or you get 401.

---

Networks & assets

Network	CAIP-2	USDC contract
Base	eip155:8453	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
Polygon	eip155:137	0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359
Arbitrum	eip155:42161	0xaf88d065e77c8cC2239327C5EDb3A432268e5831
Solana	solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp	EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

EVM endpoints accept all three EVM chains on the main path; Solana settlement uses the explicit /solana route. CDP sponsors gas on every chain, so your wallet only needs the listed USDC amount — no ETH/SOL for gas.

---

Common status codes

Code	Meaning
402	Payment required — the client signs USDC and retries (AgentCash does this for you).
400	Bad input — missing param, malformed address/tx hash, unsupported currency.
401	Signature didn't match the claimed wallet (start-eoa).
404	No record — e.g. KYC sanctions on an unverified wallet.
429	Rate limit — only on the free KYC endpoints.
503	Upstream blip (sanctions DB / scanner) — retry with backoff.

---

Discovery

Every service publishes machine-readable discovery, which is what discover_api_endpoints reads:

• GET /.well-known/x402 — list of payable resource URLs.

• GET /openapi.json — full OpenAPI 3.1 with x-payment-info (price, currency, network) and x-payment-networks per operation.

Endpoints are also auto-registered in the Coinbase Bazaar after their first settlement, so x402-aware agents can find them without a hardcoded list.

---

Calling raw x402

Without AgentCash, use any x402 client (e.g. @x402/fetch with a funded signer):

import { wrapFetchWithPayment } from "@x402/fetch"
import { privateKeyToAccount } from "viem/accounts"

const account = privateKeyToAccount(process.env.PAYER_PRIVATE_KEY)
const fetchWithPay = wrapFetchWithPayment(fetch, account) // signs the 402 + retries

const res = await fetchWithPay(
  "https://scan.madhousewallet.com/api/public/quick-scan?address=vitalik.eth"
)
console.log(await res.json())

The signer needs only USDC on Base (or Polygon/Arbitrum/Solana) — gas is sponsored. For questions or integration support, contact [e-mail].