Introduction

AI agents already navigate catalogs, assemble carts, and execute purchases; what’s missing is a universal, merchant-controlled interface. The Open Agentic Commerce API defines that interface. It standardizes how agents and services discover a merchant’s capabilities, retrieve products and offers, create orders with deterministic totals (items, tax, shipping, discounts), and settle payments across existing and emerging rails—while preserving merchant security, policy, and brand.

This specification meets merchants where they are. A .well-known Manifest publishes endpoints and policies; Schema.org–aligned data ensures interoperable product and order semantics; order creation returns the full payable amount before settlement; a unified pay endpoint connects to current processors and agent-native rails; and modular authentication maps precise methods to each endpoint. The result is a predictable contract that reduces bespoke integration work, improves observability and control, and accelerates time-to-live for new channels.

What this spec defines:

• Manifest — a single source of truth for endpoints, schemas, payments, and auth.

• Product Discovery — a stable, machine-readable catalog model for products and offers.

• Orders — a two-step flow that computes complete totals and establishes state.

• Payment Processing — a unified surface that routes to the merchant’s chosen rails.

• Authentication & Authorization — explicit, per-endpoint requirements and options.

See How to View for a stakeholder-focused reading guide (merchants, agents, platforms, and aggregators) and the specific value each derives from adopting this contract.

Market Problems

1) Fragmented discovery & brittle integrations

Today, agents have no predictable way to know if a merchant is “agent-ready.” They’re forced to scrape HTML, reverse-engineer flows, or stumble across one-off APIs. Even when a Product Catalog or Checkout API exists, they’re not discoverable, so agents default to brittle, high-maintenance integrations that break on site changes and deliver poor consumer experiences.

2) Inconsistent product semantics

Merchants and platforms model products in conflicting ways: some split every variant into separate SKUs, others nest attributes like color or gender inside SKUs, and some expose only minimal metadata. Agents can’t reliably interpret what is being sold, which cascades into cart building, enrichment, search, and fulfillment. Without a standard schema, misidentification and transaction errors are inevitable.

3) Checkout opacity & brittleness

Pricing is opaque - taxes, shipping, and discounts may appear only at the last UI step, and every merchant represents them differently. Agents are forced to guess at totals and often get them wrong. At the same time, “headless checkout” usually means replaying fragile browser calls that break with minor UI or bot-defense changes. There’s no stable, programmatic contract to create an order, compute a final price, and pay reliably.

4) Authentication, consent & agent trust gaps

Current systems assume a human in session. Agents lack portable ways to prove identity, delegation, or spending scope. Merchants can’t tell a trusted agent acting on behalf of a user from a generic bot, so they block traffic or misclassify it. Fraud and bot defenses operate on crude “good vs. bad” heuristics, without upstream signals about consent or intent. The result is that legitimate commerce is throttled alongside abuse.

5) Payments & operational fragmentation

Payments are fragmented across cards, wallets, local APMs, and multiple processors—each with different APIs and contracts. This causes a high degree of brittleness when integrating with payment methods, making payment failures a common issue among Agents.

There is also the risk that new agentic platforms will impose entirely new catalogs, settlement rails, chargeback processes, and fraud models. Merchants end up running parallel systems: two catalogs to maintain, two fraud stacks to tune, and two sets of disputes to reconcile. Instead of lowering costs, ownership explodes.

6) Long-tail merchant readiness

Tens of thousands of merchants have only HTML storefronts, with no APIs, catalog feeds, or checkout endpoints. Without a clear uplift path, they’re locked out of agent-driven channels. Scraping is brittle and non-compliant, but replatforming is unrealistic. A manifest-first onboarding path with lightweight adapters is the only way to include the long tail in this ecosystem.

7) Compliance & data minimization

In the absence of standardized APIs, agents fall back to browser automation that often touches raw cardholder data and PII. This creates massive PCI, privacy, and governance risk—PANs flow where they don’t belong, consent is murky, and compliance scope balloons. Merchants and platforms need tokenization, encrypted payloads, and standard pay surfaces so sensitive data stays with processors, not scattered across agents.

Practical Outcomes by Audience

Merchants

Treat this as your direct path to agent-driven sales without replatforming. You expose a single, predictable interface on top of what you already run, keeping complete control of pricing, inventory, fraud rules, and brand. The spec lowers integration cost for partners, opens new acquisition channels, and lets you turn on richer automation (quotes, carts, and fulfillment) at your pace with clear guardrails.

Agents

This gives you one consistent contract to discover products, assemble orders, and settle transactions across many merchants. You integrate once, get clean, machine-readable data, and transact with deterministic totals and clear outcomes. Fewer bespoke adapters, fewer edge cases, faster time-to-live, so you can focus on user experience instead of chasing one-off integrations.

E-commerce platforms

