Universal Checkout

AgnicPay's Universal Checkout lets any AI agent — not just those using the MCP server — make x402 purchases. It works with ChatGPT, Gemini, Claude, LangChain agents, or any system that can send an HTTP header.

How It Works

AI generates a link to the /buy page with the merchant URL and network
User opens the link, authenticates with AgnicPay, and approves the payment amount
User copies the one-time token (agnic_ot_...) back to the AI
AI calls /api/x402/fetch with the token as the X-Agnic-Token header
AgnicPay handles payment signing, KYA credential attachment, and transaction logging — same as always

AI Agent                    User                      AgnicPay
   |                         |                           |
   |-- "Open this link" ---->|                           |
   |                         |-- /buy?merchant=... ----->|
   |                         |<-- Show approval form ----|
   |                         |-- Approve $10 max ------->|
   |                         |<-- agnic_ot_abc123... ----|
   |<-- Paste token ---------|                           |
   |-- x402/fetch + token -------------------------------->|
   |<-- Response (paid) -----------------------------------|

The `/buy` Page

The buy page is hosted at pay.agnic.ai/buy and accepts these URL parameters:

Parameter	Required	Description
`merchant`	Yes	The merchant API endpoint (e.g., `wine-merchant-test.fly.dev/api/wine/purchase`)
`network`	No	Blockchain network. Default: `base`. Options: `base`, `base-sepolia`, `solana`, `solana-devnet`
`amount`	No	Pre-fill the max amount field

Example URL:

https://pay.agnic.ai/buy?merchant=wine-merchant-test.fly.dev/api/wine/purchase&network=base&amount=10

The page offers two actions:

Pay Now — Creates a token and immediately executes the payment. Shows a receipt when done.
Approve & Copy Token — Creates a token and displays it for the user to copy back to their AI agent.

Purchase Token API

Create a Token

POST /api/purchase-token/create
Authorization: Bearer <privy_access_token>
Content-Type: application/json

{
  "merchant_url": "https://wine-merchant-test.fly.dev/api/wine/purchase",
  "network": "base",
  "max_amount_usd": 10.00
}

Response:

{
  "token": "agnic_ot_dGhpcyBpcyBhIHRlc3Q",
  "id": "pt_1709654321_a1b2c3d4",
  "expires_at": "2024-03-05T12:35:21.000Z",
  "merchant_url": "wine-merchant-test.fly.dev/api/wine/purchase",
  "network": "base",
  "max_amount_usd": 10
}

Use the Token

curl -X POST "https://api.agnic.ai/api/x402/fetch?url=https://wine-merchant-test.fly.dev/api/wine/purchase" \
  -H "X-Agnic-Token: agnic_ot_dGhpcyBpcyBhIHRlc3Q"

The token works identically to regular API tokens — the existing x402/fetch proxy handles everything.

Security Model

Purchase tokens are designed to be maximally safe:

One-time use: Token is consumed on first successful payment. Cannot be reused.
5-minute expiry: Unused tokens expire automatically.
Merchant-bound: Token only works for the specific merchant URL it was created for.
Network-bound: Token only works on the specified blockchain network.
Amount-capped: The max_amount_usd acts as a spending ceiling. The actual charge may be less.
Hash-only storage: Only the SHA-256 hash is stored. The raw token is returned once and never persisted.

Integration Examples

Claude (System Prompt)

When the user wants to buy something, generate a link to:
https://pay.agnic.ai/buy?merchant=MERCHANT_URL&network=base&amount=AMOUNT

Ask them to open it, approve the payment, and paste the token back.
Then call the merchant via:
POST https://api.agnic.ai/api/x402/fetch?url=MERCHANT_URL
Header: X-Agnic-Token: <the token they pasted>

ChatGPT GPT (Actions)

openapi: 3.0.0
info:
  title: AgnicPay x402 Proxy
  version: "1.0"
servers:
  - url: https://api.agnic.ai
paths:
  /api/x402/fetch:
    post:
      operationId: makePayment
      parameters:
        - name: url
          in: query
          required: true
          schema:
            type: string
        - name: X-Agnic-Token
          in: header
          required: true
          schema:
            type: string

Generic Agent (Python)

import requests
 
# User provides this after approving on pay.agnic.ai/buy
token = "agnic_ot_..."
 
response = requests.post(
    "https://api.agnic.ai/api/x402/fetch",
    params={"url": "https://merchant.example.com/api/endpoint"},
    headers={"X-Agnic-Token": token},
)
 
print(response.json())

Universal Checkout

On this page