@quackai/q402-mcp

MCP server for Q402 - gasless USDC, USDT, RLUSD, and USDG payments across 12 EVM chains (USDG on Robinhood Chain), callable from Claude (Desktop / Code), OpenAI Codex CLI, and any other Model Context Protocol client.

Free trial available. 500 gasless transactions on BNB Chain + Base (USDC + USDT), no card. One wallet signature: https://q402.quackai.ai. Limited-time bonus: Mantle (USDC + USDT) is also covered by trial keys during 2026-08-21~08-28 UTC+9.

Trial-scope policy: API keys minted under the free-trial program (plan: "trial") settle on BNB Chain (USDC/USDT gasless) and Base (USDC/USDT gasless) as permanent chains. Avalanche trial has ended — use a Multichain key for avax. Mantle (USDC/USDT gasless) is covered during the limited-time window 2026-08-21~08-28 UTC+9 — server-side time enforcement, returns TRIAL_BNB_ONLY outside the window. Paid API keys see the full 12-chain matrix at all times.

Quote → route → (optional) settle stablecoin payments across 12 EVM chains, from any MCP client. Recipient gets the full amount; sender pays $0 gas via Q402's EIP-7702 relayer.

---

Quick start

1. Register the server with your client (one-line per client).
2. Say "Set up Q402" to your agent. It runs q402_doctor → creates ~/.q402/mcp.env → walks you through pasting keys.

1. Register the server

Client	Command / config
Claude Code (CLI)	claude mcp add q402 -- npx -y @quackai/q402-mcp
Claude Desktop (app)	Edit claude_desktop_config.json (Settings → Developer → Edit Config): { "mcpServers": { "q402": { "command": "npx", "args": ["-y", "@quackai/q402-mcp"] } } }. Restart the app.
OpenAI Codex CLI	codex mcp add q402 -- npx -y @quackai/q402-mcp (Windows fallback: see below)
Cursor	Add to ~/.cursor/mcp.json: { "mcpServers": { "q402": { "command": "npx", "args": ["-y", "@quackai/q402-mcp"] } } }
Cline	Cline → Settings → MCP Servers → Edit JSON. Same shape as Cursor.
GitHub Copilot (VS Code)	Add to .vscode/mcp.json - root key is servers, not mcpServers: { "servers": { "q402": { "command": "npx", "args": ["-y", "@quackai/q402-mcp"] } } }. Reload VS Code, then enable q402 in the Copilot Chat tools picker.
Hermes Agent (Nous Research)	YAML, not JSON. Add under mcp_servers in ~/.hermes/config.yaml (see below), then run /reload-mcp.
Any other stdio MCP client	Point it at npx -y @quackai/q402-mcp. No client-specific code.

Hermes reads MCP servers from ~/.hermes/config.yaml under mcp_servers (YAML, not JSON):

mcp_servers:
  q402:
    command: "npx"
    args: ["-y", "@quackai/q402-mcp"]
    enabled: true

After editing, run /reload-mcp in Hermes to load the tools. Or use the CLI: hermes mcp add q402 --command npx --args -y @quackai/q402-mcp.

Claude Code (the CLI, claude binary) and Claude Desktop (the macOS / Windows app) are different products. The claude mcp add command only exists in the CLI; the Desktop app needs the JSON config above.

Secrets are NOT in this config. The server reads them from ~/.q402/mcp.env (same pattern as AWS / Stripe / gh CLIs).

Some Windows setups block codex.exe from writing its own config. Add the stanza to ~/.codex/config.toml by hand:

[mcp_servers.q402]
command = "npx"
args = ["-y", "@quackai/q402-mcp"]

Then restart Codex. Same effect as codex mcp add q402 -- npx -y @quackai/q402-mcp.

2. First-time setup

Restart your client, ask: > "Set up Q402"

The agent runs q402_doctor. On first install:

1. Creates ~/.q402/mcp.env (placeholders)
2. Opens it in your editor
3. Walks you through pasting an API key + a signing path into the file, not into chat
4. Restart + re-run q402_doctor to verify

Keys never paste into chat. Local modes sign on your machine; the key never leaves the device. Mode C (server-managed) needs no PK on the client.

Pick a signing mode

