# MagicPay Full Agent Docs This file is optimized for LLM and agent ingestion. It mirrors the visible public documentation and should be treated as a retrieval aid, not as a hidden policy source. --- # MagicPay Docs Canonical URL: https://magiccard.ai/docs Markdown URL: https://magiccard.ai/docs/index.md Summary: MagicPay gives personal AI agents one user-authorized payment stack: MagicCard, Memory requests, and routing across browser, API, and agentic payment rails. Description: Product and developer documentation for MagicPay, the payment infrastructure for personal AI agents. ## Canonical Answer MagicPay gives personal AI agents one user-authorized payment stack: MagicCard, Memory requests, and routing across browser, API, and agentic payment rails. Product and developer documentation for MagicPay, the payment infrastructure for personal AI agents. MagicCard, requests, secrets, and approvals stay under the human owner's control. ![MagicPay overview architecture](https://magiccard.ai/docs-assets/images/magicpay-overview-architecture.png) ## Key Points - Mercuryo-backed payment infrastructure for personal AI agents. - One user-authorized payment stack for online purchases, subscriptions, and agent-native rails. - MagicCard, requests, secrets, and approvals stay under the human owner's control. - Sensitive data is resolved inside MagicPay, never in LLM context. ## What MagicPay Is MagicPay is designed to be the universal payment tool for a personal AI agent. The agent can use Mercuryo-backed cards and payment operations, APIs, crypto rails, browser checkout, and agent-native protocols to get the job done, while the user sees a simple MagicCard with one balance. MagicCard makes payments in the complex world of agentic protocols, new payment standards, and crypto feel as simple as topping up a card. ## MagicPay Overview MagicPay is payment infrastructure for personal AI agents. The goal is to feel as simple as Apple Pay for users and their agents while hiding wallets, cards, protocols, approval routing, and protected execution behind one MagicCard interface. - Protected requests: Approvals, secrets, identity details, and payment execution move through user-controlled requests instead of model context. (https://magiccard.ai/docs/components/memory-fill) - Commerce Routing: MagicSearch, MagicBrowse, SDK, API, and agentic protocols pick the best payment path for each agent purchase. (https://magiccard.ai/docs/reference/payment-methods) ## Purchase Loop Every purchase is a session: the personal agent clarifies intent, MagicPay raises requests when user authority is needed, and execution continues through the best available payment rail. - Intent To Session: The user asks their agent for a purchase, and MagicPay turns it into a tracked payment session with events. (https://magiccard.ai/docs/reference/entities#payment-session) - User Authority: KYC, balance, approvals, secrets, and final confirmations stay owned by the human. (https://magiccard.ai/docs/reference/entities#request) - Payment Execution: The session can finish through x402, MCP/API, SDK calls, or protected browser checkout. (https://magiccard.ai/docs/guides/e2e-purchase) ## Build With MagicPay Use the built-in payment agent for end-to-end purchases, or connect your own personal agent runtime through the SDK and API while the user stays in control through the MagicPay apps. - Built-In Payment Agent: Searches providers, coordinates MagicBrowse, ranks payment channels, and asks the user to approve each protected step. (https://magiccard.ai/docs/guides/e2e-purchase) - MagicPay SDK: Bridges agents to Mercuryo payment infrastructure and MagicPay backend services for sessions, auth, and preferences. (https://magiccard.ai/docs/integrations/sdk) - Human UI: Web, mobile, ChatGPT, Claude, Telegram, and email apps handle approvals, sessions, card state, and confirmations. (https://magiccard.ai/docs/components/omnichannel-ui) ## Choose Your Path Use the docs path that matches what you want to do next. - Set up an account: Create the user account, pass KYC, top up the MagicCard balance, and connect your first agent. (https://magiccard.ai/docs/guides/account-setup) - Understand the product: Start with MagicCard, Memory requests, MagicBrowse, MagicSearch, and the SDK. (https://magiccard.ai/docs/components) - Run a purchase: Follow the built-in agent purchase flow from intent discovery to provider selection and user approval. (https://magiccard.ai/docs/guides/e2e-purchase) - Integrate the SDK: Use MagicPay from your own agent, worker, MCP tool, or browser runtime. (https://magiccard.ai/docs/integrations/sdk) ## Recommended Path Most users and builders should follow the same staged path before a real payment. This keeps setup, safety, and payment authority understandable for both humans and agents. 1. Create a MagicPay account and complete account, KYC, and balance prerequisites. 2. Connect one agent runtime and verify that MagicPay and MagicBrowse are available. 3. Run a browser-only task so the agent proves it can navigate without any protected data. 4. Run a low-risk protected form handoff, such as a shipping address. 5. Add reusable MagicPay Memory values only after the user understands what will be stored. 6. Move to SDK, API, or full purchase flows once request handling is observable end to end. ## Use Case Entry Points Start from the workflow you are trying to ship. The components underneath are modular, but each path trusts the agent with a different amount. - I want my agent to buy something: Use the end-to-end purchase guide to combine MagicSearch, MagicBrowse, approvals, and payment execution. (https://magiccard.ai/docs/guides/e2e-purchase) - I want protected form fill: Use MagicPay Memory fill when the agent reaches card, login, identity, or confirmation fields. (https://magiccard.ai/docs/components/memory-fill) - I want to integrate the SDK: Use MagicPay SDK when your app owns the surrounding agent or browser runtime. (https://magiccard.ai/docs/integrations/sdk) - I want Mercuryo-backed payments: Use Mercuryo Bridge docs for account linking, KYC, card state, top-up, and provider callbacks. (https://magiccard.ai/docs/components/mercuryo-bridge) - I want agent-readable rules: Use the agent operating guide for machine-readable rules, routing guidance, and discovery hints. (https://magiccard.ai/docs/agents) - Something is stuck: Use troubleshooting for checkout, request, Memory, payment, and Mercuryo failure modes. (https://magiccard.ai/docs/guides/troubleshooting) ## Related - MagicCard: https://magiccard.ai/docs/magiccard - Getting Started: https://magiccard.ai/docs/getting-started - MagicPay Components: https://magiccard.ai/docs/components - MagicPay SDK: https://magiccard.ai/docs/integrations/sdk --- # MagicCard Canonical URL: https://magiccard.ai/docs/magiccard Markdown URL: https://magiccard.ai/docs/magiccard.md Summary: MagicCard turns agentic payments, crypto, APIs, browser checkout, and new payment protocols into one simple top-up balance. Description: MagicCard is the simple user-facing balance and payment interface for personal AI agents. ## Canonical Answer MagicCard turns agentic payments, crypto, APIs, browser checkout, and new payment protocols into one simple top-up balance. MagicCard is the simple user-facing balance and payment interface for personal AI agents. Card data and final confirmations stay behind MagicPay approval requests. ![MagicCard payment methods](https://magiccard.ai/docs-assets/images/magiccard_image.png) ## Key Points - One card-like interface for personal AI agent payments. - As simple for the user as topping up a single card balance. - Supports one-time purchases, marketplace cards, and subscription-specific payment methods. - Card data and final confirmations stay behind MagicPay approval requests. ## Supported Payment Methods MagicCard is not one physical rail. It is the user-facing abstraction over the payment methods MagicPay can orchestrate for each agent session. Method | Status | Use when --- | --- | --- Card payments | Live | The merchant supports ordinary online checkout and no merchant integration is required. API access | Live | A developer or agent can complete the payment through a programmatic MagicPay or provider API path. x402 | Live | The provider supports HTTP-native stablecoin micropayments. ACP | Planned | The provider supports Agentic Commerce Protocol checkout. AP2 | Planned | The flow needs secure delegation of payment authority from human to agent. Future protocols | Planned | New agent payment standards become available behind the same MagicCard interface as they ship. ## How MagicPay Chooses A Method MagicPay ranks the safest and most direct route first. Agent-native protocols and official APIs are preferred when available; reverse APIs and browser checkout are fallback paths when the merchant only supports legacy flows. - The user does not need to choose rails for every purchase. - The agent should request the purchase intent, not a specific card number or secret. - MagicSearch and provider metadata can influence routing before MagicBrowse opens a page. - User approval and policy still decide whether money can move. ## Card Types Different payment relationships need different persistence. MagicCard keeps the user-facing model simple while MagicPay scopes the payment method to the job. Type | Best for | Persistence --- | --- | --- One-time purchase | Tickets, bookings, goods, and single checkout sessions. | Card details are isolated to the payment and not reused by the agent. Marketplace purchase | Amazon, delivery, travel, and other accounts that may need a saved method. | A provider-scoped relationship can remain available for future approved sessions. Recurring subscription | SaaS, memberships, renewals, and scheduled charges. | A dedicated subscription payment method persists with next-charge and cancellation context. ## No Data In LLM Context MagicCard does not mean the model gets card data. Card numbers, credentials, OTPs, identity fields, and final payment confirmations stay inside MagicPay protected flows and never enter LLM context. The agent receives only safe state such as request status, approval outcome, selected provider, and whether the workflow can continue. ## Smart Internal Top-Up MagicPay presents one simple MagicCard balance while agents spend only through approved sessions, policy-controlled limits, and available balance checks. Internal top-up and routing logic can prepare the right payment path for the session while keeping wallet, swap, card, and protocol complexity out of the user-facing flow. ## Related - Payment Methods: https://magiccard.ai/docs/reference/payment-methods - MagicPay Memory fill: https://magiccard.ai/docs/components/memory-fill - Mercuryo Bridge: https://magiccard.ai/docs/components/mercuryo-bridge - Manage Subscriptions: https://magiccard.ai/docs/guides/subscriptions --- # Getting Started Canonical URL: https://magiccard.ai/docs/getting-started Markdown URL: https://magiccard.ai/docs/getting-started.md Summary: Install the MagicPay skill, let `magicpay setup next` guide account connection, then top up MagicCard before the first low-risk payment session. Description: The shortest path from a new MagicPay account to an agent that can complete a payment session. ## Canonical Answer Install the MagicPay skill, let `magicpay setup next` guide account connection, then top up MagicCard before the first low-risk payment session. The shortest path from a new MagicPay account to an agent that can complete a payment session. Protected payment and identity data stays behind MagicPay requests instead of entering LLM-visible context. ## Prompt-First Setup Installing and using MagicPay should start with one short instruction to your personal agent: read and install the hosted MagicPay skill. The skill owns CLI repair, email OTP setup, existing-connection handling, status checks, and top-up link generation. The user keeps authority over approvals, sensitive data, card state, and balance. ## Get Started With UI Use this path when you want to set up the human control surface first. The UI lets you manage MagicCard state, review sessions, respond to requests, create UI-connected agent prompts, and choose the platform where approvals should arrive. 1. Create an account with email, Apple, or Google. Email signup uses an OTP. 2. Create or link the Mercuryo payment account for the same email. 3. Complete identity verification (KYC) in the Mercuryo verification flow opened from MagicPay. 4. Top up the MagicCard balance. Crypto top-up is available now; fiat top-up depends on the active provider route. 5. Open the Web app, mobile app, ChatGPT app, Claude app, or Telegram miniapp and choose the request channels you want to use. 6. Create an agent from the UI when you want MagicPay to generate a setup-token prompt for that specific agent. 7. Add useful Memory such as delivery addresses, logins, or passport details from the UI before a session needs them. ## Get Started With The Agent Use this path when you already know which agent runtime should pay for you. The agent setup flow installs the MagicPay skill, asks `magicpay setup next` for the exact next step, and then relies on requests whenever user approval or Memory data is needed. 1. Send the agent `Set up MagicPay from https://magiccard.ai/skill.md` or use the platform-specific prompt shown by the landing page. 2. The skill installs or repairs the MagicPay CLI and verifies that `magicpay --help` includes `setup next`. 3. The skill runs `magicpay setup next --intent landing --platform --agent-name " Agent" --api-url https://durcottggsiesxxqzvbb.supabase.co/functions/v1/api --env production` and follows the returned `instructions` exactly. 4. If setup asks for email and OTP, provide them only through the setup flow. If an existing connection is found, choose reuse or another email explicitly. 5. After setup succeeds, let the skill run `magicpay status` and generate a hosted MagicCard top-up link when needed. 6. Ask for a small, specific first task with a clear success condition, such as a low-risk checkout or a page you already trust. 7. Let the agent create the payment session and wait for MagicPay requests when approval, choice, login, identity data, or payment execution is required. 8. Approve or deny requests in whichever MagicPay app you prefer. 9. Review the session events after the run and save any reusable Memory items or preferences that make the next session smoother. Note: Prefer the MagicPay cabinet for passwords, card numbers, passport details, OTPs, and other protected values. Chat entry can be convenient for reusable Memory facts, but anything typed into chat is model-visible. ## What Both Paths Need Both paths lead to the same operating model: the user owns payment authority, MagicPay owns Memory request handling, and the agent continues only after the required approvals or protected actions complete. - A user account with a linked Mercuryo payment account. - Completed KYC for the supported region. - A funded MagicCard balance. - At least one enabled request channel for approvals and confirmations. - An installed MagicPay skill plus a CLI whose help output includes `setup next`. - A constrained first purchase that is easy to verify. ## Related - Set Up Your Account: https://magiccard.ai/docs/guides/account-setup - Connect An Agent: https://magiccard.ai/docs/guides/connect-agent - E2E Purchase Flow: https://magiccard.ai/docs/guides/e2e-purchase --- # MagicPay Components Canonical URL: https://magiccard.ai/docs/components Markdown URL: https://magiccard.ai/docs/components.md Summary: MagicPay is modular payment infrastructure for personal AI agents. Each component can stand alone, but together they form an end-to-end purchase flow where agents act for humans without owning sensitive data. Description: The MagicPay component map: browser execution, commerce discovery, saved user data, Mercuryo connectivity, and the apps people approve from. ## Canonical Answer MagicPay is modular payment infrastructure for personal AI agents. Each component can stand alone, but together they form an end-to-end purchase flow where agents act for humans without owning sensitive data. The MagicPay component map: browser execution, commerce discovery, saved user data, Mercuryo connectivity, and the apps people approve from. One user balance and approval model across every connected agent. ## Key Points - Single payment stack for browser checkout, API checkout, and agent-native protocols. - One user balance and approval model across every connected agent. - Protected data stays behind MagicPay requests instead of entering LLM context. - Components can be adopted separately or composed into the built-in payment agent. ## Component Map MagicPay splits the payment problem into modules with clear edges. MagicBrowse handles legacy web execution. MagicSearch finds the best provider and channel before a browser is opened. MagicPay Memory stores reusable user data. MagicPay Memory fill writes approved values into any target the runtime owns — an API call, a provider SDK, or a browser field. Mercuryo Bridge connects MagicPay sessions to payment account, KYC, card, balance, and transaction services. Omnichannel UI keeps the human in control. - MagicCard: A single balance and payment interface your personal agent can use across Mercuryo-backed cards, crypto, swaps, and agentic rails. (https://magiccard.ai/docs/magiccard) - MagicBrowse: Commerce-specialized browser automation for navigation, checkout, and safe sensitive-step handoff. (https://magiccard.ai/docs/components/magicbrowse) - MagicSearch: Provider discovery, channel ranking, and agentic search fallback before browser handoff. (https://magiccard.ai/docs/components/magicsearch) - MagicPay Memory: User-owned storage for logins, identity details, payment cards, and reusable checkout fields. (https://magiccard.ai/docs/components/memory) - MagicPay Memory fill: Applies user-approved values to the target — a browser field, API header, or provider call — so values never reach the LLM. (https://magiccard.ai/docs/components/memory-fill) - Mercuryo Bridge: Payment backend bridge for account linking, KYC, card issuance, top-up, and execution callbacks. (https://magiccard.ai/docs/components/mercuryo-bridge) - Omnichannel UI: Web, mobile, Telegram, ChatGPT, Claude, and browser-extension apps for approvals and supervision. (https://magiccard.ai/docs/components/omnichannel-ui) ## End-To-End Shape A typical flow starts with user intent, moves through MagicSearch for provider selection, uses MagicBrowse or an API/protocol channel for execution, pauses at protected steps, resolves data or actions through MagicPay Memory and MagicPay Memory fill, and asks the user through Omnichannel UI before Mercuryo-backed payment execution proceeds. ## Related - MagicBrowse: https://magiccard.ai/docs/components/magicbrowse - MagicSearch: https://magiccard.ai/docs/components/magicsearch - MagicPay Memory fill: https://magiccard.ai/docs/components/memory-fill --- # MagicBrowse Canonical URL: https://magiccard.ai/docs/components/magicbrowse Markdown URL: https://magiccard.ai/docs/components/magicbrowse.md Summary: MagicBrowse helps agents use legacy commerce websites by combining browser automation, checkout-specific behavior, and a growing site memory. Description: MagicBrowse is the commerce-specialized browser agent layer for checkouts, forms, and payment flows. ## Canonical Answer MagicBrowse helps agents use legacy commerce websites by combining browser automation, checkout-specific behavior, and a growing site memory. MagicBrowse is the commerce-specialized browser agent layer for checkouts, forms, and payment flows. LLM planner with vision plus a high-speed DOM navigator for checkout execution. ![MagicBrowse checkout trace](https://magiccard.ai/docs-assets/images/components-magicbrowse-handoff.svg) ## Key Points - Browser-use agent purpose-built for real e-commerce navigation and checkout flows. - LLM planner with vision plus a high-speed DOM navigator for checkout execution. - Stops at login, payment, identity, CAPTCHA, and every other protected step. - Learns from successful runs through site memory, runtime hints, and checkout traces. ## Commerce-First Browser Use General browser agents are broad and brittle around checkout. MagicBrowse narrows the problem: search result pages, product pages, carts, guest checkout, provider handoff, form observation, and sensitive-step detection. The active package is `@nuanu-ai/magicbrowse`, and the CLI is `@nuanu-ai/magicbrowse-cli`. ## Planner And Navigator MagicBrowse separates planning from low-level browser movement. The planner reasons over the task, visual state, and commerce-specific policies. The navigator performs DOM-oriented actions and reports structured observations. This lets MagicPay keep the agent fast on ordinary browsing while enforcing hard stops before sensitive entry. ```ts import { act, launch } from '@nuanu-ai/magicbrowse'; const session = await launch({ headless: false, url: 'https://www.booking.com', }); const result = await act({ sessionId: session.id, goal: 'Find a Hilton stay from May 10 to May 12 and stop before sensitive guest or payment data.', }); if (result.status === 'needs_handoff') { await createMagicPayRequest(result.handoff); } ``` ## Sensitive-step Handoff MagicBrowse should not type passwords, card values, passport details, OTPs, or final payment confirmations directly from model context. When it observes a protected form, MagicPay creates a request, resolves the approved artifact, writes the value through the trusted fill path, and returns only the continuation state the browser agent needs. ## Site Memory MagicBrowse teaches itself after each successful checkout. Successful commerce traces can be converted into site-specific hints: useful URLs, checkout milestones, button labels, form shapes, provider handoff patterns, and recovery notes. These hints speed up future runs and reduce repeated exploration, but they never override live page state, policy, or user approval. Over time, this becomes an agentic knowledge base of internet commerce: a practical memory of how real merchants, booking sites, marketplaces, and checkout flows work for AI agents. ## Related - E2E Purchase Flow: https://magiccard.ai/docs/guides/e2e-purchase - Agent Skills: https://magiccard.ai/docs/integrations/agent-skills - MagicPay Memory fill: https://magiccard.ai/docs/components/memory-fill --- # MagicSearch Canonical URL: https://magiccard.ai/docs/components/magicsearch Markdown URL: https://magiccard.ai/docs/components/magicsearch.md Summary: MagicSearch gives agents fast commerce routing data: trusted providers, scored payment methods, checkout targets, API-capable paths, and fallback search results when the index is not enough. Description: MagicSearch is an extensible commerce provider index and query layer for personal AI agents. ## Canonical Answer MagicSearch gives agents fast commerce routing data: trusted providers, scored payment methods, checkout targets, API-capable paths, and fallback search results when the index is not enough. MagicSearch is an extensible commerce provider index and query layer for personal AI agents. Protected payment and identity data stays behind MagicPay requests instead of entering LLM-visible context. ![Provider search and ranking](https://magiccard.ai/docs-assets/images/components-magicsearch-routing.svg) ## Key Points - Extensible provider index populated by curated entries and automated discovery. - Query interface for merchant, product, category, geography, intent, and preferred payment channels. - Ranks payment methods such as x402, MCP, official API, reversed API, and browser checkout. - Returns either an API-capable payment route or a checkout URL for MagicBrowse. - Uses choice requests when the user needs to pick between several viable options. ## Provider Index MagicSearch is a commerce provider index built for agents, not a browser search page built for humans. The index can contain human-curated providers, automatically discovered providers, trust information, supported countries, merchant domains, checkout entry points, provider tags, historical purchase signals, and payment method records. The goal is to answer the agent quickly: which provider should handle this intent, which channel should be used, and whether the workflow can continue through an API or should hand off to MagicBrowse. ```ts // Simplified shapes — see @nuanu-ai/magicsearch for the full types. type MagicSearchProviderRecord = { id: string; name: string; description: string | null; category: string | null; enabled: boolean; status: 'active' | 'paused' | 'deprecated'; domains: string[]; searchTerms: string[]; intentTypes: string[]; categories: string[]; tags: string[]; score: number; metadata: Record; }; type MagicSearchPurchaseMethodRecord = { id: string; providerId: string; type: 'x402' | 'mcp' | 'api' | 'reversed_api' | 'browser'; status: 'active' | 'experimental' | 'paused'; metadata: Record; }; ``` ## Agent Query Interface Agents query MagicSearch with the user request plus structured hints. The query can include merchant, domain, product, category, country, region, place, intent type, checkout shape, quote requirements, authentication context, and preferred method types. MagicSearch normalizes those inputs into a provider query and a discovery query, so the agent does not need to open a browser just to find the right starting point. ```ts import { createRemoteMagicSearchClient } from '@nuanu-ai/magicsearch'; const search = createRemoteMagicSearchClient({ apiUrl: process.env.MAGICPAY_API_URL!, apiKey: process.env.MAGICPAY_API_KEY!, }); const result = await search.query({ query: 'Book a hotel in Lisbon for May 10 to 12', purpose: 'checkout', hints: { merchantHint: 'Booking.com', category: 'hotel', country: 'PT', placeHint: 'Lisbon', }, providerQuery: { intentType: 'booking', preferredMethodTypes: ['mcp', 'api', 'browser'], quoteRequirements: ['dates', 'room', 'refund policy'], }, }); ``` ## Payment Methods A provider can expose multiple payment methods. MagicSearch scores the compatible methods before the workflow starts, so the agent can prefer the fastest and most agent-native channel while still falling back to legacy commerce when needed. Method | Use when | Default rank --- | --- | --- x402 | The provider supports HTTP-native stablecoin payment or machine-readable paywall settlement. | Highest priority because the payment can be handled as an agent-native protocol. MCP | The provider exposes an MCP-compatible commerce tool or MagicPay can call a provider-specific MCP facade. | Preferred after x402 because the agent can use a structured tool interface. API | The provider has an official API or MagicPay backend can complete the checkout programmatically. | Preferred when it avoids browser work and keeps the payment process server-side. Reversed API | MagicPay has learned a provider flow that can be called without ordinary browser interaction. | Useful when there is no official API but the flow is reliable enough to automate. Browser | The provider only supports a normal website checkout or account flow. | Fallback method that hands a start URL to MagicBrowse. ## Scoring Provider scoring combines evidence about the provider and evidence about the method. Exact merchant or domain matches rank highest. Vertical matches such as hotel or flight providers beat loose text matches. Intent, category, tag, country, region, and product hints help narrow the catalog. Payment method scoring then favors x402, MCP, API, reversed API, and browser in that order, with a small bonus for method types requested by the agent. Low-confidence matches fall back to discovery instead of pretending the index knows the answer. - Only active and enabled provider entries can be selected. - A strong provider match needs exact provider evidence, vertical evidence, intent/category evidence, or enough trusted metadata. - If the selected provider has no compatible active payment method, MagicSearch falls back to discovery. - Scores improve routing, but they never bypass user approval, MagicPay policy, or protected payment requests. ## Result Shape MagicSearch returns the route and runtime method the agent should use next. Every successful beta result has methodType browser, so the runtime hands the URL to MagicBrowse. Provider capability metadata remains nested for later x402, MCP, API, or other dispatchers. ```ts // Simplified shape — see @nuanu-ai/magicsearch for the full type. type MagicSearchUrlResult = { url: string; source: MagicSearchResultSource; methodType: 'x402' | 'mcp' | 'api' | 'reversed_api' | 'browser'; title: string | null; query: string; confidence: 'high' | 'medium' | 'low'; provider: { id: string; name: string | null; methodId: string | null; methodType: 'x402' | 'mcp' | 'api' | 'reversed_api' | 'browser' | null; confidence: 'high' | 'medium' | 'low' | 'none'; } | null; choices?: MagicSearchChoiceOption[]; }; ``` ## Choice Request When MagicSearch finds several plausible items, providers, hotels, flights, products, or checkout targets, it can pause the workflow with a MagicPay choice request. The user picks the option that matches their intent instead of forcing the agent to guess. The user can also add notes, such as a preferred room type, delivery constraint, budget, or merchant preference; MagicSearch can use those notes as adjusted search input and continue the job with better context. - Choice options can include title, subtitle, description, URL, price, images, and characteristics. - The agent receives the selected option and can continue with the selected checkout URL. - Choice requests are especially useful for travel, tickets, restaurants, products, and services where the phrase “best option” depends on user preference. ## Search Fallback If the provider index has no match, has only a low-confidence match, or has a provider without a usable URL, MagicSearch falls back to agentic web discovery using web search providers. The fallback result gives MagicBrowse a better starting URL than a blank browser search, and multiple fallback results can become choice options for the user. - Fallback is a recovery path, not the primary product model. - The discovery query is built from the prompt plus merchant, product, domain, category, geography, and purchase-purpose hints. - MagicBrowse starts from the returned provider, product, or checkout page instead of browsing like a human from the homepage. ## Related - E2E Purchase Flow: https://magiccard.ai/docs/guides/e2e-purchase - Payment Methods: https://magiccard.ai/docs/reference/payment-methods - Trust System: https://magiccard.ai/docs/reference/trust-system --- # MagicPay Memory Canonical URL: https://magiccard.ai/docs/components/memory Markdown URL: https://magiccard.ai/docs/components/memory.md Summary: MagicPay Memory stores user-owned items and protected fields so agents can request the right data during a workflow without seeing raw values. Description: MagicPay Memory is user-data storage designed specifically for personal AI agents and user-approved data use. ## Canonical Answer MagicPay Memory stores user-owned items and protected fields so agents can request the right data during a workflow without seeing raw values. MagicPay Memory is user-data storage designed specifically for personal AI agents and user-approved data use. Memory reads go through MagicPay requests and MagicPay Memory fill instead of LLM context. ![How MagicPay Memory is organised: identities, items, fields](https://magiccard.ai/docs-assets/images/components-memory-model.svg) ## Key Points - Secure data storage designed for personal AI agents, not a prompt memory system. - Items group related fields and can identify the person or organization they belong to. - Users can manage data directly, while agents can request or save approved data during work. - Memory reads go through MagicPay requests and MagicPay Memory fill instead of LLM context. ## Agent Memory Storage MagicPay Memory is the user-data layer for personal AI agents. It stores reusable facts and secrets in a user-bound model, so an agent can ask for the right data at the right moment without asking the user to paste passwords, identity details, card values, or addresses into chat. Users can create and edit records from the UI. Agents can request records during a checkout, ask the user for missing data, and save approved values for future sessions. ## Items, Subjects, And Fields The current storage model is intentionally small: the user owns each Memory item, an item groups related fields, and optional subject links record who or what the item is about. A subject link can distinguish the user, a spouse, another traveler, or an organization when that context was explicitly saved. This supports requests such as “buy tickets for me and my wife” without claiming a separate identity graph or inferring relationships that the user did not provide. ```ts type MemoryItem = { id: string; owner_user_id: string; display_label: string; status: 'active' | 'pending' | 'revoked' | 'deleted'; subject_links: Array<{ subject_ref: string; role?: string }>; scope: Array>; fields: MemoryField[]; availability: Record; }; ``` ## Entries An entry is a reusable Memory item: login, identity document, payment method, wallet, address-like identity data, or another saved record. A user can have several entries with overlapping fields. If a checkout needs a delivery address and several address entries match, MagicPay should ask a choice request instead of guessing. The selected entry becomes the source for that session, and the user can save new entries when an agent discovers missing information along the way. ```ts type MemoryField = { name: string; label: string; hint?: string | null; value_type?: 'date' | 'phone_number' | 'person_name' | 'country'; is_secret: boolean; }; ``` ## Fields A field is a key-value pair with a label, type, requirement flag, sensitivity, and optional semantic tags. Fields can appear in several entries: date of birth can exist on a basic identity entry, a passport entry, and a driver license entry. MagicPay Memory keeps this flexible by separating schema definitions from values and by enforcing a sensitivity floor for hard-secret keys such as passwords, card numbers, CVV, document numbers, private keys, seed phrases, and dates of birth. Field property | Meaning | Example --- | --- | --- key | Stable machine key used by agents and form matching. | date_of_birth label | Human-readable label shown to the user. | Date of birth type | Value type used by editors and validation. | text, secret, date, email, url sensitivity | Whether the field is marked secret. | secret flag semantic_tags | Hints for secure matching and Memory fill. | document_number, password ## Choice Requests When more than one entry can satisfy a request, MagicPay Memory should hand the decision to the user. For example, a user may have a home address, an office address, and a hotel address; the agent should not infer which one to use for the current checkout. A choice request can show the safe labels and summaries, let the user pick the right entry, and optionally collect a note that helps the agent continue. - Use choice requests when multiple identities, addresses, documents, or payment-related entries match. - Show safe summaries rather than raw values. - Persist the selected entry only when the user explicitly chooses to save or reuse it. ## Agent Access Agents reach MagicPay Memory through requests and tools, never through direct database access. Listing Memory returns safe labels and handles so the agent can understand what exists without seeing raw values. Creating or updating Memory requires user approval. Reading Memory values happens through a MagicPay request flow and returns a short-lived artifact for the trusted fill or provider call. ```ts const items = await tools.list_memory_items(); const editableAddress = items.find((item) => item.label === 'Hotel delivery address' && item.readOnly !== true ); await tools.create_memory_item({ label: 'Hotel delivery address', scope: [{ kind: 'site', value: 'merchant.example' }], fields: [{ name: 'postal_code', value: '10001', hint: 'Hotel delivery postal code' }], }); ``` ## Out-of-context Read When a protected value is requested and approved, the goal is that the orchestrating LLM never receives the raw value. The agent asks for a field, MagicPay resolves the request, and MagicPay Memory fill or another trusted runtime applies the value in the browser, in an API call, or in a provider call. The value is transmitted as Memory request material and decrypted only where it has to be applied. The agent receives status, selected item, field keys, and completion state, not the value itself. - Do not paste protected values into chat. - Do not log, summarize, or store request artifacts in prompts. - Use MagicPay Memory fill for browser forms so protected values bypass LLM context. - Use provider or API calls for non-browser flows when a backend can complete the action directly. ## Security And Storage MagicPay Memory is user-bound and permissioned through MagicPay. Memory records keep open metadata separate from protected values, and they can point to provider-backed records such as Mercuryo payment cards instead of copying them. Identity data that comes from the KYC flow stays provider-sourced: MagicPay references the verification result rather than storing every verified field itself. The rule that matters: raw protected values never reach model context, and they are released only through approved requests. - Open fields can support matching and user-visible summaries. - Protected fields are redacted from ordinary list and get responses. - Provider-backed records can store references instead of copying provider-owned secrets. - Revoked Memory items remain unavailable to agents until re-enabled by the user. ## Extensible Schemas The model is intentionally flexible. Today the registry includes login, identity, identity document, provider-backed payment card, and wallet schemas. New entries can add fields and semantic tags without changing how agents request data. This lets MagicPay Memory act as a secure store for ordinary checkout data now and expand toward richer personal and organizational identity graphs over time. ```ts type MemoryField = { key: string; label: string; type: 'text' | 'secret' | 'date' | 'number' | 'email' | 'url'; required: boolean; secret: boolean; semantic_tags?: string[]; }; ``` ## Save During Workflows MagicPay Memory can be populated before a session from UI, or during a session when the user supplies missing data. Session-time writes should be explicit so the user understands what identity, entry, and fields will be reusable later. - Reusable Memory facts can be convenient, but sensitive values belong in Memory items. - Provider-backed card items are synced from Mercuryo state rather than manually edited. - Artifacts should not be logged, stored in prompts, or reused after the protected step. ## Related - Manage Memory: https://magiccard.ai/docs/guides/manage-secrets - MagicPay Memory fill: https://magiccard.ai/docs/components/memory-fill - Entities: https://magiccard.ai/docs/reference/entities --- # MagicPay Memory fill Canonical URL: https://magiccard.ai/docs/components/memory-fill Markdown URL: https://magiccard.ai/docs/components/memory-fill.md Summary: MagicPay Memory fill is the step where approved values are written into a target — such as a browser checkout field for card, login, identity, or confirmation — without ever entering the LLM context. Description: MagicPay Memory fill resolves and applies approved values without exposing them to LLM context. ## Canonical Answer MagicPay Memory fill is the step where approved values are written into a target — such as a browser checkout field for card, login, identity, or confirmation — without ever entering the LLM context. MagicPay Memory fill resolves and applies approved values without exposing them to LLM context. LLM-first semantic matcher maps observed fields to Memory handles and request inputs. ![Where MagicPay Memory fill applies approved values](https://magiccard.ai/docs-assets/images/components-memory-fill-flow.svg) ## Key Points - MagicPay Memory plan/apply workflow for fields the agent must not see. - LLM-first semantic matcher maps observed fields to Memory handles and request inputs. - Masks protected fields and blocks screenshots while protected values are applied. - Returns completion state to the agent, not raw secrets in model-visible context. ## Why It Exists Browser agents are vulnerable to prompt injection and visual leakage. MagicPay Memory fill enforces the MagicPay rule that protected values never enter the agent prompt, page screenshot stream, or ordinary browser action log when the user chooses the MagicPay path. ## MagicBrowse Bridge When MagicBrowse observes fillable targets, MagicPay plans against Memory descriptors and then applies the approved plan through the trusted browser writer. ```ts import { planFill, applyFill } from '@nuanu-ai/magicpay-sdk/fill-plan-apply'; // Value-free plan over observed targets, semantic matches, and the handle catalog. const plan = await planFill({ sessionId, targetSet, // fingerprint + observed fillable targets targetMatches, // LLM-first semantic field matches memoryCatalog, // handles only, no raw secrets }); // applyFill writes through your guarded targetWriter and never submits, pays, // or books. Values are materialized only inside this trusted writer. const result = await applyFill({ plan, currentTargetState: { fingerprint: targetSet.fingerprint, targets: targetSet.targets }, materializeValue, targetWriter, }); ``` ## Semantic Field Matching Field matching uses an LLM-first semantic matcher. If matching is unavailable, invalid, or uncertain, Memory fill fails closed and stops instead of guessing. ## Security Model MagicPay Memory fill is designed around a narrow guarantee: protected values do not enter the agent prompt, screenshots, action logs, or stored run records. The browser agent can tell that a protected field exists, but the value is resolved by MagicPay and applied through a guarded fill path. - Screenshots and page captures are banned while a protected value is being applied and immediately after the fill unless the runtime can guarantee masking or redaction before model ingestion. - Protected forms are masked from the agent: the model can see field purpose, target refs, labels, and status, but not passwords, card values, document numbers, OTPs, private keys, or other Memory values. - After a Memory fill, later observations, prompts, debug text, and stored run records do not echo the submitted values. - Debug and log output is redacted so it does not echo submitted values or other sensitive keys. - Memory fills use short-lived artifacts. The match and fill results carry refs, field keys, filled status, and summaries rather than raw values. - Ambiguous protected forms, missing targets, unavailable artifacts, unsupported field groups, invalid date or expiry values, and low-confidence assistive fills block instead of guessing. ## Form Masking The Memory fill path treats the form as a hard stop for the agent. MagicBrowse first observes fillable targets and submit targets, then MagicPay Memory fill builds a value-free plan from semantic field matches. After approval, values are applied directly to the target fields by the guarded writer. Follow-up observations and run records are redacted with the exact-value profile, so the agent can continue from completion state without reading back the submitted secrets. Surface | What the agent can see | What stays protected --- | --- | --- Before approval | Field purpose, label, target ref, page URL, and requested action. | Stored secret values and request artifacts. During fill | Request status and whether the protected operation is blocked, filled, or failed. | Raw artifact values and browser field contents. After fill | Filled field refs, completion state, and next required non-secret actions. | Exact submitted values in observations, logs, screenshots, and prompts. ## Operational Rules MagicPay Memory fill only works if the surrounding runtime respects the same stop rule. Browser agents should stop at login, identity, payment, and final confirmation fields, let MagicPay handle the protected values, then refresh visible page state and continue only with required non-secret fields. Final submit, purchase, booking, terms acceptance, or account changes still require the appropriate user approval. - Do not ask the user to paste protected values into chat. - Do not route request artifacts through the LLM or ordinary tool logs. - Do not fill optional newsletter, marketing, promo, survey, or analytics fields after Memory fill. - Do not submit, book, buy, accept terms, or change account data unless that exact action was approved. - Treat a compromised browser, host, or agent runtime as outside this SDK-level guarantee; MagicPay Memory fill narrows LLM exposure but cannot protect against code execution on the fill host. ## Related - MagicBrowse: https://magiccard.ai/docs/components/magicbrowse - MagicPay Memory: https://magiccard.ai/docs/components/memory - Omnichannel UI: https://magiccard.ai/docs/components/omnichannel-ui --- # Mercuryo Bridge Canonical URL: https://magiccard.ai/docs/components/mercuryo-bridge Markdown URL: https://magiccard.ai/docs/components/mercuryo-bridge.md Summary: Mercuryo Bridge is the backend connectivity layer that gives agents a simple MagicPay interface while payment operations run through Mercuryo-backed infrastructure. Description: Mercuryo Bridge connects MagicPay sessions to Mercuryo payment account, KYC, card, top-up, and transaction execution services. ## Canonical Answer Mercuryo Bridge is the backend connectivity layer that gives agents a simple MagicPay interface while payment operations run through Mercuryo-backed infrastructure. Mercuryo Bridge connects MagicPay sessions to Mercuryo payment account, KYC, card, top-up, and transaction execution services. Protected payment and identity data stays behind MagicPay requests instead of entering LLM-visible context. ![What MagicPay owns and what Mercuryo owns](https://magiccard.ai/docs-assets/images/components-mercuryo-bridge.svg) ## Key Points - Links user Mercuryo accounts through OTP and stores provider token metadata server-side. - Coordinates KYC status, questionnaire, phone, card issuance, balance, and top-up flows. - Handles provider-backed payment cards and transaction webhooks behind MagicPay requests. - Keeps provider details out of the agent contract; agents call MagicPay sessions and actions. ## Payment Connectivity Mercuryo Bridge maps MagicPay product concepts to Mercuryo-backed payment operations: account linking, KYC, card state, card balance, crypto top-up, payment account metadata, and callback-driven transaction state. Mercuryo backend and first-class support give MagicPay the payment foundation needed for the new agentic economy: reliable account infrastructure, mature card and crypto operations, provider-owned compliance workflows, and operational support behind real money movement. The agent sees MagicPay sessions and requests, while the complex provider workflows stay behind the bridge. - Reliability: payment state, card state, balance, and provider callbacks are handled by infrastructure built for live financial operations. - Coverage: card issuing, crypto top-up, KYC, payment accounts, and transaction events can be composed behind one MagicPay interface. - Separation of concerns: Mercuryo owns the regulated payment backend while MagicPay owns agent sessions, requests, routing, and user approvals. - Agent-ready abstraction: personal AI agents call MagicPay APIs instead of handling provider credentials, KYC details, card operations, or webhook semantics directly. ## Account And Card Flow A user links a Mercuryo account through OTP, completes KYC and provider prerequisites, opens or syncs a spend card, and funds the card through supported top-up routes. Provider-backed card values are then available only through approved MagicPay data or action requests. - Email OTP link and verify routes store provider token metadata. - KYC and questionnaire state are fetched from Mercuryo and mirrored into MagicPay state. - Spend-card status and balance are provider-owned and synced into payment accounts. - Webhooks update card, top-up, and transaction events through signed ingress. ## Payment Actions Agent runtimes request payment execution through MagicPay action requests. The backend validates scope, user authority, and provider-backed payment availability, then returns a reference or waits for a provider callback rather than exposing payment credentials to the agent. ```ts const actionHandle = await client.actions.run(session.id, { clientRequestId: 'checkout-payment-approval', capability: 'authorize_payment', params: { amount: 49.0, currency: 'USD', }, display: { summary: 'Confirm merchant checkout payment', }, context: { merchantName: 'Merchant Example', url: 'https://merchant.example/checkout', }, }); const actionResult = await client.actions.waitForResult(session.id, actionHandle); if (!actionResult.ok) throw new Error(actionResult.message ?? actionResult.reason); ``` ## Related - API Reference: https://magiccard.ai/docs/api - Payment Methods: https://magiccard.ai/docs/reference/payment-methods - MagicPay Memory: https://magiccard.ai/docs/components/memory --- # Omnichannel UI Canonical URL: https://magiccard.ai/docs/components/omnichannel-ui Markdown URL: https://magiccard.ai/docs/components/omnichannel-ui.md Summary: MagicPay supports a growing set of user-facing apps so agents can request approval, ask for missing data, and show progress without exposing protected values in chat. Description: Omnichannel UI gives humans cross-platform supervision and control over agent payments, choices, credentials, and approvals. ## Canonical Answer MagicPay supports a growing set of user-facing apps so agents can request approval, ask for missing data, and show progress without exposing protected values in chat. Omnichannel UI gives humans cross-platform supervision and control over agent payments, choices, credentials, and approvals. Approval and session control across web, iOS, Android, Telegram, ChatGPT, Claude, and the browser extension. ![One request delivered to the channel you choose](https://magiccard.ai/docs-assets/images/components-omnichannel-requests.svg) ## Key Points - Approval and session control across web, iOS, Android, Telegram, ChatGPT, Claude, and the browser extension. - Choice, Memory, OTP, Memory fill, and payment requests share one request flow. - Users supervise actions from their preferred channel while agents continue through a stable API. - The UI is user-friendly and agent-friendly: lower friction without removing human authority. ## Side Channel For Human Control MagicPay is backed by an omnichannel UI because agentic payments still need a side mechanism for approvals, management, choices, and reviewing saved data. The goal is to make work seamless for the agent, but some moments should leave the agent loop and return to the human: approving money movement, choosing between options, checking request details, managing MagicCard balance, or deciding whether a secret can be reused. People are already used to UI for sensitive decisions, so MagicPay lets the user choose the platform that fits the moment while the agent continues through the same backend request contract. ## Web App The web app is where you manage MagicPay. Users can review payment sessions, inspect request history, manage MagicCard state, configure request channels, edit MagicPay Memory, and see what an agent is waiting for. Use it for setup, account-level changes, and reviewing details before a higher-risk approval. ![The web app](https://magiccard.ai/docs-assets/images/omnichannel-web-app.svg) ## Mobile Apps Mobile is the fast way to approve. A user can approve a payment, answer a choice request, review a Memory fill request, or check a session while away from the desktop where the agent is running. Mobile keeps the human decision close without forcing the checkout workflow back into chat. ![iOS and Android apps](https://magiccard.ai/docs-assets/images/omnichannel-mobile-apps.svg) ## Telegram Miniapp Telegram is a lightweight request channel for users who want approvals and session updates in an app they already keep open. It is useful for quick choice requests, onboarding handoffs, secure review links, and notifications that bring the user back into MagicPay when a protected action is needed. ![Telegram mini app](https://magiccard.ai/docs-assets/images/omnichannel-telegram.svg) ## ChatGPT App The ChatGPT app puts MagicPay next to the conversation without putting protected values into the chat transcript. It can show account state, sessions, requests, and Memory summaries while keeping payment approval and secret handling on the MagicPay request path. ![ChatGPT app](https://magiccard.ai/docs-assets/images/omnichannel-chatgpt.svg) ## Claude App The Claude app follows the same model for Claude-compatible workflows. It lets users supervise MagicPay sessions and requests near the agent conversation, while raw secrets, card data, identity values, and final approvals stay inside MagicPay requests. ![Claude app](https://magiccard.ai/docs-assets/images/omnichannel-claude.svg) ## Request Types Every app wraps the same backend request model. The display differs by channel, but the agent contract stays stable: the agent creates or waits on a request, the user resolves it through a side UI, and the agent receives a safe result. The three most important request families are choices, Memory, and approvals. - Choices: Used when MagicSearch or the agent finds several viable products, providers, routes, addresses, documents, or checkout targets. The user picks the right option and can add notes that guide the next step. - Memory: Used for Memory reads, missing-field collection, and Memory writes. Passwords, identity data, card values, OTPs, and reusable checkout fields stay on the MagicPay request path instead of chat. - Approvals: Used for payment execution, protected form fill, final submit, subscription setup, account changes, and other consequential actions. The user approves the action before execution continues. ## Runtime Contract A MagicPay request stops agent execution and moves the sensitive decision to a side mechanism outside the agent. Protected form filling also happens outside the agent: MagicPay resolves the request, MagicPay Memory fill writes the data through the trusted path, and the agent only receives the result. The agent can then continue execution with safe state such as approved, denied, selected option, filled, or failed, without access to sensitive data or permission to perform untrusted actions directly. ## Related - MagicPay Memory: https://magiccard.ai/docs/components/memory - MagicPay Memory fill: https://magiccard.ai/docs/components/memory-fill - E2E Purchase Flow: https://magiccard.ai/docs/guides/e2e-purchase --- # Set Up Your Account Canonical URL: https://magiccard.ai/docs/guides/account-setup Markdown URL: https://magiccard.ai/docs/guides/account-setup.md Summary: Follow this guide when you are preparing a user account for the first real payment session. Description: Create the MagicPay account, link Mercuryo, pass KYC, fund MagicCard, connect an agent, and add Memory. ## Canonical Answer Follow this guide when you are preparing a user account for the first real payment session. Create the MagicPay account, link Mercuryo, pass KYC, fund MagicCard, connect an agent, and add Memory. Protected payment and identity data stays behind MagicPay requests instead of entering LLM-visible context. ![Account setup, step by step](https://magiccard.ai/docs-assets/images/guides-account-setup-flow.svg) ## Account Flow The user account is the authority behind agent payments. 1. Start from the MagicPay UI or send the hosted MagicPay skill prompt to your agent. 2. For landing setup, the skill asks for email, runs the setup command, and asks you for the OTP. 3. For UI-created agents, use the generated setup-token prompt; the agent should run `magicpay init ""` and then `magicpay status`. 4. Create or link the Mercuryo payment account associated with the same email. 5. Complete identity verification (KYC) in the Mercuryo verification flow opened from MagicPay. 6. Top up the MagicCard balance. Crypto top-up is available now; fiat top-up depends on the active provider route. 7. Connect one or more agents through the MagicPay skill or UI-generated setup prompt. 8. Add public facts and sensitive Memory items that will make future payment sessions smoother. Note: Done when: KYC is approved, the MagicCard shows a balance, and at least one agent is connected. ## Connect The First Agent Send the agent `Set up MagicPay from https://app.magiccard.ai/skill.md`. The installed skill verifies the CLI, runs `magicpay setup next`, handles email/OTP or existing-connection branches, and generates the top-up link when the account is ready. ## First Payment Ask the agent for a low-risk payment operation first, such as buying a coffee or completing a checkout page you already trust. Add more Memory and preferences as the agent learns your payment behavior. ## Related - Connect An Agent: https://magiccard.ai/docs/guides/connect-agent - Getting Started: https://magiccard.ai/docs/getting-started - MagicPay Components: https://magiccard.ai/docs/components --- # Connect An Agent Canonical URL: https://magiccard.ai/docs/guides/connect-agent Markdown URL: https://magiccard.ai/docs/guides/connect-agent.md Summary: Use this guide to install the MagicPay skill, let setup choose the right branch, verify status, and run the first Memory-managed workflow. Description: Connect MagicPay to a supported personal AI agent runtime and prepare the protected checkout steps. ## Canonical Answer Use this guide to install the MagicPay skill, let setup choose the right branch, verify status, and run the first Memory-managed workflow. Connect MagicPay to a supported personal AI agent runtime and prepare the protected checkout steps. Protected payment and identity data stays behind MagicPay requests instead of entering LLM-visible context. ## Before You Start You need one supported runtime where the agent can install skills or persistent instructions. A raw API key is no longer the normal first-run path for landing setup; the MagicPay skill should ask `magicpay setup next` what to do and follow the returned instructions. ## Install The Right Surface Every runtime needs the MagicPay skill for setup, Memory-managed payment, login, identity, and confirmation flows. The MagicPay CLI bundles the product workflow and installs the browser support it needs. ```ts npx skills add MercuryoAI/skills --skill magicpay --global --yes --copy magicpay --help magicpay setup next --intent landing --platform --agent-name " Agent" --api-url https://durcottggsiesxxqzvbb.supabase.co/functions/v1/api --env production ``` ## Verify Confirm the installed CLI exposes the current setup surface and that MagicPay can read the local setup state before starting a real checkout flow. 1. `magicpay --help` must include `setup next`. 2. Follow the `instructions` returned by `magicpay setup next`; do not map debug states to your own prompts. 3. After setup, run `magicpay status`. 4. Restart the runtime if newly installed skills are not visible. 5. Begin with a browser-only task, then move to a protected form such as a shipping address. Note: Done when: both commands succeed, the agent can open a page with MagicBrowse, and a MagicPay request shows up in your approval channel. ## Related - Agent Skills: https://magiccard.ai/docs/integrations/agent-skills - Claude App: https://magiccard.ai/docs/integrations/claude - ChatGPT App: https://magiccard.ai/docs/integrations/chatgpt --- # E2E Purchase Flow Canonical URL: https://magiccard.ai/docs/guides/e2e-purchase Markdown URL: https://magiccard.ai/docs/guides/e2e-purchase.md Summary: The built-in agent clarifies intent, searches providers, selects a channel, uses MagicBrowse or an agentic protocol, and raises user requests during the session. Description: How the built-in MagicPay agent turns a user payment intent into a completed purchase session. ## Canonical Answer The built-in agent clarifies intent, searches providers, selects a channel, uses MagicBrowse or an agentic protocol, and raises user requests during the session. How the built-in MagicPay agent turns a user payment intent into a completed purchase session. Protected payment and identity data stays behind MagicPay requests instead of entering LLM-visible context. ![A purchase from intent to receipt](https://magiccard.ai/docs-assets/images/guides-e2e-purchase-flow.svg) ## Flow The end-to-end purchase flow starts from a user intent and ends with a completed session or an explicit stop reason. 1. User asks the built-in agent to complete a purchase or payment intent. 2. The agent checks previous payment operations and infers the full payment prompt when possible. 3. If required data is missing, the agent asks clarifying questions. 4. MagicSearch returns ranked provider candidates with rating, geography, and payment channel availability. 5. The agent chooses a provider and channel, preferring agentic protocols, then public API/MCP, reverse API/MCP, and legacy browser checkout. 6. If no candidate is found, the agent falls back to agentic web search. 7. MagicBrowse or the selected payment protocol executes the flow while MagicPay delivers requests to the user. Note: Done when: the session reaches a completed payment, or it stops with an explicit reason you can act on. ## During The Session The user receives requests for approvals, choices, Memory reads, Memory writes, and payment confirmation through enabled channels. ## Completion The session records events, payment results, and any learned hints that can improve future purchase sessions. ## Related - MagicSearch: https://magiccard.ai/docs/components/magicsearch - MagicBrowse: https://magiccard.ai/docs/components/magicbrowse - Omnichannel UI: https://magiccard.ai/docs/components/omnichannel-ui --- # SDK Purchase Flow Canonical URL: https://magiccard.ai/docs/guides/sdk-purchase Markdown URL: https://magiccard.ai/docs/guides/sdk-purchase.md Summary: Your own agent can search, browse, and reason independently, then call MagicPay SDK to resolve a protected value or run a protected payment action. Description: How an external agent or backend calls MagicPay SDK when it reaches a payment or other protected step. ## Canonical Answer Your own agent can search, browse, and reason independently, then call MagicPay SDK to resolve a protected value or run a protected payment action. How an external agent or backend calls MagicPay SDK when it reaches a payment or other protected step. Protected payment and identity data stays behind MagicPay requests instead of entering LLM-visible context. ![Your runtime hands the protected step to MagicPay](https://magiccard.ai/docs-assets/images/guides-sdk-purchase-flow.svg) ## When To Use The SDK Use the SDK when your application already owns the surrounding agent, browser, worker, or MCP tool and needs a typed MagicPay client for sessions, requests, data resolution, and actions. ## Flow Your agent runs until it reaches a protected step — payment, login, identity, confirmation — then hands only that step to MagicPay. 1. Create or reuse a MagicPay workflow session. 2. Create a data, action, or choice request with a stable client request id. 3. Wait for user approval or supplied data. 4. Use the returned artifact only in the trusted browser or provider call. 5. Resume the agent workflow after MagicPay reports the result. Note: Done when: your agent gets a result object back — approved, denied, filled, or failed — and never sees the raw value. ## Minimal SDK Shape A typical purchase uses sessions, data resolution, action execution, and result waiting. ```ts const { session } = await client.sessions.create({ type: 'payment' }); // The agent never sees raw data; it asks for a value or a use-approval. const handle = await client.memory.createRequest(session.id, input); const result = await client.memory.waitForResult(session.id, handle); ``` ## Related - MagicPay SDK: https://magiccard.ai/docs/integrations/sdk - API Reference: https://magiccard.ai/docs/api - MagicPay Memory fill: https://magiccard.ai/docs/components/memory-fill --- # Manage Memory Canonical URL: https://magiccard.ai/docs/guides/manage-secrets Markdown URL: https://magiccard.ai/docs/guides/manage-secrets.md Summary: Saved Memory items reduce repeated questions while protected values stay behind MagicPay requests. Description: Add, approve, reuse, and update the logins, addresses, identity details, and payment data your agent needs. ## Canonical Answer Saved Memory items reduce repeated questions while protected values stay behind MagicPay requests. Add, approve, reuse, and update the logins, addresses, identity details, and payment data your agent needs. Each item holds fields; secrets are redacted from ordinary reads. ![MagicPay asking the user for a missing value](https://magiccard.ai/docs-assets/images/ui-request-provide.png) ## Key Points - Save logins, addresses, identity details, and cards once — reuse them in every session. - Each item holds fields; secrets are redacted from ordinary reads. - When a value is missing, MagicPay asks you, not the agent. - Reuse is approved per request, in the same channel as payments. ## Add Memory Before A Session Use the MagicPay app to add the data you expect agents to need: marketplace logins, delivery addresses, identity details, and travel-document information. Each record is a Memory item that holds related fields, and every field can be marked as a secret. 1. Open Memory in the web app and create a new item. 2. Give it a label you will recognize in an approval request, for example "Booking.com login". 3. Add the fields the checkout will need. Mark passwords, card numbers, and document numbers as secrets. 4. Scope the item to a site when it belongs to one merchant. ## Save Memory During A Session When the agent reaches a field with no saved value, MagicPay asks you for it instead of letting the agent ask in chat. You can store the answer for next time in the same request. ## Approve Reuse Later sessions ask for access to a stored item. You approve or deny in the same channel you use for payment approvals, and the agent gets only the result — never the value. - Keep account credentials, identity details, and payment values out of agent chat. - Scope a Memory item to one site where possible, so it is not offered on every checkout. - Review old items when a marketplace account or identity document changes. Note: Done when: the agent completes a checkout without asking you to type a password, a card number, or a document number into chat. ## Related - MagicPay Memory: https://magiccard.ai/docs/components/memory - Omnichannel UI: https://magiccard.ai/docs/components/omnichannel-ui --- # Manage Subscriptions Canonical URL: https://magiccard.ai/docs/guides/subscriptions Markdown URL: https://magiccard.ai/docs/guides/subscriptions.md Summary: Subscription purchases use a dedicated static card and store renewal and cancellation context so users can manage recurring payments in one place. Description: How MagicPay coordinates Mercuryo-backed recurring card payments through a manageable subscription interface. ## Canonical Answer Subscription purchases use a dedicated static card and store renewal and cancellation context so users can manage recurring payments in one place. How MagicPay coordinates Mercuryo-backed recurring card payments through a manageable subscription interface. Protected payment and identity data stays behind MagicPay requests instead of entering LLM-visible context. ![Subscription card: create, renew, cancel](https://magiccard.ai/docs-assets/images/guides-subscriptions-timeline.svg) ## Subscription Card When a purchase is recognized as recurring, MagicPay requests or coordinates a Mercuryo-backed static card specifically for that subscription instead of using a one-time card. ## Stored Context MagicPay stores details needed to manage the subscription later. - Merchant or provider. - Subscription purpose. - Next charge date when available. - Cancellation instructions and route. ## Renewal Reminder Before the next charge, MagicPay reminds the user so they can cancel or continue. The goal is a single App Store-like place for subscriptions created anywhere on the internet. Note: Done when: the subscription shows a next-charge date and a cancellation route you can act on from MagicPay. ## Related - MagicPay Components: https://magiccard.ai/docs/components - Payment Methods: https://magiccard.ai/docs/reference/payment-methods - Entities: https://magiccard.ai/docs/reference/entities --- # Troubleshooting Canonical URL: https://magiccard.ai/docs/guides/troubleshooting Markdown URL: https://magiccard.ai/docs/guides/troubleshooting.md Summary: Use this page when a checkout, a Memory request, a value that will not resolve, or a payment action is stuck. Description: Common MagicPay troubleshooting paths for agents, requests, Memory, Memory fill, payment execution, and Mercuryo state. ## Canonical Answer Use this page when a checkout, a Memory request, a value that will not resolve, or a payment action is stuck. Common MagicPay troubleshooting paths for agents, requests, Memory, Memory fill, payment execution, and Mercuryo state. Protected payment and identity data stays behind MagicPay requests instead of entering LLM-visible context. ![Where a stuck session is waiting](https://magiccard.ai/docs-assets/images/guides-troubleshooting-tree.svg) ## First Checks Start by separating browser progress, MagicPay request state, and provider payment state. Most failures become clear once you know which step is waiting. - Confirm the session id and client request id are stable and visible in logs. - Confirm the user has at least one enabled approval channel. - Check whether the agent is waiting on MagicSearch, MagicBrowse, a request artifact, or a provider callback. - Never retry by asking the user to paste protected values into chat. ## MagicBrowse Cannot Reach Checkout If MagicBrowse cannot reach a checkout, reduce the task to a browser-only milestone. Ask it to reach the cart, provider handoff, or visible protected step before involving MagicPay Memory fill. - Use a precise merchant URL when possible. - Prefer MagicSearch when the provider choice is ambiguous. - Treat CAPTCHA, login, and payment pages as handoff points instead of failures. ## Request Not Appearing If a request is created but not visible to the user, check request channel configuration and whether the request is scoped to the expected user, agent, and session. ## Memory Value Not Resolving If MagicPay Memory cannot resolve a value, verify the field purpose, merchant context, candidate item, and user approval path. Missing data should become a write request, not an LLM-visible chat question. ## Payment Action Stuck If a payment action is stuck, distinguish user approval from provider execution. A fulfilled request may still wait for a Mercuryo callback, webhook replay protection, or card/provider state update. ## Mercuryo Account Or Card State For Mercuryo-backed issues, check account link status, KYC status, questionnaire and phone prerequisites, spend-card issuance, balance sync, top-up transaction state, and signed webhook ingress. ## Related - MagicPay Memory fill: https://magiccard.ai/docs/components/memory-fill - Mercuryo Bridge: https://magiccard.ai/docs/components/mercuryo-bridge - API Reference: https://magiccard.ai/docs/api --- # Agent Operating Guide Canonical URL: https://magiccard.ai/docs/agents Markdown URL: https://magiccard.ai/docs/agents.md Summary: Agents should use this page as the compact source of truth for MagicPay routing, protected steps, and safe checkout behavior. Description: Machine-readable MagicPay operating rules for LLM agents, AI search, MCP clients, and coding assistants. ## Canonical Answer Agents should use this page as the compact source of truth for MagicPay routing, protected steps, and safe checkout behavior. Machine-readable MagicPay operating rules for LLM agents, AI search, MCP clients, and coding assistants. Protected payment and identity data stays behind MagicPay requests instead of entering LLM-visible context. ## Answer First MagicPay lets agents perform commerce work for a user while keeping payment authority and protected data under human control. Use MagicSearch to choose a provider, MagicBrowse to navigate legacy websites, MagicPay Memory fill for protected fields, MagicPay Memory for user-approved reusable data, Mercuryo Bridge for payment backend execution, and Omnichannel UI for user decisions. ## Routing Rules Choose the narrowest component that can safely complete the next step. Need | Use | Do not use --- | --- | --- Find a provider or checkout target | MagicSearch | Blind browser search loops Navigate ordinary website UI | MagicBrowse | Typing protected values Fill card, login, identity, or OTP fields | MagicPay Memory fill | LLM prompt context Reuse sensitive user data | MagicPay Memory request | Chat messages Ask the user to choose or approve | Omnichannel UI request | Implicit consent Execute Mercuryo-backed payment state | Mercuryo Bridge through MagicPay action | Raw provider credentials in agent code ## Sensitive Data Boundary Stop and request MagicPay help before entering passwords, card PAN, CVV, identity-document fields, OTPs, final payment confirmations, CAPTCHA/human-verification steps, or anything the user has not explicitly approved for this session. ## Discoverability Contract Agents and AI search systems should prefer the official docs URLs, the LLM index, the full text export, and the machine-readable OpenAPI JSON route over scraped marketing copy. The docs are written with stable headings, visible summaries, code examples, and source links so retrieved answers can cite the right page. - Do not treat `llms.txt` as proof of ranking or endorsement; treat it as a concise index. - Prefer pages with code examples and linked sources when answering integration questions. - Use exact component names: MagicBrowse, MagicSearch, MagicPay Memory, MagicPay Memory fill, Mercuryo Bridge, Omnichannel UI. - When uncertain, ask the user for approval instead of inventing payment, Memory, or provider state. ## Minimal Agent Prompt Use this compressed operating rule when an agent runtime needs a short instruction. ```ts Use MagicSearch for provider discovery, MagicBrowse for ordinary commerce navigation, and MagicPay requests for protected data, choices, approvals, and payments. Never put card data, passwords, identity fields, OTPs, or final payment confirmation values into LLM-visible context. Stop at protected steps and wait for MagicPay. ``` ## Related - MagicPay Components: https://magiccard.ai/docs/components - Connect An Agent: https://magiccard.ai/docs/guides/connect-agent - Troubleshooting: https://magiccard.ai/docs/guides/troubleshooting --- # Agent Skills Canonical URL: https://magiccard.ai/docs/integrations/agent-skills Markdown URL: https://magiccard.ai/docs/integrations/agent-skills.md Summary: Agent skills package the instructions, rules, and commands an AI runtime needs to use MagicPay safely. Description: Use MagicPay and MagicBrowse through runtimes that support the Agent Skill format. ## Canonical Answer Agent skills package the instructions, rules, and commands an AI runtime needs to use MagicPay safely. Use MagicPay and MagicBrowse through runtimes that support the Agent Skill format. Protected payment and identity data stays behind MagicPay requests instead of entering LLM-visible context. ## Supported Runtimes MagicPay supports OpenClaw, Hermes, Claude Code, Codex, Manus, and other agents that can read skill-style instructions and run the public CLIs. Skill bundles are published from the public GitHub repository nuanu-ai/skills. Runtime | Install path | Skills available --- | --- | --- Claude Code | Release bundles into `.claude/skills/` | MagicPay + MagicBrowse Codex | Release bundles into `~/.codex/skills/` | MagicPay + MagicBrowse OpenClaw | ClawHub install | MagicPay + MagicBrowse Hermes | nuanu-ai/skills tap | MagicPay (Hermes drives its own browser) Manus / other agents | CLIs plus persistent instructions | CLI + instructions ## Install Install the MagicPay skill first. The skill carries the setup rules, CLI repair instructions, MagicBrowse handoff behavior, and top-up guidance for first-time setup. ```ts npx skills add MercuryoAI/skills --skill magicpay --global --yes --copy ``` ## Setup Command After install, the agent should verify `magicpay --help` and run `magicpay setup next`. The returned `instructions` field is the setup plan; agents should follow it directly instead of maintaining a separate state mapping. ```ts magicpay --help magicpay setup next --intent landing --platform --agent-name " Agent" --api-url https://durcottggsiesxxqzvbb.supabase.co/functions/v1/api --env production ``` ## Runtime Rule The agent should browse and reason normally until it reaches login, identity, payment, confirmation, or CAPTCHA. At that point it should stop and call the MagicPay path instead of typing Memory values. OpenClaw and Hermes should prefer their native page-control tools when those tools can drive the same browser process; MagicBrowse remains the fallback browser controller. ## Related - Connect An Agent: https://magiccard.ai/docs/guides/connect-agent - Claude App: https://magiccard.ai/docs/integrations/claude - ChatGPT App: https://magiccard.ai/docs/integrations/chatgpt --- # MagicPay SDK Canonical URL: https://magiccard.ai/docs/integrations/sdk Markdown URL: https://magiccard.ai/docs/integrations/sdk.md Summary: The SDK is the right entry point when you own the surrounding agent, browser, or backend runtime and need MagicPay as the Memory request layer. Description: Integrate MagicPay sessions, requests, Memory, data resolution, actions, and choices from trusted TypeScript code. ## Canonical Answer The SDK is the right entry point when you own the surrounding agent, browser, or backend runtime and need MagicPay as the Memory request layer. Integrate MagicPay sessions, requests, Memory, data resolution, actions, and choices from trusted TypeScript code. Protected payment and identity data stays behind MagicPay requests instead of entering LLM-visible context. ![What each part of the SDK client does](https://magiccard.ai/docs-assets/images/integrations-sdk-client-map.svg) ## Install Use the public package in trusted Node or TypeScript runtimes. ```ts npm i @nuanu-ai/magicpay-sdk ``` ## Client Responsibilities The SDK handles communication with MagicPay. Your app still owns browser control, provider calls, UI, and what happens after a protected result is returned. Memory fill is target-agnostic by design: the same value-free flow writes an approved value into an API header, a provider SDK call, or a browser field, with MagicBrowse as the browser adapter. - Create workflow sessions. - Resolve protected field values through user-approved requests. - Run protected actions such as a payment authorization. - Ask the user to choose from runtime-provided options. - Create hosted links when a request or session needs to move back to a MagicPay-controlled UI. - Wait for request results without writing custom polling. ## Security Rule Treat request artifacts as short-lived handoff material. Do not log them, print them, store them in prompts, or give them to the LLM. ## Related - SDK Purchase Flow: https://magiccard.ai/docs/guides/sdk-purchase - API Reference: https://magiccard.ai/docs/api - MagicPay Memory fill: https://magiccard.ai/docs/components/memory-fill --- # ChatGPT App Canonical URL: https://magiccard.ai/docs/integrations/chatgpt Markdown URL: https://magiccard.ai/docs/integrations/chatgpt.md Summary: The ChatGPT app gives users a familiar place to start sessions and review payment-related state while MagicPay keeps protected values outside model context. Description: Use the MagicPay ChatGPT app to start sessions and review requests, approvals, and MagicCard state. ## Canonical Answer The ChatGPT app gives users a familiar place to start sessions and review payment-related state while MagicPay keeps protected values outside model context. Use the MagicPay ChatGPT app to start sessions and review requests, approvals, and MagicCard state. Protected payment and identity data stays behind MagicPay requests instead of entering LLM-visible context. ## What It Is For The ChatGPT app is a cross-platform MagicPay client. It can show MagicCard state, payment sessions, requests, top-up flows, and approval UI. ## MCP Role The app exposes MagicPay flows over MCP, so ChatGPT can start or continue a session while the backend keeps request handling. ## User Control Payment approvals and protected-data requests still go through MagicPay. Users may choose chat convenience for reusable Memory facts, but raw secrets and card values typed into ChatGPT are model-visible and cannot be retroactively protected by MagicPay. ## Related - Omnichannel UI: https://magiccard.ai/docs/components/omnichannel-ui - E2E Purchase Flow: https://magiccard.ai/docs/guides/e2e-purchase - Entities: https://magiccard.ai/docs/reference/entities --- # Claude App Canonical URL: https://magiccard.ai/docs/integrations/claude Markdown URL: https://magiccard.ai/docs/integrations/claude.md Summary: Claude can use MagicPay through the same MagicBrowse plus MagicPay skill model used by other supported agents. Description: Connect Claude-compatible runtimes to MagicPay through the shared agent setup flow. ## Canonical Answer Claude can use MagicPay through the same MagicBrowse plus MagicPay skill model used by other supported agents. Connect Claude-compatible runtimes to MagicPay through the shared agent setup flow. Protected payment and identity data stays behind MagicPay requests instead of entering LLM-visible context. ## Setup Model Install or paste the runtime-specific setup instructions generated by MagicPay, then verify that both MagicBrowse and MagicPay are available to the agent. ## Runtime Behavior Claude should use MagicBrowse for ordinary navigation and MagicPay for protected data, payment, identity, and confirmation steps. ## Approval Flow Requests are delivered through the user enabled channels, so the Claude chat does not need to contain sensitive payment or identity data. ## Related - Connect An Agent: https://magiccard.ai/docs/guides/connect-agent - Agent Skills: https://magiccard.ai/docs/integrations/agent-skills --- # Telegram Miniapp Canonical URL: https://magiccard.ai/docs/integrations/telegram Markdown URL: https://magiccard.ai/docs/integrations/telegram.md Summary: The Telegram miniapp delivers requests, shows approvals, hands off KYC, and keeps session work out of the chat. Description: Use the Telegram miniapp for onboarding, approvals, and secure request review. ## Canonical Answer The Telegram miniapp delivers requests, shows approvals, hands off KYC, and keeps session work out of the chat. Use the Telegram miniapp for onboarding, approvals, and secure request review. Protected payment and identity data stays behind MagicPay requests instead of entering LLM-visible context. ## What It Handles The miniapp is a helper app for Telegram users. It supports onboarding, approvals, request auto-open, KYC handoff, and secure review flows that should not stay in chat. ## Request Delivery When a payment session needs human input, Telegram can be one of the enabled channels for approvals, choices, or reviewing saved data. ## Security Rule Keep sensitive data in MagicPay requests. Telegram chat can carry convenient Memory facts, but raw secrets typed into chat are model-visible to the receiving agent path. ## Related - Omnichannel UI: https://magiccard.ai/docs/components/omnichannel-ui - Set Up Your Account: https://magiccard.ai/docs/guides/account-setup --- # Entities Canonical URL: https://magiccard.ai/docs/reference/entities Markdown URL: https://magiccard.ai/docs/reference/entities.md Summary: Use this page when you need the stable nouns used across product, SDK, API, and agent flows. Description: Reference definitions for payment sessions, requests, events, Memory, and MagicCards. ## Canonical Answer Use this page when you need the stable nouns used across product, SDK, API, and agent flows. Reference definitions for payment sessions, requests, events, Memory, and MagicCards. Protected payment and identity data stays behind MagicPay requests instead of entering LLM-visible context. ![How sessions, requests, Memory and MagicCard relate](https://magiccard.ai/docs-assets/images/reference-entities-map.svg) ## Payment Session A payment operation initiated by an agent. It groups the user intent, provider work, requests, events, payment execution state, and final outcome. ## Request The human-in-the-loop mechanism raised during session execution. Requests handle payment approvals, Memory reads and writes, purchase choices, and protected actions. ## Event A recorded step in session execution. Events make the session inspectable and help the agent or UI show progress. ## Memory item A reusable user-owned record such as a login, address, passport, or payment method that holds related fields. Fields can be open profile facts or secrets; the secret marker adds stricter handling (redaction, logging, and extra approval). ## MagicCard The user-facing payment instrument and balance abstraction that hides individual payment rails from the user. ## Related - Glossary: https://magiccard.ai/docs/glossary - API Reference: https://magiccard.ai/docs/api - Omnichannel UI: https://magiccard.ai/docs/components/omnichannel-ui --- # Payment Methods Canonical URL: https://magiccard.ai/docs/reference/payment-methods Markdown URL: https://magiccard.ai/docs/reference/payment-methods.md Summary: MagicPay hides payment method details from users while routing agent sessions through the best available rail. Description: Reference the payment channels and purchase operation types MagicPay can route for personal AI agents. ## Canonical Answer MagicPay hides payment method details from users while routing agent sessions through the best available rail. Reference the payment channels and purchase operation types MagicPay can route for personal AI agents. Protected payment and identity data stays behind MagicPay requests instead of entering LLM-visible context. ![Payment channels, best fit first](https://magiccard.ai/docs-assets/images/reference-payment-methods-ladder.svg) ## Channel Ranking MagicPay ranks payment channels by fit for the purchase and by how much browser work can be avoided. Ranking is the routing preference, not a list of shipped rails: agent-native protocols rank first because they are the least fragile, and they are used once a provider actually supports them. x402 is live today; ACP and AP2 are planned. Card payments and API paths still carry most purchases — see the status column on the MagicCard page. Rank | Channel | Use when --- | --- | --- 1 | Agent-native protocols (x402, ACP, AP2) | The provider supports a native agent payment protocol 2 | Public MCP/API | The provider exposes an official callable interface 3 | Reverse MCP/API | MagicPay can adapt to a provider flow without browser checkout 4 | Browser checkout | The purchase must happen through an ordinary website checkout ## Purchase Operation Types The same MagicCard interface supports one-time purchases, marketplace-attached cards, and recurring subscriptions. - One-time purchase: pay for goods such as tickets or website checkout items. - Marketplace purchase: attach a card to a marketplace account such as Amazon or Uber Eats. - Recurring payment: create a dedicated subscription card and manage renewals from MagicPay. ## Protocol Philosophy x402 and other agentic protocols are payment infrastructure, not user-facing complexity. The user should not need to think about the payment protocol, just as they do not think about payment rails when tapping a card. ## Related - MagicPay Components: https://magiccard.ai/docs/components - MagicSearch: https://magiccard.ai/docs/components/magicsearch - Manage Subscriptions: https://magiccard.ai/docs/guides/subscriptions --- # Trust System Canonical URL: https://magiccard.ai/docs/reference/trust-system Markdown URL: https://magiccard.ai/docs/reference/trust-system.md Summary: Agentic commerce needs trust signals across the open internet. MagicPay can store purchase outcomes, provider reputation, and flow hints after sessions. Description: How MagicPay can use provider scores, purchase outcomes, and trace-derived hints to make agent commerce safer and faster. ## Canonical Answer Agentic commerce needs trust signals across the open internet. MagicPay can store purchase outcomes, provider reputation, and flow hints after sessions. How MagicPay can use provider scores, purchase outcomes, and trace-derived hints to make agent commerce safer and faster. Protected payment and identity data stays behind MagicPay requests instead of entering LLM-visible context. ![How a finished session makes the next one faster](https://magiccard.ai/docs-assets/images/reference-trust-system-loop.svg) ## Self-Improvement After successful purchases, the system can analyze the trace and store hints that help future sessions on the same site. The goal is less time, fewer tokens, and a higher success rate. ## Provider Trust E-commerce outside marketplaces is messy. Agentic actors can maintain a shared trust layer by updating provider scores after purchase operations. ## Limits Hints and trust scores only improve ranking and navigation; they do not override live page checks, user approvals, KYC limits, payment policy, or Memory requests. ## Related - MagicSearch: https://magiccard.ai/docs/components/magicsearch - MagicBrowse: https://magiccard.ai/docs/components/magicbrowse - Payment Methods: https://magiccard.ai/docs/reference/payment-methods --- # API Reference Canonical URL: https://magiccard.ai/docs/api Markdown URL: https://magiccard.ai/docs/api.md Summary: Use this page when you need the HTTP API: integration rules and the generated OpenAPI contract in one place. Description: Public MagicPay API reference with base URL, authentication rules, scope notes, and embedded OpenAPI. ## Canonical Answer Use this page when you need the HTTP API: integration rules and the generated OpenAPI contract in one place. Public MagicPay API reference with base URL, authentication rules, scope notes, and embedded OpenAPI. Protected payment and identity data stays behind MagicPay requests instead of entering LLM-visible context. ## Overview This page is the stable entry point for developers. It keeps the human-readable integration basics close to the generated OpenAPI spec so prose and machine-readable contract stay aligned. ## Base URL All public API routes are served from the production MagicPay API base URL, `https://durcottggsiesxxqzvbb.supabase.co/functions/v1/api`. ## Authentication Authenticated routes require a bearer API key. Public routes are intentionally limited to health and schema discovery. ## Key Scopes API keys are either agent-scoped or user-scoped. Agent-scoped keys are narrower and should be used whenever the workflow belongs to one concrete agent. ## Route Groups The public API is organized around health, agent identity, workflow sessions, observability, LLM compatibility, and tooling support such as CAPTCHA. ## Schema The embedded OpenAPI section below is the automatically updated reference. Use it for exact request and response fields, and use the JSON schema route when you need the machine-readable contract directly. ## Related - MagicPay SDK: https://magiccard.ai/docs/integrations/sdk - Entities: https://magiccard.ai/docs/reference/entities - Glossary: https://magiccard.ai/docs/glossary --- # Glossary Canonical URL: https://magiccard.ai/docs/glossary Markdown URL: https://magiccard.ai/docs/glossary.md Summary: Use this page when a docs page mentions a term you do not recognize. Description: Plain-language definitions for recurring MagicPay terms used across product and developer docs. ## Canonical Answer Use this page when a docs page mentions a term you do not recognize. Plain-language definitions for recurring MagicPay terms used across product and developer docs. Protected payment and identity data stays behind MagicPay requests instead of entering LLM-visible context. ## Core Product Terms These terms describe the public MagicPay product model. Term | Meaning --- | --- MagicPay | The agent payment layer that owns sessions, requests, approvals, protected-data handling, and payment execution. MagicCard | The simple user-facing payment instrument and balance abstraction given to an agent. MagicBrowse | The commerce-specialized browser automation layer for checkout and payment flows. MagicSearch | The indexed commerce search layer used to find and rank providers. MagicPay Memory | The user-owned store for reusable data an agent can use — logins, identity, addresses, and payment methods. Often shortened to "Memory". ## Runtime Terms These terms appear in SDK, API, and agent setup docs. Term | Meaning --- | --- Runtime | The environment where the agent runs, such as Codex, Claude, OpenClaw, ChatGPT, or another supported tool. Skill | A reusable instruction bundle that tells a runtime how to use MagicPay or MagicBrowse. CLI | A command-line tool the runtime can execute after reading the skill instructions. Workflow session | One MagicPay server-side task grouping related requests and events. ## Request and Memory Terms These terms describe the human-in-the-loop and context-isolation payment model. Term | Meaning --- | --- Request | One user-facing checkpoint for an approval, a choice, a protected value, or an action. Approval | Explicit user authorization that allows a payment or another sensitive operation to continue. Artifact | The one-time result of a completed request. Memory item | A reusable user-owned record (login, identity, address, payment method) that holds related fields. Handle | An opaque reference to a stored value, materialized only inside the trusted fill path and never shown to the model. Secret | A field marked sensitive, such as a password, card number, CVV, or document number. The marker adds stricter handling — redaction, logging, and extra caution — on top of normal Memory handling. It is not a separate release path. Profile fact | Reusable open user-provided data with a flexible key, such as name, preference, or task-specific facts. Trust rule | A policy that decides whether a request can auto-resolve or must ask the user. ## Related - Entities: https://magiccard.ai/docs/reference/entities - API Reference: https://magiccard.ai/docs/api - MagicPay Memory fill: https://magiccard.ai/docs/components/memory-fill