For e-commerce platforms, a repeatable path to enable agentic commerce for every merchant without guesswork or one-off builds or plugin support. You publish one documented, versioned interface and a consistent discovery point; agents use discoverability and work across all stores. Internally, this interface maps to existing architectures, creating a smooth merchant onboarding experience.

Product/checkout aggregators

This provides a common language to ingest catalogs, normalize offers, and orchestrate checkout across many sources. You accelerate time-to-coverage, improve accuracy with consistent schemas, and simplify payment and order status handling behind a single pattern. That means higher conversion, lower operational overhead, and easier expansion into new categories and regions.

Integration Optionality

Protocol Layering & Compatibility (AP2, MCP, APIs, etc)

This whitepaper defines a merchant-controlled contract—manifest, schemas, order/pay semantics, and auth—that agent ecosystems can consume over multiple communication protocols. It is complementary, not competitive: protocols like AP2 and MCP describe how agents communicate with some structure; this spec defines what they discover and how commerce flows behave. A single manifest is the stable boundary; adapters or gateways can project it into A2P, MCP, or direct HTTP APIs without changing business semantics. Merchants implement once and remain compatible as protocols evolve; agents read the manifest, honor the declared schemas and states, and transact predictably across transports.

Experience Ownership & Extensions

Combining these protocols and specs gives a starting point for machine-to-machine commerce, and allows merchants to steer agents into richer, brand-controlled experiences when appropriate. In the manifest, merchants can advertise preferred surfaces and deep links (non-normative) so agents know when to (a) transact silently via API, or (b) hand off to a guided flow.

• Branded conversations. Expose a conversational entry (e.g., “support/concierge” surface) for pre-sale guidance, post-sale care, or high-consideration purchases; agents can deep-link into that flow while preserving order or session context.

• Single customizer interfaces. For configurable goods/services, point agents to one canonical configurator rather than reverse-engineering options from product pages; agents return the selected configuration as structured options when creating the order.

• Assisted onboarding for complex categories. Where eligibility, risk, or compliance apply (e.g., insurance, financing, regulated goods), link to a guided application/quote flow; declare the handoff requirements and expected outputs so agents can resume with an order ID, quote reference, or eligibility token.

Systems Integration

Existing API

Use this path when a stable external API already exists. Keep discovery on the public site via /.well-known/commerce-manifest, then layer a thin Open Agentic Commerce adapter over current services.

New Platform

Use this path when building fresh or adopting a new commerce layer. Build an entire platform for Agentic commerce, or utilize a pre-built platform for exposing data and flows.

Existing Website

Use this path when the website is the primary system of record with no other simple alternatives for product or order functionality. Serve the manifest from /.well-known/commerce-manifest, then expose the Open Commerce endpoints by driving the same site functionality programmatically: extract product data from existing HTML or website APIs, and wrap checkout flows to produce order and pay endpoints. This achieves compatibility without a backend rewrite.

Manifest

