# Nuncio 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. --- # Nuncio Docs Canonical URL: https://nuncio.one/docs Markdown URL: https://nuncio.one/docs/index.md Summary: Nuncio gives personal AI agents one user-authorized payment stack: MagicCard, Secrets requests, and routing across browser, API, and agentic payment rails. Description: Product and developer documentation for Nuncio, the payment infrastructure for personal AI agents. ## Canonical Answer Nuncio gives personal AI agents one user-authorized payment stack: MagicCard, Secrets requests, and routing across browser, API, and agentic payment rails. Product and developer documentation for Nuncio, the payment infrastructure for personal AI agents. MagicCard, requests, secrets, and approvals stay under the human owner's control. ![Nuncio overview architecture](https://nuncio.one/docs-assets/images/nuncio-overview-architecture.png) ## Key Points - 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 Nuncio, never in LLM context. ## What Nuncio Is Nuncio is designed to be the universal payment tool for a personal AI agent. The agent can use provider-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. ## Nuncio Overview Nuncio 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://nuncio.one/docs/components/secrets-fill) - Commerce Routing: Marketmap finds provider-method guidance; the agent executes with built-in browser, an API, or an agentic protocol. (https://nuncio.one/docs/reference/payment-methods) ## Purchase Loop Every purchase is a session: the personal agent clarifies intent, Nuncio 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 Nuncio turns it into a tracked payment session with events. (https://nuncio.one/docs/reference/entities#payment-session) - User Authority: KYC, balance, approvals, secrets, and final confirmations stay owned by the human. (https://nuncio.one/docs/reference/entities#request) - Payment Execution: The session can finish through x402, MCP/API, or the host browser for the approved checkout. (https://nuncio.one/docs/guides/e2e-purchase) ## Build With Nuncio Connect your agent through remote MCP for purchase requests, decisions and payment tracking while the host owns its native browser. - Built-In Payment Agent: Searches providers, coordinates built-in browser, ranks payment channels, and asks the user to approve each protected step. (https://nuncio.one/docs/guides/e2e-purchase) - Connect With MCP: Use the host’s native remote MCP connection, then discover the current tools and follow their returned requests. (https://nuncio.one/docs/guides/connect-agent) - Human UI: Web, mobile, ChatGPT, Claude, Telegram, and email apps handle approvals, sessions, card state, and confirmations. (https://nuncio.one/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://nuncio.one/docs/guides/account-setup) - Understand the product: Start with account readiness, Secrets requests, the host browser, discovery and current MCP tools. (https://nuncio.one/docs/components) - Run a purchase: Follow the built-in agent purchase flow from intent discovery to provider selection and user approval. (https://nuncio.one/docs/guides/e2e-purchase) - Connect With MCP: Use the host’s native remote MCP connection, then discover the current tools and follow their returned requests. (https://nuncio.one/docs/guides/connect-agent) ## 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 Nuncio account and complete account, KYC, and balance prerequisites. 2. Connect one agent runtime and verify that Nuncio and built-in browser 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 Nuncio Secrets values only after the user understands what will be stored. 6. Move to MCP, 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 Marketmap, built-in browser, approvals, and payment execution. (https://nuncio.one/docs/guides/e2e-purchase) - I want protected form fill: Use Nuncio Secrets fill when the agent reaches card, login, identity, or confirmation fields. (https://nuncio.one/docs/components/secrets-fill) - I want to connect my agent: Use the host’s native remote MCP connection, then discover the current tools and follow their returned requests. (https://nuncio.one/docs/guides/connect-agent) - I want provider-backed payments: Use Payment Bridge docs for account linking, KYC, card state, top-up, and provider callbacks. (https://nuncio.one/docs/components/payment-bridge) - I want agent-readable rules: Use the agent operating guide for machine-readable rules, routing guidance, and discovery hints. (https://nuncio.one/docs/agents) - Something is stuck: Use troubleshooting for checkout, request, Secrets, payment, and payment provider failure modes. (https://nuncio.one/docs/guides/troubleshooting) ## Related - MagicCard: https://nuncio.one/docs/magiccard - Getting Started: https://nuncio.one/docs/getting-started - Nuncio Components: https://nuncio.one/docs/components --- # MagicCard Canonical URL: https://nuncio.one/docs/magiccard Markdown URL: https://nuncio.one/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 Nuncio approval requests. ![MagicCard payment methods](https://nuncio.one/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 Nuncio approval requests. ## Supported Payment Methods MagicCard is not one physical rail. It is the user-facing abstraction over the payment methods Nuncio 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 Nuncio 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 Nuncio Chooses A Method Nuncio 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. - Marketmap guidance can inform the agent before it opens a page or calls a provider method. - 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 Nuncio 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 Nuncio 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 Nuncio 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://nuncio.one/docs/reference/payment-methods - Nuncio Secrets fill: https://nuncio.one/docs/components/secrets-fill - Payment Bridge: https://nuncio.one/docs/components/payment-bridge - Manage Subscriptions: https://nuncio.one/docs/guides/subscriptions --- # Getting Started Canonical URL: https://nuncio.one/docs/getting-started Markdown URL: https://nuncio.one/docs/getting-started.md Summary: Install the Nuncio skill, connect the runtime to the remote MCP, then top up MagicCard before the first low-risk payment session. Description: The shortest path from a new Nuncio account to an agent that can complete a payment session. ## Canonical Answer Install the Nuncio skill, connect the runtime to the remote MCP, then top up MagicCard before the first low-risk payment session. The shortest path from a new Nuncio account to an agent that can complete a payment session. Protected payment and identity data stays behind Nuncio requests instead of entering LLM-visible context. ## Prompt-First Setup Installing and using Nuncio should start with one short instruction to your personal agent: install the native Nuncio plugin described by the hosted setup page. The plugin loads the skill and remote MCP together. The remote service owns account setup, existing-connection handling, status, and top-up tools; 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 payment account for the same email. 3. Complete identity verification (KYC) in the provider verification flow opened from Nuncio. 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 Nuncio to generate a setup-token prompt for that specific agent. 7. Add useful Secrets 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 setup flow installs the native Nuncio plugin, authenticates its bundled remote MCP, verifies capabilities, and then relies on remote requests whenever user approval or Secrets data is needed. 1. Send the agent `Set up Nuncio from https://magiccard.ai/skill.md` or use the platform-specific prompt shown by the landing page. 2. The plugin installs no package, Nuncio CLI, library, browser controller, browser driver, or local service. 3. The runtime activates the plugin's bundled remote MCP endpoint and opens its browser OAuth connection page. 4. Enter the email and OTP only on that page. OTP confirmation signs in the account and authorizes the MCP connection in one flow; do not send the setup OTP through agent chat. 5. After connection succeeds, the skill calls `get_aftercard_capabilities` and uses remote account and top-up tools 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 Nuncio requests when approval, choice, login, identity data, or payment execution is required. 8. Approve or deny requests in whichever Nuncio app you prefer. 9. Review the session events after the run and save any reusable secrets or preferences that make the next session smoother. Note: Prefer the Nuncio cabinet for passwords, card numbers, passport details, OTPs, and other protected values. Chat entry can be convenient for reusable Secrets 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, Nuncio owns Secrets request handling, and the agent continues only after the required approvals or protected actions complete. - A user account with a linked payment account. - Completed KYC for the supported region. - A funded MagicCard balance. - At least one enabled request channel for approvals and confirmations. - An installed Nuncio skill plus an authenticated remote MCP connection whose capabilities report remote session authority. - A constrained first purchase that is easy to verify. ## Related - Set Up Your Account: https://nuncio.one/docs/guides/account-setup - Connect An Agent: https://nuncio.one/docs/guides/connect-agent - E2E Purchase Flow: https://nuncio.one/docs/guides/e2e-purchase --- # Nuncio Components Canonical URL: https://nuncio.one/docs/components Markdown URL: https://nuncio.one/docs/components.md Summary: Nuncio 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 Nuncio component map: browser execution, commerce discovery, saved user data, payment provider connectivity, and the apps people approve from. ## Canonical Answer Nuncio 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 Nuncio component map: browser execution, commerce discovery, saved user data, payment provider 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 Nuncio requests instead of entering LLM context. - Components can be adopted separately or composed into the built-in payment agent. ## Component Map Nuncio splits the payment problem into modules with clear edges. built-in browser handles web execution. Marketmap finds relevant provider-method instructions without executing them. Nuncio Secrets stores reusable user data. Nuncio Secrets fill writes approved values into any target the runtime owns — an API call, a provider SDK, or a browser field. Payment Bridge connects Nuncio 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 provider-backed cards, crypto, swaps, and agentic rails. (https://nuncio.one/docs/magiccard) - MagicFill: Exact protected-field materialization and clicks behind the host browser bridge. (https://nuncio.one/docs/components/magicfill) - Marketmap: Semantic provider-method lookup with URLs, official docs, and agent guidance. (https://nuncio.one/docs/components/marketmap) - Nuncio Secrets: User-owned storage for logins, identity details, payment cards, and reusable checkout fields. (https://nuncio.one/docs/components/secrets) - Nuncio Secrets fill: Applies user-approved values to the target — a browser field, API header, or provider call — so values never reach the LLM. (https://nuncio.one/docs/components/secrets-fill) - Payment Bridge: Payment backend bridge for account linking, KYC, card issuance, top-up, and execution callbacks. (https://nuncio.one/docs/components/payment-bridge) - Omnichannel UI: Web, mobile, Telegram, ChatGPT, Claude, and browser-extension apps for approvals and supervision. (https://nuncio.one/docs/components/omnichannel-ui) ## End-To-End Shape A typical flow starts with user intent, optionally uses Marketmap to find provider-method guidance, then lets the agent execute through built-in browser or an API/protocol channel. Protected steps use Nuncio Secrets and Nuncio Secrets fill, and Omnichannel UI asks the user before payment execution proceeds. ## Related - MagicFill: https://nuncio.one/docs/components/magicfill - Marketmap: https://nuncio.one/docs/components/marketmap - Nuncio Secrets fill: https://nuncio.one/docs/components/secrets-fill --- # MagicFill Canonical URL: https://nuncio.one/docs/components/magicfill Markdown URL: https://nuncio.one/docs/components/magicfill.md Summary: The host built-in browser analyzes the page; MagicFill only materializes and applies exact protected values and one exact final click. Description: MagicFill is a deliberately dumb actuator for exact protected form targets. ## Canonical Answer The host built-in browser analyzes the page; MagicFill only materializes and applies exact protected values and one exact final click. MagicFill is a deliberately dumb actuator for exact protected form targets. Resolves exact value-free targets before protected materialization. ![Host browser to MagicFill contract](https://nuncio.one/docs-assets/images/components-magicfill-handoff.svg) ## Key Points - No navigation, observation, page analysis, search, or challenge handling. - Resolves exact value-free targets before protected materialization. - Returns only target identifiers and opaque receipts. - Works behind thin Codex, Claude, OpenClaw, Hermes, and future host adapters. ## One Page-Control Owner The current agent runtime built-in browser owns navigation, observation, form analysis, ordinary values, exact target selection, and result interpretation. MagicFill never starts or controls a browser. ## Exact Protected Actuation The host browser supplies one stable document identity and closed exact target contracts. MagicFill resolves every target first, then materializes and applies approved protected values without exposing them to the host agent. ```ts const { fillResolvedTargets } = await import('./scripts/magicfill-browser.mjs'); const result = await fillResolvedTargets({ actuator: hostActuator, page, fields: resolvedProtectedFields, }); ``` ## Value-Free Receipts Fill and click results contain target identifiers, status, and opaque authority only. The host browser observes the page again and decides what the result means. ## Generic Host Contract Codex App has the concrete acceptance adapter. Claude, OpenClaw, Hermes, and future hosts implement the same narrow actuator interface and become supported only after passing the real form matrix. ## Related - E2E Purchase Flow: https://nuncio.one/docs/guides/e2e-purchase - Agent Skills: https://nuncio.one/docs/integrations/agent-skills - Nuncio Secrets fill: https://nuncio.one/docs/components/secrets-fill --- # Marketmap Canonical URL: https://nuncio.one/docs/components/marketmap Markdown URL: https://nuncio.one/docs/components/marketmap.md Summary: Marketmap answers natural-language discovery questions with provider and method names, useful URLs, official documentation, and concise operating guidance. The agent performs the work. Description: Marketmap is a small semantic registry of provider methods and agent guidance. ## Canonical Answer Marketmap answers natural-language discovery questions with provider and method names, useful URLs, official documentation, and concise operating guidance. The agent performs the work. Marketmap is a small semantic registry of provider methods and agent guidance. Protected payment and identity data stays behind Nuncio requests instead of entering LLM-visible context. ![Provider-method semantic registry](https://nuncio.one/docs-assets/images/components-marketmap-routing.svg) ## Key Points - One database row per provider and method. - Semantic search over provider, method, and guidance. - Returns up to three advisory matches with URLs and an official docs URL. - Keeps execution, browsing, authorization, and payment outside the registry. ## One Provider-Method Record Each enabled record describes one provider and one method. Actions such as paid discovery and a later purchase stay in the guidance text instead of becoming separate database rows or workflow types. ```ts type ProviderMethod = { provider: string; method: string; urls: string[]; docsUrl: string | null; guidance: string; }; ``` ## Natural-Language Search The agent sends one short natural-language query. Exact provider or method names use a deterministic name path. Other queries use one text-embedding-3-small embedding and exact pgvector cosine ordering. The registry returns the nearest three enabled methods without thresholds, pagination, or scores. ```ts const { matches } = await search_provider_methods({ query: 'find live hotel availability through a paid API', }); ``` ## Guidance, Not an Action Schema Guidance follows a simple editorial template: Purpose, Instructions, and Notes. It can explain entry points, required inputs, expected results, side effects, paid discovery, and purchase behavior. The API treats it as bounded plain text rather than parsing Markdown into another protocol. ## Agent-Owned Execution A match is a guide, not a callable capability or approval. The agent reads the official docs, chooses an available capability, supplies ordinary inputs, executes the provider method, and interprets the result. If the method becomes payable, the agent brings the exact current payment requirement to Nuncio. - Marketmap does not browse, call provider APIs, or keep execution state. - Marketmap does not create choices, approvals, payment operations, or receipts. - Nuncio remains responsible for exact payment identity, approval, settlement, and reconciliation. ## Small Operational Surface Operators edit the six public fields and enabled state in backoffice. Content changes generate a new embedding before the row is saved; URL-only edits reuse the current vector. A semantic embedding or database failure returns search_unavailable instead of silently changing the meaning of the result. - No cache, queue, retry worker, crawler, or separate search service. - No action rows, metadata JSON, ranking rules, or approximate-vector index. - Disabled drafts may omit embeddings; enabled records may not. ## Related - E2E Purchase Flow: https://nuncio.one/docs/guides/e2e-purchase - Payment Methods: https://nuncio.one/docs/reference/payment-methods - Trust System: https://nuncio.one/docs/reference/trust-system --- # Nuncio Secrets Canonical URL: https://nuncio.one/docs/components/secrets Markdown URL: https://nuncio.one/docs/components/secrets.md Summary: Secrets stores user-owned details so agents can discover suitable fields and request authorized values for the intended task. Description: Nuncio Secrets is user-data storage designed specifically for personal AI agents and user-approved data use. ## Canonical Answer Secrets stores user-owned details so agents can discover suitable fields and request authorized values for the intended task. Nuncio Secrets is user-data storage designed specifically for personal AI agents and user-approved data use. Protected payment and identity data stays behind Nuncio requests instead of entering LLM-visible context. ![How Nuncio Secrets is organised: identities, items, fields](https://nuncio.one/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. - Metadata discovery is value-free; an approved release may return task values to the host. ## Agent Secrets Storage Nuncio Secrets 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 secret, 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 SecretsItem = { 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: SecretsField[]; availability: Record; }; ``` ## Entries An entry is a reusable secret: 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, Nuncio 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 SecretsField = { 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. Nuncio Secrets 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 Secrets fill. | document_number, password ## Choice Requests When more than one entry can satisfy a request, Nuncio Secrets 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 use the current connected Secrets tools rather than direct database access. Start with value-free metadata and template discovery, select the exact fields and revisions, and follow any returned consent or secure collection request. Continue the same request after its recorded decision; Save and Use once have separate persistence outcomes. ## Authorized Task Values Discover saved metadata first, then resolve exact selected fields and current revisions through the connected Secrets workflow. An approved response may return values to the host for this task. This does not provide model or transcript isolation. - Use authorized values only for the intended form, person and role. - Keep credentials out of public replies, helper files, logs and exported evidence. - Use supported targeted native browser input for the current rendered controls. - Data-use consent does not authorize form submission or a purchase. ## Security And Storage Nuncio Secrets is user-bound and permissioned through Nuncio. Secrets records keep open metadata separate from protected values, and they can point to provider-backed records such as provider-issued payment cards instead of copying them. Identity data that comes from the KYC flow stays provider-sourced: Nuncio references the verification result rather than storing every verified field itself. Authorized requests may return values to the host; keep their use tied to the intended task and current permissions. - 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 secrets 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 Nuncio Secrets act as a secure store for ordinary checkout data now and expand toward richer personal and organizational identity graphs over time. ```ts type SecretsField = { key: string; label: string; type: 'text' | 'secret' | 'date' | 'number' | 'email' | 'url'; required: boolean; secret: boolean; semantic_tags?: string[]; }; ``` ## Save During Workflows Nuncio Secrets 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 Secrets facts can be convenient, but sensitive values belong in secrets. - Provider-backed card items are synced from provider state rather than manually edited. - Artifacts should not be logged, stored in prompts, or reused after the protected step. ## Related - Manage Secrets: https://nuncio.one/docs/guides/manage-secrets - Nuncio Secrets fill: https://nuncio.one/docs/components/secrets-fill - Entities: https://nuncio.one/docs/reference/entities --- # Nuncio Secrets fill Canonical URL: https://nuncio.one/docs/components/secrets-fill Markdown URL: https://nuncio.one/docs/components/secrets-fill.md Summary: Nuncio supplies authorized values for the intended task. The host owns rendered-page understanding, native input, challenges and the exact final approved action. Description: Resolve saved and missing details for the rendered form, then use the host’s native browser input. ## Canonical Answer Nuncio supplies authorized values for the intended task. The host owns rendered-page understanding, native input, challenges and the exact final approved action. Resolve saved and missing details for the rendered form, then use the host’s native browser input. Protected payment and identity data stays behind Nuncio requests instead of entering LLM-visible context. ![Where Nuncio Secrets fill applies approved values](https://nuncio.one/docs-assets/images/components-memory-fill-flow.svg) ## Key Points - Discover current metadata and preserve the selected field revisions. - Reuse suitable saved fields and collect only missing details through the secure request. - Authorized values may be visible to the host and model for the intended task. - Data use, Save and final submission require their own applicable authority. ## Resolve The Intended Form Inspect the rendered form and use the current get_secret_footprint, template discovery and resolve_browser_form_values schemas. Bind each field to the intended person and role, preserve suitable saved selections and collect only what is missing. ## Continue The Same Request Present the returned consent or secure collection request once. After its recorded decision, replay the original resolver identity and input as directed. Do not open a sibling request to bypass denial or a mapping error. ## Authorized Values And Native Input A successful authorized response may return task values to the host and model. Use the host’s documented targeted input for the intended tab and current rendered controls. Do not quote credentials in chat or save them in helper scripts, files, logs or exported evidence. ## Screenshots And Fresh Observation Normal screenshots support page understanding throughout the checkout, including after protected input. Re-observe after a country, payment-method or other form-revealing transition and discard stale targets. Do not export screenshots containing credentials. ## Validate And Submit Read labels, validation and totals normally. Secrets consent authorizes the intended data use, not form submission or payment. Use the exact final action only when that action and checkout are approved. After an unclear submission, observe and reconcile the same operation without another possible final click. ## Related - MagicFill: https://nuncio.one/docs/components/magicfill - Nuncio Secrets: https://nuncio.one/docs/components/secrets - Omnichannel UI: https://nuncio.one/docs/components/omnichannel-ui --- # Payment Bridge Canonical URL: https://nuncio.one/docs/components/payment-bridge Markdown URL: https://nuncio.one/docs/components/payment-bridge.md Summary: Payment Bridge is the backend connectivity layer that gives agents a simple Nuncio interface while payment operations run through provider-backed infrastructure. Description: Payment Bridge connects Nuncio sessions to the provider payment account, KYC, card, top-up, and transaction execution services. ## Canonical Answer Payment Bridge is the backend connectivity layer that gives agents a simple Nuncio interface while payment operations run through provider-backed infrastructure. Payment Bridge connects Nuncio sessions to the provider payment account, KYC, card, top-up, and transaction execution services. Protected payment and identity data stays behind Nuncio requests instead of entering LLM-visible context. ![What Nuncio owns and what the payment provider owns](https://nuncio.one/docs-assets/images/components-payment-bridge.svg) ## Key Points - Links user payment 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 Nuncio requests. - Keeps provider details out of the agent contract; agents call Nuncio sessions and actions. ## Payment Connectivity Payment Bridge maps Nuncio product concepts to provider-backed payment operations: account linking, KYC, card state, card balance, crypto top-up, payment account metadata, and callback-driven transaction state. The provider backend and first-class support give Nuncio 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 Nuncio 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 Nuncio interface. - Separation of concerns: the payment provider owns the regulated payment backend while Nuncio owns agent sessions, requests, routing, and user approvals. - Agent-ready abstraction: personal AI agents call Nuncio APIs instead of handling provider credentials, KYC details, card operations, or webhook semantics directly. ## Account And Card Flow A user links a payment 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 Nuncio data or action requests. - Email OTP link and verify routes store provider token metadata. - KYC and questionnaire state are fetched from the provider and mirrored into Nuncio 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 Nuncio 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://nuncio.one/docs/api - Payment Methods: https://nuncio.one/docs/reference/payment-methods - Nuncio Secrets: https://nuncio.one/docs/components/secrets --- # Omnichannel UI Canonical URL: https://nuncio.one/docs/components/omnichannel-ui Markdown URL: https://nuncio.one/docs/components/omnichannel-ui.md Summary: Nuncio 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 Nuncio 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, and Claude. ![One request delivered to the channel you choose](https://nuncio.one/docs-assets/images/components-omnichannel-requests.svg) ## Key Points - Approval and session control across web, iOS, Android, Telegram, ChatGPT, and Claude. - Choice, Secrets, OTP, Secrets 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 Nuncio 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 Nuncio 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 Nuncio. Users can review payment sessions, inspect request history, manage MagicCard state, configure request channels, edit Nuncio Secrets, 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://nuncio.one/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 Secrets 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://nuncio.one/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 Nuncio when a protected action is needed. ![Telegram mini app](https://nuncio.one/docs-assets/images/omnichannel-telegram.svg) ## ChatGPT App The ChatGPT app puts Nuncio next to the conversation without putting protected values into the chat transcript. It can show account state, sessions, requests, and Secrets summaries while keeping payment approval and secret handling on the Nuncio request path. ![ChatGPT app](https://nuncio.one/docs-assets/images/omnichannel-chatgpt.svg) ## Claude App The Claude app follows the same model for Claude-compatible workflows. It lets users supervise Nuncio sessions and requests near the agent conversation, while raw secrets, card data, identity values, and final approvals stay inside Nuncio requests. ![Claude app](https://nuncio.one/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, Secrets, and approvals. - Choices: Used when the agent finds several viable products, routes, addresses, documents, or checkout targets. The user picks the right option and can add notes that guide the next step. - Secrets: Used for Secrets reads, missing-field collection, and Secrets writes. Passwords, identity data, card values, OTPs, and reusable checkout fields stay on the Nuncio 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 Nuncio request stops agent execution and moves the sensitive decision to a side mechanism outside the agent. Protected form filling also happens outside the agent: Nuncio resolves the request, Nuncio Secrets 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 - Nuncio Secrets: https://nuncio.one/docs/components/secrets - Nuncio Secrets fill: https://nuncio.one/docs/components/secrets-fill - E2E Purchase Flow: https://nuncio.one/docs/guides/e2e-purchase --- # Set Up Your Account Canonical URL: https://nuncio.one/docs/guides/account-setup Markdown URL: https://nuncio.one/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 Nuncio account, link the payment account, pass KYC, fund MagicCard, connect an agent, and add Secrets. ## Canonical Answer Follow this guide when you are preparing a user account for the first real payment session. Create the Nuncio account, link the payment account, pass KYC, fund MagicCard, connect an agent, and add Secrets. Protected payment and identity data stays behind Nuncio requests instead of entering LLM-visible context. ![Account setup, step by step](https://nuncio.one/docs-assets/images/guides-account-setup-flow.svg) ## Account Flow The user account is the authority behind agent payments. 1. Start from the Nuncio UI or send the hosted Nuncio skill prompt to your agent. 2. For landing setup, paste the one-line prompt that points to the hosted `skill.md`. 3. Complete email and OTP confirmation on the runtime-native MCP OAuth page. That same confirmation authorizes the remote MCP connection. 4. Create or link the payment account associated with the same email. 5. Complete identity verification (KYC) in the provider verification flow opened from Nuncio. 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 Nuncio skill or UI-generated setup prompt. 8. Add public facts and sensitive secrets 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 Nuncio from https://magiccard.ai/skill.md`. The native plugin opens one remote MCP OAuth flow for email and OTP confirmation, then uses remote tools for capabilities, status, and top-up. ## 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 Secrets and preferences as the agent learns your payment behavior. ## Related - Connect An Agent: https://nuncio.one/docs/guides/connect-agent - Getting Started: https://nuncio.one/docs/getting-started - Nuncio Components: https://nuncio.one/docs/components --- # Connect An Agent Canonical URL: https://nuncio.one/docs/guides/connect-agent Markdown URL: https://nuncio.one/docs/guides/connect-agent.md Summary: Use this guide to install the native Nuncio plugin, authenticate its remote MCP, verify capabilities, and run the first Secrets-managed workflow. Description: Connect Nuncio to a supported personal AI agent runtime and prepare the protected checkout steps. ## Canonical Answer Use this guide to install the native Nuncio plugin, authenticate its remote MCP, verify capabilities, and run the first Secrets-managed workflow. Connect Nuncio to a supported personal AI agent runtime and prepare the protected checkout steps. Protected payment and identity data stays behind Nuncio requests instead of entering LLM-visible context. ## Before You Start You need one supported runtime where the agent can install skills or persistent instructions and connect a remote MCP server. Use the runtime's native MCP authentication flow rather than a local Nuncio command. ## Install The Right Surface Install the host-native Nuncio plugin. It contains only the skill, the skill-shipped MagicFill actuator, and a remote MCP declaration. The host keeps using its own built-in browser; no package, Nuncio CLI, library, local service, or second browser runtime is installed. ## Authenticate Once Use the MCP connection page opened by the host. Enter the email and OTP there; the same OAuth flow verifies the account, authorizes the remote MCP, and redirects to the host. Never send the setup OTP through agent chat. ## Verify Confirm the runtime can call the remote Nuncio MCP before starting a real checkout flow. 1. Call `get_aftercard_capabilities` through the connected remote MCP. 2. Require `client_browser`, remote database session authority, and skill-script MagicFill delivery. 3. Restart the runtime if newly installed skills are not visible. 4. Begin with a browser-only task, then move to a protected form such as a shipping address. Note: Done when: capabilities are available, the agent can open a page with its built-in browser, and a Nuncio request shows up in your approval channel. ## Related - Agent Skills: https://nuncio.one/docs/integrations/agent-skills - Claude App: https://nuncio.one/docs/integrations/claude - ChatGPT App: https://nuncio.one/docs/integrations/chatgpt --- # E2E Purchase Flow Canonical URL: https://nuncio.one/docs/guides/e2e-purchase Markdown URL: https://nuncio.one/docs/guides/e2e-purchase.md Summary: The built-in agent clarifies intent, searches providers, selects a channel, uses built-in browser or an agentic protocol, and raises user requests during the session. Description: How the built-in Nuncio 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 built-in browser or an agentic protocol, and raises user requests during the session. How the built-in Nuncio agent turns a user payment intent into a completed purchase session. Protected payment and identity data stays behind Nuncio requests instead of entering LLM-visible context. ![A purchase from intent to receipt](https://nuncio.one/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. Marketmap returns relevant provider methods, URLs, official docs, and operating guidance. 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. built-in browser or the selected payment protocol executes the flow while Nuncio 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, Secrets reads, Secrets 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 - Marketmap: https://nuncio.one/docs/components/marketmap - MagicFill: https://nuncio.one/docs/components/magicfill - Omnichannel UI: https://nuncio.one/docs/components/omnichannel-ui --- # Manage Secrets Canonical URL: https://nuncio.one/docs/guides/manage-secrets Markdown URL: https://nuncio.one/docs/guides/manage-secrets.md Summary: Saved secrets reduce repeated questions while protected values stay behind Nuncio requests. Description: Add, approve, reuse, and update the logins, addresses, identity details, and payment data your agent needs. ## Canonical Answer Saved secrets reduce repeated questions while protected values stay behind Nuncio 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. ![Nuncio asking the user for a missing value](https://nuncio.one/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, Nuncio asks you, not the agent. - Reuse is approved per request, in the same channel as payments. ## Add Secrets Before A Session Use the Nuncio app to add the data you expect agents to need: marketplace logins, delivery addresses, identity details, and travel-document information. Each record is a secret that holds related fields, and every field can be marked as a secret. 1. Open Secrets 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 Secrets During A Session When the agent reaches a field with no saved value, Nuncio 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 secret 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 - Nuncio Secrets: https://nuncio.one/docs/components/secrets - Omnichannel UI: https://nuncio.one/docs/components/omnichannel-ui --- # Manage Subscriptions Canonical URL: https://nuncio.one/docs/guides/subscriptions Markdown URL: https://nuncio.one/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 Nuncio coordinates provider-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 Nuncio coordinates provider-backed recurring card payments through a manageable subscription interface. Protected payment and identity data stays behind Nuncio requests instead of entering LLM-visible context. ![Subscription card: create, renew, cancel](https://nuncio.one/docs-assets/images/guides-subscriptions-timeline.svg) ## Subscription Card When a purchase is recognized as recurring, Nuncio requests or coordinates a provider-backed static card specifically for that subscription instead of using a one-time card. ## Stored Context Nuncio 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, Nuncio 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 Nuncio. ## Related - Nuncio Components: https://nuncio.one/docs/components - Payment Methods: https://nuncio.one/docs/reference/payment-methods - Entities: https://nuncio.one/docs/reference/entities --- # Troubleshooting Canonical URL: https://nuncio.one/docs/guides/troubleshooting Markdown URL: https://nuncio.one/docs/guides/troubleshooting.md Summary: Use this page when a checkout, a Secrets request, a value that will not resolve, or a payment action is stuck. Description: Common Nuncio troubleshooting paths for agents, requests, Secrets, Secrets fill, payment execution, and payment provider state. ## Canonical Answer Use this page when a checkout, a Secrets request, a value that will not resolve, or a payment action is stuck. Common Nuncio troubleshooting paths for agents, requests, Secrets, Secrets fill, payment execution, and payment provider state. Protected payment and identity data stays behind Nuncio requests instead of entering LLM-visible context. ![Where a stuck session is waiting](https://nuncio.one/docs-assets/images/guides-troubleshooting-tree.svg) ## First Checks Start by separating browser progress, Nuncio 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 provider execution, built-in browser, a request artifact, or a provider callback. - Never retry by asking the user to paste protected values into chat. ## built-in browser Cannot Reach Checkout If built-in browser 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 Nuncio Secrets fill. - Use a precise merchant URL when possible. - Use Marketmap when the agent needs provider-method guidance. - 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. ## Secrets Value Not Resolving If Nuncio Secrets 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 provider callback, webhook replay protection, or card/provider state update. ## Payment Account Or Card State For provider-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 - Nuncio Secrets fill: https://nuncio.one/docs/components/secrets-fill - Payment Bridge: https://nuncio.one/docs/components/payment-bridge - API Reference: https://nuncio.one/docs/api --- # Agent Operating Guide Canonical URL: https://nuncio.one/docs/agents Markdown URL: https://nuncio.one/docs/agents.md Summary: Agents should use this page as the compact source of truth for Nuncio routing, protected steps, and safe checkout behavior. Description: Machine-readable Nuncio 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 Nuncio routing, protected steps, and safe checkout behavior. Machine-readable Nuncio operating rules for LLM agents, AI search, MCP clients, and coding assistants. Protected payment and identity data stays behind Nuncio requests instead of entering LLM-visible context. ## Answer First Nuncio lets agents perform commerce work for a user while keeping payment authority and protected data under human control. Use Marketmap to find provider-method guidance, built-in browser to navigate websites, Nuncio Secrets fill for protected fields, Nuncio Secrets for user-approved reusable data, Payment 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 provider-method instructions | Marketmap | Treating registry guidance as execution Navigate ordinary website UI | built-in browser | Typing protected values Fill card, login, identity, or OTP fields | Nuncio Secrets fill | LLM prompt context Reuse sensitive user data | Nuncio Secrets request | Chat messages Ask the user to choose or approve | Omnichannel UI request | Implicit consent Execute provider-backed payment state | Payment Bridge through Nuncio action | Raw provider credentials in agent code ## Sensitive Data Boundary Stop and request Nuncio 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: built-in browser, Marketmap, Nuncio Secrets, Nuncio Secrets fill, Payment Bridge, Omnichannel UI. - When uncertain, ask the user for approval instead of inventing payment, Secrets, or provider state. ## Minimal Agent Prompt Use this compressed operating rule when an agent runtime needs a short instruction. ```ts Use Marketmap to find provider-method URLs, official docs, and guidance. Execute with your own available capability. Use built-in browser for ordinary commerce navigation and Nuncio 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. ``` ## Related - Nuncio Components: https://nuncio.one/docs/components - Connect An Agent: https://nuncio.one/docs/guides/connect-agent - Troubleshooting: https://nuncio.one/docs/guides/troubleshooting --- # Agent Skills Canonical URL: https://nuncio.one/docs/integrations/agent-skills Markdown URL: https://nuncio.one/docs/integrations/agent-skills.md Summary: Agent skills package the instructions, rules, and commands an AI runtime needs to use Nuncio safely. Description: Use Nuncio and built-in browser through runtimes that support the Agent Skill format. ## Canonical Answer Agent skills package the instructions, rules, and commands an AI runtime needs to use Nuncio safely. Use Nuncio and built-in browser through runtimes that support the Agent Skill format. Protected payment and identity data stays behind Nuncio requests instead of entering LLM-visible context. ## Supported Runtimes Nuncio supports OpenClaw, Hermes, Claude Code, Codex, Manus, and other agents that can load a skill and connect a remote MCP server. Native host plugins bundle both pieces so installation does not add a Nuncio executable or local service. Runtime | Install path | Skills available --- | --- | --- Claude Code | Native Nuncio plugin | Nuncio + built-in browser Codex | Native Nuncio plugin | Nuncio + built-in browser OpenClaw | Native Nuncio plugin | Nuncio + built-in browser Hermes | Skill plus native remote MCP | Nuncio (Hermes drives its own browser) Manus / other agents | Skill plus native remote MCP connection | Nuncio + built-in browser ## Install Install Nuncio through the runtime's native plugin manager. The plugin carries the skill, remote MCP declaration, built-in browser handoff behavior, and dumb MagicFill actuator. It installs no packages, CLIs, libraries, browser drivers, or local servers. ## Connect The Remote MCP After install, authenticate the remote endpoint bundled by the plugin and call `get_aftercard_capabilities`. The runtime keeps no local workflow mapping. ## Runtime Rule The agent uses its built-in browser for every page step, including ordinary form fill and challenge handling. At a protected field, it calls the Nuncio bridge with exact targets. MagicFill never becomes a page controller and there is no fallback browser. ## Related - Connect An Agent: https://nuncio.one/docs/guides/connect-agent - Claude App: https://nuncio.one/docs/integrations/claude - ChatGPT App: https://nuncio.one/docs/integrations/chatgpt --- # ChatGPT App Canonical URL: https://nuncio.one/docs/integrations/chatgpt Markdown URL: https://nuncio.one/docs/integrations/chatgpt.md Summary: The ChatGPT app gives users a familiar place to start sessions and review payment-related state while Nuncio keeps protected values outside model context. Description: Use the Nuncio 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 Nuncio keeps protected values outside model context. Use the Nuncio ChatGPT app to start sessions and review requests, approvals, and MagicCard state. Protected payment and identity data stays behind Nuncio requests instead of entering LLM-visible context. ## What It Is For The ChatGPT app is a cross-platform Nuncio client. It can show MagicCard state, payment sessions, requests, top-up flows, and approval UI. ## MCP Role The app exposes Nuncio 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 Nuncio. Users may choose chat convenience for reusable Secrets facts, but raw secrets and card values typed into ChatGPT are model-visible and cannot be retroactively protected by Nuncio. ## Related - Omnichannel UI: https://nuncio.one/docs/components/omnichannel-ui - E2E Purchase Flow: https://nuncio.one/docs/guides/e2e-purchase - Entities: https://nuncio.one/docs/reference/entities --- # Claude App Canonical URL: https://nuncio.one/docs/integrations/claude Markdown URL: https://nuncio.one/docs/integrations/claude.md Summary: Claude can use Nuncio through the same built-in browser plus Nuncio skill model used by other supported agents. Description: Connect Claude-compatible runtimes to Nuncio through the shared agent setup flow. ## Canonical Answer Claude can use Nuncio through the same built-in browser plus Nuncio skill model used by other supported agents. Connect Claude-compatible runtimes to Nuncio through the shared agent setup flow. Protected payment and identity data stays behind Nuncio requests instead of entering LLM-visible context. ## Setup Model Install or paste the runtime-specific setup instructions generated by Nuncio, then verify that both built-in browser and Nuncio are available to the agent. ## Runtime Behavior Claude should use built-in browser for ordinary navigation and Nuncio 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://nuncio.one/docs/guides/connect-agent - Agent Skills: https://nuncio.one/docs/integrations/agent-skills --- # Telegram Miniapp Canonical URL: https://nuncio.one/docs/integrations/telegram Markdown URL: https://nuncio.one/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 Nuncio 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 Nuncio requests. Telegram chat can carry convenient Secrets facts, but raw secrets typed into chat are model-visible to the receiving agent path. ## Related - Omnichannel UI: https://nuncio.one/docs/components/omnichannel-ui - Set Up Your Account: https://nuncio.one/docs/guides/account-setup --- # Entities Canonical URL: https://nuncio.one/docs/reference/entities Markdown URL: https://nuncio.one/docs/reference/entities.md Summary: Use this page when you need the stable nouns used across product, API, and agent flows. Description: Reference definitions for payment sessions, requests, events, Secrets, and MagicCards. ## Canonical Answer Use this page when you need the stable nouns used across product, API, and agent flows. Reference definitions for payment sessions, requests, events, Secrets, and MagicCards. Protected payment and identity data stays behind Nuncio requests instead of entering LLM-visible context. ![How sessions, requests, Secrets and MagicCard relate](https://nuncio.one/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, Secrets 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. ## secret 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://nuncio.one/docs/glossary - API Reference: https://nuncio.one/docs/api - Omnichannel UI: https://nuncio.one/docs/components/omnichannel-ui --- # Payment Methods Canonical URL: https://nuncio.one/docs/reference/payment-methods Markdown URL: https://nuncio.one/docs/reference/payment-methods.md Summary: Nuncio hides payment method details from users while routing agent sessions through the best available rail. Description: Reference the payment channels and purchase operation types Nuncio can route for personal AI agents. ## Canonical Answer Nuncio hides payment method details from users while routing agent sessions through the best available rail. Reference the payment channels and purchase operation types Nuncio can route for personal AI agents. Protected payment and identity data stays behind Nuncio requests instead of entering LLM-visible context. ![Payment channels, best fit first](https://nuncio.one/docs-assets/images/reference-payment-methods-ladder.svg) ## Channel Ranking Nuncio 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 | Nuncio 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 Nuncio. ## 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 - Nuncio Components: https://nuncio.one/docs/components - Marketmap: https://nuncio.one/docs/components/marketmap - Manage Subscriptions: https://nuncio.one/docs/guides/subscriptions --- # Trust System Canonical URL: https://nuncio.one/docs/reference/trust-system Markdown URL: https://nuncio.one/docs/reference/trust-system.md Summary: Agentic commerce needs trust signals across the open internet. Nuncio can store purchase outcomes, provider reputation, and flow hints after sessions. Description: How Nuncio 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. Nuncio can store purchase outcomes, provider reputation, and flow hints after sessions. How Nuncio can use provider scores, purchase outcomes, and trace-derived hints to make agent commerce safer and faster. Protected payment and identity data stays behind Nuncio requests instead of entering LLM-visible context. ![How a finished session makes the next one faster](https://nuncio.one/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 Secrets requests. ## Related - Marketmap: https://nuncio.one/docs/components/marketmap - MagicFill: https://nuncio.one/docs/components/magicfill - Payment Methods: https://nuncio.one/docs/reference/payment-methods --- # API Reference Canonical URL: https://nuncio.one/docs/api Markdown URL: https://nuncio.one/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 Nuncio 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 Nuncio API reference with base URL, authentication rules, scope notes, and embedded OpenAPI. Protected payment and identity data stays behind Nuncio 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 Nuncio API base URL, `https://pdunymeeorxrooaxznwt.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 - Entities: https://nuncio.one/docs/reference/entities - Glossary: https://nuncio.one/docs/glossary --- # Public Directory Canonical URL: https://nuncio.one/docs/api/directory Markdown URL: https://nuncio.one/docs/api/directory.md Summary: Use this page when an agent or a page needs to find sellers without an account: natural-language search, the filterable list, one provider method with its guidance, and the trust record behind a hostname. Description: Open, key-less HTTP directory of sellers with an advisory trust verdict on every listing. ## Canonical Answer Use this page when an agent or a page needs to find sellers without an account: natural-language search, the filterable list, one provider method with its guidance, and the trust record behind a hostname. Open, key-less HTTP directory of sellers with an advisory trust verdict on every listing. Protected payment and identity data stays behind Nuncio requests instead of entering LLM-visible context. ## Key Points - No API key, account, or login: the same access model as x402 Bazaar. - The same natural-language search the signed-in tool runs, joined to trust. - Every listing carries a verdict; purchase statistics publish only above a floor. - Read-only. Nothing on this surface probes a seller, writes, or pays. ## Endpoints Four GET routes under the API base URL from the API Reference page. Responses are JSON, cacheable for five minutes, and answer every browser origin. ```ts GET /api/public/v1/services?q=find+live+hotel+availability GET /api/public/v1/services?category=data&verdict=proceed&payable=true GET /api/public/v1/services/{slug} GET /api/public/v1/merchants/{hostname} ``` ## Search and List With `q`, the directory runs the internal Marketmap ranking unchanged: an exact provider or method name resolves directly, anything else is embedded once and the nearest three enabled methods within the similarity band are returned. Without `q`, the full enabled list is returned with `category`, `verdict`, `kind`, `payable`, `hostname` and `limit` filters plus category facets. List items omit `guidance`; the slug route returns it in full. ## Trust Block Each item carries `trust`: the verdict, score, probe outcome and age, the network, asset and price the seller advertised on the last probe, and any operator override. It is advisory. A verdict never authorizes a payment; Nuncio approval does. `stats` holds settled-payment counts and the delivery rate for the hostname and is `null` below five settled payments. ## Limits Search is rate-limited per caller and by a daily allowance because each novel query costs one embedding. A limited caller receives 429 and an exhausted allowance receives 503, both with `Retry-After`; the plain list keeps working. Queries are capped at 1024 UTF-8 bytes. ## Reserved Filter The `verified` parameter is reserved for the Verified badge, which does not exist yet; requests carrying it are rejected with 400 so nothing can silently mean less than it says. Use `verdict=proceed` for the closest current filter. ## Related - API Reference: https://nuncio.one/docs/api - Marketmap: https://nuncio.one/docs/components/marketmap - Trust System: https://nuncio.one/docs/reference/trust-system --- # Glossary Canonical URL: https://nuncio.one/docs/glossary Markdown URL: https://nuncio.one/docs/glossary.md Summary: Use this page when a docs page mentions a term you do not recognize. Description: Plain-language definitions for recurring Nuncio 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 Nuncio terms used across product and developer docs. Protected payment and identity data stays behind Nuncio requests instead of entering LLM-visible context. ## Core Product Terms These terms describe the public Nuncio product model. Term | Meaning --- | --- Nuncio | 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. MagicFill | The deliberately small actuator that materializes protected values into exact targets supplied by a host browser. Marketmap | The semantic registry used to find provider-method URLs, docs, and guidance. Nuncio Secrets | The user-owned store for reusable data an agent can use — logins, identity, addresses, and payment methods. Often shortened to "Secrets". ## Runtime Terms These terms appear in MCP, 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 Nuncio or built-in browser. Remote MCP | The authenticated remote tool server that owns Nuncio sessions, approvals, protected grants, and reconciliation. Workflow session | One Nuncio server-side task grouping related requests and events. ## Request and Secrets 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. secret | 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 Secrets 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://nuncio.one/docs/reference/entities - API Reference: https://nuncio.one/docs/api - Nuncio Secrets fill: https://nuncio.one/docs/components/secrets-fill