Mode	Env	Signer	Notes
A	Q402_PRIVATE_KEY	MetaMask EOA, local	Simplest. Shows "Smart account" after first use (reversible via q402_clear_delegation). After EIP-7702 delegation to an older implementation, q402_x402_fetch is unavailable until q402_clear_delegation is called (gasless, reversible; next q402_pay re-delegates). If delegated to the current ERC-1271-capable implementation, q402_x402_fetch works normally.
B	Q402_AGENTIC_PRIVATE_KEY	Agent Wallet, local	Export PK from the dashboard → Wallets → Danger Zone → Export private key. MetaMask untouched.
C	(just an API key)	Agent Wallet, server-managed	No PK on the client. One-shot pays accept Trial or Multichain keys; recurring needs Multichain on every chain (BNB included).

When more than one mode is set, q402_pay asks the user which to use. Picker: walletMode = "agentic-server" \| "agentic-local" \| "eoa".

Manual setup (no AI)

Create ~/.q402/mcp.env yourself with the template below. Live mode only flips when an API key + a signing path are populated, so saving the template as-is stays in sandbox. Q402_ENABLE_REAL_PAYMENTS=0 forces sandbox even with real keys.

# ~/.q402/mcp.env

# ── API key (pick one or both for auto-routing) ──
Q402_TRIAL_API_KEY=          # Free Trial, BNB (permanent) + Base (permanent) + Mantle limited-time (from /event)
Q402_MULTICHAIN_API_KEY=     # Paid Multichain, all 12 chains (from /payment)

# ── Signing path - pick ONE of Mode A / B / C ──
# Mode A: your MetaMask EOA's hex private key.
# Hardware wallets (Ledger / Trezor) are NOT supported here - Q402
# needs a raw hex key it can sign EIP-7702 type-4 authorizations with.
Q402_PRIVATE_KEY=

# Mode B: exported Agent Wallet pk from the dashboard. Keeps your
# MetaMask untouched. Get it at:
#   https://q402.quackai.ai/dashboard → Agent tab → Export
Q402_AGENTIC_PRIVATE_KEY=

# Mode C: no PK needed. A Trial key also enables Mode C one-shot payments;
# leave both PK lines blank. Q402 signs with the server-managed Agent Wallet.
# Multichain key required for recurring, Mode C batch, and bridge/OFT.
# Optional: pin one of your Agent Wallets when you have multiple (max 10).
# Q402_AGENT_WALLET_ADDRESS=0x...

# Live mode switch:
#   0 = sandbox (test mode, no funds move)
#   1 = real on-chain payments
# Default 1 - safe because mode only flips to live when an API key AND
# at least one valid signing path (A/B/C) are populated above.
Q402_ENABLE_REAL_PAYMENTS=1

# Default Q402 deployment. Only change for self-hosted.
Q402_RELAY_BASE_URL=https://q402.quackai.ai/api

# Safety guards (max-amount ships uncommented at $200; lower for tighter caps):
Q402_MAX_AMOUNT_PER_CALL=200
# Q402_ALLOWED_RECIPIENTS=0xabc...,0xdef...

# Pre-check (automatic trust-check before outgoing payments in live mode).
# Triggers when paying a first-time counterparty OR amount >= $1.
# Fee: $0.02 per check; verdict cached 7 days (no repeat charge within TTL).
# Set to 1 to disable pre-check entirely (even first-time / large-amount pays).
# Q402_DISABLE_PRECHECK=0

Then chmod 600 ~/.q402/mcp.env (Unix) and restart your client. That's the full configuration. Heads up on the EIP-7702 side effect: after your first live payment on a chain, your wallet will show 'Smart account' in MetaMask / OKX - that's the delegation Q402 uses for gasless settlement, reversible anytime via q402_clear_delegation. Important for x402 users: if EIP-7702 delegation is active on an older implementation, q402_x402_fetch cannot sign x402 payments until you call q402_clear_delegation (gasless on Base, reversible — the next q402_pay re-delegates automatically). Wallets delegated to the current ERC-1271-capable implementation work normally.

Advanced - explicit env injection

If you'd rather skip the file and inject env vars yourself (e.g. via Codex env_vars allow-list, a secrets manager, or shell exports), the server falls through to process.env - and process.env wins over file values on conflicts. So existing shell-export setups keep working unchanged.

[mcp_servers.q402]
command = "npx"
args = ["-y", "@quackai/q402-mcp"]
startup_timeout_sec = 20.0
env_vars = [
  "Q402_TRIAL_API_KEY",
  "Q402_MULTICHAIN_API_KEY",
  "Q402_PRIVATE_KEY",
  "Q402_AGENTIC_PRIVATE_KEY",
  "Q402_AGENT_WALLET_ADDRESS",
  "Q402_ENABLE_REAL_PAYMENTS",
  "Q402_RELAY_BASE_URL",
]

