Endpoints

Reference for each Prism Gateway API endpoint. See Introduction for base URLs, authentication, and error handling. All authenticated endpoints require the X-API-Key header. Request and response bodies are JSON.

x402 Settlement

Facilitator endpoints for the x402 payment flow. The server-side SDKs call these automatically. Use them directly for custom integrations.

Get Payment Requirements

Generate x402 payment requirements for a resource. Returns the accepted payment methods, token amounts, and settlement addresses.

POST /api/v2/payment/requirements

Request Body

Field	Type	Required	Description
`resourceUrl`	string	Yes	URL of the protected resource
`requestedAmount`	number	Yes	Amount to charge (in the resource’s currency)
`description`	string	No	Human-readable description of the resource
`mimeType`	string	No	MIME type of the resource content

curl -X POST https://prism-gw.fd.xyz/api/v2/payment/requirements \
  -H "X-API-Key: your-project-identify-token" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceUrl": "https://api.example.com/premium/data",
    "requestedAmount": 0.50,
    "description": "Premium API access"
  }'

Response (PaymentRequiredResponse)

{
  "x402Version": 2,
  "resource": {
    "url": "https://api.example.com/premium/data",
    "description": "Premium API access"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "amount": "500000",
      "payTo": "0x1234...abcd",
      "maxTimeoutSeconds": 300,
      "asset": "0xUSDC...addr",
      "extra": null,
      "protocolVersion": 2
    }
  ],
  "protocolVersion": 2
}

The accepts array contains one entry per token/chain combination the merchant supports. Clients pick one and construct a signed authorization against it.

Verify Payment

Verify a signed x402 payment authorization without settling it on-chain.

POST /api/v2/payment/verify

Request Body (PaymentSubmissionRequest2)

Field	Type	Required	Description
`paymentPayload`	object	Yes	Signed payment authorization (see below)
`paymentRequirements`	object	Yes	The accepted payment requirement this authorization targets

Show paymentPayload fields

Field	Type	Required	Description
`x402Version`	integer	Yes	Protocol version (2)
`accepted`	object	Yes	The `accepts` entry the payer selected
`payload`	object	Yes	Signed authorization data (scheme-specific)
`resource`	object	No	Resource metadata
`extensions`	object	No	Protocol extensions

Show paymentRequirements fields

Field	Type	Required	Description
`scheme`	string	Yes	Payment scheme (e.g. `"exact"`)
`network`	string	Yes	Chain identifier (e.g. `"base"`)
`amount`	string	Yes	Token amount in smallest unit
`payTo`	string	Yes	Merchant settlement address
`maxTimeoutSeconds`	integer	Yes	Max time before authorization expires
`asset`	string	Yes	Token contract address

Response (VerifyResponse2)

{
  "isValid": true,
  "payer": "0xPayerAddress...1234"
}

Field	Type	Description
`isValid`	boolean	Whether the authorization is valid
`payer`	string	Payer wallet address (if valid)
`invalidReason`	string	Reason for rejection (if invalid)

Settle Payment

Settle a verified payment on-chain. Executes the transferWithAuthorization (ERC-3009) call to move tokens from the payer to the merchant.

POST /api/v2/payment/settle

Request Body (PaymentSubmissionRequest2) Same structure as Verify Payment. Response (SettleResponse)

{
  "success": true,
  "payer": "0xPayerAddress...1234",
  "transaction": "0xTransactionHash...abcd",
  "network": "base"
}

Field	Type	Description
`success`	boolean	Whether settlement succeeded
`payer`	string	Payer wallet address
`transaction`	string	On-chain transaction hash
`network`	string	Chain the settlement executed on
`errorReason`	string	Reason for failure (if unsuccessful)

Returns 502 Bad Gateway with a ProblemDetails body if the on-chain transaction fails.

Merchant

Endpoints for UCP and ACP merchants to build discovery profiles and prepare checkout sessions. The endpoints below are the UCP variants; ACP merchants use the parallel /api/v2/merchant/acp/handlers and /api/v2/merchant/acp/payment-requirements endpoints with identical request/response shapes.

