# VotexPay: approval and completion layer for agent-initiated purchases > VotexPay is infrastructure for external AI agents. Agents authenticate with a > scoped API key, browse and research in isolated sessions, request payments > that a human approves, and create user-paid purchase handoffs that the user > completes on the merchant site. VotexPay does not give agents raw card data, and > agents cannot approve their own payments or purchases. Status legend: LIVE = production today; COMING SOON = not live yet. ## Current capability status (6 November 2026) LIVE - Supabase auth: email/password, TOTP, passkeys, trusted devices. - Free and Pro plans with server-enforced quotas and Stripe Billing. - API keys with scopes, hashed at rest, revocable. - Public OAuth 2.1 for AI platforms (MCP): dynamic registration, PKCE, consent, rotating refresh tokens and revocation. - MCP streamable HTTP and Python/TypeScript SDKs. - Isolated browser sessions and actions on the Pro plan. - Agent Runs with a dual-LLM planner and quarantined extractor. They browse and research; they do not execute real merchant payments. Free: no agent runs; Pro: 500/month; Business: 3 000/month. - Stripe saved-card payments with human approval, 3DS and webhooks (Pro). - User-paid purchase handoff: create purchase, one-time /pay/{token} approval link, approve or reject, open merchant checkout, user confirms completion, agent polls status. Pending purchases also appear on the Agent Runs page. - Docs, security headers, CORS, request IDs, SSRF DNS guard, screenshot blocking after card fill, RLS, and test/prod Supabase separation. COMING SOON (test preview only) - Basis Theory test vault, PCI autofill, unified card entry, and vault purchase fill/submit. Production PCI is disabled. - Stripe Elements iframe filling and the select action. Merchant CAPTCHAs and 3DS may require user handoff. Automated Stripe Checkout is blocked by hCaptcha. COMING SOON (disabled) - Link Agent Wallet is disabled (`LINK_ENABLED=false`) until its registered redirect URI exactly matches `https://votexpay.com/api/link/callback`. Eligible Link wallets will be US/Canada only when enabled. - Supplier API and reseller rail. Not built. - Stripe SPT and Forwarding. Coming soon. PLATFORM CONNECTORS - ChatGPT, Claude and Cursor connectors use the live MCP/OAuth endpoints; test each target client before claiming platform certification. COMING SOON - Live PCI vault. - Production card autofill and arbitrary-merchant autonomous card purchases. - Virtual cards. Stripe Issuing was refused; Nium and Marqeta are not integrated. ## Endpoints - MCP (streamable HTTP): https://api.votexpay.com/mcp - REST API base: https://api.votexpay.com - AI docs: https://votexpay.com/ai-docs - Human docs: https://votexpay.com/docs - This file: https://votexpay.com/llms.txt - Test deployment (vault purchases and autofill): https://votex-test-43ec.up.railway.app ## Architecture User and external agent -> VotexPay API and MCP -> Supabase (auth, Postgres, RLS), Stripe (saved-card payments, 3DS, webhooks), isolated browser (sessions, actions, screenshots), policy and audit (scopes, approvals, request IDs). Payment rails: - User-paid handoff: LIVE. User pays the merchant. VotexPay does not receive card data or charge for the purchase. - Vault card fill: COMING SOON (test preview only). Production returns `503 PCI vault is disabled`. - Supplier API: COMING SOON. - Link for US/Canada: COMING SOON and disabled until the registered callback URI is fixed. - Virtual cards: COMING SOON. ## Authentication ### OAuth 2.1 (recommended for AI platforms) - Protected resource metadata: `https://api.votexpay.com/.well-known/oauth-protected-resource/mcp` - Authorization server metadata: `https://api.votexpay.com/.well-known/oauth-authorization-server` - Dynamic registration: `POST /api/oauth/register` (public clients, no secret) - Authorization: `GET /api/oauth/authorize` -> consent at `/oauth/authorize` - Token: `POST /api/oauth/token` (`authorization_code` + PKCE S256, `refresh_token`) - Revocation: `POST /api/oauth/revoke` The MCP endpoint returns `401` plus `WWW-Authenticate: Bearer resource_metadata="..."` when unauthenticated, so MCP clients can discover OAuth. Tokens are opaque, hashed at rest, bound to one user, and enforce the same scopes as API keys. Users can disable AI platform access in Settings; that revokes every OAuth token immediately. ### API key (legacy) Send this header on every MCP and REST request: ``` Authorization: Bearer sk_votex_... ``` API keys are created by the user at /keys, shown once, stored hashed and revocable. Use one key per agent. Never expose keys client-side. ## Connectors MCP URL: `https://api.votexpay.com/mcp`. - **ChatGPT:** in developer/connector mode, add a remote MCP connector at the URL and use OAuth/DCR. Complete VotexPay consent, then call `votex_whoami` (returns plan, features, limits and scopes). - **Claude:** add a remote MCP connector at the URL, complete browser OAuth, then call `votex_whoami` (returns plan and capabilities). - **Cursor:** add a Streamable HTTP MCP server at the URL, choose OAuth/DCR and complete VotexPay consent. Loopback callbacks are allowed for native clients. - **API-key fallback:** use a dedicated key in `Authorization: Bearer sk_votex_...` for clients without OAuth. Never put it in prompts or browser code. Common errors: `401` means missing/expired/revoked auth; `invalid_redirect_uri` means the callback does not match the client registration or redirect-host allowlist; a missing-scope error requires reconnecting. Payments require `payments:write`; automatic confirmation additionally needs the explicit high-trust `payments:auto` scope and a policy that allows it. ## Age verification Age verification is available on **Pro** and **Business** only. Free accounts can view the status section but cannot start a session. VotexPay uses Stripe Identity (document + selfie). Verified accounts receive a trusted badge next to their email. VotexPay stores only session/report IDs, status and dates; documents, selfies, DOB and address are not stored. - https://stripe.com/identity - https://docs.stripe.com/identity ## Plans | Feature | Free (€0) | Pro (€39) | Business (€129) | | --- | --- | --- | --- | | Agent runs / Dual-LLM | No (Pro) | 500 / month | 3 000 / month | | Age verification (Stripe Identity) | No (Pro) | Yes | Yes | | Active API keys | 1 | 10 | 50 | | Saved cards | 1 | 5 | 20 | | User-paid purchases | 25 / month | 1 000 / month | 5 000 / month | | Saved-card payments | No | Yes | Yes | | PCI vault / autofill | No | No | Coming soon | | Virtual cards (Issuing) | No | No | Coming soon | | Standalone browser sessions | No | Yes | Yes | Plan and quota failures return `403` with an upgrade message. Limits reset on the first day of each calendar month (UTC). Manage the plan at `https://votexpay.com/billing`; Stripe Checkout and the Customer Portal handle payment and cancellation. ## API key scopes and presets The /keys page has a Permissions selector with one checkbox per scope. Presets: | Preset | Scopes | | --- | --- | | Read only | `cards:read`, `payments:read`, `agent:read` | | Agent safe (default for new keys) | `cards:read`, `payments:read`, `payments:write`, `browser`, `purchases`, `agent:read`, `agent:run` | | Select all | Every scope except `issuing` and `payments:auto` | Allowed scopes: | Scope | Allows | | --- | --- | | `cards:read` | View saved cards and masked metadata. | | `payments:read` | View payments and status. | | `payments:write` | Create payment requests and start payment flows. Payments stay pending unless the credential also has `payments:auto`. | | `payments:auto` | Confirm payments on saved cards without a per-payment approval, within the user's VotexPay policy and threshold. High trust; unchecked by default. | | `browser` | Open isolated browser sessions and run browser actions. | | `purchases` | Create and manage purchase requests and handoffs. | | `agent:read` | View agent runs and their results. | | `agent:run` | Start and control agent runs (Pro+ plan also required). | | `billing:write` | Create a Stripe Checkout/portal link to upgrade. No charge by itself. | | `issuing` | Legacy reserved scope. Not advertised through OAuth; API keys may still carry it. Virtual cards are coming soon. | `issuing` is a legacy reserved scope. OAuth no longer advertises it and the virtual-card tools return coming-soon errors. API keys may still carry it for compatibility. There is no "*" checkbox. Legacy keys that already carry `*` show a Full access badge. Keys cannot be edited: revoke the key and create a new one. The create button is disabled when no scopes are selected. API: `POST /api/v1/keys` accepts `{ "name": "...", "scopes": ["..."] }` with a Supabase JWT and step-up. Omitting `scopes` applies the agent-safe default. An unknown scope returns `400`. A call missing a required scope returns `403 API key missing scope: ...`. OAuth: a request without an explicit `scope` receives the Agent safe preset (`cards:read`, `payments:read`, `payments:write`, `browser`, `purchases`, `agent:read`, `agent:run`). Read only and Full are also available and the consent screen displays the preset and exact scopes. `payments:auto` is a separate, high-trust scope; without it, OAuth payments remain pending for human approval even if the account policy auto-approves. ChatGPT/MCP guidance: create a dedicated key for each client with only the scopes it needs. ChatGPT cannot change a key's scopes. Use Read only for read-only or Pro connectors and Agent safe for full agent actions. Never paste a key into a description, prompt or chat message. ## MCP transport - Streamable HTTP, stateless. Send JSON-RPC 2.0 POSTs to /mcp. - Sequence: initialize -> notifications/initialized -> tools/list -> tools/call. - The server may return text/event-stream; parse it as a JSON-RPC stream. ## MCP tools Each tool is marked with its current status. A tool that exists in the server does not imply that its downstream rail is available. ### votex_whoami (LIVE) Verify the credential. No parameters. Returns `{ authenticated, user_id, auth_type, api_key_id, oauth_client_id, scopes, plan, plan_label, features, limits }`. Use it first so you know whether Agent Runs/Dual-LLM are available (Pro+) and how many purchases remain. User-paid purchases work on Free. ### votex_upgrade_plan (LIVE) Create a Stripe Checkout link (Free→Pro/Business) or billing portal link (Pro→Business). Requires `billing:write`. Returns `{ current_plan, target_plan, mode, url, note }`. It never changes the plan or charges until the user pays in Stripe. ### votex_run_agent (LIVE) Start a goal-based browsing/research run (isolated browser plus planner and quarantined extractor). Pro+: 500/month on Pro, 3 000/month on Business. Free cannot start agent runs and keeps user-paid purchase handoffs. Params: `goal` (string, required, natural language); `url` (string, optional starting URL). Returns `{ run_id, status: "pending" }` immediately; the run is queued. Poll `votex_get_status`. If the plan hits a payment step, the run pauses with `status: "awaiting_approval"`; the user must approve in the VotexPay app before it resumes. The run does not execute a real merchant payment. ### votex_get_status (LIVE) Get a run's status and results. Params: `run_id` (string, required). Returns `{ run_id, status, goal, source, plan, extracted_data, payment_required, payment_amount, error_message }`. Statuses: `pending|running|awaiting_approval|completed|failed|cancelled`. ### votex_list_runs (LIVE) List the user's recent agent runs (most recent first, up to 20). No parameters. Returns `{ runs: [{ id, status, goal, source, payment_required, payment_amount, created_at }] }`. Use `votex_get_status` for details. ### votex_list_cards (LIVE) List the user's tokenized cards (masked). No parameters. Returns `{ cards: [{ id, pci_card_id, last4, brand, created_at }] }`. Use `id` for payments (`votex_request_payment`) and `pci_card_id` for purchases and autofill. `pci_card_id` is null when autofill is not enabled for that card. Full card numbers are never exposed. ### votex_create_purchase (LIVE for user_paid; Pro for vault) Create an agent purchase approval on one of two rails. Params: `amount` (required, > 0); `rail` (optional, default `vault`: `vault|user_paid`); `card_id` (required for `vault`, the `pci_card_id`); `session_id` (required for `vault`); `checkout_url` (required for `user_paid`, absolute HTTP(S) merchant checkout); `currency` (optional, default `eur`); `merchant_name` (optional); `item_description` (optional); `run_id` (optional, the Agent Run that requested the purchase; it must belong to the authenticated user or the call fails with `Agent run not found`). `user_paid` is available on Free (25/month), Pro (1 000/month) and Business (5 000/month). `vault` requires Business and an enabled PCI vault. For `vault`, the merchant origin is taken from the current page. For `user_paid`, no card or browser session is needed and the merchant origin comes from `checkout_url`. Returns `{ purchase_id, rail, status: "pending", amount, currency, merchant_origin, checkout_url, agent_run_id, agent_name, approval_url, handoff_url }`. `agent_name` is the API key name or OAuth client name. Approval and handoff URLs are absolute (`https://votexpay.com/...`). The `/pay/{token}` page shows the purchase ID, agent run ID, agent name, amount, merchant, item, rail and status; it never shows card data. A duplicate active user-paid purchase for the same user, merchant, amount and currency within 15 minutes is refused. Create the purchase once, or cancel the existing request first. The user must approve before the agent can fill a vault card or before a user-paid checkout link is released. The amount, merchant origin, card and session (vault) are bound to the approval. `handoff_url` is a one-time `/pay/{token}` link. Call `POST /api/v1/purchases/{id}/handoff` to create or rotate it. ### votex_list_purchases (LIVE) List the user's recent purchases and statuses. Requires `purchases`. ### votex_cancel_purchase (LIVE) Cancel a purchase created by this agent/client. Allowed while `pending`, or while `approved|awaiting_payment` for `user_paid`. Never approves a purchase. Params: `purchase_id` (required). ### votex_get_purchase (LIVE) Get a purchase approval status. Params: `purchase_id` (required). Returns `rail`, `checkout_url` (only for approved/awaiting-payment user-paid purchases), `order_reference` and `user_confirmed_at`. Statuses: `pending|awaiting_payment|approved|rejected|filled|completed|failed|expired`. `completed` means the user confirmed with an `order_reference`; `verification_status=user_confirmed` by default. It becomes `merchant_verified` only after an operator checks the merchant receipt/order. Billing/history-like `checkout_url` paths are returned with `warnings`. ### votex_fill_card (COMING SOON, Business) Fill an approved purchase card into the current checkout. Requires the Business plan and a test PCI vault. Params: `purchase_id` (required), `session_id` (required), `card_id` (required, `pci_card_id`), `selectors` (required object: `number`, `expiry`, `cvc?`, `name?`, `expiry_month?`, `expiry_year?`, `expiry_month_input?`, `expiry_year_input?`), `expiry_format` (optional: `MM/YY`, `MMYY`, `MM / YY`). Each selector can be a CSS string or an iframe-aware object: `{ "frame": "iframe[title=...]", "selector": "input[name=...]" }`. Use `expiry_month_input`/`expiry_year_input` for separate text inputs; use `expiry_month`/`expiry_year` for select elements. Iframe support enables Stripe Elements and Checkout card fields in test. The card is revealed server-side and never returned. The purchase must be `approved`; the current origin must match the approved origin. ### votex_submit_purchase (COMING SOON, Business) Submit an approved and filled purchase by clicking a checkout selector. Requires the Business plan and a test PCI vault. Params: `purchase_id` (required), `session_id` (required), `selector` (required), `wait_ms` (optional), `success_selector` (optional), `success_text` (optional), `success_url_contains` (optional). Returns `{ status: "submitted"|"filled", success_signal_detected, user_confirmation_required, url, content }`. The agent's success selector/text/URL is only a hint. It never marks a purchase `completed`; the purchase becomes `submitted` and the user must verify the merchant order in VotexPay. A URL change alone is never proof of success. ### votex_request_payment (LIVE, Pro) Request a payment on a saved card. This charges the saved Stripe card to VotexPay; it is not a merchant checkout. Requires the Pro plan. Params: `card_id` (string, required, from `votex_list_cards`); `amount` (number, required, > 0, major units: `12.5` = 12.50); `currency` (string, optional, ISO 4217 lowercase, default `eur`); `idempotency_key` (optional, deduplicates retries and prevents duplicate PaymentIntents). Returns `{ payment_id, status, amount, currency, auto_approved, message }`. Human-in-the-loop by default: status is `pending` until the user approves it in the app. Auto-confirmation requires the explicit `payments:auto` scope **and** a user policy that allows it; without `payments:auto`, the payment stays pending. Never assume a charge happened; check `status` and poll `votex_get_payment` or `GET /api/v1/payments/{payment_id}`. ### votex_list_payments (LIVE) List the user's payments (most recent first, up to 20). No parameters. Returns `{ payments: [{ id, amount, currency, status, created_at, confirmed_at }] }`. ### votex_get_payment (LIVE) Get a payment by id. Params: `payment_id` (string, required). Returns `{ id, amount, currency, status, created_at, confirmed_at }`. Statuses: `pending|confirmed|succeeded|failed|canceled|rejected`. ### votex_payment_policy (LIVE) Read the user's payment approval policy. No parameters. Returns `{ require_approval, threshold }`. When `require_approval` is false, payments are confirmed immediately; when a threshold is set, amounts at or below it are auto-approved and larger ones wait for the user. ### votex_navigate (LIVE, Pro) One-shot: navigate in a fresh isolated session, return sanitized page text (first ~2000 chars). Requires the Pro plan. Params: `url` (string, required, HTTP/HTTPS; localhost and private IPs are blocked). Returns `{ blocked: false, url, content }` or `{ blocked: true, reason }`. The session is closed after the call. ### votex_extract (LIVE, Pro) One-shot: navigate and extract fields with the quarantined LLM. Requires Pro. Params: `url` (string, required); `data_needed` (array of strings, optional, e.g. `["title","price"]`). Returns `{ blocked: false, url, extracted_data }` or `{ blocked: true, reason }`. ### votex_open_browser (LIVE, Pro) Open a persistent isolated browser session for multi-step work. Requires Pro. No parameters. Returns `{ session_id, provider }`. Sessions are user-scoped and in-memory; always close them with `votex_close_browser`. ### votex_browser_action (LIVE, Pro) Run an action inside an existing session. Requires Pro. Params: `session_id` (required); `action_type` (required: `navigate|click|type|wait|scroll|press|select|extract`); `params` (object): - `navigate`: `{ url }` - `click`: `{ selector }` - `type`: `{ selector, text }` - `wait`: `{ ms?, selector? }` - `scroll`: `{ x?, y? }` - `press`: `{ key }` - `select`: `{ selector, value }` - `extract`: `{ data_needed?: string[] }` Returns `{ session_id, blocked, action, result, url }`. SSRF guards apply to `navigate`; page content is sanitized. ### votex_fill_form (LIVE, Pro) Fill multiple fields in an existing session. Each field needs `selector`, `label`, `placeholder` or `role`; `kind` is `text|select|checkbox|radio`. Optional `submit_selector` and `wait_after_ms`. File uploads are not supported; values are never returned. ### votex_screenshot (LIVE, Pro) Capture a PNG screenshot of the current page in an existing session. Requires Pro. Params: `session_id` (required). Returns an image. Open a session and navigate first. Screenshots are disabled after `fill_card` for that session. ### votex_close_browser (LIVE, Pro) Close a session. Requires Pro. Params: `session_id` (required). Returns `{ status: "closed", session_id }`. ### votex_issue_virtual_card (COMING SOON) Virtual cards are coming soon. Issuing is disabled; do not rely on this tool. ### votex_list_virtual_cards (COMING SOON) Virtual cards are coming soon. Issuing is disabled. ### votex_freeze_virtual_card (COMING SOON) Virtual cards are coming soon. Issuing is disabled. ## REST endpoints (API-key friendly) ``` GET /api/v1/vault/cards -> masked cards (includes pci_card_id) POST /api/v1/purchases -> create a purchase (rail vault|user_paid) POST /api/v1/purchases/{id}/handoff -> create/rotate a /pay/{token} handoff_url GET /api/v1/purchases -> list purchases GET /api/v1/purchases/{id} -> purchase status GET /api/v1/handoffs/{token} -> purchase view for the approval page POST /api/v1/payments -> request a payment (HITL) GET /api/v1/payments -> list payments GET /api/v1/payments/{id} -> payment status POST /api/v1/actions -> {type:"navigate"|"extract", params:{...}} POST /api/v1/browser/sessions -> open session POST /api/v1/browser/sessions/{id}/actions DELETE /api/v1/browser/sessions/{id} ``` User-only (JWT, not API key): `POST /api/v1/purchases/{id}/approve|reject`, `POST /api/v1/purchases/{id}/user-paid/complete` (requires `{order_reference}` from the merchant), `POST /api/v1/purchases/{id}/user-verify`, `POST /api/v1/handoffs/{token}/approve|reject`, `POST /api/v1/payments/{id}/approve|reject`, card writes, API-key management and passkeys. Approved user-paid purchases can be cancelled with `/reject` before completion. Sensitive purchase decisions require step-up (2FA/passkey or a trusted device). Billing (JWT): `GET /api/v1/billing`, `POST /api/v1/billing/checkout`, `POST /api/v1/billing/portal`. ## Examples ### Request a payment 1. `votex_list_cards` -> pick `id`. 2. `votex_request_payment { card_id, amount: 12.5, currency: "eur" }` -> `pending`. 3. The user approves in the VotexPay app (`/vault` -> Payment approvals). 4. Poll `votex_get_payment { payment_id }` until `confirmed` or `failed`. ### Run a task and poll 1. `votex_run_agent { goal: "Open https://example.com and report the title" }` -> `run_id`. 2. Poll `votex_get_status { run_id }` every few seconds. 3. If `awaiting_approval`, ask the user to approve; otherwise read `extracted_data`. ### Make a user-paid purchase (works without PCI) 1. `votex_create_purchase { rail: "user_paid", amount, currency, checkout_url, merchant_name, item_description, run_id? }`. No card or browser session is needed. `run_id` is optional and must reference an Agent Run owned by the authenticated user. 2. Share the returned absolute `handoff_url` (`https://votexpay.com/pay/{token}`) with the user. 3. The user opens the link, approves, opens the merchant checkout, pays and confirms completion with the merchant order reference. 4. Poll `votex_get_purchase { purchase_id }` until `completed`. 5. If the URL or amount is wrong, call `votex_cancel_purchase { purchase_id }` before the user pays. The user pays in their own browser; VotexPay never sees card data. The user must verify the merchant, amount and origin before paying. ### Make a vault card purchase (COMING SOON, test preview only) 1. `votex_list_cards` -> pick a card with `pci_card_id`. 2. `votex_open_browser` -> `session_id`; navigate to the merchant checkout. 3. `votex_create_purchase { rail: "vault", card_id: pci_card_id, session_id, amount, currency, merchant_name, item_description, run_id? }`. `run_id` must belong to the authenticated user. 4. The user approves in the VotexPay app (`/vault` or the returned `/pay/{token}` handoff). 5. `votex_fill_card { purchase_id, session_id, card_id, selectors }`. 6. `votex_submit_purchase { purchase_id, session_id, selector, success_selector|success_text|success_url_contains }`. 7. Poll `votex_get_purchase { purchase_id }` until `completed`. The user must verify the amount on the checkout page before approving. VotexPay binds the approved amount, merchant origin, card and session, but does not scrape the merchant total automatically. ### Browse and extract 1. `votex_open_browser` -> `session_id`. 2. `votex_browser_action { session_id, action_type: "navigate", params: { url: "https://example.com" } }`. 3. `votex_browser_action { session_id, action_type: "click", params: { selector: "a" } }`. 4. `votex_browser_action { session_id, action_type: "extract", params: { data_needed: ["title"] } }`. 5. `votex_close_browser { session_id }`. ## Region gating and honest limits - Link is coming soon and disabled for all accounts until its callback is fixed. It will be limited to eligible US/Canada accounts, not EU/PT customers. - OAuth 2.1 for AI platforms is LIVE (dynamic registration, PKCE, consent, rotating refresh tokens, revocation). - Supplier API, Stripe SPT and Forwarding are coming soon. - Virtual cards, production card autofill and arbitrary-merchant autonomous card purchases are coming soon. - ChatGPT and Claude plugins are coming soon. - Agents cannot approve payments or purchases, or bypass human approval. - Agent Runs browse and research. They do not execute real merchant payments. Purchases are a separate approval and handoff flow. - `votex_request_payment` charges a saved Stripe card to VotexPay. It is not a merchant checkout. - User-paid purchases are paid by the user on the merchant site. VotexPay does not charge for those. - Cards are tokenized by Stripe; agents only see brand and last4. - Browser sessions are in-memory and per-user; a restart drops them (queued runs are durable). Close sessions when done. - Supported browser actions: `navigate, click, type, wait, scroll, press, select, extract`. No file upload or download. - `votex_screenshot` is available, but screenshots are disabled after `fill_card` for that session. - `user_paid` purchases work without PCI/issuer. Vault purchases, `fill_card` and autofill return `503 PCI vault is disabled` in production until a live Basis Theory vault is configured; use the test deployment for vault flows. - Merchant CAPTCHAs, 3DS and checkout changes may require user handoff. Automated Stripe Checkout is blocked by hCaptcha. - `localhost`, private/internal IPs and non-HTTP(S) URLs are blocked. - Amounts are in major units of the passed currency (default `eur`); no FX conversion. - If a tool returns an error, surface it to the user; do not retry blindly. - The API may return `403` when a user-only step-up (2FA/passkey) is required.