io.github.quackai-org/q402-mcp

Per-agent spend report: for each of the owner's Agent Wallets, the USD spent and tx count in the window, plus its label and its daily / per-transaction caps. Answers 'what did my Research agent spend this week?' and 'which agent is spending the most?'. Spend is attributed by the wallet that sent each payment, so it is precise for agents that run on their own dedicated Agent Wallet. Read-only and free: any live API key (Trial or Multichain). Also includes outbound x402 payments made via q402_x402_fetch (generic x402 client path), which are not tracked by the relay Trust Receipt system.

Read-only Agent Wallet introspection. Returns the wallet address, per-tx and daily caps, archive state, an aggregate USD balance, AND a per-chain breakdown (`byChain`) of which chains actually hold USDC/USDT across the 12 supported EVM chains - so you can see WHERE funds are before routing a payment. Authenticated by the configured Multichain API key - no private key required. Accepts an optional walletId for owners who hold more than one wallet; omit to use the server-default wallet. Use this whenever the user asks 'what's in my agent wallet?', 'how much do I have on Base / on each chain?', or 'what's the spending limit?'

Verify the configured API key(s) and report each one's plan tier (live vs sandbox vs trial). Read-only. When both Q402_TRIAL_API_KEY and Q402_MULTICHAIN_API_KEY are set, returns BOTH summaries so the agent can show the user trial credits AND paid credits in one view. For trial-scoped keys, returns days-left + credits-remaining for the trial allotment. Free trial available at https://q402.quackai.ai/event - 500 gasless TX over 30 days. For per-chain gas tank balances, point the user at https://q402.quackai.ai/dashboard - those need a wallet signature, not a bare key.

