Introduction

The Prism Gateway API handles payment settlement, payment requirement generation, and merchant profile management. For most x402 integrations, the server-side SDKs wrap these endpoints automatically. Use the API directly for custom integrations or when building on top of UCP.

Base URLs

Environment	URL
Production	`https://prism-gw.fd.xyz`

Authentication

Authenticate by including your Project Identify Token in the X-API-Key header:

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

Get your Project Identify Token from the Prism Console under Project Identify Tokens.

Keep your Project Identify Token secret. Never expose it in client-side code, browser requests, or public repositories.

Endpoint Groups

The API is organized into three groups:

Group	Auth	Purpose
x402 Settlement	`X-API-Key`	Generate payment requirements, verify authorizations, settle payments
Merchant	`X-API-Key`	UCP checkout helpers: get your payment profile for discovery, convert fiat amounts to x402 payment handler entries
Gateway	Public	UCP handler reference files: JSON schema and handler spec

x402 Settlement

Facilitator endpoints for the x402 payment flow. The SDKs call these under the hood.

Method	Endpoint	Description
`POST`	`/api/v2/payment/requirements`	Generate x402 payment requirements for a resource
`POST`	`/api/v2/payment/verify`	Verify a signed x402 payment authorization
`POST`	`/api/v2/payment/settle`	Settle a verified payment on-chain

Merchant

For UCP and ACP merchants. Call these from your server to build your discovery profile and prepare checkout sessions. Each protocol has its own handlers and payment-requirements endpoint.

Method	Endpoint	Description
`GET`	`/api/v2/merchant/ucp/handlers`	Get the `payment_handlers` block for your UCP discovery profile
`POST`	`/api/v2/merchant/ucp/payment-requirements`	Convert a fiat amount into UCP x402 payment handler entries with resolved token amounts
`GET`	`/api/v2/merchant/acp/handlers`	Get the payment handler block for your ACP capabilities
`POST`	`/api/v2/merchant/acp/payment-requirements`	Convert a fiat amount into ACP payment handler entries with resolved token amounts

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

Gateway

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

Method	Endpoint	Description
`GET`	`/ucp/schema.json`	UCP handler JSON schema
`GET`	`/ucp/prism.md`	UCP handler specification

See Endpoints for full request/response documentation.

Request Format

Content-Type: application/json
All request bodies are JSON
Standard HTTP methods: GET, POST

Error Format

Errors follow the RFC 7807 Problem Details format:

{
  "type": "https://tools.ietf.org/html/rfc7807",
  "title": "Bad Request",
  "status": 400,
  "detail": "Amount is required"
}

HTTP Status	Meaning
400	Bad Request (invalid input)
401	Unauthorized (missing or invalid Project Identify Token)
404	Not Found (merchant not configured)
502	Bad Gateway (upstream settlement failure)

When rate limited, the API returns 429 Too Many Requests. Back off and retry after the reset time.

SDKs

For most integrations, use a server-side SDK instead of calling the API directly. The SDKs handle authentication, x402 protocol flow, payment verification, and type safety:

TypeScript

Express, NestJS, Next.js, Fastify, and more

Python

FastAPI, Flask, Django

Java

Servlet-based applications

Getting Started

Concepts

Architecture

Integrations

API Reference

Going to Production

AI Tooling

Base URLs

Authentication

Endpoint Groups

x402 Settlement

Merchant

Gateway

Request Format

Error Format

SDKs

TypeScript

Python

Java

​Base URLs

​Authentication

​Endpoint Groups

​x402 Settlement

​Merchant

​Gateway

​Request Format

​Error Format

​SDKs

TypeScript

Python

Java

Base URLs

Authentication

Endpoint Groups

x402 Settlement

Merchant

Gateway

Request Format

Error Format

SDKs