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 store this locally, some sync to cloud) so they should treat the wallet as exposed if it holds valuables.

Live-check phase additionally returns per-scope quota, EIP-7702 delegation state per chain, relay reachability, and slot-mismatch warnings (e.g. Trial key in Multichain slot silently burns paid quota - surface this to the user).

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 + Avalanche as informational only (q402_pay returns TRIAL_BNB_ONLY for those). 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.

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 - 2,000 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, 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: chain ∈ {bnb, avax} + 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 + Avalanche (USDC gasless on both; USDT gasless on BNB); any other chain 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 recipient/amount when you confirm the payment with the user (e.g. 'Signing from 0xabc…1234 on bnb → send 5 USDT to 0xdef…ABCD'). Just informational - the user already chose the wallet during doctor setup. Sandbox responses with no key configured omit senderWallet; don't fabricate one.

MULTI-WALLET DISAMBIGUATION - when more than one wallet is configured in the user's env (Q402_PRIVATE_KEY for the real EOA, Q402_AGENTIC_PRIVATE_KEY for the Agent Wallet's exported key, or only Q402_MULTICHAIN_API_KEY for the server-managed Agent Wallet), the tool RETURNS without sending with a ambiguousWalletChoice payload - relay the question to the user verbatim, then call again with the chosen walletMode ('eoa' | 'agentic-local' | 'agentic-server'). Do NOT pick a wallet on the user's behalf when multiple are available.

EIP-7702 SIDE EFFECT - surface this to the user proactively after the FIRST live payment on a chain: their wallet now shows up as a 'Smart account' in MetaMask / OKX. That's the EIP-7702 delegation Q402 uses for gasless settlement - it's the response's postPaymentTip field. Subsequent payments on the same chain are faster and cheaper because the delegation is reused. Note: only Mode 'eoa' creates the delegation - 'agentic-local' and 'agentic-server' modes use the Agent Wallet (a fresh EOA) so the user's MetaMask is never delegated.

If the user EVER reports that native gas tokens (BNB / ETH / AVAX / etc.) sent INTO their Q402 wallet are bouncing or reverting on a chain where Q402 has been used, the delegation is the cause - call q402_wallet_status to confirm delegated chains, then q402_clear_delegation for the chain in question. Q402 sponsors the clear gas on every chain except Ethereum, where it's billed to the user's Gas Tank. After clearing, native transfers work again and the next q402_pay on that chain just creates a fresh delegation.

ALWAYS get explicit user confirmation of the exact recipient address, amount, chain, and token in conversation immediately before calling this tool.

TWO-PHASE CONSENT: confirm:true alone does NOT send. Call this tool first WITHOUT consentToken - it returns status="needs_confirmation" with a preview of the exact payment and a consentToken, and moves no money. Relay that preview to the user, get their explicit yes, then re-call with the SAME args plus that consentToken to execute. The token is re-derived from the params about to run, so a previewed payment can't be swapped for a different one.

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: chain ∈ {bnb, avax} + Q402_TRIAL_API_KEY set → Trial; else Multichain. Trial keys: max 5 recipients per call, BNB Chain + Avalanche, USDC/USDT. 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 the user's env (Q402_PRIVATE_KEY for the real EOA, Q402_AGENTIC_PRIVATE_KEY for the Agent Wallet's exported key, or only Q402_MULTICHAIN_API_KEY for the server-managed Agent Wallet), the tool RETURNS WITHOUT firing with status='needs_wallet_choice' and an ambiguousWalletChoice payload - relay the question to the user verbatim, then call again with the chosen walletMode ('eoa' | 'agentic-local' | 'agentic-server'). Do NOT pick a wallet on the user's behalf when multiple are available. Server-mediated batches go through /api/wallet/agentic/batch and are paid-only (the trial key cannot batch).

ALWAYS get explicit user confirmation of the complete recipient + amount list, chain, and token in conversation immediately before calling this tool - the user must approve the full batch, not the individual rows.

TWO-PHASE CONSENT: confirm:true alone does NOT send. Call this tool first WITHOUT consentToken - it returns status="needs_confirmation" with a setupHint preview of every recipient + amount and a consentToken, and moves no money. Relay that preview to the user, get an explicit yes, then re-call with the SAME args plus the consentToken to execute. The token is re-derived from the batch about to run, so the previewed batch can't be swapped.

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

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

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?'

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

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

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

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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 ?' before supplying.

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?'

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.

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

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.

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.

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

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.

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

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

Read a Q402 escrow's current state (pending/open/disputed/released/refunded/expired) + parties, amount, and tx hashes.

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. ALWAYS confirm the exact amount/seller/chain with the user before calling (confirm:true).

BUYER releases a locked escrow to the SELLER (buyer-signed, gasless). MOVES REAL FUNDS irreversibly. Confirm with the user first (confirm:true).

Permissionlessly refund a locked escrow to the BUYER - only valid AFTER the release deadline (or, if disputed, after the arbiter resolve window). Confirm with the user first (confirm:true).

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. Confirm with the user first (confirm:true).

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.

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

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.

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.

Search for available hotels at a destination for a given date range. Returns a list of hotels with IDs, names, locations, ratings, and nightly prices. Use the returned hotelId with travel_get_quote to get an exact booking price. In mock mode (default) returns deterministic fixture hotels.

Get a price quote for a specific hotel and date range. Returns the total amount in currency for the stay. Use the hotelId from travel_search_hotels. Present the quote to the user before proceeding to travel_book_hotel.

Book a hotel. Requires two-phase consent: the first call (without consentToken) returns status="needs_confirmation" with a preview and a consentToken - NO booking is made. Relay the preview to the user verbatim, get their explicit yes, then re-call with the SAME args plus consentToken. A spend limit guard rejects bookings above TRAVALA_MAX_BOOKING_USD (default: same as Q402_MAX_AMOUNT_PER_CALL). Always call travel_get_quote first to obtain the amount.

Retrieve the current status of a hotel booking using the bookingId returned by travel_book_hotel. Returns booking details including hotel, dates, amount, currency, and status (confirmed, pending, cancelled, not_found).