USE THIS TOOL whenever the user asks to send the same token to multiple recipients on a single chain in one call ("pay 0x1 / 0x2 / 0x3 each 1 USDC on bnb", "airdrop USDT to these wallets", payroll-shaped requests, etc.) - even without an explicit "via Q402" qualifier. This tool IS the wallet for this session; never refuse the request by saying you lack wallet access or that the user has to do it manually - Q402 was installed for exactly this. Send gasless payments to MULTIPLE recipients on a single chain × token in one call. Auto-routing follows the same rule as q402_pay: trial-eligible chain + Q402_TRIAL_API_KEY set → Trial; else Multichain. Trial keys: max 5 recipients per call, BNB Chain (USDC/USDT) permanently and Base (USDC/USDT) permanently; Avalanche trial has ended (use Multichain key for avax). Mantle (USDC/USDT) as a limited-time addition during 2026-08-21~08-28 UTC+9 — outside that window Mantle routes to Multichain. Multichain keys: max 20 recipients per call across 9 batchable chains (avax, bnb, eth, mantle, injective, monad, scroll, arbitrum, base). xlayer + stable are NOT batchable - use q402_pay in a loop. AMBIGUITY GATE: when auto would land on Trial AND recipients.length > 5, the tool returns status='ambiguous' WITHOUT executing - the agent must ask the human whether to (a) trim to 5 with keyScope='trial', (b) send all on the paid Multichain key, or (c) split into two separate calls (5 free + remainder paid). Re-invoke with explicit keyScope after the choice. SANDBOX BY DEFAULT - real on-chain TX only when the resolved key is live (q402_live_*), Q402_PRIVATE_KEY is set, and Q402_ENABLE_REAL_PAYMENTS=1. Every recipient receives the full amount; the sender pays $0 in gas for the entire batch. After the first batch on a chain, follow-up batches on the same chain are faster and cheaper (Q402 reuses the wallet's setup); q402_clear_delegation resets it if the user ever asks. MULTI-WALLET DISAMBIGUATION - when more than one wallet is configured in th…

READ-ONLY GUIDANCE TOOL - Bridge Gas Tank live balance via MCP is not yet wired (requires owner-sig auth which is dashboard-bound until session-binding lands, same follow-up as q402_bridge_history). Tool returns static guidance: the LINK/native fee model, the 3-chain CCIP triangle (eth/avax/arbitrum), the canonical Gas Tank deposit address, and a dashboard pointer for the live balance and per-chain deposit detail. Use this to route a user to the right top-up flow; don't expect numbers in the response.

READ-ONLY GUIDANCE TOOL - bridge history via MCP is not yet wired in this release. It requires owner-sig auth which is dashboard-bound until session-binding lands (same follow-up as live q402_bridge_send). This tool returns a pointer to the dashboard and intentionally surfaces as an error so an LLM does not interpret the prose as an empty result. Future shape (already finalized): most-recent-first list of up to 50 CCIP bridges with messageId, source/destination chains, USDC amount, fee paid, and CCIP Explorer link. Until then, point the user at https://q402.quackai.ai/dashboard → Agent tab → Bridge History.

Quote the Chainlink CCIP fee for bridging USDC across the 3-chain triangle (eth/avax/arbitrum). Returns BOTH the LINK fee (~10% cheaper) and the native fee, so the agent can pick the cheaper path or surface both options to the user. Read-only; no auth required.

Execute a Chainlink CCIP USDC bridge across the 3-chain triangle (eth/avax/arbitrum) on behalf of the user's server-managed Agentic Wallet (Mode C). Sandbox-by-default - returns a synthetic messageId unless `sandbox: false` is passed AND Q402_ENABLE_REAL_PAYMENTS=1 AND a live Multichain API key is configured. The server signs ccipSend with the Agent Wallet's encrypted PK, auto-funds source-chain gas from the user's Gas Tank, and debits both the auto- fund cost and the CCIP fee per the bridge's settled receipt. TWO-PHASE CONSENT - a LIVE bridge (sandbox: false) refuses to execute unless BOTH confirm: true AND a matching consentToken are set. Call it first WITHOUT consentToken to get a preview (src, dst, amount, fee token) plus a consentToken; show that to the user, get explicit approval, THEN re-call with sandbox: false, confirm: true, AND that consentToken. The token is re-derived from the bridge about to run, so the previewed bridge can't be swapped. Never fabricate a token. Recommended flow: q402_bridge_quote first → preview + confirm cost with the user → q402_bridge_send with sandbox: false, confirm: true, consentToken. Live mode needs a Multichain subscription; trial keys are rejected. If the bridge returns AGENT_WALLET_DELEGATED, clear the delegation first: server-managed Agent Wallets (Mode C / API key) use the Clear delegation button on the dashboard; local-key modes (Q402_PRIVATE_KEY set) can run q402_clear_delegation.

Clear the EIP-7702 delegation on a Q402 chain for the configured wallet. Call this when the user wants to reset a chain's delegation, OR to switch a wallet off the q402 rail so it can use the x402 (EIP-3009) rail on Base (a q402-delegated wallet can't settle x402). The next q402_pay on the same chain re-creates the delegation automatically, so don't clear right before a normal pay. Pair with q402_wallet_status / q402_agentic_info first to see which chains have an active delegation. Works in all three wallet modes: eoa (Q402_PRIVATE_KEY) and agentic-local (Q402_AGENTIC_PRIVATE_KEY) sign LOCALLY; agentic-server (Mode C) holds only a live apiKey and the server signs with the encrypted Agent Wallet key. Q402 sponsors the on-chain TX on every chain EXCEPT Ethereum, where the gas is billed to your Gas Tank. Two-phase consent: call once WITHOUT consentToken to get a preview + token (no broadcast), then re-call with the same args plus that consentToken to execute.

