io.github.bitgett/q402-mcp
Q402 β gasless USDC/USDT payments across 7 EVM chains, callable from any MCP client.
Ask AI about io.github.bitgett/q402-mcp
Powered by Claude Β· Grounded in docs
I know everything about io.github.bitgett/q402-mcp. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
@quackai/q402-mcp
MCP server for Q402 β gasless USDC and USDT payments across 7 EVM chains, callable directly from Claude Desktop and any other Model Context Protocol client.
Claude can now reason about stablecoin payments end to end β quote a transfer across 7 chains, pick the cheapest route, and (optionally) settle the transaction over Q402's EIP-7702 relayer infrastructure. The recipient receives the full amount; the sender pays $0 in gas.
Quick start (Claude Desktop)
claude mcp add q402 -- npx -y @quackai/q402-mcp
Or, if you prefer editing the config file directly, add this entry to your claude_desktop_config.json:
{
"mcpServers": {
"q402": {
"command": "npx",
"args": ["-y", "@quackai/q402-mcp"]
}
}
}
Restart Claude Desktop and ask:
"Compare gas costs to send 50 USDC to vitalik.eth across all 7 Q402 chains."
You'll get a ranked breakdown immediately β no API key, no signup, no funds at risk.
Tools exposed
| Tool | Auth | Purpose |
|---|---|---|
q402_quote | none | Compare gas cost and supported tokens across chains. Read-only. |
q402_balance | API key | Verify the API key and report its plan tier (live vs sandbox). |
q402_pay | API key + private key + flag | Send a gasless payment. Sandbox by default β see Sandbox vs live mode. |
q402_pay follows a "confirm in chat first" contract: the tool description instructs the model to never call it without explicit user approval of the recipient address, amount, chain, and token.
Per-chain gas tank balances and full transaction history live in the dashboard β those endpoints require a wallet signature, not a bare API key, so the MCP server points the agent there instead of exposing them.
Sandbox vs live mode
By default the MCP server operates in sandbox mode: q402_pay returns a deterministic-looking fake transaction hash, no funds move, no gas-tank credit is consumed. That makes it safe to plug into any Claude Desktop install without worrying about an LLM hallucinating a payment.
To enable real on-chain transactions, all three environment variables must be set:
Q402_API_KEY=q402_live_... # live-tier key from /dashboard
Q402_PRIVATE_KEY=0xabc... # signer for the payer EOA
Q402_ENABLE_REAL_PAYMENTS=1 # explicit opt-in
Anything missing β automatic sandbox fallback with a hint pointing at what to set.
Hard caps
Two additional guards run before every payment regardless of mode:
| Env var | Default | Effect |
|---|---|---|
Q402_MAX_AMOUNT_PER_CALL | 5 | Reject any single call where amount > N USD-equivalent. |
Q402_ALLOWED_RECIPIENTS | (empty = off) | Comma-separated address allowlist. When set, all other recipients are rejected. |
Combined with the confirm: true argument the tool requires, this means the model needs (a) explicit user OK in chat, (b) amount β€ cap, (c) recipient on allowlist if one exists, (d) all three live-mode env vars set, before a single wei moves.
Configuration reference
| Env var | Required for | Notes |
|---|---|---|
Q402_API_KEY | balance, live-pay | Issue at https://q402.quackai.ai/dashboard. q402_test_* keys keep sandbox on. |
Q402_PRIVATE_KEY | live-pay | Signer for the payer EOA. Never share. Never paste in chat. |
Q402_ENABLE_REAL_PAYMENTS | live-pay | Set to 1 to opt in. Any other value (or unset) β sandbox. |
Q402_MAX_AMOUNT_PER_CALL | optional | USD-equivalent cap. Defaults to 5. |
Q402_ALLOWED_RECIPIENTS | optional | Comma-separated lowercase addresses. Defaults to no allowlist. |
Q402_RELAY_BASE_URL | optional | Defaults to https://q402.quackai.ai/api. Override for self-hosted Q402. |
Supported chains
| Chain | Chain ID | Token(s) | Notes |
|---|---|---|---|
| BNB Chain | 56 | USDC, USDT | |
| Ethereum | 1 | USDC, USDT | L1 β gas is volatile, quote is a snapshot. |
| Avalanche C-Chain | 43114 | USDC, USDT | |
| X Layer | 196 | USDC, USDT | |
| Stable | 988 | USDT0 (USDC and USDT both alias) | Gas paid in USDT0. |
| Mantle | 5000 | USDC, USDT0 | LayerZero OFT USDT0 since 2025-11-27. |
| Injective EVM | 1776 | USDT only | Native USDC via Circle CCTP announced for Q2 2026. |
Why this exists
x402 standardised "402 Payment Required" semantics for AI agents but the official Coinbase facilitator only covers a few chains and assumes ERC-3009 token support β which excludes BNB USDT, Mantle USDT0, Injective USDT, and the chains where most stablecoin volume actually lives.
Q402 implements the same payer experience (single signature, $0 gas, instant settlement) on all 7 of those chains using EIP-7702 delegated execution, which works with any ERC-20. This MCP server makes that infrastructure addressable from Claude itself.
If you want to dig into how the wire protocol differs from x402, see Q402 docs.
Repository
Source code: https://github.com/bitgett/q402-mcp Issues / requests: https://github.com/bitgett/q402-mcp/issues
License
Apache-2.0 β see LICENSE.
