Q402 Developer Docs

<script src="https://q402.quackai.ai/q402-sdk.js"></script>

// Trial keys are BNB-only. No Gas Tank needed — Q402 sponsors gas.
const q402 = new Q402Client({
  apiKey: "q402_live_YOUR_TRIAL_KEY",   // from /event (your Trial API Key)
  chain:  "bnb",
});

const result = await q402.pay({
  to:     recipientAddress,
  amount: "1.00",
  token:  "USDT",   // or "USDC"
});
// result → { success: true, txHash: "0x...", chain: "bnb", method: "eip7702" }

// Multichain keys work across all supported chains. Each chain needs
// a funded Gas Tank — deposit at /dashboard → Treasury.
const q402 = new Q402Client({
  apiKey: "q402_live_YOUR_KEY",
  chain:  "bnb",   // "bnb" | "avax" | "eth" | "xlayer" | "stable" | "mantle" | "injective" | "monad" | "scroll" | "arbitrum" | "base"
});
// Note: Injective supports both USDC and USDT (native Circle USDC via CCTP).

// Wallet popup appears — user signs, Q402 relays on-chain
// amount MUST be a human-readable decimal STRING (e.g. "50.00", "0.123456").
// Never pass a JS Number — IEEE-754 loses precision on 18-decimal tokens.
// Inputs exceeding the token's decimals or non-decimal strings throw.
const result = await q402.pay({
  to:     recipientAddress,
  amount: "50.00",
  token:  "USDC",
});
// result → { success: true, txHash: "0xabc...", tokenAmount: "50", chain: "bnb" }

const q402 = new Q402Client({
  apiKey: "q402_live_YOUR_KEY",
  chain:  "injective",
});

const result = await q402.pay({
  to:     recipientAddress,
  amount: "50.00",
  token:  "USDC",   // USDC and USDT both supported on Injective
});

const q402 = new Q402Client({
  apiKey: "q402_live_YOUR_KEY",
  chain:  "eth",
});

const result = await q402.pay({
  to:     recipientAddress,
  amount: "10.00",
  token:  "RLUSD",   // Ethereum-only — throws on any other chain
});

// Full result shape:
// {
//   success:       true,
//   txHash:        "0xdef456...",
//   chain:         "bnb",
//   blockNumber:   "38482910",
//   tokenAmount:   "50",
//   token:         "USDC",
//   gasCostNative: 0.000021,
//   method:        "eip7702",
// }
console.log("Paid! TX:", result.txHash);

# Claude Code / Claude Desktop
claude mcp add q402 -- npx -y @quackai/q402-mcp

# OpenAI Codex CLI
codex mcp add q402 -- npx -y @quackai/q402-mcp

# Cursor — paste into ~/.cursor/mcp.json (or .cursor/mcp.json for per-project scope)
# Cline  — Cline → Settings → MCP Servers → Edit JSON. Same shape.
{
  "mcpServers": {
    "q402": {
      "command": "npx",
      "args": ["-y", "@quackai/q402-mcp"]
    }
  }
}

# GitHub Copilot (VS Code) — .vscode/mcp.json. Root key is "servers", NOT mcpServers.
{
  "servers": {
    "q402": {
      "command": "npx",
      "args": ["-y", "@quackai/q402-mcp"]
    }
  }
}

# Hermes Agent (Nous Research) — ~/.hermes/config.yaml (YAML). Reload with /reload-mcp.
mcp_servers:
  q402:
    command: "npx"
    args: ["-y", "@quackai/q402-mcp"]
    enabled: true

# ~/.q402/mcp.env — what q402_doctor creates on first install.
# Paste your values on the right of `=`. Q402_ENABLE_REAL_PAYMENTS
# already defaults to 1 — the gate refuses empty values, so partial
# setups stay in sandbox automatically.

# ── 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
Q402_PRIVATE_KEY=
# Mode B: exported Agent Wallet pk from dashboard (keeps MetaMask untouched)
Q402_AGENTIC_PRIVATE_KEY=
# Mode C: no PK needed. Paid Multichain key alone + server-managed Agent Wallet.
#   Optional picker when you have multiple wallets:
# 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

{
  "success":      true,
  "txHash":       "0x9afd...52a4",
  "tokenAmount":  "0.10",
  "token":        "USDT",
  "chain":        "bnb",
  "receiptId":    "rct_afa5f50bc49a65ebba3b28ab",
  "receiptUrl":   "https://q402.quackai.ai/receipt/rct_afa5f50bc49a65ebba3b28ab"
}

