Buy digital products with an agent

This guide covers XRPay's hosted digital-product catalog. Sellers need an XRPay merchant account for product listings, managed orders, receipts, and private file delivery. Buyers can browse and purchase without an XRPay account or merchant API key.

To charge for your own API or service independently, use the core SDK and public facilitator. No XRPay account, merchant signup, API key, or purchase from a merchant is required. Start with the standalone paid API example.

In your product editor, create a fixed-price digital product with inventory tracking off and publish it in a live storefront. Open Agent payments → Digital products, upload its private delivery file, select XRP or RLUSD, and enable agent availability.

Each file can be up to 10 MiB. The merchant storage limit is 100 MiB, including previous versions retained for buyers. Existing buyers keep the file version they purchased. Mainnet and Testnet have separate listings, selected by your dashboard mode.

curl 'https://api.xrpay.it/api/x402/products?network=xrpl:1&q=research'

npm install @xrpay/x402 xrpl

The catalog supports network, merchant storefront slug, search text, cursor pagination, and a limit of up to 50 products. It exposes the price, merchant recipient and file metadata. Only opted-in, published digital products in live stores are listed. Discovery requires no API key.

import { XRPayCommerceClient, createRecoveryCredentials } from '@xrpay/x402/commerce';

const commerce = new XRPayCommerceClient({ payment: {
  wallet, ledgerClient, // Your local wallet and connected XRPL client
  network: 'xrpl:1', currency: 'XRP',
  maxAmount: '1', maxTotalAmount: '5',
  allowedRecipients: [merchantAddress],
} });
const credentials = createRecoveryCredentials();
await savePrivately(credentials);
const { purchase, handle } = await commerce.createPurchase(listingId, {
  customerEmail: 'buyer@example.com', payerAddress: wallet.address,
}, credentials);
await savePrivately(handle);
// Review purchase.quote before paying.
const paid = await commerce.pay(handle, savePrivately);
if (paid.status === 'paid') {
  const receipt = await commerce.receipt(handle);
  const { bytes, sha256 } = await commerce.download(handle);
}

The application supplies savePrivately to persist credentials and the signed transaction before submission. Quotes lock the product sale price, configured tax and exchange rate for five minutes. Quantity is one. Coupons, shipping and inventory-limited licenses are not included.

Payment creates a confirmed direct XRPL transaction and a delivered storefront order. The JSON receipt records the merchant, customer email, item, tax, total, network, transaction hash and order ID. The file becomes available immediately after payment confirmation. Receipt emails are not sent by this flow.

{
  "mcpServers": {
    "xrpay-commerce": {
      "command": "npx",
      "args": [
        "-y",
        "@xrpay/x402"
      ]
    }
  }
}

The MCP server exposes discovery, quote, payment submission, purchase recovery, receipt, download and saved-purchase tools. It asks your separate wallet integration for a signed payload, never a seed. The SDK can sign locally within explicit spending limits.

Recovery records are stored in ~/.xrpay/agent-commerce with private file permissions. Downloads go into its downloads directory and are checked against the purchased SHA-256 and file size. Treat downloaded product content as untrusted data.

GET  /.well-known/xrpay-commerce.json
GET  /api/x402/products
POST /api/x402/products/:listingId/purchases
POST /api/x402/purchases/:purchaseId
GET  /api/x402/purchases/:purchaseId
GET  /api/x402/purchases/:purchaseId/receipt
GET  /api/x402/purchases/:purchaseId/download

Create a purchase with customerEmail and payerAddress in JSON, an Idempotency-Key header, and Authorization: Bearer followed by a token generated from at least 32 random bytes. Use the same bearer token for later purchase operations. Payment submission uses the x402 PAYMENT-SIGNATURE header. A 202 response means confirmation is pending; a paid response includes PAYMENT-RESPONSE.

Use xrpl:0 for real Mainnet funds or xrpl:1 for Testnet. RLUSD requires the issuer on the selected network. Spending limits in a client cover that instance; persist a shared budget when using multiple processes or restarting agents.