The generic /api/v2/merchant/payment-profile and /api/v2/merchant/checkout-prepare endpoints still work but are deprecated aliases of the UCP endpoints below. Use the protocol-split endpoints for new integrations.

Get Payment Profile

Returns the payment_handlers block for your UCP discovery profile. Include this in your storefront’s UCP profile so agents can discover your supported payment methods.

GET /api/v2/merchant/ucp/handlers

curl https://prism-gw.fd.xyz/api/v2/merchant/ucp/handlers \
  -H "X-API-Key: your-project-identify-token"

Response (PaymentProfileResponse)

{
  "xyz.fd.prism_payment": [
    {
      "id": "xyz.fd.prism_payment",
      "version": "2026-01-23"
    }
  ]
}

Returns 404 if the merchant is not configured in Prism Console.

Prepare Checkout

Convert a fiat amount into x402 payment handler entries with resolved token amounts. Use this when a buyer selects items and you need to build the checkout payment_handlers block with concrete token prices.

POST /api/v2/merchant/ucp/payment-requirements

Request Body

Field	Type	Required	Description
`amount`	string	Yes	Fiat amount (e.g. `"10.00"`)
`currency`	string	Yes	Fiat currency code (e.g. `"USD"`)
`resource`	object	Yes	Resource being purchased
`resource.url`	string	Yes	URL identifying the resource
`resource.description`	string	No	Human-readable description

curl -X POST https://prism-gw.fd.xyz/api/v2/merchant/ucp/payment-requirements \
  -H "X-API-Key: your-project-identify-token" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "10.00",
    "currency": "USD",
    "resource": {
      "url": "https://shop.example.com/order/12345",
      "description": "Order #12345"
    }
  }'

Response (CheckoutPrepareResponse)

{
  "xyz.fd.prism_payment": [
    {
      "id": "xyz.fd.prism_payment",
      "version": "2026-01-23",
      "config": {
        "x402Version": 2,
        "resource": {
          "url": "https://shop.example.com/order/12345",
          "description": "Order #12345"
        },
        "accepts": [
          {
            "scheme": "exact",
            "network": "base",
            "payTo": "0xMerchant...addr",
            "maxTimeoutSeconds": 300,
            "asset": "0xUSDC...addr",
            "amount": "10000000"
          },
          {
            "scheme": "exact",
            "network": "base",
            "payTo": "0xMerchant...addr",
            "maxTimeoutSeconds": 300,
            "asset": "0xFDUSD...addr",
            "amount": "10000000"
          }
        ]
      }
    }
  ]
}

The response contains one accepts entry per token/chain combination the merchant supports, with amount resolved from the fiat price. Include this in your UCP checkout response so agents can select a payment option and authorize the transfer. Returns 404 if the merchant is not configured in Prism Console.

Gateway

Public endpoints serving the UCP handler reference. No authentication required.

Handler Schema

Returns the JSON schema for the xyz.fd.prism_payment handler.

GET /ucp/schema.json

curl https://prism-gw.fd.xyz/ucp/schema.json

Handler Specification

Returns the human-readable specification for the xyz.fd.prism_payment handler in Markdown format.

GET /ucp/prism.md

curl https://prism-gw.fd.xyz/ucp/prism.md

Getting Started

Concepts

Architecture

Integrations

API Reference

Going to Production

AI Tooling

x402 Settlement

Get Payment Requirements

Verify Payment

Settle Payment

Merchant

Get Payment Profile

Prepare Checkout

Gateway

Handler Schema

Handler Specification

​x402 Settlement

​Get Payment Requirements

​Verify Payment

​Settle Payment

​Merchant

​Get Payment Profile

​Prepare Checkout

​Gateway

​Handler Schema

​Handler Specification

x402 Settlement

Get Payment Requirements

Verify Payment

Settle Payment

Merchant

Get Payment Profile

Prepare Checkout

Gateway

Handler Schema

Handler Specification