Q402 MCP Server

@quackai/q402-mcp

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

Free trial available (through 2026-06-30) — 2,000 gasless transactions on BNB Chain (USDC + USDT), 30-day window, no card. One wallet signature: https://q402.quackai.ai.

Trial-scope policy: API keys minted under the free-trial program (plan: "trial") are restricted to BNB Chain with USDC/USDT — server-side enforcement, returns 403 TRIAL_BNB_ONLY otherwise. Paid API keys see the full 11-chain matrix at all times.

Quote → route → (optional) settle stablecoin payments across 11 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 only (from /event)
Q402_MULTICHAIN_API_KEY=     # Paid Multichain, all 11 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. Set ONLY the paid Multichain key above, leave
# both PK lines blank. Q402 signs with the server-managed Agent Wallet.
# 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...

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.

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 11 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

27 tools — read-only by default; live mode needs an API key + signing path + Q402_ENABLE_REAL_PAYMENTS=1.

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

ℹ️ q402_pay expects a 0x address — ENS isn't resolved server-side. Resolve client-side first. Per-chain Gas Tank balances + full TX history live in the dashboard (wallet-signature only).

---

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" + Q402_TRIAL_API_KEY set  → Trial (free sponsored)
#   anything else                          → Multichain (paid 11-chain)
# Batch ambiguity: 6+ recipient BNB 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-only sponsored Trial key (from /event)
Q402_MULTICHAIN_API_KEY=           # paid 11-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, set only the paid Multichain key
# above. 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

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 payment needs: a preview the user approved + amount ≤ cap + recipient allowed + all 3 live envs.

---

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

---

Repository

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

License

Apache-2.0 — see LICENSE.