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. The UCP flow has two calls: fetch the handlers declaration for your UCP version, and call Payment Requirements at checkout. ACP merchants use the same Payment Requirements call and fetch the declaration from /api/v2/merchant/acp/handlers, which needs the API key.

Get Handlers

Returns the xyz.fd.prism_payment handler declaration for a UCP version. Put it in your storefront’s UCP profile. Cache it. This route is public and needs no API key.

GET /ucp/{ucpVersion}/handlers

It returns the 2026-10-07 handler for UCP 2026-01-23, 2026-04-08 and 2026-08-25. See Prism contract selection.

curl https://prism-gw.fd.xyz/ucp/2026-08-25/handlers

An unsupported version returns 422 version_unsupported. The unversioned GET /api/v2/merchant/ucp/handlers stays as a legacy route for older plugins. The versioned /api/v2/merchant/ucp/{ucpVersion}/handlers form was removed. Use the route above. Response (UcpHandlersResponse)

{
  "xyz.fd.prism_payment": [
    {
      "id": "xyz.fd.prism_payment",
      "version": "2026-10-07",
      "spec": "https://prism-gw.fd.xyz/ucp/prism.md",
      "schema": "https://prism-gw.fd.xyz/ucp/schema.json",
      "available_instruments": [{ "type": "x402" }],
      "config": {}
    }
  ]
}

Unsupported version (422)

{"title":"version_unsupported","detail":"Version 2099-01-01 is not supported. Enabled versions: 2026-01-23, 2026-04-08, 2026-08-25."}

Payment Requirements

Convert a fiat amount into the raw x402 PaymentRequired object. Call it at checkout, when a buyer selects items. The response has no protocol wrapper and does not depend on the UCP version. Requires the API key.

POST /api/v2/merchant/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/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/checkout/1"}}'

Response

{
  "x402Version": 2,
  "resource": { "url": "https://shop.example/checkout/1" },
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "payTo": "0xMerchant...addr",
      "maxTimeoutSeconds": 300,
      "asset": "0xUSDC...addr",
      "amount": "10000000"
    }
  ]
}

The response has one accepts entry per token and chain the merchant supports, with amount resolved from the fiat price. It may also include promotions. Returns 404 if the merchant is not configured in Prism Console. Build the UCP checkout entry from the handlers declaration for your UCP version and this object:

{
  "xyz.fd.prism_payment": [
    { "id": "<declaration id>", "version": "<declaration version>", "config": { "x402Version": 2, "resource": {}, "accepts": [] } }
  ]
}

Gateway

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

Handler Schema

Returns the JSON schema for the xyz.fd.prism_payment handler. The handler config schema is the entry schema. The instrument schema is linked at $defs["xyz.fd.prism_payment"].instrument.

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

Resources

x402 Settlement

Get Payment Requirements

Verify Payment

Settle Payment

Merchant

Get Handlers

Payment Requirements

Gateway

Handler Schema

Handler Specification

​x402 Settlement

​Get Payment Requirements

​Verify Payment

​Settle Payment

​Merchant

​Get Handlers

​Payment Requirements

​Gateway

​Handler Schema

​Handler Specification

x402 Settlement

Get Payment Requirements

Verify Payment

Settle Payment

Merchant

Get Handlers

Payment Requirements

Gateway

Handler Schema

Handler Specification