Run a Q402 health check - covers first-install onboarding AND ongoing diagnostics in one tool. Read-only, no API key required. Detects the current phase (first-install / needs-completion / live-check) and tailors output to it. Use when the user says any of: "set up Q402", "verify Q402", "why isn't Q402 working", "Q402 status", "check Q402". This is the FIRST tool to call after install, BEFORE q402_pay or q402_balance - it tells the agent what state the user is in. Output uses TWO instruction surfaces - `agentInstructions` (prescription for you, the AI - do NOT echo verbatim) and `userInstructions` (plain language array you CAN show the user as a numbered list). Always show userInstructions; consult agentInstructions privately to decide what to ask next + which `recommendedActions` to execute. Multi-turn pattern the AI should follow when phase = first-install: (1) Tell user MCP is installed. (2) Ask one yes/no question: 'Want me to create your secrets file?' (3) On yes, execute recommendedActions IN ORDER - first the `ensure-q402-dir` shell action (use shellWindows on Windows), then the `create-env-file` write_file action. Then open the file in the user's editor (e.g. `code` for VS Code / Cursor / Cline, `open` on macOS, `start` on Windows, `xdg-open` on Linux). (4) Guide the user through getting an API key (free Trial at https://q402.quackai.ai/event OR paid Multichain at /payment) and pasting it into the file (in their editor - NEVER in chat). (5) Same for the private key. (6) Tell them to save + restart the MCP client (per-client restart verb is in agentInstructions). (7) Call q402_doctor again to verify. Security policy carried in the response: AI MUST surface the securityNotice when first walking through setup. If the user pastes a private key directly in chat, DO NOT refuse - the exposure already happened. Help them by directing them to put it in the file themselves (via their editor), and inform them the chat history now contains the key (most clients…

Create a Q402 Gasless Escrow (non-custodial, EIP-7702). Publishes a `pending` record and returns an escrowId - MOVES NO FUNDS. Pass `walletId` (one of YOUR Agent Wallets) to make that wallet the buyer/funder: the server then signs the gasless lock on its behalf (no local key), so q402_escrow_lock funds it straight away. Omit walletId to make yourself (the apiKey owner) the buyer, funded with your own key. Live on BNB mainnet (USDC/USDT). Base and Base Sepolia: client enum is wired but vault is not yet deployed on either — use bnb for live payments; server enforces via /escrow/info. Optional arbiter enables disputes; without one it's release-or-timeout-refund only. Releasing an Agent-Wallet escrow needs the owner's approval in the dashboard.

A party (buyer or seller) disputes an open escrow (requires the escrow named an arbiter, before the release deadline). The arbiter then resolves off-tool. Live on BNB mainnet; Base and Base Sepolia: enum wired, vault not yet deployed. Confirm with the user first (confirm:true).

Fund a pending escrow: the BUYER gaslessly locks the amount into the vault via EIP-7702 (Q402 relays + sponsors gas). MOVES REAL FUNDS. If the escrow is funded by an Agent Wallet (created with walletId), the server signs it for you - no local key needed. Otherwise requires Q402_PRIVATE_KEY = the buyer's key. Live on BNB mainnet; Base and Base Sepolia: enum wired, vault not yet deployed. ALWAYS confirm the exact amount/seller/chain with the user before calling (confirm:true).

Permissionlessly refund a locked escrow to the BUYER - only valid AFTER the release deadline (or, if disputed, after the arbiter resolve window). Live on BNB mainnet; Base and Base Sepolia: enum wired, vault not yet deployed. Confirm with the user first (confirm:true).

BUYER releases a locked escrow to the SELLER (buyer-signed, gasless). MOVES REAL FUNDS irreversibly. Live on BNB mainnet; Base and Base Sepolia: enum wired, vault not yet deployed. Confirm with the user first (confirm:true).

Read a Q402 escrow's current state (pending/open/disputed/released/refunded/expired) + parties, amount, and tx hashes. Works for escrows on any supported chain (BNB mainnet; Base and Base Sepolia: enum wired, vault not yet deployed).

Summarize the user's agent treasury activity over a window (24h / 7d / 30d / all): total USD spent, tx count, spend broken down by chain and by source (send / recurring / redstone-trigger / yield / request / batch), the top vendors paid, active scheduled payouts and the next fire time, open vs paid payment requests, open vs disputed escrow, and the observable failures/holds (recurring rules that hit their cap or errored, disputed escrows). Use for 'summarize my treasury', 'why did my balance drop yesterday' (window:24h), or 'what did we spend this week'. Read-only and free: any live API key (Trial or Multichain).