To facilitate easy discovery of a merchant’s capabilities, the API uses a well-known URI approach. Merchants host a manifest discovery file at a standardized path (e.g., https://merchant.com/.well-known/commerce-manifest). The .well-known URI prefix is a convention defined by IETF (RFC 8615) to expose site metadata or services at consistent locations across all servers. By using a well-known URL, any client or agent knows exactly where to look for the merchant’s API manifest without needing the merchant to embed custom HTML tags or headers.

• Merchant Info: Basic information like the store name, description, and perhaps a reference to the merchant’s organization identity. This might align with Schema.org’s business schema, but primary use is identification and versioning of the API.

• Product Listing Endpoint: The URL or path where an agent can retrieve product data (e.g., /api/products). The manifest specifies how to query this (e.g., a GET request, with optional filters or pagination parameters)

• Pricing and Offers: Alongside basic product info, pricing is typically provided via Schema.org Offer objects.

• Order Creation Endpoint: The manifest defines how an agent can initiate an order. This is usually a POST endpoint (e.g., /api/orders or /api/cart/checkout).

• Context transportation: This mechanism enables websites and merchants to indicate they'd prefer (or require) agents to instruct them on what context is driving their consumer to these endpoints (e.g., the prompt summary of cost or feature analyzing multiple products).

• Agentic Landing Pad: This indicates that this website offers a specific experience for consumers being handed off from an Agentic experience, giving them an experience based on the context of what they are looking for.

• Other Endpoints: The manifest might list other related endpoints, such as one for retrieving a single product’s details, updating an order (e.g., adding/removing items before finalizing), or listing acceptable shipping or payment methods. For simplicity, these can be considered optional or part of the primary endpoints. The manifest should also contain a list of supported and authenticated payment methods (discussed in upcoming sections). Notably, Schema.org’s Offer type has an acceptedPaymentMethod property to enumerate what payment types are accepted. While the manifest can directly list payment options in its own schema, aligning with this concept means a merchant could indicate (for example) that it accepts "card", "crypto", "paypal", etc. The manifest might represent this information as an array of method identifiers or URLs to more details (like PaymentMethod schema or a custom enum).

Systems Architecture

The manifest does not define your system's architecture; it describes how your organization exposes capabilities to the agent ecosystem via a standardized contract. Capabilities have inherent dependencies (e.g., Products → Orders, Orders → Pay) that include shared data—an Order must reference Products—not just protocol flow. These capabilities can still be implemented as standalone services, provided the manifested interfaces and identifiers remain consistent.

Schema

Request

Response (complete manifest example)

{
  "version": "v0.1.0-draft",
  "merchant": {
    "name": "Acme Audio",
    "domain": "<https://shop.acmeaudio.com>",
  },
  "endpoints": {
    "catalog": "<https://shop.acmeaudio.com/api/products>",
    "product": "<https://shop.acmeaudio.com/api/products/{productId}>",
    "orders": "<https://shop.acmeaudio.com/api/orders>",
    "pay": "<https://shop.acmeaudio.com/api/orders/{orderId}/pay>",
  },
  "schemas": {
    "context": "<https://schema.org>",
    "product": "<https://schema.org/Product>",
    "offer": "<https://schema.org/Offer>",
    "order": "<https://schema.org/Order>",
    "priceSpecification": "<https://schema.org/PriceSpecification>"
  },
  "authentication": {
    "methods": [
      { "type": "APIKey", "header": "X-API-Key" },
      { "type": "OAuth2", "header": "Authorization", "format": "Bearer <token>" },
      { "type": "mTLS" },
      { "type": "KYAPay-kya+pay", "header": "x-kyapay" },
      { "type": "KYAPay-kya", "header": "x-kyapay" },
      { "type": "CloudflareAccess", "header": "CF-Access-JWT-Assertion" },
    ],
    "scopes": {
      "catalog": { "required": false },
      "orders": { "required": true, "allowedMethods": ["APIKey", "OAuth2", "Skyfire", "CloudflareAccess", "mTLS"] },
      "pay": { "required": true, "allowedMethods": ["APIKey", "OAuth2", "Skyfire", "CloudflareAccess", "mTLS"] }
    }
  },
  "payments": {
    "acceptedPaymentMethod": [
      {
        "type": "card",
        "networks": ["Visa", "Mastercard"],
      },
      {
        "type": "kyapay",
	    },
      {
        "type": "kyapay+pay",
	    },
      {
        "type": "paypal",
      },
      {
        "type": "applepay",
      },
      {
        "type": "googlepay",
      },
      {
        "type": "bank",
      },
      {
        "type": "crypto",
        "protocols": ["x402", "eip-712", "eip-2612"],
        "assets": [
          { "symbol": "USDC", "chain": "Ethereum" },
          { "symbol": "USDC", "chain": "Solana" }
        ]
      }
    ],
    "defaultCurrency": "USD"
  },
  "capabilities": {
	  "promptSummary": true,
  },
  "terms": {
    "privacyPolicy": "<https://shop.acmeaudio.com/privacy>",
    "tos": "<https://shop.acmeaudio.com/terms>",
    "rateLimits": "<https://shop.acmeaudio.com/rate-limits>",
    "returnsPolicy": "<https://shop.acmeaudio.com/terms/returns>",
    "cancellationPolicy": "<https://shop.acmeaudio.com/terms/cancellation>",
    "exchangesPolicy": "<https://shop.acmeaudio.com/terms/exchanges>",
  }
}

Property Table

Merchant

Endpoints

Authentication

AuthMethod

Scope

Payments

PaymentMethod

CardPaymentMethod (type = "card")

WalletPaymentMethod (type = "**applepay**")

ProviderPaymentMethod (type = "paypal")

BankPaymentMethod (type = "bank")

CryptoPaymentMethod (type = "crypto")

Asset (for crypto.assets)

Capabilities

Terms

Product Discovery

Expose a machine-readable catalog that maps your merchandise (or services) to a stable API. Crucially, it also notes the data schema used for product information, which in this standard is based on Schema.org Product. Product data is returned in a structured format (likely JSON-LD) that follows schema.org conventions for products. Using Schema.org vocabulary ensures interoperability and understanding across different systems. For example, each product item can be represented as a Product type with properties like name, description, image, and offers/pricing. The Schema.org definition of Product is broad: “any offered product or service” (it can be a physical good, a rental, etc.). This means even services or digital goods can be described in a similar way to physical products, using the same data model.

Source data from:

• Direct DB models (cleanest: serialize from source of truth).

• Existing internal/external APIs (adapter layer).

• Structured scraping of your own pages (bridge step when no API exists).

The approach is standardized around schema.org: Product is the container, Offer is for price/availability, and optional ItemList is for paging. This unlocks universal parsing and search while preserving your merchandising rules (variants, options, bundles).

Product Details

Model granularity

Each purchasable item is a Product with a unique sku and url. Price/availability live in the item’s offers (an Offer). If you sell families (colorways, sizes, bundles), still expose one Product per buyable selection; group them with a shared variant group identifier and/or native schema relations.

Variants & grouping

Represent product families in a way agents can traverse:

• Use native relations when available (e.g., hasVariant/isVariantOf) and/or include a stable variantGroupId via additionalProperty.

• Put the attributes that distinguish variants (e.g., color, size, material) directly on the variant item using native fields where they exist (color, size) and additionalProperty for the rest.

• Surface a normalized set of variant dimensions (e.g., ["color","size"]) so agents can build categorization.

Enrichment attributes

Map enrichment consistently so that agents can filter, for example:

• Gender/fit: use size → SizeSpecification.suggestedGender (or audience.audienceType).

• Season/style/other facets: add as additionalProperty (PropertyValue with name/value).

• Collections/curation: expose first-class Collections and tag products with a collection ID list.

Collections & categories

• Add a Collections endpoint returning an ItemList of curated groups (e.g., “New Arrivals”, “Spring Jackets”).

• On each Product, use category for taxonomy labels (free-text or codes) and optionally include inCollection (array of collection IDs) via additionalProperty.

Considerations

Merchants should plan how agents will consume exposed product details, URLs, and media. Decide whether agent-driven linkouts land on a dedicated, AI-optimized flow rather than the public storefront, and publish canonical, stable deep links per product/variant. Provide media that renders well in conversational UIs (clean primary image, predictable aspect ratios). Where appropriate, offer embeddable purchase surfaces (e.g., a compact product card or checkout intent) so agents can keep users in-flow.

Product Listing Endpoint:

The URL/path for retrieving product data (e.g., /api/products). The manifest specifies query mechanics (e.g., GET, filters, pagination) and the data schema for product information, based on Schema.org Product. Product data returns in structured form (typically JSON-LD) following schema.org conventions. Each item uses a Product with properties such as name, description, image, and offers/pricing. The Product definition accommodates physical goods, services, rentals, or digital goods, enabling a uniform model.

Pricing and Offers:

Pricing uses Schema.org Offer objects. A product’s offers property references an Offer with price, priceCurrency, availability, and related details. This establishes a clear, interoperable structure for currency, discounts, and availability.

Schema

Catalog Request

Catalog Response

{
  "@context": "https://schema.org",
  "@type": "ItemList",
  "itemListElement": [
    { "@type": "ListItem", "position": 1, "item": { "@type": "Product", "sku": "EBUD-MODX-BLK", "name": "Wireless Earbuds Model X" } }
  ],
  "numberOfItems": 1
}

Request (product detail)

GET /api/products/EBUD-MODX-BLK

Response (Product with Offer)

{
  "@context": "https://schema.org",
  "@type": "Product",
  "sku": "EBUD-MODX-BLK",
  "name": "Wireless Earbuds Model X",
  "description": "Noise-cancelling wireless earbuds with charging case.",
  "offers": {
    "@type": "Offer",
    "price": "99.99",
    "priceCurrency": "USD",
    "availability": "https://schema.org/InStock"
  }
}

Property Tables

Product

• Base Spec: Schema.org Product

• Extensions:

  Property	Type	Description
  (none beyond Schema.org at this time)

Offer

• Base Spec: Schema.org Offer

• Extensions:

  Property	Type	Description
  (none beyond Schema.org at this time)

Item List

• Base Spec: Schema.org ItemList

• Notes: Used for catalog pagination, can base64 pagination if doesn’t support item cursors.

• Extensions:

  Property	Type	Description
  nextItem	string	Cursor token for next page.
  prevItem	string (optional)	Cursor token for previous page.

Orders

Create Order

Define a two-step, deterministic flow: create (get full costs and state) → pay (handled in the next section). Order creation must compute all totals (subtotal, tax, shipping, discounts) and return a stable orderId. Inventory reservations and expirations are policy-driven and disclosed in the manifest.

The manifest defines how an agent can initiate an order and describes the required inputs for creating an order: a list of product IDs (and quantities) the customer wants to purchase, plus customer details like shipping address, chosen shipping method, and contact info. The data format for order creation requests and responses also leverages Schema.org types.

When the agent posts the order request, the system will calculate additional costs (tax, shipping, etc.) and return an Order summary. This is where complete order amount details are provided: the item subtotal, applicable taxes, shipping fees, discounts, and the final total payable. Ensuring the agent can get the complete price breakdown is critical – the previous step (product listing) only gave item prices, but now we include location-based tax, chosen shipping cost, etc. The manifest’s documentation of the order endpoint will clarify that the response consists of these components. For example, the response might include fields (or JSON-LD properties) like price (subtotal), tax (total tax amount), shippingCost, and a totalPaymentDue. In Schema.org terms, an Order or Invoice can use PriceSpecification to detail such components (e.g., indicating whether tax is included or not), or use specific properties like totalPaymentDue (often as an embedded PriceSpecification). The key outcome is that the agent knows exactly how much to pay and for what.

Key behaviors:

• Deterministic pricing at creation time.

• Clear state machine: PendingPayment → PaymentComplete → FulfillmentInProgress → Shipped (example).

• Shipping and tax inclusion are based on the address and the selected method.

• Idempotency via client-provided keys.

Order Flow

1. Initiating the Order: The agent selects items (IDs/quantities) and calls POST /api/orders with payload including items, shipping address, and chosen shipping option (optionally discovered via GET /api/shipping-options?dest=ZIP). The manifest specifies required fields (e.g., { "items":[...], "shippingAddress":{...}, "shippingOption":"standard" }).

2. Order Calculation: The backend computes subtotal, discounts, tax, and shipping, then creates a pending order (or a priced estimate, depending on implementation). The system returns an order ID for subsequent payment.

3. Next Step – Payment Trigger: With totals known, the agent triggers payment (e.g., POST /api/orders/{orderId}/pay or an automated protocol flow). Separating order creation from payment enables verification and inventory holds before settlement.

Other Order capabilities

Order Details

Returns the latest snapshot of an order for polling, post-payment checks, and fulfillment tracking. Auth must follow the manifest scope for the orders resource. Support GET /api/orders/{orderId}. The response SHOULD mirror the create order schema, augmented with any fulfillment, refund, and timeline metadata.

Order Request Return

Initiates a return for all or part of an order. Use POST /api/orders/{orderId}/return with a list of line items/quantities and optional reason codes. The server MAY respond synchronously with authorization (RMA) details or asynchronously with a pending state on the Order.

Order Request Cancellation

Requests cancellation before fulfillment cutoffs. Use POST /api/orders/{orderId}/cancel with an optional reason. If the order is still cancelable, transition to canceled; otherwise, respond with a clear state and remediation (e.g., initiate a return after delivery).

Schema

Request

{
  "items": [
    { "sku": "EBUD-MODX-BLK", "quantity": 1 }
  ],
  "shippingAddress": { "city": "Des Moines", "region": "IA", "postalCode": "50309", "country": "US" },
  "shippingOption": "UPS_STANDARD",
  "idempotencyKey": "c7b2c8f1-9f07-4f1a-9a2b-0d2b1f0d9e21"
}

Response

{
  "@context": "https://schema.org",
  "@type": "Order",
  "orderNumber": "ORD-2025-000123",
  "orderedItem": [ { "@type": "OrderItem", "orderedItem": { "@type": "Product", "sku": "EBUD-MODX-BLK" }, "orderedQuantity": 1 } ],
  "totalPaymentDue": { "@type": "PriceSpecification", "price": "112.99", "priceCurrency": "USD" },
  "orderStatus": "https://schema.org/OrderProcessing",
  "paymentStatus": "https://schema.org/PaymentDue"
}

Property Tables

Order

• Base Spec: Schema.org Order

• Extensions:

OrderItem

• Base Spec: Schema.org OrderItem

• Extensions: (none)

PriceSpecification

• Base Spec: Schema.org PriceSpecification

• Extensions: (none)

ParcelDelivery

• Base Spec: Schema.org ParcelDelivery

• Extensions: (none)

PostalAddress

• Base Spec: Schema.org PostalAddress

• Extensions: (none)

Person (Customer)

• Base Spec: Schema.org Person

• Extensions: (none)

Payment Processing

Payment is often the most complex part of a transaction, and our standard aims to accommodate any method of payment that a consumer and merchant agree on. The manifest will advertise the acceptable payment methods (as mentioned, possibly via an acceptedPaymentMethod list or a dedicated section enumerating options like Credit Card, specific digital wallets, or cryptocurrency). The Payment section of the specification needs to detail how each method works in this API context – especially for autonomous agents. Below, we break down different modes of payment and introduce the x402 payment framework as a core component for on-chain payments, ensuring interoperability with that approach.

This schema provides a unified pay endpoint that wires into the merchant’s existing rails. The endpoint accepts method-specific payloads (cards, PayPal orders, stablecoin x402 receipts, Skyfire PAY tokens) and advances the order state. Keep order creation and payment separate to guarantee pricing transparency and predictable state transitions.

• Hook into current gateways (Stripe/Adyen/etc.) or implement light adapters.

• Enable agentic flows without rewiring the entire checkout stack.

• Return a consistent payment result that updates the Order (paymentStatus, receipts, references).

This approach creates a simplified method for a Merchant to decide their Payment strategy:

• Existing Payment Platform: wire into the APIs that exist today from their platform or ecosystem

• New Platform: Merchant may build new Agentic Payment rails for these processes to avoid inter-mingling e-commerce traffic with Agentic traffic

• Offload entirely: Merchants can offload payments for Agentic transactions to a platform that services these payments end-to-end.

Payment Methods

• Card Tokens / Network Tokens (gateway charge via tokenized PAN).

• PayPal (order/authorization reference confirmation).

• Wallets (Apple/Google Pay via token rails when pre-authorized).

• Skyfire KYA/PAY (agent identity + escrowed/authorized spend).

• x402 (HTTP 402 challenge-response with stablecoin settlement).

• ACH/Bank (asynchronous confirmation, where applicable).

Tokenized Cards

Card payments are supported through tokenized flows rather than raw card numbers, ensuring PCI compliance and automation safety. Agents either present a gateway-issued token (e.g., Stripe Payment Intent) or instruct the merchant to charge a card-on-file linked to an authenticated customer account. The manifest advertises accepted card networks and methods, while the pay endpoint (POST /api/orders/{id}/pay) standardizes how tokens are exchanged. On success, the merchant updates the Order object with paymentMethod=card and paymentStatus=PaymentComplete.

Virtual Cards / Agentic Credentials

Virtual cards are on-demand card credentials, tied to an underlying funding source, allowing agents to use them anywhere a regular card is accepted. These credentials enable policy enablement: single-use vs. multi-use, merchant/MID or MCC locks, hard spend limits (per-transaction/day/month/year/lifetime), and expiry—reducing fraud and AML risk alongside upfront KYC/KYB and/or post-transaction monitoring. These credentials will be fully interoperable as a regular credit card.

Digital Wallets and External Providers

Digital wallets such as Apple Pay, Google Pay, or PayPal can be exposed if the merchant already supports them. Apple/Google Pay is limited for AI-driven scenarios due to device confirmation, but PayPal with pre-authorized tokens is feasible. The manifest signals support via acceptedPaymentMethod, and the pay endpoint either accepts wallet tokens directly or provides a redirect/payment URL. While less suited to fully autonomous flows, wallet and provider integrations remain useful for bridging existing consumer payment ecosystems.

On-Chain Payments via x402 (HTTP 402)

For autonomous transactions, the framework integrates x402, which uses HTTP 402 Payment Required as a challenge-response mechanism. When an agent posts to the pay endpoint without proof, the server responds with headers specifying amount, asset, network, and recipient address. The agent completes a stablecoin transfer and retries the request with a payment proof header (e.g., X-PAYMENT: <txHash>). The merchant verifies on-chain settlement, then finalizes the order. This creates a standardized, interoperable payment flow that eliminates custom APIs, reduces fraud, and provides instant, verifiable settlement in stable value (e.g., USDC).

Skyfire KYAPAY

Skyfire introduces a header-based payment and identity framework designed for autonomous agents. Instead of a 402 challenge, agents present a Skyfire token in the x-kyapay header. The KYA (Know Your Agent) component proves the agent’s identity, while the PAY component carries an escrowed or pre-authorized spend for a specific order and merchant. The merchant verifies the token signature against Skyfire’s issuer keys, ensuring identity and funds are valid.

This approach removes the need for the agent to manage card data or broadcast blockchain transactions directly. For the merchant, it collapses authentication and settlement into a single step: if the token is valid, the order’s paymentStatus moves to PaymentComplete. The manifest advertises Skyfire support in its authentication.methods and payments.acceptedPaymentMethod, enabling agents in the Skyfire ecosystem to transact seamlessly without custom integrations.

Other Payment Methods

The model remains extensible to ACH, bank transfers, Lightning (L402), or new rails. The manifest advertises which methods are available, whether they require prior authentication (e.g., account-linked cards), or operate through direct protocols like x402. The guiding principle is method-agnosticism: agents always use the same /pay surface, while merchants plug in their existing or future payment rails. This ensures long-term flexibility while preserving predictable, standardized integration for autonomous agents.

Schema

Pay (envelope):

{
  "method": "card|paypal|skyfire|x402",
  "payload": { /* method-specific */ }
}

Card token example:

{
  "method": "card",
  "payload": {
    "cardToken": "tok_1PxAbcDxyz",
    "network": "Visa",
    "saveOnFile": false
  }
}

Skyfire PAY token example:

POST /api/orders/ORD-123/pay
x-kyapay: <KYA|PAY token>
-> 200 OK
   { "orderId":"ORD-123", "paymentStatus":"PaymentComplete", ... }

eip-712 (envelope):

{
  "method": "eip-712",
  "payload": {  }
}

// response
{
  "orderId": "ORD-2025-000123",
  "paymentStatus": "PaymentPending",
  "details": {
	  "token": "0xA0b86991c6218b36...",      // USDC
	  "spender": "0xMerchantSpender",
	  "amount": "113990000",                  // token units
	  "deadline": "1725811200",
	  "eip712": { "domain": { ... }, "types": { ... }, "message": { ... } },
	  "intentId": "ord_123_pay_1",
	  "callbackUrl": "https://merchant.example.com/payments/permit
  }
}

x402:

POST /api/orders/ORD-123/pay
X-PAYMENT: <signed-payment-payload-or-tx-hash>
-> 200 OK
   X-PAYMENT-RESPONSE: <settlement-metadata>
   { "orderId"

Pay response:

{
  "orderId": "ORD-2025-000123",
  "paymentStatus": "PaymentComplete",
  "paymentMethod": "card",
  "paymentReference": "ch_1Px99Zabc",
  "receiptUrl": "https://gateway.example.com/receipts/ch_1Px99Zabc",
  "updatedOrder": {
    "@type": "Order",
    "orderNumber": "ORD-2025-000123",
    "paymentStatus": "https://schema.org/PaymentComplete",
    "orderStatus": "https://schema.org/OrderProcessing"
  }
}

Property Tables

Base Spec

• Impacted resource: Schema.org Order

Path Params

PayRequest (envelope)

CardPayload (for method = "card")

WalletPayload (for method = "wallet" — device/token rails)

Skyfire (for method = "skyfire")

Header-driven; body optional.

Required Request Header

Optional Body (if you emit one)

x402 (for method = "x402")

Two-step, header-mediated challenge/response using HTTP 402.

PayResult

Status Codes

Return Endpoint

Authentication and Authorization

A flexible authentication mechanism is crucial, as it allows merchants to control access to their API and protect sensitive operations (like order creation and payment) while possibly enabling open access to public data (like product listings). The key principle is that there are many ways to authenticate, and the design does not mandate a single method – instead, the merchant’s manifest explicitly exposes which authentication methods are supported or required for various endpoints. This could range from no auth required to API keys, OAuth tokens, or specialized protocols like Skyfire or Cloudflare’s solutions. The manifest serves as the contract, enabling integration with security services or autonomous identity systems with minimal friction.

Granular Access Control

The merchant should be able to grant granular access to specific functions:

• Product Data: can often be public (read-only). A merchant might choose to let product catalog information be fetched without any authentication since it’s similar to a public website’s content. This lowers the barrier for discovery (an agent can crawl product info freely). If not public, a simple auth like a static key could be used to track usage.

• Order Creation / Submission: This is a more sensitive action (it can reserve inventory, etc.). Likely, the merchant will want to know who (which agent or partner) is creating the order. Authentication at this step is essential to prevent abuse (e.g., someone spamming fake orders). The manifest might indicate that the /api/orders endpoint requires an API key or an OAuth Bearer token. In an AI agent scenario, the agent might be pre-registered with the merchant or use a universal identity.

• Payment Execution: Payment itself might piggy-back on the order auth or require additional credentials. For example, charging a card on file requires the agent to act on behalf of a logged-in user (so definitely authenticated). On the other hand, an X402 payment might not require prior identity if the value is transferred upfront (the payment itself is the authorization).

To support this, the manifest can define an authentication section, potentially mapping each endpoint or function to accepted auth methods. By making auth explicit and flexible, we enable various implementations:

• No Auth / Public: Great for basic data retrieval. Also useful for testing or open services. (The merchant could still impose rate limits per IP, etc., but that is not a concern of the spec itself.)

• API Keys: A simple approach where the agent includes a key in headers (e.g., Authorization: Bearer <API_KEY> or X-API-Key: <key>). Keys can be scoped and rotated. This is common for partner integrations.

• OAuth 2.0 / Bearer Tokens: If merchants have a full OAuth server, they could require OAuth tokens. This might be more relevant if the agent is acting on behalf of a user (the user could authorize the agent). However, many agent use-cases don’t have a user login, so API keys or specialized tokens are more likely.

• Mutual TLS or Signature: Some merchants might use client TLS certificates or request signatures (like HMAC) for auth. If so, the manifest can advertise that (e.g., a field indicating the need for a client certificate or a specific signing scheme).

• Open Protocol Agent Authentication

  • (Skyfire KYA Tokens): One of the more advanced methods is using the Skyfire platform’s identity tokens. Skyfire (by skyfire.xyz) provides a system where AI agents (buyers) can authenticate with sellers using KYA (Know Your Agent) tokens for identity and PAY tokens for payments. If a merchant is a Skyfire-integrated seller, they would likely specify that they accept Skyfire tokens in the request. For example, the manifest might say: “For protected endpoints, supply an Authorization: Bearer <token> where the token is a Skyfire KYA+Pay JWT.” The details: the agent (buyer) obtains a token from Skyfire that can combine identity and a payment credential if needed. The merchant (seller) verifies this token using Skyfire’s JWKS (JSON Web Key Set) public keys. This tells the merchant who the agent is (authenticated) and possibly carries a payload that authorizes a certain payment or spending limit. In essence, Skyfire can serve both as an auth and a payment mechanism (with off-chain tokens representing on-chain funds in escrow).

• Proprietary Agent Authentication

  • Cloudflare: Cloudflare’s Signed Agents program lets legitimate bots and AI agents authenticate via Web Bot Authentication using a verifiable message signature, so they can be allowed while generic bot traffic is mitigated.

In essence, the authentication model is plug-and-play. The manifest’s job is to state what is expected clearly:

• If no auth is needed: the manifest says so.

• If an API key is needed: the manifest explains the header or parameter for it.

• If OAuth is needed: the manifest provides the token endpoint or auth URL (or points to the standard OpenID Connect discovery if relevant).

• If a custom scheme like Skyfire is used: the manifest indicates “Skyfire tokens accepted” (and possibly includes a link to the Skyfire service or documentation for agents to register).

• If multiple methods are allowed, list them all. This way, an agent can choose one it supports. For example, maybe an agent doesn’t have Skyfire, but the merchant also allows a straightforward API key – then the agent can use that.

Options

• Skyfire (KYA identity; PAY tokens for spend authorization)

• Cloudflare Access (JWT assertion at edge)

• mTLS (client certificates)

• OAuth 2.0 / OIDC (Bearer tokens; scopes)

• API Keys (scoped/rotated)

Schema

Authentication declaration (in manifest):

{
  "authentication": {
    "methods": [
      { "type": "APIKey", "header": "X-API-Key" },
      { "type": "OAuth2", "header": "Authorization", "format": "Bearer <token>", "discovery": "https://shop.acmeaudio.com/.well-known/openid-configuration" },
      { "type": "mTLS" },
      { "type": "Skyfire", "header": "Authorization", "format": "Bearer <KYA|PAY token>", "issuer": "https://skyfire.xyz" },
      { "type": "CloudflareAccess", "header": "CF-Access-JWT-Assertion" },
      { "type": "VisaApprovedSignatures", "header": "X-Signature", "algo": "RSA-SHA256" }
    ],
    "scopes": {
      "/api/products": { "required": false },
      "/api/orders": { "required": true, "allowedMethods": ["APIKey", "OAuth2", "Skyfire", "CloudflareAccess", "mTLS"] },
      "/api/orders/{orderId}/pay": { "required": true, "allowedMethods": ["APIKey", "OAuth2", "Skyfire", "CloudflareAccess", "mTLS", "VisaApprovedSignatures"] }
    }
  }
}

Platforms learn how to authenticate by reading the authentication object of the manifest and selecting a supported method.

Conclusion

Open Agentic Commerce API establishes a single, predictable interface for autonomous commerce. The manifest makes capability discovery trivial via a well-known path, eliminating bespoke integrations and scraping. Schema.org alignment standardizes product, offer, and order semantics so agents parse once and operate across every compliant merchant. Order creation returns deterministic totals (items, tax, shipping, discounts) before settlement, removing ambiguity and enabling inventory holds and idempotent retries. Payment processing converges on a unified /pay surface that wires into existing rails (card tokens, PayPal, wallets), agent-native rails (Skyfire), and on-chain settlement (x402), without forcing a checkout rewrite. Authentication remains modular and explicit, mapping methods to endpoints and supporting API keys, OAuth2, mTLS, Cloudflare Access, Skyfire, and signed requests.

This design delivers tangible outcomes. Merchants expose a controlled, standards-based surface that preserves brand, pricing, and risk policies while unlocking new channels. Agents gain a consistent contract for discovery, pricing, and payment across ecosystems. Implementers minimize lift: keep current gateways and tax/shipping engines, layer small adapters, and adopt x402 or Skyfire where autonomy or instant settlement matters. Security improves through tokenization, strict scoping, and verifiable payments; operations improve through idempotency, clear state machines, and manifest-declared limits.

The path forward is straightforward. Ship the .well-known manifest, serialize Product/Offer/Order with JSON-LD, implement POST /api/orders to return a complete price breakdown, and expose POST /api/orders/{id}/pay with the methods you support (card, PayPal, wallets) while enabling x402 and/or Skyfire for agentic flows. Document auth in the manifest and enforce it at the edge and application layers. Measure success with time-to-first-integration, checkout success rate, chargeback/fraud rate, and order latency to fulfillment.

Adopting this specification creates a composable foundation for autonomous commerce: any compliant agent can transact with any compliant merchant, using any agreed-upon rail. It aligns with web standards, keeps merchants in control, and scales from today’s platforms to tomorrow’s payment protocols - without re-platforming.