io.github.Dempty-glitch/z-zero-mcp

⚠️ MANDATORY: Read mcp://resources/sop first. Only use on PAYMENT pages where final total is visible. Auto-detects Web3 or Fiat and completes payment. For physical goods (Shopify, Etsy), get_merchant_hints first.

Cancel unused token and refund instantly. Use when user cancels the purchase or to free up a card slot.

Check spendable USD balance for a card alias. For active token limits, use list_cards instead.

Execute a payment with a one-time token. TWO CALLS: call it first WITHOUT `recheck` — nothing is charged and it hands you what the owner actually asked for, locked when the card was issued; look at the page again, then call it a second time with `recheck` to pay or to pause. Then Z-Zero opens a headless browser, injects the card (you NEVER see the PAN), clicks Pay, and watches for a REAL confirmation before reporting success. Returns a `status`: `confirmed` (order placed → token burned, receipt_id may hold a real order #), `declined` (merchant rejected → token kept for refund), `unconfirmed` (submitted but no confirmation seen → do NOT retry blindly, verify first), `not_submitted` (no Pay button → supply a submit_selector hint), or `no_fields`. ALWAYS pass actual_amount so overcharges are blocked and underspend refunded.

Get your Base deposit address to top up your wallet with USDC (or any supported stablecoin on Base).

Get merchant navigation flow for a domain or platform key (e.g. '_platform_etsy'). Returns pre_steps (how to navigate checkout) and platform notes. Call BEFORE starting checkout to understand the multi-step flow.

List all available virtual card aliases and their balances. No sensitive data is returned.

Report a checkout you could not complete. Pick the failure_class that best matches what you saw — this feeds Z-ZERO's self-healing loop (labeled failures become better merchant hints for the next run). If nothing fits, use 'unknown' and describe what happened in error_message.

Pause and ask the user for approval before risky actions (price mismatch, large amount, unusual request).

Request a single-use JIT virtual card ($1–$100) locked to one amount + merchant. ⚠️ Read mcp://resources/sop first. Only call once the FINAL total is visible — for physical goods that is AFTER shipping is submitted (use get_merchant_hints to navigate there). For digital goods with the price already visible, prefer auto_pay_checkout instead. BEFORE requesting: look at the checkout page one more time and compare it against what the user actually asked for — same items, same quantity, same variant, same destination? If anything differs, do NOT request a token; fix the cart or check with the user first. A mismatch you catch here costs nothing; after this point it costs a card. If you pass `cart`, the server signs your declared intent and binds the card to it — the user gets cryptographic proof of what this card was authorized for. Pass `criteria` too: the few things the owner actually cared about, which this purchase gets scored against at payment time.

Activate a new Passport Key instantly, no restart needed. Only call when user explicitly provides a key.

Check if Passport Key is configured. Shows prefix only, for debugging.

UCP discovery + quote — creates an UNPAID draft checkout; no money moves; NOT a payment rail yet. Checks whether a merchant speaks UCP (Shopify-native agent commerce), lists its declared payment handlers, and — when variant_gid or query is given — creates a DRAFT checkout and returns the merchant's real quote: total_minor (wire units, 8900 = $89.00), total_major, currency, status, blockers, continue_url. NO payment happens; drafts expire server-side. Completing a UCP checkout needs Shopify Token-tier agent auth, which Z-Zero does not hold yet — to PAY, hand the buyer continue_url or use the standard execute_payment flow where permitted. Call this first on Shopify stores: their robots.txt bans scripted checkout, so the UCP lane is the sanctioned path.

Check where an order ENDED UP, and prove it. Returns TWO separate axes: `order_status` — 'completed' (bought, issuer not reported yet) · 'settled' (issuer confirmed) · 'reversed' (auth voided before clearing — the order does NOT stand) · 'partially_refunded' / 'refunded' (merchant returned money AFTER settlement — the order still happened) — and `funds_status` — 'no_payout_due' · 'payout_pending' (money owed back but not yet confirmed on-chain) · 'returned' (confirmed on-chain). Read BOTH before speaking: 'reversed' or 'refunded' with funds 'payout_pending' means the buyer has NOT got the money back yet — never say they have. If you told the user a purchase was done and a later check returns 'reversed', tell them unprompted.