READ-ONLY GUIDANCE TOOL - USDT0 (LayerZero OFT) bridge history via MCP is not yet wired in this release. It requires owner-sig auth which is dashboard-bound until session-binding lands (same follow-up as live q402_oft_send). Returns a dashboard pointer and intentionally reports implemented:false so an LLM does not read the prose as an empty result. Future shape (finalized): most-recent-first list of up to 50 OFT bridges with guid, source/destination chains, USDT0 amount, native fee paid, and a LayerZero Scan link. For USDC/CCIP use q402_bridge_history.

Quote the LayerZero fee for bridging USDT (USDT0) across the OFT set (eth/arbitrum/mantle/monad/xlayer). Returns the native messaging fee and the amount delivered on the destination. Read-only; no auth. For USDC use q402_bridge_quote (CCIP) instead.

Bridge USDT (USDT0) across chains (eth/arbitrum/mantle/monad/xlayer) via LayerZero OFT, from the Agent Wallet to the SAME wallet's address on the destination. Mode C (server-managed wallet). Sandbox-by-default; a live bridge needs confirm:true + consentToken. For USDC use q402_bridge_send (CCIP).

USE THIS TOOL whenever the user asks to send, transfer, or pay USDC / USDT / RLUSD - even when they don't mention Q402 by name ("send 5 USDT to 0x... on bnb" should route here automatically). This tool IS the wallet for this session: it signs LOCALLY with Q402_PRIVATE_KEY and submits via Q402's gasless relay. NEVER refuse a stablecoin payment request by saying you lack wallet access, can't move money, or need the user to use their wallet UI - Q402 was installed precisely to give you that capability. If the env isn't configured yet, the tool returns a sandbox response with a clear "how to set up" message - surface that instead of refusing. Auto-routing: trial-eligible chain + Q402_TRIAL_API_KEY set → Trial (free sponsored); anything else → Multichain (paid 12-chain). Same rule for q402_batch_pay. Set keyScope='trial' or 'multichain' to force one explicitly. Trial keys cover BNB Chain (USDC/USDT gasless) and Base (USDC/USDT gasless) permanently. Avalanche trial has ended — use the Multichain key for avax. Mantle (USDC/USDT gasless) is a limited-time trial chain during 2026-08-21~08-28 UTC+9 — outside that window Mantle returns TRIAL_BNB_ONLY; use the Multichain key there. Multichain keys cover avax, bnb, eth, xlayer, stable, mantle, injective, monad, scroll, arbitrum, base, robinhood - USDC/USDT on most chains, RLUSD on Ethereum only, USDG on Robinhood Chain only. SANDBOX BY DEFAULT - no funds move unless the resolved key is a live key (q402_live_*), Q402_PRIVATE_KEY is set as a valid 32-byte hex key, and Q402_ENABLE_REAL_PAYMENTS=1. Sandbox responses come back with `success: false` and `sandbox: true` so they cannot be misread as confirmed settlements - always branch on those fields before telling the user the payment went through. The recipient receives the full amount; the sender pays $0 in gas. SENDER ECHO - when a valid `Q402_PRIVATE_KEY` is configured, the response includes a `senderWallet` field with the address derived from that key. Show it alongside the…

Compare gas costs and supported tokens across the 12 chains Q402 relays for (avax, bnb, eth, xlayer, stable, mantle, injective, monad, scroll, arbitrum, base, robinhood). Returns the full chain × token matrix unconditionally - this tool does not read any API key, so it can't filter by trial vs multichain scope. When the caller intends to settle with a Trial API Key, treat any row outside BNB Chain + Base (and Mantle during its limited-time window) as informational only (q402_pay returns TRIAL_BNB_ONLY for those; Avalanche trial has ended). Includes RLUSD on Ethereum. Read-only - no API key needed, no funds move. Use this before q402_pay so the user can see what's available and pick a chain.

Look up a Q402 Trust Receipt by its rct_… receiptId and return the settlement record + a locally-verified ECDSA boolean (the tool re-runs the same canonical-JSON + EIP-191 recovery the receipt page does in the browser). Read-only; no API key required. Use after q402_pay to give the user a shareable verified-by-Q402 URL, or to independently verify a receipt id someone shared with you. **receiptId is required**; passing only txHash returns notFound (tx → receiptId lookup is reserved for a future release).