curl https://q402.quackai.ai/api/receipt/rct_afa5f50bc49a65ebba3b28ab

> Send 0.10 USDT to alice on BNB via Q402, then verify the receipt.

Claude → q402_pay   → settles + returns rct_afa5...
Claude → q402_receipt → verified: true · signed by 0xfc77...74ff466

"Show my Q402 wallet status."
"Clear my Q402 delegation on BNB Chain."

PRIVATE_KEY=0x<yourKey> node scripts/undelegate-7702.mjs --chain bnb

// POST /api/relay
{
  "apiKey": "q402_live_YOUR_API_KEY",
  "chain":  "avax",
  "token":  "USDC",
  ...
}

// Implementation contract per chain
const CONTRACTS = {
  avax:   "0x96a8C74d95A35D0c14Ec60364c78ba6De99E9A4c", // Q402 Avalanche (chainId: 43114)
  bnb:    "0x6cF4aD62C208b6494a55a1494D497713ba013dFa", // Q402 BNB Chain (chainId: 56)
  eth:    "0x8E67a64989CFcb0C40556b13ea302709CCFD6AaD", // Q402 Ethereum  (chainId: 1)
  xlayer: "0x8D854436ab0426F5BC6Cc70865C90576AD523E73", // Q402 X Layer   (chainId: 196)
  stable: "0x2fb2B2D110b6c5664e701666B3741240242bf350", // Q402 Stable    (chainId: 988)
  mantle: "0xE5b90D564650bdcE7C2Bb4344F777f6582e05699", // Q402 Mantle    (chainId: 5000)
  injective: "0xa9a7dcE76DEF2AC36057FeF0d8103dF10581d61e", // Q402 Injective (chainId: 1776)
  monad:  "0xc5d4dFA6D2e545409C1abf86f336Dd43bb87621f", // Q402 Monad     (chainId: 143)
  scroll: "0x7635F32D893B64b5944CB8cbF2AC4cd3dA41B2f1", // Q402 Scroll    (chainId: 534352)
  arbitrum: "0x8D854436ab0426F5BC6Cc70865C90576AD523E73", // Q402 Arbitrum  (chainId: 42161)
  base:   "0x2fb2B2D110b6c5664e701666B3741240242bf350", // Q402 Base      (chainId: 8453)
};

// EIP-712 domain name — must match contract NAME constant exactly
const DOMAIN_NAMES = {
  avax:      "Q402 Avalanche",
  bnb:       "Q402 BNB Chain",
  eth:       "Q402 Ethereum",
  xlayer:    "Q402 X Layer",
  stable:    "Q402 Stable",
  mantle:    "Q402 Mantle",
  injective: "Q402 Injective",
  monad:     "Q402 Monad",
  scroll:    "Q402 Scroll",
  arbitrum:  "Q402 Arbitrum",
  base:      "Q402 Base",
};

// verifyingContract:
//   ALL chains → user's own EOA  (address(this) under EIP-7702 delegation)

// Every deployed Q402 impl contract uses the same EIP-712 typed struct:
const types = {
  TransferAuthorization: [
    { name: "owner",       type: "address" }, // token sender (user's EOA)
    { name: "facilitator", type: "address" }, // gas sponsor (Q402 relayer)
    { name: "token",       type: "address" }, // ERC-20 contract (USDC / USDT / USDT0)
    { name: "recipient",   type: "address" }, // payment destination
    { name: "amount",      type: "uint256" }, // atomic units
    { name: "nonce",       type: "uint256" }, // random uint256, replay protection
    { name: "deadline",    type: "uint256" }, // unix timestamp
  ],
};

// verifyingContract is ALWAYS the user's own EOA — the contract computes its
// domain separator with address(this), which equals the user EOA under EIP-7702.

// Fetch facilitator address first (required for all chains)
const { facilitator } = await fetch("https://q402.quackai.ai/api/relay/info").then(r => r.json());

const domain = {
  name:              DOMAIN_NAMES[chain],
  version:           "1",
  chainId:           chainId,
  verifyingContract: userAddress,  // user's own EOA — same for all chains under EIP-7702
};

const nonce = ethers.toBigInt(ethers.randomBytes(32)); // random uint256

const signature = await signer.signTypedData(domain, types, {
  owner:       userAddress,
  facilitator,
  token:       tokenAddress,
  recipient:   recipientAddress,
  amount:      ethers.parseUnits("50", decimals), // 6 decimals on most chains; 18 only for Stable chain's USDT0
  nonce,
  deadline:    BigInt(Math.floor(Date.now() / 1000) + 600),
});