Then export the values in ~/.zshrc / ~/.bashrc. See the Codex config reference for the full schema.

Try it without any setup

q402_quote works with zero configuration - no API key, no private key, no env file. Ask:

"Compare gas costs to send 50 USDC to vitalik.eth across all 12 Q402 chains."

---

Q402_RELAY_BASE_URL overrides the relay endpoint. Set it explicitly when running against a self-hosted Q402 deployment or a non-canonical environment.

---

Tools exposed

47 tools, grouped by capability. Read-only by default; live mode needs a live API key, a signing path, and Q402_ENABLE_REAL_PAYMENTS=1. Rows marked live mode move funds and need an explicit in-chat confirmation.

Tool	Auth	Purpose
Payments & wallet
q402_doctor	none	First-install onboarding + ongoing health check (per-scope quota, EIP-7702 state, relay reachability, slot-mismatch warnings).
q402_quote	none	Compare gas + supported tokens across chains.
q402_balance	api key	Verify key + remaining quota.
q402_pay	live mode	Single-recipient gasless transfer. Sandbox by default. In live mode, automatically runs a trust-check ($0.02) on the recipient before each payment when it is a first-time counterparty or the amount ≥ $1; verdict cached 7 days (no double-charge within TTL). Degrades to free basic verdict only when wallet balance exactly covers the transfer but not the $0.02 fee, or when only a non-USDC rail token is available. Pre-check never blocks the main transaction. Disable with Q402_DISABLE_PRECHECK=1.
q402_batch_pay	live mode	Up to 20 recipients per call. Trial: 5 - applies when paying with your own key (Mode A/B); server-managed Agent Wallet (Mode C) batch is paid Multichain-only. Same auto-routing as q402_pay. 6+ BNB batches with Trial set return status="ambiguous" so the agent asks how to split. xlayer + stable not batchable - use q402_pay in a loop.
q402_receipt	none	Fetch + locally verify a Trust Receipt (rct_… id, ECDSA against the relayer EOA).
q402_wallet_status	private key	Per-chain EIP-7702 state for the EOA derived from Q402_PRIVATE_KEY.
q402_clear_delegation	private key / api key	Clear EIP-7702 delegation (Mode A/B local key OR Mode C api key, server-signed). Sponsored on every chain except Ethereum (billed to your Gas Tank). Two-phase consent (consentToken).
q402_agentic_info	api key	Agent Wallet info (addresses, per-wallet caps, daily-spend used, ERC-8004 id). Drives Mode C.
Treasury memory
q402_memory_summary	api key	Treasury overview over a window: USD-stablecoin spend by chain/source, top vendors, schedules, open requests/escrow, failures. Read-only.
q402_vendor_history	api key	Total paid to one vendor (or a vendor leaderboard) with recurring cadence. Read-only.
q402_agent_spend_report	api key	Per-Agent-Wallet spend with each wallet's caps. Read-only.
Recurring
q402_recurring_list	api key	List scheduled rules.
q402_recurring_create	api key	Author a recurring rule. Paid Multichain on EVERY chain (BNB included).
q402_recurring_fires	api key	Last 50 fires per rule (timestamp + txHashes + amount).
q402_recurring_pause	api key	Pause a rule (reversible).
q402_recurring_resume	api key	Resume a paused / stopped rule.
q402_recurring_skip_next	api key	Skip only the next scheduled fire.
q402_recurring_cancel	api key	Permanently stop a rule.
Bridge (CCIP + LayerZero)
q402_bridge_quote	none	Quote a Chainlink CCIP USDC bridge across eth/avax/arbitrum. Returns LINK + native fee.
q402_bridge_send	live mode	Execute a CCIP bridge from the user's Agent Wallet. Mode C only (server-managed). Sandbox-by-default; sandbox: false + live Multichain key + Q402_ENABLE_REAL_PAYMENTS=1 fires a real on-chain bridge.
q402_bridge_history	not yet wired	Pointer to the dashboard. Returns { implemented: false, dashboardUrl, dashboardPath } - read-only guidance until owner-sig auth lands in MCP.
q402_bridge_gas_tank	not yet wired	Static guidance + dashboard pointer for the Bridge Gas Tank top-up flow. Live balance lookup needs owner-sig auth (dashboard for now).
q402_oft_quote	none	Quote the LayerZero fee for bridging USDT0 across the OFT set (eth/arbitrum/mantle/monad/xlayer). Returns native messaging fee + delivered amount. Companion to q402_bridge_quote (CCIP/USDC).
q402_oft_send	live mode	Bridge USDT0 via LayerZero OFT from the Agent Wallet to the same address on the destination chain. Mode C (server-managed). Sandbox-by-default; confirm: true + live Multichain key + Q402_ENABLE_REAL_PAYMENTS=1 fires a real bridge.
q402_oft_history	not yet wired	Pointer to the dashboard for LayerZero OFT bridge history. Returns { implemented: false, dashboardUrl } - read-only guidance until owner-sig auth lands in MCP.
Yield
q402_yield_reserves	none	List Q402 Yield lending markets - protocol, chain, asset, market address, supply APY. Curated lending markets per chain (Aave/Lista on BNB, Morpho on Base); each market reports its own venue.
q402_yield_positions	api key	Show the Agent Wallet's open Q402 Yield positions (balance, principal, accrued interest, APY) + total supplied in USD. Mode C.
q402_yield_deposit	live mode	Supply the Agent Wallet's stablecoins into Q402 Yield's curated lending market per chain: BNB (USDC/USDT) or Base (USDC only). Mode C. Requires confirm: true; sandbox-by-default.
q402_yield_withdraw	live mode	Withdraw supplied stablecoins out of Q402 Yield (curated lending markets on BNB and Base) back to the Agent Wallet (amount: "max" = max currently redeemable, which vault caps or queues can leave below the full position). Mode C. Requires confirm: true; sandbox-by-default.
Staking
q402_stake	live mode	Gasless Q (QuackAI) staking into QuackAiStake on BNB Chain. Lock tiers 0-3 (30d/10%, 60d/15%, 120d/32%, 180d/40% APR). amount: "max" stakes the whole Q balance. Mode C. Requires confirm: true; sandbox-by-default.
q402_unstake	live mode	Gasless unstake of matured Q on BNB. Per-record: exit one stake by index (ith) or all: true for every matured stake. Mode C. Requires confirm: true; sandbox-by-default.
q402_stake_positions	live mode	The Agent Wallet's open Q stakes (indices, maturity, exitable) + liquid Q balance. Read-only; Mode C.
Payment requests
q402_request_create	api key	Publish a payment request (invoice). No funds move; returns a shareable /pay link + req_… id. Recipient defaults to the Agent Wallet.
q402_request_status	none	Look up a payment request by req_… id (amount, token, chain, recipient, status). Read-only; notFound instead of throwing.
q402_request_pay	live mode	Pay a request gaslessly from the payer's own Agent Wallet (Mode C). Terms come from the stored request, so they can't be redirected. Two-phase consent (same as q402_pay).
Escrow
q402_escrow_create	api key	Create a gasless non-custodial escrow (pending record, moves no funds); optional walletId funds it from an Agent Wallet. Chain availability served by GET /api/escrow/chains — the server enforces on every request.
q402_escrow_status	none	Read an escrow's state, parties, amount, and tx hashes. Read-only.
q402_escrow_lock	live mode	Fund a pending escrow gaslessly (EIP-7702); the server signs for an Agent-Wallet buyer. Sandbox-by-default. Chain availability served by GET /api/escrow/chains.
q402_escrow_release	live mode	Buyer releases a locked escrow to the seller (gasless). Sandbox-by-default.
q402_escrow_refund	live mode	Permissionless refund to the buyer after the timeout / resolve window.
q402_escrow_dispute	live mode	A party disputes an open escrow (requires a named arbiter).
Triggers (RedStone)
q402_redstone_feeds	none	Which RedStone feeds this deployment can drive triggers off (NAV / price / RWA). Read-only.
q402_redstone_trigger_create	live mode	Arm a gasless payout that fires once when a RedStone feed crosses a threshold (edge-latched).
q402_redstone_trigger_list	live mode	List the Agent Wallet's RedStone triggers + their state.
q402_redstone_trigger_cancel	live mode	Permanently stop a RedStone trigger.
x402 (outbound)
q402_x402_fetch	live mode	Fetch any x402-gated URL and handle HTTP 402 automatically: validates Base USDC payment option, guards against excess spend, signs EIP-3009 TransferWithAuthorization, and retries with the correct payment header (PAYMENT-SIGNATURE for v2 servers, X-PAYMENT for v1 legacy). Non-402 responses pass through unchanged. Returns status:"settled_no_delivery" (fundsMoved:true, retrySafe:false) when a txHash in the response confirms funds moved but the seller returned an error. Returns status:"settled_status_unknown" (fundsMovedUnknown:true, retrySafe:false) when no settlement proof exists — funds may or may not have moved. Do NOT retry either outcome.
q402_governance_analyze	live mode	Paid governance proposal analysis. Paste a snapshot.org / snapshot.box link (or raw text) and optionally describe your priority in plain language; get a vote recommendation (For / Against / Abstain), five dimension ratings, and the reasoning. Pass language (e.g. "zh") to receive results in the user's language. $0.05 USDC per call on Base via x402.