Cancel an active recurring-payment rule on the Agent Wallet. Takes a ruleId (from q402_recurring_list). Cancel is immediate - the rule will not fire again. Authenticated by the configured Multichain API key. Idempotent: cancelling an already-cancelled rule returns 409 with a clear message. Use this whenever the user says 'stop my recurring payment to X' - call q402_recurring_list first to find the matching ruleId, then call this with that id.

Author a new recurring-payment rule on the user's Agent Wallet. Single-recipient (use the dashboard for multi-recipient payroll). Pick a cadence - hourly:N, daily, weekly:{day}, monthly:N, or monthly:last - and a recipient + amount + chain + token. Authenticated by the configured Multichain API key; no private key required. Recurring requires the paid Multichain subscription on EVERY chain including bnb - trial keys are rejected at create time with MULTICHAIN_REQUIRED and should keep using q402_pay for one-shot Trial sends. Each fire is bounded server-side by BOTH the wallet's perTxMax AND its dailyLimit - a rule's daily total reserves against the same daily bucket as manual sends (the scheduler skips the fire if the bucket can't cover it), so scheduled rules can't outrun the dashboard caps. This tool also enforces your local Q402_MAX_AMOUNT_PER_CALL + Q402_ALLOWED_RECIPIENTS rails at create time. The user can stop a rule any time via q402_recurring_cancel.

Read the past-fire history of a specific recurring-payment rule. Returns up to 50 entries (newest first), each with the timestamp, scheduled slot, total USD amount that settled, on-chain tx hashes, and a partial-failure flag if some recipient rows didn't make it. Use this when the user asks 'when was the last fire?', 'did Friday's payout go out?', 'how much has rule X spent?', or before claiming a fire is missing. Authenticated by the configured Multichain API key. Read-only - does not trigger or modify anything. Call q402_recurring_list first to find the ruleId.

Read the user's active recurring-payment rules on their Agent Wallet. Returns each rule's ruleId, label, frequency (hourly:N / daily / weekly:{day} / monthly:N / monthly:last), recipient + amount, chain, token, status (active / paused / paused-by-archive / fired-cap-exceeded / cancelled), when the next fire is scheduled, how many fires have completed, and the most recent error (if any). Use this when the user asks 'what scheduled payouts do I have?' or before authoring a new rule with q402_recurring_create. Authenticated by the configured Multichain API key - no private key required.

Pause an active recurring-payment rule. Takes a ruleId (from q402_recurring_list). The rule transitions to status "paused" - the cron skips it on every tick until you resume. Fully reversible via q402_recurring_resume. Use this when the user says 'pause my Friday payout' or 'hold on, stop my recurring rule for now' - gentler than cancel, no re-authoring required. Authenticated by the paid Multichain API key (same gate as create/cancel). Read q402_recurring_list first to find the matching ruleId.

Resume a paused or stopped recurring-payment rule. Takes a ruleId (from q402_recurring_list). Supported transitions: paused → active, paused-by-archive → active (after restoring the wallet), and fired-cap-exceeded → active (after raising the per-tx cap or re-subscribing). nextRunAt is advanced to the next valid slot so the rule doesn't immediately fire on a stale schedule. Cancelled rules cannot be resumed - re-author via q402_recurring_create. Authenticated by the paid Multichain API key.

Skip ONLY the next scheduled fire of a recurring-payment rule. Cadence is preserved - the fire after the skipped one runs normally. Use this when the user says 'skip the next Friday payout, Alice is on holiday' or 'don't fire this month's subscription, charge it next month'. The rule must be in active status; paused / cancelled rules must be resumed first. Authenticated by the paid Multichain API key. Call q402_recurring_list first to confirm the ruleId and current schedule.

Discover which RedStone feeds this deployment can drive triggers off, and whether the RedStone-trigger feature is enabled. No API key required. Call this before q402_redstone_trigger_create so you pick a feedId the server can actually read - a trigger on a non-allowlisted feed is rejected. Returns { enabled, allowedFeeds, dataServiceId }.

