Q402 MCP Server

@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

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

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: after EIP-7702 delegation is active, q402_x402_fetch cannot sign x402 payments until you call q402_clear_delegation (gasless on Base, reversible — the next q402_pay re-delegates automatically).

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.

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

Two-phase consent flow: the first call (without consentToken) returns needs_confirmation and a preview of the amount and recipient. Re-call with the same arguments plus the returned consentToken to authorize the payment.

Result outcomes — read before summarizing to users.

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. Re-call with those same arguments plus the consentToken to authorize payment.

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.

Prerequisite — delegation check. q402_x402_fetch uses EIP-3009 signing, which is incompatible with an EIP-7702-delegated wallet. If you have previously called q402_pay on this wallet, it may be EIP-7702-delegated (shown as 'Smart account' in MetaMask / OKX). In that state, q402_x402_fetch will fail. Recovery: call q402_clear_delegation (gasless on Base, reversible). After clearing, q402_x402_fetch works again. The next q402_pay re-delegates automatically.

---

Sandbox vs live mode

Sandbox default: q402_pay returns a fake txHash with success: false and sandbox: true. No funds, no quota.

Live = (a) live API key (q402_live_*), (b) a signing path (A / B / C), (c) Q402_ENABLE_REAL_PAYMENTS=1. The live flag defaults to 1 - gate only flips when both other conditions are met. Set to 0 to force sandbox even with real keys.

Template q402_doctor writes to ~/.q402/mcp.env:

# ── API key - fill ONE (or both for auto-routing) ──
# Auto-routing (same for q402_pay AND q402_batch_pay):
#   chain="bnb" or "base" + Q402_TRIAL_API_KEY set  → Trial (free sponsored)
#   anything else                                    → Multichain (paid 12-chain)
# Batch ambiguity: 6+ recipient BNB/Base batch with Trial set returns
#   status="ambiguous" instead of executing - agent asks user to pick.
# Override per call with keyScope: "auto" | "trial" | "multichain".
Q402_TRIAL_API_KEY=                # BNB + Base sponsored Trial key (from /event; Avalanche trial ended)
Q402_MULTICHAIN_API_KEY=           # paid 12-chain key (per-chain Gas Tank)

# ── Signing path - pick ONE of Mode A / B / C ──
Q402_PRIVATE_KEY=                  # Mode A: real EOA pk (0x + 64 hex)
Q402_AGENTIC_PRIVATE_KEY=          # Mode B: exported Agent Wallet pk (from dashboard)
# Mode C: leave both PK lines blank. A Trial key enables one-shot Mode C
# payments; Multichain key required for recurring, batch, and bridge/OFT.
# Q402 signs with the server-managed Agent Wallet. Optionally:
# Q402_AGENT_WALLET_ADDRESS=0x...   # pin one of your wallets when you have multiple

# Live mode switch:
#   0 = sandbox (test mode, no funds move - every q402_pay returns a fake hash)
#   1 = real on-chain payments (live mode)
# Default 1. Safe because the gate only flips to live when an API key AND
# at least one valid signing path (A/B/C) are populated. Empty values
# fail the gate, so partial setups stay in sandbox with a hint.
Q402_ENABLE_REAL_PAYMENTS=1

# Pre-check trust-check (live mode). Triggers for first-time counterparties or
# payments >= $1. Fee: $0.02 per check; cached 7 days. Never blocks the main tx.
# Set Q402_DISABLE_PRECHECK=1 to opt out.

Anything missing for the resolved scope → automatic sandbox fallback with a hint pointing at what to set.

Sandbox responses carry success: false, sandbox: true, mode: "sandbox", method: "sandbox", plus a setupHint explaining why - four signals so a downstream summary can't claim success.

Hard caps

Combined with the two-phase consentToken + live-mode env, a stablecoin payment needs: a preview the user approved + amount ≤ cap + recipient allowed + all 3 live envs. Q (QuackAI) is exempt from the cap (your own token); the preview, recipient allowlist, and live-mode env still apply to it.

---

Configuration reference

If you set up Q402 before v0.5.0 you may have a single Q402_API_KEY env var. The server still resolves that silently - your existing integration won't break. New installs should use the two-key model above (Q402_TRIAL_API_KEY and/or Q402_MULTICHAIN_API_KEY); q402_doctor and the rest of the docs only guide users to those two. To migrate, rename your existing var to Q402_MULTICHAIN_API_KEY in ~/.q402/mcp.env and restart your MCP client.

---

Supported chains

---

Why this exists

AI agents are becoming the default interface for software, but the moment they need to move money the stack breaks: holding gas tokens, signing every transaction, managing wallets across many chains. None of that scales when the agent is supposed to act on its own.

Q402 is the payment layer for that gap. A single signing primitive (EIP-712 + EIP-7702) settles gasless stablecoin payments across 12 EVM chains, with an ECDSA-signed Trust Receipt for every transaction. The MCP package exposes that surface inside Claude, Codex, Cursor, and Cline - your agent can quote, send, batch, and audit payments from a natural-language prompt.

Single transfers and multi-recipient batches ship today. The next layer - recurring payouts, conditional execution, and policy-gated treasury automation - is the same primitive composed differently. We're building toward agents that operate real budgets, settle among themselves, and move value through workflows no human triggers manually.

---

Hooks - programmable payment policies

Q402 Hooks 1.0 is a policy engine that attaches rules to the payment lifecycle: OFAC compliance screening, spend caps + recipient allowlists, ERC-8004 reputation gating, Chainlink-oracle conditional settlement ("only when BTC ≥ $80k"), and automatic multi-payee splits - plus an approval-required soft block for large payments (returns 202 approval_required; the caller re-submits out of band, no stored hold in v1). Uniswap v4 brought programmable hooks to DEX liquidity; Q402 brings them to AI-agent payments.

Developer reference: docs/HOOKS.md - lifecycle, the Hook contract, every shipped hook with config + examples.

Escrow on Base: docs/ESCROW-VS-INSTANT.md - instant vs. escrowed payment decision guide for agents. docs/ESCROW-BASE-DEPLOY-RUNBOOK.md - engineering runbook for Base mainnet vault deploy (hands-only, not for agents).

---

Repository

Source code: https://github.com/quackai-org/q402-mcp Issues / requests: https://github.com/quackai-org/q402-mcp/issues

License

Apache-2.0 - see LICENSE.