q402_pay + q402_batch_pay + q402_bridge_send + q402_yield_deposit + q402_yield_withdraw + q402_stake + q402_unstake + q402_request_pay require explicit in-chat confirmation. Batch confirmation = full batch, not per-row.

Note: q402_pay expects a 0x address; ENS is not resolved server-side, so resolve it client-side first. Per-chain Gas Tank balances + full TX history live in the dashboard (wallet-signature only).

---

x402 outbound payments (q402_x402_fetch)

q402_x402_fetch is a general-purpose x402 client. It fetches any URL and handles HTTP 402 payment-required responses automatically. When the server returns a non-402 status, the response passes through unchanged, so it also works as a regular fetch tool.

What it solves. Some APIs and content endpoints use the x402 protocol to charge per-request. An agent hitting such a URL receives an HTTP 402 response with machine-readable payment requirements. q402_x402_fetch reads those requirements, validates the payment option, signs an EIP-3009 TransferWithAuthorization against Base USDC, encodes it as a base64 JSON payload, and retries the request — using PAYMENT-SIGNATURE for x402 v2 servers and X-PAYMENT for legacy v1 servers — all in one call.

Supported. scheme=exact + network=base (CAIP-2 eip155:8453; also accepted: base-mainnet) + Base USDC only. Any other scheme, network, or asset returns an explicit rejection and no signature is produced.