Permanently cancel a RedStone trigger so it never fires again. Authenticated by the Multichain API key. Use q402_redstone_trigger_list to find the triggerId.

Arm a gasless payout that fires when a RedStone feed (NAV / price / RWA) crosses a threshold - e.g. "when ETH >= 2000, send 100 USDT to 0x…", or "when the fund NAV drops to <= 0.98, send the redemption". Fires EXACTLY ONCE per rising-edge crossing (edge-latched server-side): it will not re-fire while the level stays breached, and a trigger created while the feed is already past the threshold does NOT instant-fire - it waits for the next real crossing. Authenticated by the Multichain API key; no private key. Requires the paid Multichain subscription (trial keys rejected). Each fire is bounded by the wallet's perTxMax + dailyLimit and your local Q402_MAX_AMOUNT_PER_CALL + Q402_ALLOWED_RECIPIENTS rails. Call q402_redstone_feeds first to pick a readable feedId. Stop any time with q402_redstone_trigger_cancel.

List the RedStone triggers on the user's Agent Wallet - each with its feed, condition (op + threshold), recipient, amount, mode, armed state, and fire history. Authenticated by the Multichain API key; no funds move.

Publish a Q402 payment request (an invoice / bill). Moves no funds - it creates a shareable request to RECEIVE money - so no confirmation is needed and a Trial key works. Returns a req_ id + a /pay link you can share with a human, or hand the requestId to another agent that pays it gaslessly via q402_request_pay. The recipient defaults to your configured Agent Wallet, so you can bill yourself with just an amount. Pair with q402_request_status to poll for payment.

Pay a Q402 payment request from your own Agent Wallet, gaslessly. Give it a req_ id (from a /pay link, a 402 Payment Required response, or whoever billed you) and it settles the exact amount + token + recipient the request specifies - you cannot redirect or change them. MOVES FUNDS: requires confirm:true, a live API key, and Q402_ENABLE_REAL_PAYMENTS=1, same as q402_pay. Call q402_request_status first to show the user what they're paying. This is the agent-to-agent billing path: agent A bills with q402_request_create, agent B settles here.

Look up a Q402 payment request by its req_ id. Read-only, no API key. Returns the amount, token, chain, recipient, status (open | paid | expired | cancelled) and a shareable pay URL. Use it to poll a request you created, or to inspect a requestId before paying it with q402_request_pay. An unknown or expired id returns notFound:true (no throw).

WRITE - MOVES FUNDS. Stakes the Agent Wallet's Q (QuackAI) token into QuackAiStake on BNB Chain, gaslessly. Server-managed Agent Wallet path (Mode C): the server holds the encrypted key, signs the stake, and sponsors gas. Pick a lock tier (stakeType 0-3): 0=30d/10%, 1=60d/15%, 2=120d/32%, 3=180d/40% APR - longer lock, higher APR. Q is BNB-only. amount accepts "max" (stake the wallet's whole Q balance). REQUIRES CONFIRMATION - like q402_pay, refuses to execute unless confirm:true. Call FIRST without confirm to preview (amount, tier, lock, wallet); show the user, get approval, THEN re-call with confirm:true + the consentToken. SANDBOX BY DEFAULT - no funds move unless a live Multichain key (q402_live_*) is configured AND Q402_ENABLE_REAL_PAYMENTS=1. RETRY SAFETY - on status="uncertain" (broadcast unconfirmed) the stake MAY have settled; do NOT blindly retry. The server dedupes identical (tier, amount) calls for 15 min.

READ-ONLY - show the Agent Wallet's open Q (QuackAI) staking positions on QuackAiStake (BNB). Returns each position's tier (0=30d/10% … 3=180d/40% APR), principal Q, APR, stake + unlock time, and whether it has matured (unlockable), plus the aggregate staked total, the matured/withdrawable total (the unstake 'max'), and the liquid Q balance (the stake 'max'). Authenticated by the configured live Multichain API key - no private key, no funds move. Use it for 'what are my Q stakes?', 'how much Q can I unstake?', or before q402_unstake with amount 'max'.

