For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

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

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

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

Response — flagged

Response — clean

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.

Sanctions name check ($0.04)

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

Request

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

Response

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:

Quote

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

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

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.

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.

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

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.

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):

The signer needs only USDC on Base (or Polygon/Arbitrum/Solana) — gas is sponsored. For questions or integration support, contact support@madhousewallet.com.

Last updated

Was this helpful?