# Payrail Agent 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. --- # Payrail Agent Docs Canonical URL: https://agent.payrail.one/docs Markdown URL: https://agent.payrail.one/docs/index.md Summary: Payrail Agent gives personal AI agents one user-authorized payment stack: Payrail Agent Card, Memory requests, and routing across browser, API, and agentic payment rails. Description: Product and developer documentation for Payrail Agent, the payment infrastructure for personal AI agents. ## Canonical Answer Payrail Agent gives personal AI agents one user-authorized payment stack: Payrail Agent Card, Memory requests, and routing across browser, API, and agentic payment rails. Product and developer documentation for Payrail Agent, the payment infrastructure for personal AI agents. Payrail Agent Card, requests, secrets, and approvals stay under the human owner's control. ![Payrail Agent overview architecture](https://agent.payrail.one/docs-assets/images/overview-architecture.svg) ## Key Points - Payment infrastructure for personal AI agents. - One user-authorized payment stack for online purchases, subscriptions, and agent-native rails. - Payrail Agent Card, requests, secrets, and approvals stay under the human owner's control. - Sensitive data is resolved inside Payrail Agent, never in LLM context. ## What Payrail Agent Is Payrail Agent 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 Payrail Agent Card with one balance. Payrail Agent Card makes payments in the complex world of agentic protocols, new payment standards, and crypto feel as simple as topping up a card. ## Payrail Agent Overview Payrail Agent 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 Payrail Agent Card interface. - Protected requests: Approvals, secrets, identity details, and payment execution move through user-controlled requests instead of model context. (https://agent.payrail.one/docs/components/memory-fill) - Commerce Routing: Payrail Agent Search finds provider-method guidance; the agent executes with built-in browser, an API, or an agentic protocol. (https://agent.payrail.one/docs/reference/payment-methods) ## Purchase Loop Every purchase is a session: the personal agent clarifies intent, Payrail Agent 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 Payrail Agent turns it into a tracked payment session with events. (https://agent.payrail.one/docs/reference/entities#payment-session) - User Authority: KYC, balance, approvals, secrets, and final confirmations stay owned by the human. (https://agent.payrail.one/docs/reference/entities#request) - Payment Execution: The session can finish through x402, MCP/API, SDK calls, or protected browser checkout. (https://agent.payrail.one/docs/guides/e2e-purchase) ## Build With Payrail Agent 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 Payrail Agent apps. - Built-In Payment Agent: Searches providers, coordinates built-in browser, ranks payment channels, and asks the user to approve each protected step. (https://agent.payrail.one/docs/guides/e2e-purchase) - Payrail Agent SDK: Bridges agents to the payment provider infrastructure and Payrail Agent backend services for sessions, auth, and preferences. (https://agent.payrail.one/docs/integrations/sdk) - Human UI: Web, mobile, ChatGPT, Claude, Telegram, and email apps handle approvals, sessions, card state, and confirmations. (https://agent.payrail.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 Payrail Agent Card balance, and connect your first agent. (https://agent.payrail.one/docs/guides/account-setup) - Understand the product: Start with Payrail Agent Card, Memory requests, built-in browser, Payrail Agent Search, and the SDK. (https://agent.payrail.one/docs/components) - Run a purchase: Follow the built-in agent purchase flow from intent discovery to provider selection and user approval. (https://agent.payrail.one/docs/guides/e2e-purchase) - Integrate the SDK: Use Payrail Agent from your own agent, worker, MCP tool, or browser runtime. (https://agent.payrail.one/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 Payrail Agent account and complete account, KYC, and balance prerequisites. 2. Connect one agent runtime and verify that Payrail Agent 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 Payrail Agent 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 Payrail Agent Search, built-in browser, approvals, and payment execution. (https://agent.payrail.one/docs/guides/e2e-purchase) - I want protected form fill: Use Payrail Agent Memory fill when the agent reaches card, login, identity, or confirmation fields. (https://agent.payrail.one/docs/components/memory-fill) - I want to integrate the SDK: Use Payrail Agent SDK when your app owns the surrounding agent or browser runtime. (https://agent.payrail.one/docs/integrations/sdk) - I want provider-backed payments: Use Payment Bridge docs for account linking, KYC, card state, top-up, and provider callbacks. (https://agent.payrail.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://agent.payrail.one/docs/agents) - Something is stuck: Use troubleshooting for checkout, request, Memory, payment, and payment provider failure modes. (https://agent.payrail.one/docs/guides/troubleshooting) ## Related - Payrail Agent Card: https://agent.payrail.one/docs/payrailAgentCard - Getting Started: https://agent.payrail.one/docs/getting-started - Payrail Agent Components: https://agent.payrail.one/docs/components - Payrail Agent SDK: https://agent.payrail.one/docs/integrations/sdk --- # Payrail Agent Card Canonical URL: https://agent.payrail.one/docs/payrailAgentCard Markdown URL: https://agent.payrail.one/docs/payrailAgentCard.md Summary: Payrail Agent Card turns agentic payments, crypto, APIs, browser checkout, and new payment protocols into one simple top-up balance. Description: Payrail Agent Card is the simple user-facing balance and payment interface for personal AI agents. ## Canonical Answer Payrail Agent Card turns agentic payments, crypto, APIs, browser checkout, and new payment protocols into one simple top-up balance. Payrail Agent Card is the simple user-facing balance and payment interface for personal AI agents. Card data and final confirmations stay behind Payrail Agent approval requests. ![Payrail Agent Card payment methods](https://agent.payrail.one/docs-assets/images/payrail-agent-card-payment-stack.svg) ## 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 Payrail Agent approval requests. ## Supported Payment Methods Payrail Agent Card is not one physical rail. It is the user-facing abstraction over the payment methods Payrail Agent 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 Payrail Agent 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 Payrail Agent Card interface as they ship. ## How Payrail Agent Chooses A Method Payrail Agent 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. - Payrail Agent Search 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. Payrail Agent Card keeps the user-facing model simple while Payrail Agent 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 Payrail Agent Card does not mean the model gets card data. Card numbers, credentials, OTPs, identity fields, and final payment confirmations stay inside Payrail Agent 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 Payrail Agent presents one simple Payrail Agent Card 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://agent.payrail.one/docs/reference/payment-methods - Payrail Agent Memory fill: https://agent.payrail.one/docs/components/memory-fill - Payment Bridge: https://agent.payrail.one/docs/components/payment-bridge - Manage Subscriptions: https://agent.payrail.one/docs/guides/subscriptions --- # Getting Started Canonical URL: https://agent.payrail.one/docs/getting-started Markdown URL: https://agent.payrail.one/docs/getting-started.md Summary: Install the Payrail Agent skill, connect the runtime to the remote MCP, then top up Payrail Agent Card before the first low-risk payment session. Description: The shortest path from a new Payrail Agent account to an agent that can complete a payment session. ## Canonical Answer Install the Payrail Agent skill, connect the runtime to the remote MCP, then top up Payrail Agent Card before the first low-risk payment session. The shortest path from a new Payrail Agent account to an agent that can complete a payment session. Protected payment and identity data stays behind Payrail Agent requests instead of entering LLM-visible context. ## Prompt-First Setup Installing and using Payrail Agent should start with one short instruction to your personal agent: install the native Payrail Agent 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 Payrail Agent Card 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 Payrail Agent. 4. Top up the Payrail Agent Card 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 Payrail Agent 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 setup flow installs the native Payrail Agent plugin, authenticates its bundled remote MCP, verifies capabilities, and then relies on remote requests whenever user approval or Memory data is needed. 1. Send the agent `Set up Payrail Agent from https://agent.payrail.one/skill.md` or use the platform-specific prompt shown by the landing page. 2. The plugin installs no package, Payrail Agent 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_payrail_agent_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 Payrail Agent requests when approval, choice, login, identity data, or payment execution is required. 8. Approve or deny requests in whichever Payrail Agent 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 Payrail Agent 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, Payrail Agent owns Memory 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 Payrail Agent Card balance. - At least one enabled request channel for approvals and confirmations. - An installed Payrail Agent 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://agent.payrail.one/docs/guides/account-setup - Connect An Agent: https://agent.payrail.one/docs/guides/connect-agent - E2E Purchase Flow: https://agent.payrail.one/docs/guides/e2e-purchase --- # Payrail Agent Components Canonical URL: https://agent.payrail.one/docs/components Markdown URL: https://agent.payrail.one/docs/components.md Summary: Payrail Agent 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 Payrail Agent component map: browser execution, commerce discovery, saved user data, payment provider connectivity, and the apps people approve from. ## Canonical Answer Payrail Agent 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 Payrail Agent 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 Payrail Agent requests instead of entering LLM context. - Components can be adopted separately or composed into the built-in payment agent. ## Component Map Payrail Agent splits the payment problem into modules with clear edges. built-in browser handles web execution. Payrail Agent Search finds relevant provider-method instructions without executing them. Payrail Agent Memory stores reusable user data. Payrail Agent Memory fill writes approved values into any target the runtime owns — an API call, a provider SDK, or a browser field. Payment Bridge connects Payrail Agent sessions to payment account, KYC, card, balance, and transaction services. Omnichannel UI keeps the human in control. - Payrail Agent Card: A single balance and payment interface your personal agent can use across provider-backed cards, crypto, swaps, and agentic rails. (https://agent.payrail.one/docs/payrailAgentCard) - Payrail Agent Fill: Exact protected-field materialization and clicks behind the host browser bridge. (https://agent.payrail.one/docs/components/payrailAgentFill) - Payrail Agent Search: Semantic provider-method lookup with URLs, official docs, and agent guidance. (https://agent.payrail.one/docs/components/payrailAgentSearch) - Payrail Agent Memory: User-owned storage for logins, identity details, payment cards, and reusable checkout fields. (https://agent.payrail.one/docs/components/memory) - Payrail Agent Memory fill: Applies user-approved values to the target — a browser field, API header, or provider call — so values never reach the LLM. (https://agent.payrail.one/docs/components/memory-fill) - Payment Bridge: Payment backend bridge for account linking, KYC, card issuance, top-up, and execution callbacks. (https://agent.payrail.one/docs/components/payment-bridge) - Omnichannel UI: Web, mobile, Telegram, ChatGPT, Claude, and browser-extension apps for approvals and supervision. (https://agent.payrail.one/docs/components/omnichannel-ui) ## End-To-End Shape A typical flow starts with user intent, optionally uses Payrail Agent Search to find provider-method guidance, then lets the agent execute through built-in browser or an API/protocol channel. Protected steps use Payrail Agent Memory and Payrail Agent Memory fill, and Omnichannel UI asks the user before payment execution proceeds. ## Related - Payrail Agent Fill: https://agent.payrail.one/docs/components/payrailAgentFill - Payrail Agent Search: https://agent.payrail.one/docs/components/payrailAgentSearch - Payrail Agent Memory fill: https://agent.payrail.one/docs/components/memory-fill --- # Payrail Agent Fill Canonical URL: https://agent.payrail.one/docs/components/payrailAgentFill Markdown URL: https://agent.payrail.one/docs/components/payrailAgentFill.md Summary: The host built-in browser analyzes the page; Payrail Agent Fill only materializes and applies exact protected values and one exact final click. Description: Payrail Agent Fill is a deliberately dumb actuator for exact protected form targets. ## Canonical Answer The host built-in browser analyzes the page; Payrail Agent Fill only materializes and applies exact protected values and one exact final click. Payrail Agent Fill is a deliberately dumb actuator for exact protected form targets. Resolves exact value-free targets before protected materialization. ![Host browser to Payrail Agent Fill contract](https://agent.payrail.one/docs-assets/images/components-payrail-agent-fill-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. Payrail Agent Fill never starts or controls a browser. ## Exact Protected Actuation The host browser supplies one stable document identity and closed exact target contracts. Payrail Agent Fill resolves every target first, then materializes and applies approved protected values without exposing them to the host agent. ```ts const { fillResolvedTargets } = await import('./scripts/payrail-agent-fill-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://agent.payrail.one/docs/guides/e2e-purchase - Agent Skills: https://agent.payrail.one/docs/integrations/agent-skills - Payrail Agent Memory fill: https://agent.payrail.one/docs/components/memory-fill --- # Payrail Agent Search Canonical URL: https://agent.payrail.one/docs/components/payrailAgentSearch Markdown URL: https://agent.payrail.one/docs/components/payrailAgentSearch.md Summary: Payrail Agent Search answers natural-language discovery questions with provider and method names, useful URLs, official documentation, and concise operating guidance. The agent performs the work. Description: Payrail Agent Search is a small semantic registry of provider methods and agent guidance. ## Canonical Answer Payrail Agent Search answers natural-language discovery questions with provider and method names, useful URLs, official documentation, and concise operating guidance. The agent performs the work. Payrail Agent Search is a small semantic registry of provider methods and agent guidance. Protected payment and identity data stays behind Payrail Agent requests instead of entering LLM-visible context. ![Provider-method semantic registry](https://agent.payrail.one/docs-assets/images/components-payrail-agent-search-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 Payrail Agent. - Payrail Agent Search does not browse, call provider APIs, or keep execution state. - Payrail Agent Search does not create choices, approvals, payment operations, or receipts. - Payrail Agent 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://agent.payrail.one/docs/guides/e2e-purchase - Payment Methods: https://agent.payrail.one/docs/reference/payment-methods - Trust System: https://agent.payrail.one/docs/reference/trust-system --- # Payrail Agent Memory Canonical URL: https://agent.payrail.one/docs/components/memory Markdown URL: https://agent.payrail.one/docs/components/memory.md Summary: Payrail Agent Memory stores user-owned items and protected fields so agents can request the right data during a workflow without seeing raw values. Description: Payrail Agent Memory is user-data storage designed specifically for personal AI agents and user-approved data use. ## Canonical Answer Payrail Agent Memory stores user-owned items and protected fields so agents can request the right data during a workflow without seeing raw values. Payrail Agent Memory is user-data storage designed specifically for personal AI agents and user-approved data use. Memory reads go through Payrail Agent requests and Payrail Agent Memory fill instead of LLM context. ![How Payrail Agent Memory is organised: identities, items, fields](https://agent.payrail.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. - Memory reads go through Payrail Agent requests and Payrail Agent Memory fill instead of LLM context. ## Agent Memory Storage Payrail Agent 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, Payrail Agent 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. Payrail Agent 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, Payrail Agent 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 Payrail Agent 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 Payrail Agent 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, Payrail Agent resolves the request, and Payrail Agent 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 Payrail Agent 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 Payrail Agent Memory is user-bound and permissioned through Payrail Agent. Memory 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: Payrail Agent 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 Payrail Agent 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 Payrail Agent 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 provider state rather than manually edited. - Artifacts should not be logged, stored in prompts, or reused after the protected step. ## Related - Manage Memory: https://agent.payrail.one/docs/guides/manage-secrets - Payrail Agent Memory fill: https://agent.payrail.one/docs/components/memory-fill - Entities: https://agent.payrail.one/docs/reference/entities --- # Payrail Agent Memory fill Canonical URL: https://agent.payrail.one/docs/components/memory-fill Markdown URL: https://agent.payrail.one/docs/components/memory-fill.md Summary: Payrail Agent 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: Payrail Agent Memory fill resolves and applies approved values without exposing them to LLM context. ## Canonical Answer Payrail Agent 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. Payrail Agent 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 Payrail Agent Memory fill applies approved values](https://agent.payrail.one/docs-assets/images/components-memory-fill-flow.svg) ## Key Points - Payrail Agent 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. Payrail Agent Memory fill enforces the Payrail Agent rule that protected values never enter the agent prompt, page screenshot stream, or ordinary browser action log when the user chooses the Payrail Agent path. ## Host Browser Bridge The host browser analyzes the form and supplies exact targets. Payrail Agent resolves protected handles and Payrail Agent Fill applies only those supplied targets. ```ts import { planFill, applyFill } from '@payrail-one/agent-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 Payrail Agent 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 Payrail Agent 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. built-in browser first observes fillable targets and submit targets, then Payrail Agent 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 Payrail Agent 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 Payrail Agent 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; Payrail Agent Memory fill narrows LLM exposure but cannot protect against code execution on the fill host. ## Related - Payrail Agent Fill: https://agent.payrail.one/docs/components/payrailAgentFill - Payrail Agent Memory: https://agent.payrail.one/docs/components/memory - Omnichannel UI: https://agent.payrail.one/docs/components/omnichannel-ui --- # Payment Bridge Canonical URL: https://agent.payrail.one/docs/components/payment-bridge Markdown URL: https://agent.payrail.one/docs/components/payment-bridge.md Summary: Payment Bridge is the backend connectivity layer that gives agents a simple Payrail Agent interface while payment operations run through provider-backed infrastructure. Description: Payment Bridge connects Payrail Agent 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 Payrail Agent interface while payment operations run through provider-backed infrastructure. Payment Bridge connects Payrail Agent sessions to the provider payment account, KYC, card, top-up, and transaction execution services. Protected payment and identity data stays behind Payrail Agent requests instead of entering LLM-visible context. ![What Payrail Agent owns and what the payment provider owns](https://agent.payrail.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 Payrail Agent requests. - Keeps provider details out of the agent contract; agents call Payrail Agent sessions and actions. ## Payment Connectivity Payment Bridge maps Payrail Agent 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 Payrail Agent 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 Payrail Agent 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 Payrail Agent interface. - Separation of concerns: the payment provider owns the regulated payment backend while Payrail Agent owns agent sessions, requests, routing, and user approvals. - Agent-ready abstraction: personal AI agents call Payrail Agent 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 Payrail Agent 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 Payrail Agent 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 Payrail Agent 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://agent.payrail.one/docs/api - Payment Methods: https://agent.payrail.one/docs/reference/payment-methods - Payrail Agent Memory: https://agent.payrail.one/docs/components/memory --- # Omnichannel UI Canonical URL: https://agent.payrail.one/docs/components/omnichannel-ui Markdown URL: https://agent.payrail.one/docs/components/omnichannel-ui.md Summary: Payrail Agent 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 Payrail Agent 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://agent.payrail.one/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 Payrail Agent 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 Payrail Agent Card balance, or deciding whether a secret can be reused. People are already used to UI for sensitive decisions, so Payrail Agent 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 Payrail Agent. Users can review payment sessions, inspect request history, manage Payrail Agent Card state, configure request channels, edit Payrail Agent 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://agent.payrail.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 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://agent.payrail.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 Payrail Agent when a protected action is needed. ![Telegram mini app](https://agent.payrail.one/docs-assets/images/omnichannel-telegram.svg) ## ChatGPT App The ChatGPT app puts Payrail Agent 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 Payrail Agent request path. ![ChatGPT app](https://agent.payrail.one/docs-assets/images/omnichannel-chatgpt.svg) ## Claude App The Claude app follows the same model for Claude-compatible workflows. It lets users supervise Payrail Agent sessions and requests near the agent conversation, while raw secrets, card data, identity values, and final approvals stay inside Payrail Agent requests. ![Claude app](https://agent.payrail.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, Memory, 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. - Memory: Used for Memory reads, missing-field collection, and Memory writes. Passwords, identity data, card values, OTPs, and reusable checkout fields stay on the Payrail Agent 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 Payrail Agent request stops agent execution and moves the sensitive decision to a side mechanism outside the agent. Protected form filling also happens outside the agent: Payrail Agent resolves the request, Payrail Agent 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 - Payrail Agent Memory: https://agent.payrail.one/docs/components/memory - Payrail Agent Memory fill: https://agent.payrail.one/docs/components/memory-fill - E2E Purchase Flow: https://agent.payrail.one/docs/guides/e2e-purchase --- # Set Up Your Account Canonical URL: https://agent.payrail.one/docs/guides/account-setup Markdown URL: https://agent.payrail.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 Payrail Agent account, link the payment account, pass KYC, fund Payrail Agent Card, 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 Payrail Agent account, link the payment account, pass KYC, fund Payrail Agent Card, connect an agent, and add Memory. Protected payment and identity data stays behind Payrail Agent requests instead of entering LLM-visible context. ![Account setup, step by step](https://agent.payrail.one/docs-assets/images/guides-account-setup-flow.svg) ## Account Flow The user account is the authority behind agent payments. 1. Start from the Payrail Agent UI or send the hosted Payrail Agent 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 Payrail Agent. 6. Top up the Payrail Agent Card balance. Crypto top-up is available now; fiat top-up depends on the active provider route. 7. Connect one or more agents through the Payrail Agent 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 Payrail Agent Card shows a balance, and at least one agent is connected. ## Connect The First Agent Send the agent `Set up Payrail Agent from https://agent.payrail.one/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 Memory and preferences as the agent learns your payment behavior. ## Related - Connect An Agent: https://agent.payrail.one/docs/guides/connect-agent - Getting Started: https://agent.payrail.one/docs/getting-started - Payrail Agent Components: https://agent.payrail.one/docs/components --- # Connect An Agent Canonical URL: https://agent.payrail.one/docs/guides/connect-agent Markdown URL: https://agent.payrail.one/docs/guides/connect-agent.md Summary: Use this guide to install the native Payrail Agent plugin, authenticate its remote MCP, verify capabilities, and run the first Memory-managed workflow. Description: Connect Payrail Agent to a supported personal AI agent runtime and prepare the protected checkout steps. ## Canonical Answer Use this guide to install the native Payrail Agent plugin, authenticate its remote MCP, verify capabilities, and run the first Memory-managed workflow. Connect Payrail Agent to a supported personal AI agent runtime and prepare the protected checkout steps. Protected payment and identity data stays behind Payrail Agent 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 Payrail Agent command. ## Install The Right Surface Install the host-native Payrail Agent plugin. It contains only the skill, the skill-shipped Payrail Agent Fill actuator, and a remote MCP declaration. The host keeps using its own built-in browser; no package, Payrail Agent 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 Payrail Agent MCP before starting a real checkout flow. 1. Call `get_payrail_agent_capabilities` through the connected remote MCP. 2. Require `client_browser`, remote database session authority, and skill-script Payrail Agent Fill 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 Payrail Agent request shows up in your approval channel. ## Related - Agent Skills: https://agent.payrail.one/docs/integrations/agent-skills - Claude App: https://agent.payrail.one/docs/integrations/claude - ChatGPT App: https://agent.payrail.one/docs/integrations/chatgpt --- # E2E Purchase Flow Canonical URL: https://agent.payrail.one/docs/guides/e2e-purchase Markdown URL: https://agent.payrail.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 Payrail Agent 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 Payrail Agent agent turns a user payment intent into a completed purchase session. Protected payment and identity data stays behind Payrail Agent requests instead of entering LLM-visible context. ![A purchase from intent to receipt](https://agent.payrail.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. Payrail Agent Search 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 Payrail Agent 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 - Payrail Agent Search: https://agent.payrail.one/docs/components/payrailAgentSearch - Payrail Agent Fill: https://agent.payrail.one/docs/components/payrailAgentFill - Omnichannel UI: https://agent.payrail.one/docs/components/omnichannel-ui --- # SDK Purchase Flow Canonical URL: https://agent.payrail.one/docs/guides/sdk-purchase Markdown URL: https://agent.payrail.one/docs/guides/sdk-purchase.md Summary: Your own agent can search, browse, and reason independently, then call Payrail Agent SDK to resolve a protected value or run a protected payment action. Description: How an external agent or backend calls Payrail Agent SDK when it reaches a payment or other protected step. ## Canonical Answer Your own agent can search, browse, and reason independently, then call Payrail Agent SDK to resolve a protected value or run a protected payment action. How an external agent or backend calls Payrail Agent SDK when it reaches a payment or other protected step. Protected payment and identity data stays behind Payrail Agent requests instead of entering LLM-visible context. ![Your runtime hands the protected step to Payrail Agent](https://agent.payrail.one/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 Payrail Agent 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 Payrail Agent. 1. Create or reuse a Payrail Agent 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 Payrail Agent 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 - Payrail Agent SDK: https://agent.payrail.one/docs/integrations/sdk - API Reference: https://agent.payrail.one/docs/api - Payrail Agent Memory fill: https://agent.payrail.one/docs/components/memory-fill --- # Manage Memory Canonical URL: https://agent.payrail.one/docs/guides/manage-secrets Markdown URL: https://agent.payrail.one/docs/guides/manage-secrets.md Summary: Saved Memory items reduce repeated questions while protected values stay behind Payrail Agent 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 Payrail Agent 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. ![Payrail Agent asking the user for a missing value](https://agent.payrail.one/docs-assets/images/request-memory.svg) ## 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, Payrail Agent asks you, not the agent. - Reuse is approved per request, in the same channel as payments. ## Add Memory Before A Session Use the Payrail Agent 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, Payrail Agent 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 - Payrail Agent Memory: https://agent.payrail.one/docs/components/memory - Omnichannel UI: https://agent.payrail.one/docs/components/omnichannel-ui --- # Manage Subscriptions Canonical URL: https://agent.payrail.one/docs/guides/subscriptions Markdown URL: https://agent.payrail.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 Payrail Agent 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 Payrail Agent coordinates provider-backed recurring card payments through a manageable subscription interface. Protected payment and identity data stays behind Payrail Agent requests instead of entering LLM-visible context. ![Subscription card: create, renew, cancel](https://agent.payrail.one/docs-assets/images/guides-subscriptions-timeline.svg) ## Subscription Card When a purchase is recognized as recurring, Payrail Agent requests or coordinates a provider-backed static card specifically for that subscription instead of using a one-time card. ## Stored Context Payrail Agent 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, Payrail Agent 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 Payrail Agent. ## Related - Payrail Agent Components: https://agent.payrail.one/docs/components - Payment Methods: https://agent.payrail.one/docs/reference/payment-methods - Entities: https://agent.payrail.one/docs/reference/entities --- # Troubleshooting Canonical URL: https://agent.payrail.one/docs/guides/troubleshooting Markdown URL: https://agent.payrail.one/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 Payrail Agent troubleshooting paths for agents, requests, Memory, Memory fill, payment execution, and payment provider 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 Payrail Agent troubleshooting paths for agents, requests, Memory, Memory fill, payment execution, and payment provider state. Protected payment and identity data stays behind Payrail Agent requests instead of entering LLM-visible context. ![Where a stuck session is waiting](https://agent.payrail.one/docs-assets/images/guides-troubleshooting-tree.svg) ## First Checks Start by separating browser progress, Payrail Agent 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 Payrail Agent Memory fill. - Use a precise merchant URL when possible. - Use Payrail Agent Search 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. ## Memory Value Not Resolving If Payrail Agent 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 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 - Payrail Agent Memory fill: https://agent.payrail.one/docs/components/memory-fill - Payment Bridge: https://agent.payrail.one/docs/components/payment-bridge - API Reference: https://agent.payrail.one/docs/api --- # Agent Operating Guide Canonical URL: https://agent.payrail.one/docs/agents Markdown URL: https://agent.payrail.one/docs/agents.md Summary: Agents should use this page as the compact source of truth for Payrail Agent routing, protected steps, and safe checkout behavior. Description: Machine-readable Payrail Agent 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 Payrail Agent routing, protected steps, and safe checkout behavior. Machine-readable Payrail Agent operating rules for LLM agents, AI search, MCP clients, and coding assistants. Protected payment and identity data stays behind Payrail Agent requests instead of entering LLM-visible context. ## Answer First Payrail Agent lets agents perform commerce work for a user while keeping payment authority and protected data under human control. Use Payrail Agent Search to find provider-method guidance, built-in browser to navigate websites, Payrail Agent Memory fill for protected fields, Payrail Agent Memory 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 | Payrail Agent Search | Treating registry guidance as execution Navigate ordinary website UI | built-in browser | Typing protected values Fill card, login, identity, or OTP fields | Payrail Agent Memory fill | LLM prompt context Reuse sensitive user data | Payrail Agent Memory request | Chat messages Ask the user to choose or approve | Omnichannel UI request | Implicit consent Execute provider-backed payment state | Payment Bridge through Payrail Agent action | Raw provider credentials in agent code ## Sensitive Data Boundary Stop and request Payrail Agent 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, Payrail Agent Search, Payrail Agent Memory, Payrail Agent Memory fill, Payment 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 Payrail Agent Search to find provider-method URLs, official docs, and guidance. Execute with your own available capability. Use built-in browser for ordinary commerce navigation and Payrail Agent 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 - Payrail Agent Components: https://agent.payrail.one/docs/components - Connect An Agent: https://agent.payrail.one/docs/guides/connect-agent - Troubleshooting: https://agent.payrail.one/docs/guides/troubleshooting --- # Agent Skills Canonical URL: https://agent.payrail.one/docs/integrations/agent-skills Markdown URL: https://agent.payrail.one/docs/integrations/agent-skills.md Summary: Agent skills package the instructions, rules, and commands an AI runtime needs to use Payrail Agent safely. Description: Use Payrail Agent 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 Payrail Agent safely. Use Payrail Agent and built-in browser through runtimes that support the Agent Skill format. Protected payment and identity data stays behind Payrail Agent requests instead of entering LLM-visible context. ## Supported Runtimes Payrail Agent 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 Payrail Agent executable or local service. Runtime | Install path | Skills available --- | --- | --- Claude Code | Native Payrail Agent plugin | Payrail Agent + built-in browser Codex | Native Payrail Agent plugin | Payrail Agent + built-in browser OpenClaw | Native Payrail Agent plugin | Payrail Agent + built-in browser Hermes | Skill plus native remote MCP | Payrail Agent (Hermes drives its own browser) Manus / other agents | Skill plus native remote MCP connection | Payrail Agent + built-in browser ## Install Install Payrail Agent through the runtime's native plugin manager. The plugin carries the skill, remote MCP declaration, built-in browser handoff behavior, and dumb Payrail Agent Fill 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_payrail_agent_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 Payrail Agent bridge with exact targets. Payrail Agent Fill never becomes a page controller and there is no fallback browser. ## Related - Connect An Agent: https://agent.payrail.one/docs/guides/connect-agent - Claude App: https://agent.payrail.one/docs/integrations/claude - ChatGPT App: https://agent.payrail.one/docs/integrations/chatgpt --- # Payrail Agent SDK Canonical URL: https://agent.payrail.one/docs/integrations/sdk Markdown URL: https://agent.payrail.one/docs/integrations/sdk.md Summary: The SDK is the right entry point when you own the surrounding agent, browser, or backend runtime and need Payrail Agent as the Memory request layer. Description: Integrate Payrail Agent 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 Payrail Agent as the Memory request layer. Integrate Payrail Agent sessions, requests, Memory, data resolution, actions, and choices from trusted TypeScript code. Protected payment and identity data stays behind Payrail Agent requests instead of entering LLM-visible context. ![What each part of the SDK client does](https://agent.payrail.one/docs-assets/images/integrations-sdk-client-map.svg) ## Install Use the public package in trusted Node or TypeScript runtimes. ```ts npm i @payrail-one/agent-sdk ``` ## Client Responsibilities The SDK handles communication with Payrail Agent. Your app still owns browser control, provider calls, UI, and what happens after a protected result is returned. For browser fields, the host adapter supplies exact targets and Payrail Agent Fill performs only protected actuation. - 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 Payrail Agent-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://agent.payrail.one/docs/guides/sdk-purchase - API Reference: https://agent.payrail.one/docs/api - Payrail Agent Memory fill: https://agent.payrail.one/docs/components/memory-fill --- # ChatGPT App Canonical URL: https://agent.payrail.one/docs/integrations/chatgpt Markdown URL: https://agent.payrail.one/docs/integrations/chatgpt.md Summary: The ChatGPT app gives users a familiar place to start sessions and review payment-related state while Payrail Agent keeps protected values outside model context. Description: Use the Payrail Agent ChatGPT app to start sessions and review requests, approvals, and Payrail Agent Card state. ## Canonical Answer The ChatGPT app gives users a familiar place to start sessions and review payment-related state while Payrail Agent keeps protected values outside model context. Use the Payrail Agent ChatGPT app to start sessions and review requests, approvals, and Payrail Agent Card state. Protected payment and identity data stays behind Payrail Agent requests instead of entering LLM-visible context. ## What It Is For The ChatGPT app is a cross-platform Payrail Agent client. It can show Payrail Agent Card state, payment sessions, requests, top-up flows, and approval UI. ## MCP Role The app exposes Payrail Agent 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 Payrail Agent. 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 Payrail Agent. ## Related - Omnichannel UI: https://agent.payrail.one/docs/components/omnichannel-ui - E2E Purchase Flow: https://agent.payrail.one/docs/guides/e2e-purchase - Entities: https://agent.payrail.one/docs/reference/entities --- # Claude App Canonical URL: https://agent.payrail.one/docs/integrations/claude Markdown URL: https://agent.payrail.one/docs/integrations/claude.md Summary: Claude can use Payrail Agent through the same built-in browser plus Payrail Agent skill model used by other supported agents. Description: Connect Claude-compatible runtimes to Payrail Agent through the shared agent setup flow. ## Canonical Answer Claude can use Payrail Agent through the same built-in browser plus Payrail Agent skill model used by other supported agents. Connect Claude-compatible runtimes to Payrail Agent through the shared agent setup flow. Protected payment and identity data stays behind Payrail Agent requests instead of entering LLM-visible context. ## Setup Model Install or paste the runtime-specific setup instructions generated by Payrail Agent, then verify that both built-in browser and Payrail Agent are available to the agent. ## Runtime Behavior Claude should use built-in browser for ordinary navigation and Payrail Agent 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://agent.payrail.one/docs/guides/connect-agent - Agent Skills: https://agent.payrail.one/docs/integrations/agent-skills --- # Telegram Miniapp Canonical URL: https://agent.payrail.one/docs/integrations/telegram Markdown URL: https://agent.payrail.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 Payrail Agent 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 Payrail Agent 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://agent.payrail.one/docs/components/omnichannel-ui - Set Up Your Account: https://agent.payrail.one/docs/guides/account-setup --- # Entities Canonical URL: https://agent.payrail.one/docs/reference/entities Markdown URL: https://agent.payrail.one/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 PayrailAgentCards. ## 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 PayrailAgentCards. Protected payment and identity data stays behind Payrail Agent requests instead of entering LLM-visible context. ![How sessions, requests, Memory and Payrail Agent Card relate](https://agent.payrail.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, 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). ## Payrail Agent Card The user-facing payment instrument and balance abstraction that hides individual payment rails from the user. ## Related - Glossary: https://agent.payrail.one/docs/glossary - API Reference: https://agent.payrail.one/docs/api - Omnichannel UI: https://agent.payrail.one/docs/components/omnichannel-ui --- # Payment Methods Canonical URL: https://agent.payrail.one/docs/reference/payment-methods Markdown URL: https://agent.payrail.one/docs/reference/payment-methods.md Summary: Payrail Agent hides payment method details from users while routing agent sessions through the best available rail. Description: Reference the payment channels and purchase operation types Payrail Agent can route for personal AI agents. ## Canonical Answer Payrail Agent hides payment method details from users while routing agent sessions through the best available rail. Reference the payment channels and purchase operation types Payrail Agent can route for personal AI agents. Protected payment and identity data stays behind Payrail Agent requests instead of entering LLM-visible context. ![Payment channels, best fit first](https://agent.payrail.one/docs-assets/images/reference-payment-methods-ladder.svg) ## Channel Ranking Payrail Agent 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 Payrail Agent Card 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 | Payrail Agent 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 Payrail Agent Card 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 Payrail Agent. ## 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 - Payrail Agent Components: https://agent.payrail.one/docs/components - Payrail Agent Search: https://agent.payrail.one/docs/components/payrailAgentSearch - Manage Subscriptions: https://agent.payrail.one/docs/guides/subscriptions --- # Trust System Canonical URL: https://agent.payrail.one/docs/reference/trust-system Markdown URL: https://agent.payrail.one/docs/reference/trust-system.md Summary: Agentic commerce needs trust signals across the open internet. Payrail Agent can store purchase outcomes, provider reputation, and flow hints after sessions. Description: How Payrail Agent 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. Payrail Agent can store purchase outcomes, provider reputation, and flow hints after sessions. How Payrail Agent can use provider scores, purchase outcomes, and trace-derived hints to make agent commerce safer and faster. Protected payment and identity data stays behind Payrail Agent requests instead of entering LLM-visible context. ![How a finished session makes the next one faster](https://agent.payrail.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 Memory requests. ## Related - Payrail Agent Search: https://agent.payrail.one/docs/components/payrailAgentSearch - Payrail Agent Fill: https://agent.payrail.one/docs/components/payrailAgentFill - Payment Methods: https://agent.payrail.one/docs/reference/payment-methods --- # API Reference Canonical URL: https://agent.payrail.one/docs/api Markdown URL: https://agent.payrail.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 Payrail Agent 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 Payrail Agent API reference with base URL, authentication rules, scope notes, and embedded OpenAPI. Protected payment and identity data stays behind Payrail Agent 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 Payrail Agent 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 - Payrail Agent SDK: https://agent.payrail.one/docs/integrations/sdk - Entities: https://agent.payrail.one/docs/reference/entities - Glossary: https://agent.payrail.one/docs/glossary --- # Public Directory Canonical URL: https://agent.payrail.one/docs/api/directory Markdown URL: https://agent.payrail.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 Payrail Agent 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 Payrail Agent Search 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; Payrail Agent 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://agent.payrail.one/docs/api - Payrail Agent Search: https://agent.payrail.one/docs/components/payrailAgentSearch - Trust System: https://agent.payrail.one/docs/reference/trust-system --- # Glossary Canonical URL: https://agent.payrail.one/docs/glossary Markdown URL: https://agent.payrail.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 Payrail Agent 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 Payrail Agent terms used across product and developer docs. Protected payment and identity data stays behind Payrail Agent requests instead of entering LLM-visible context. ## Core Product Terms These terms describe the public Payrail Agent product model. Term | Meaning --- | --- Payrail Agent | The agent payment layer that owns sessions, requests, approvals, protected-data handling, and payment execution. Payrail Agent Card | The simple user-facing payment instrument and balance abstraction given to an agent. Payrail Agent Fill | The deliberately small actuator that materializes protected values into exact targets supplied by a host browser. Payrail Agent Search | The semantic registry used to find provider-method URLs, docs, and guidance. Payrail Agent 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 Payrail Agent or built-in browser. Remote MCP | The authenticated remote tool server that owns Payrail Agent sessions, approvals, protected grants, and reconciliation. Workflow session | One Payrail Agent 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://agent.payrail.one/docs/reference/entities - API Reference: https://agent.payrail.one/docs/api - Payrail Agent Memory fill: https://agent.payrail.one/docs/components/memory-fill