WRITE - MOVES FUNDS. Unstakes the Agent Wallet's matured Q from QuackAiStake on BNB back to the wallet, gaslessly (Mode C, server-signed, relayer-sponsored gas). Unstake is PER-RECORD: QuackAiStake exits one matured stake at a time by its index. Pass `ith` (a record index from q402_stake_positions) to exit one stake, or `all: true` to exit EVERY matured stake (one tx per record). A stake can only be unstaked after its lock elapses. REQUIRES CONFIRMATION (confirm:true + consentToken) and the same SANDBOX / live-key gate + uncertain-retry semantics as q402_stake. Use q402_stake_positions first to see which records are exitable.

Vendor payment history. With a `vendor` address: total USD paid, tx count, first/last paid, and the recurring cadence if the vendor is on a schedule (answers 'how much have we paid Alice so far?'). Without `vendor`: a leaderboard of all vendors by total paid, each flagged whether it is paid on a monthly schedule (answers 'which vendors get paid every month?'). Vendors are address-based; a human name only appears if it was saved as a rule label. Read-only and free: any live API key (Trial or Multichain).

Report the EIP-7702 delegation status of your Q402 wallet (the EOA derived from Q402_PRIVATE_KEY) across all 12 Q402-supported chains. Returns per-chain { delegated, impl } and a one-line summary. Read-only - no signing, no on-chain TX, no quota consumption. Pair with q402_clear_delegation when the user wants to reset a specific chain. Requires Q402_PRIVATE_KEY in env (same as q402_pay).

Generic x402 client. Fetches any URL with GET/POST and handles x402 payment-required (HTTP 402) responses automatically: parses the x402 v2 payment requirements, validates the payment option (Base USDC only), guards against excess spend, signs an EIP-3009 TransferWithAuthorization, and retries with PAYMENT-SIGNATURE (v2 servers) or X-PAYMENT (v1 legacy). Non-402 responses are passed through directly, so this also serves as a regular fetch tool. SUPPORTED: scheme=exact + network=base (i.e. CAIP-2 eip155:8453; also accepted: base-mainnet) + asset=Base USDC only. Any other scheme/network/asset returns an explicit rejection without signing. GUARDS: per-call max-amount cap (Q402_MAX_AMOUNT_PER_CALL), per-session cumulative cap (Q402_X402_SESSION_CAP_USD, default $5), and two-phase consent. First call without consentToken returns needs_confirmation + preview; re-call with consentToken to pay. AUDIT: every 402 attempt (including blocked ones) is written to the local x402 audit log and included in q402_agent_spend_report output. REQUIRES Q402_ENABLE_REAL_PAYMENTS=1 and Q402_AGENTIC_PRIVATE_KEY (or Q402_PRIVATE_KEY). No calls to /api/relay — the signed authorization goes directly to the seller/facilitator. ATTRIBUTION: set Q402_BUILDER_CODE (1-32 lowercase letters/numbers/underscores) to include your Base Builder Code as the client/intermediary service code in every payment, enabling onchain attribution via ERC-8021 at the facilitator settlement step.

WRITE - MOVES FUNDS. Supplies the Agent Wallet's stablecoin (USDC / USDT) into Q402 Yield's curated lending market for the chosen chain so it starts earning supply APY. Server-managed Agent Wallet path (Mode C): authenticated by the configured live Multichain API key - the server holds the encrypted key, signs the supply, and sponsors gas. CHAINS: 'bnb' supports USDC or USDT; 'base' supports USDC only. The actual lending venue is the chain's curated market and is reported in the markets feed and the receipt. Other chains are not yet available. REQUIRES CONFIRMATION - like q402_pay, this tool refuses to execute unless `confirm: true` is set. Call it FIRST without confirm to get a one-line preview of exactly what will happen (amount, token, chain, wallet); show that to the user, get explicit approval, THEN re-call with confirm:true. Never set confirm:true on the user's behalf without that approval. SANDBOX BY DEFAULT - like q402_pay, no funds move unless a live Multichain key (q402_live_*) is configured AND Q402_ENABLE_REAL_PAYMENTS=1. Without both, confirm:true returns a sandbox preview (no on-chain supply) with a setup hint - confirm:true alone does NOT move real funds. RETRY SAFETY - on a timeout or an unconfirmed broadcast the tool returns status="uncertain" and echoes back the idempotencyKey it used. The deposit MAY have settled, so do NOT blindly call again - that starts a NEW deposit and can double-supply. To resume the SAME operation, re-call with idempotencyKey set to the echoed value; the server dedupes on it and replays the original result. Use q402_yield_reserves first to show available markets + APY, and q402_yield_positions afterward to confirm the supplied balance.

