> ## Documentation Index
> Fetch the complete documentation index at: https://developers.fd.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Prism Gateway REST API for x402 payment settlement, UCP checkout preparation, and merchant profile management.

The Prism Gateway API handles payment settlement, payment requirement generation, and merchant profile management. For most x402 integrations, the [server-side SDKs](/prism/sdk/overview) 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:

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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"}}'
```

Get your Project Identify Token from the [Prism Console](https://apps.fd.xyz/prism/) under **Project Identify Tokens**.

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

## 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` (handlers route is public) | UCP checkout helpers: get the versioned handlers declaration, convert fiat amounts to raw x402 payment requirements |
| **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. Both protocols share one payment-requirements endpoint. Each has its own handlers endpoint.

| Method | Endpoint | Description |
| - | - | - |
| `POST` | `/api/v2/merchant/payment-requirements` | Convert a fiat amount into the raw x402 PaymentRequired object, with no protocol wrapper. Used by UCP and ACP |
| `GET` | `/api/v2/merchant/acp/handlers` | Get the ACP handler declaration. Needs the API key |

### 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 |
| `GET` | `/ucp/{ucpVersion}/handlers` | Handler declaration for a UCP version |

See [Endpoints](/prism/api-reference/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](https://tools.ietf.org/html/rfc7807) Problem Details format:

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "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:

<CardGroup cols={3}>
  <Card title="TypeScript" icon="js" href="/prism/sdk/typescript">
    Express, NestJS, Next.js, Fastify, and more
  </Card>

  <Card title="Python" icon="python" href="/prism/sdk/python">
    FastAPI, Flask, Django
  </Card>

  <Card title="Java" icon="java" href="/prism/sdk/java/servlet">
    Servlet-based applications
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.