# q402-mcp [Health: Active]

**Category:** 👨‍💻 Code Execution  
**Repository:** https://github.com/quackai-org/q402-mcp  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/q402-mcp

## Description
Q402 - gasless payments, yield, escrow, bridge & NAV triggers on 12 EVM chains. Sandbox-default.

## Tools
Capabilities this server exposes over MCP:

- **q402_doctor** — First-install onboarding + ongoing health check (per-scope quota, EIP-7702 state, relay reachability, slot-mismatch warnings).
- **q402_quote** — Compare gas + supported tokens across chains.
- **q402_balance** — Verify key + remaining quota.
- **q402_pay** — 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 w…
- **q402_batch_pay** — 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 n…
- **q402_receipt** — Fetch + locally verify a Trust Receipt (`rct_…` id, ECDSA against the relayer EOA).
- **q402_wallet_status** — Per-chain EIP-7702 state for the EOA derived from `Q402_PRIVATE_KEY`.
- **q402_clear_delegation** — 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** — Agent Wallet info (addresses, per-wallet caps, daily-spend used, ERC-8004 id). Drives Mode C.
- **q402_memory_summary** — Treasury overview over a window: USD-stablecoin spend by chain/source, top vendors, schedules, open requests/escrow, failures. Read-only.
- **q402_vendor_history** — Total paid to one vendor (or a vendor leaderboard) with recurring cadence. Read-only.
- **q402_agent_spend_report** — Per-Agent-Wallet spend with each wallet's caps. Read-only.
- **Recurring**
- **q402_recurring_list** — List scheduled rules.
- **q402_recurring_create** — Author a recurring rule. Paid Multichain on EVERY chain (BNB included).
- **q402_recurring_fires** — Last 50 fires per rule (timestamp + txHashes + amount).
- **q402_recurring_pause** — Pause a rule (reversible).
- **q402_recurring_resume** — Resume a paused / stopped rule.
- **q402_recurring_skip_next** — Skip only the next scheduled fire.
- **q402_recurring_cancel** — Permanently stop a rule.
- **q402_bridge_quote** — Quote a Chainlink CCIP USDC bridge across eth/avax/arbitrum. Returns LINK + native fee.
- **q402_bridge_send** — 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** — Pointer to the dashboard. Returns `{ implemented: false, dashboardUrl, dashboardPath }` - read-only guidance until owner-sig auth lands in MCP.
- **q402_bridge_gas_tank** — 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** — 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** — 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** — 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** — 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** — Show the Agent Wallet's open Q402 Yield positions (balance, principal, accrued interest, APY) + total supplied in USD. Mode C.
- **q402_yield_deposit** — 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** — 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** — 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** — 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** — The Agent Wallet's open Q stakes (indices, maturity, exitable) + liquid Q balance. Read-only; Mode C.
- **q402_request_create** — Publish a payment request (invoice). No funds move; returns a shareable `/pay` link + `req_…` id. Recipient defaults to the Agent Wallet.
- **q402_request_status** — Look up a payment request by `req_…` id (amount, token, chain, recipient, status). Read-only; `notFound` instead of throwing.
- **q402_request_pay** — 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** — 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** — Read an escrow's state, parties, amount, and tx hashes. Read-only.
- **q402_escrow_lock** — 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** — Buyer releases a locked escrow to the seller (gasless). Sandbox-by-default.
- **q402_escrow_refund** — Permissionless refund to the buyer after the timeout / resolve window.
- **q402_escrow_dispute** — A party disputes an open escrow (requires a named arbiter).
- **q402_redstone_feeds** — Which RedStone feeds this deployment can drive triggers off (NAV / price / RWA). Read-only.
- **q402_redstone_trigger_create** — Arm a gasless payout that fires once when a RedStone feed crosses a threshold (edge-latched).
- **q402_redstone_trigger_list** — List the Agent Wallet's RedStone triggers + their state.
- **q402_redstone_trigger_cancel** — Permanently stop a RedStone trigger.
- **q402_x402_fetch** — 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 thro…

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "q402-mcp": {
    "command": "npx",
    "args": ["-y","@quackai/q402-mcp"]
  }
}
```

## Documentation & README

# @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.

[![npm](https://img.shields.io/npm/v/@quackai/q402-mcp.svg)](https://www.npmjs.com/package/@quackai/q402-mcp)
[![license](https://img.shields.io/npm/l/@quackai/q402-mcp.svg)](./LICENSE)

> **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](https://q402.quackai.ai)'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. |

<details>
<summary>Hermes Agent - YAML config (<code>~/.hermes/config.yaml</code>)</summary>

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

```yaml
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`.

</details>

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

<details>
<summary>Windows: <code>codex mcp add</code> returns "Access is denied"</summary>

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

```toml
[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`.

</details>

### 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, `q402_x402_fetch` is unavailable until `q402_clear_delegation` is called (gasless, reversible; next `q402_pay` re-delegates). |
| **B** | `Q402_AGENTIC_PRIVATE_KEY` | Agent Wallet, local | Export PK from the [dashboard](https://q402.quackai.ai/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.

```bash
# ~/.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.

<details>
<summary>Codex <code>env_vars</code> allow-list example</summary>

```toml
[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](https://developers.openai.com/codex/config-reference) for the full schema.

</details>

### 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_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](https://q402.quackai.ai/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` 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.**

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

```json
{
  "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`:

```bash
# ── 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

| Env var | Default | Effect |
|---|---|---|
| `Q402_MAX_AMOUNT_PER_CALL` | `200` | Reject USDC/USDT/RLUSD calls with `amount > N` USD. Q (QuackAI) is exempt by design (your own token); the recipient allowlist + confirmation still apply to it. |
| `Q402_X402_SESSION_CAP_USD` | `5` | Per-session cumulative spend cap for `q402_x402_fetch` (USD). Blocked if the session total would exceed this value. Resets on MCP server restart. |
| `Q402_ALLOWED_RECIPIENTS` | off | Comma-separated address allowlist. |
| `Q402_BUILDER_CODE` | off | Base Builder Code for `q402_x402_fetch` on-chain attribution (ERC-8021 via x402 v2 `extensions.builder-code`). |
| `Q402_DISABLE_PRECHECK` | off | Set to `1` to opt out of the automatic pre-check trust-check on outgoing payments. |

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

| Env var | Required for | Notes |
|---|---|---|
| `Q402_TRIAL_API_KEY` | live-pay (BNB + Base + Mantle) | BNB Chain + Base sponsored Trial key (permanent). Avalanche trial has ended — use Multichain for avax. Also covers Mantle during the limited-time window 2026-08-21~08-28 UTC+9. Free at https://q402.quackai.ai/event. Auto-routed for trial-eligible chains in both `q402_pay` and `q402_batch_pay` (≤5 recipients) when set. 6+ recipient trial batches return `status="ambiguous"` so the agent can ask the user how to split. |
| `Q402_MULTICHAIN_API_KEY` | live-pay (12-chain) | Paid 12-chain key. Get one at https://q402.quackai.ai/payment. Auto-routed for chains outside BNB/Base (including avax since the Avalanche trial ended) and for BNB/Base when no Trial key is set. Cap: 20 recipients per batch. Mode C one-shot pays accept Trial or Multichain; Multichain required for recurring, Mode C batch, and bridge/OFT. |
| `Q402_PRIVATE_KEY` | Mode A | Hex private key of your MetaMask EOA. Signer for local Mode A. **Never share. Never paste in chat.** |
| `Q402_AGENTIC_PRIVATE_KEY` | Mode B | Exported Agent Wallet hex private key from the dashboard (Agent tab → Export). Signs locally, but the signer is your dedicated Agent Wallet - MetaMask is never touched. **Never share. Never paste in chat.** |
| `Q402_AGENT_WALLET_ADDRESS` | Mode C (optional) | When you have multiple server-managed Agent Wallets (max 10 per owner), set this to the lowercased 0x… address of the one Q402 should spend from. Omit to use the default wallet. Ignored in Modes A/B. |
| `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 for USDC/USDT/RLUSD. Defaults to `200`. Lower for tighter agent blast-radius. Q (QuackAI) is exempt by design (your own token). |
| `Q402_X402_SESSION_CAP_USD` | optional | Per-session cumulative spend cap for `q402_x402_fetch` (USD). Defaults to `5`. Resets on MCP server restart. |
| `Q402_ALLOWED_RECIPIENTS` | optional | Comma-separated lowercase addresses. Defaults to no allowlist. |
| `Q402_BUILDER_CODE` | optional | Base Builder Code (1–32 lowercase letters/numbers/underscores, e.g. `bc_fu2v7kgf`). Set to your registered Builder Code to attach on-chain ERC-8021 attribution to every `q402_x402_fetch` payment via the x402 `extensions.builder-code` field. |
| `Q402_DISABLE_PRECHECK` | optional | Set to `1` to disable the automatic pre-check trust-check that runs before outgoing payments in live mode. When unset (default), pre-check runs automatically for first-time counterparties and payments ≥ $1. The pre-check fee is $0.02; verdicts are cached 7 days (no repeat charge within TTL). The pre-check never blocks the main transaction. |
| `Q402_RELAY_BASE_URL` | optional | Defaults to `https://q402.quackai.ai/api`. Override for self-hosted Q402. |

<details>
<summary>Migrating from legacy single-key setups</summary>

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.

</details>

---

## Supported chains

| Chain | Chain ID | Token(s) | Notes |
|---|---|---|---|
| BNB Chain | 56 | USDC, USDT | |
| Ethereum | 1 | USDC, USDT, **RLUSD** | L1 - gas is volatile, quote is a snapshot. RLUSD (Ripple USD, NY DFS regulated, decimals 18) Ethereum-only. |
| 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 | USDC, USDT | Native Circle USDC (CCTP) live since 2026-06 + canonical Tether (USDT0). |
| Monad | 143 | USDC, USDT0 | Native Circle USDC (CCTP V2) + USDT0 (LayerZero OFT). |
| Scroll | 534352 | USDC, USDT | zkEVM L2 - EIP-7702 live since the Euclid Phase 2 upgrade (2025-04-22). |
| Arbitrum One | 42161 | USDC, USDT | Optimistic rollup - same EIP-7702 signing path as Ethereum. CCIP bridge endpoint (eth ⇄ avax ⇄ arbitrum). |
| Base | 8453 | USDC, USDT | OP Stack L2 - same EIP-7702 signing path as Ethereum. Native Circle USDC + bridged Tether USD. |
| Robinhood Chain | 4663 | **USDG** | Arbitrum Nitro L2 - USDG only (Paxos Global Dollar, 6 decimals). Circle USDC / Tether are not canonical here; gasless USDG payments. |

---

## 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](https://github.com/quackai-org/q402-mcp/blob/HEAD/docs/HOOKS.md)** - lifecycle, the Hook contract, every shipped hook with config + examples.

**Escrow on Base:** [docs/ESCROW-VS-INSTANT.md](https://github.com/quackai-org/q402-mcp/blob/HEAD/docs/ESCROW-VS-INSTANT.md) - instant vs. escrowed payment decision guide for agents. [docs/ESCROW-BASE-DEPLOY-RUNBOOK.md](https://github.com/quackai-org/q402-mcp/blob/HEAD/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](https://github.com/quackai-org/q402-mcp/blob/HEAD/LICENSE).