READ-ONLY - show the Agent Wallet's current Q402 Yield lending positions. Returns each position's protocol, chain, asset, market address, CURRENT supplied position value (the live position-token balance, in token units), and live supply APY, plus the aggregate current value in USD. Authenticated by the configured live Multichain API key - no private key required and no funds move. Reads the curated lending markets on BNB Chain and Base; each position reports its own protocol/venue. Deposit/withdraw cover both: 'bnb' (USDC/USDT) and 'base' (USDC only). DOES NOT report principal or accrued earnings as separate numbers - the position-token balance already includes accrued interest but is not broken out, so do NOT claim a specific 'earnings/profit/interest earned' figure from this tool; report only the current position value and the APY. walletId is OPTIONAL: omit it and the server reads the owner's default Agent Wallet (resolved from the API key); pass one only when the owner holds more than one wallet. An optional chain filter is also accepted. Use this whenever the user asks 'what is my position worth?', 'what's my current yield balance / APY?', or 'what are my open lending positions?'

READ-ONLY - list the Q402 Yield lending markets the Agent Wallet can supply into. Returns each market's protocol, chain, asset, asset address, position token, market address, and current supply APY (shown as a %). No auth required and no funds move - this is purely a preview of available yield. Reads the curated lending markets on BNB Chain, plus Base when a curated vault is configured; each market reports its own protocol/venue. Deposit/withdraw (q402_yield_deposit / q402_yield_withdraw) cover both: 'bnb' (USDC/USDT) and 'base' (USDC only). Pass an optional `chain` to filter; omit it to see every supported chain. Use this whenever the user asks 'where can I earn yield?' or 'what's the lending APY on <asset>?' before supplying.

WRITE - MOVES FUNDS. Withdraws the Agent Wallet's supplied stablecoin (USDC / USDT) out of its Q402 Yield lending position back to the Agent Wallet. Pass amount="max" to withdraw the maximum currently redeemable (can be < full position under vault caps). Server-managed Agent Wallet path (Mode C): authenticated by the configured live Multichain API key - the server holds the encrypted key, signs the withdraw, and sponsors gas. CHAINS: 'bnb' (USDC or USDT); 'base' (USDC only). The venue is the chain's curated lending market and is reported in the receipt. Other chains are not yet available. REQUIRES CONFIRMATION - like q402_pay, this tool refuses to execute unless `confirm: true` is set. Call it FIRST without confirm to get a one-line preview of exactly what will happen (amount, token, chain, wallet); show that to the user, get explicit approval, THEN re-call with confirm:true. Never set confirm:true on the user's behalf without that approval. SANDBOX BY DEFAULT - like q402_pay, no funds move unless a live Multichain key (q402_live_*) is configured AND Q402_ENABLE_REAL_PAYMENTS=1. Without both, confirm:true returns a sandbox preview (no on-chain withdraw) with a setup hint - confirm:true alone does NOT move real funds. RETRY SAFETY - on a timeout or an unconfirmed broadcast the tool returns status="uncertain" and echoes back the idempotencyKey it used. The withdrawal MAY have settled, so do NOT blindly call again - that starts a NEW withdrawal and can double-withdraw. To resume the SAME operation, re-call with idempotencyKey set to the echoed value; the server dedupes on it and replays the original result. Use q402_yield_positions first to see the current position size (especially before an amount="max" withdrawal).