Guards (three layers).

Guard	Env var	Default
Per-call spend cap	Q402_MAX_AMOUNT_PER_CALL	$200
Per-session cumulative cap	Q402_X402_SESSION_CAP_USD	$5
Two-phase consent	consentToken	required on payment

Two-phase consent flow: the first call (without consentToken) returns needs_confirmation with a preview quoting the exact amount and recipient plus a consentToken. Present the quote to the user verbatim and wait for their next independent message confirming payment. Only then re-call with the same arguments plus the consentToken. The token is single-use, expires in ~120 seconds, and is rejected if consumed within 2 seconds of issuance (same-round double-call protection: a timing threshold, not a proof of human confirmation). Never re-call in the same conversation turn without a separate user confirmation message.

Result outcomes — read before summarizing to users.

Outcome	Fields	Meaning
success: true	body, paid: true, payTo, amountUsd	Content delivered, payment settled.
success: false, needsConsent set	consentToken, preview	No payment made. Re-call with consentToken.
success: false, status: "settled_no_delivery"	fundsMoved: true, retrySafe: false, recipient, amount, txHash, guidance	Funds confirmed left the wallet, content not delivered. Settlement is proven by txHash from the response. The seller accepted payment but returned an error. Do NOT tell the user "the payment didn't go through" — funds moved. Do NOT retry — that would make a second payment. Surface amount, recipient, txHash, and guidance to the user so they can reconcile with the seller.
success: false, status: "settled_status_unknown"	fundsMovedUnknown: true, retrySafe: false, recipient, amount, txHash: null, guidance	Settlement unknown — funds may or may not have moved. Payment header was sent but the response contained no settlement proof (no txHash). Do NOT assert that funds moved or didn't move. Do NOT retry with the same parameters — funds may have already moved. Surface guidance so the user can check their wallet balance and contact the seller.
success: false (other)	error	Payment blocked or rejected before settlement. No funds moved. Safe to retry.

Audit. Every 402 attempt — settled, settled_no_delivery, settled_status_unknown, or blocked — is written to the local audit log at ~/.q402/x402-audit.json and surfaced in q402_agent_spend_report. Both settled_no_delivery and settled_status_unknown outcomes count as spend in the report.

Minimum working example.

{
  "url": "https://api.example.com/data",
  "method": "GET",
  "confirm": true
}

If the endpoint returns 402, the tool responds with needs_confirmation and a consentToken. Present the quote to the user verbatim and wait for their next independent message. Re-call with those same arguments plus the consentToken to authorize payment. The token is single-use and expires in ~120 seconds.

Requirements. Q402_ENABLE_REAL_PAYMENTS=1 plus a local signing key (Q402_AGENTIC_PRIVATE_KEY or Q402_PRIVATE_KEY). The signed authorization goes directly to the seller's facilitator endpoint; the Q402 relay is not involved in this path.