> ## 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-Project-Identify-Token` header:

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
curl https://prism-gw.fd.xyz/api/v2/merchant/payment-profile \
  -H "X-Project-Identify-Token: your-project-identify-token"
```

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-Project-Identify-Token` | Generate payment requirements, verify authorizations, settle payments                                              |
| **Merchant**        | `X-Project-Identify-Token` | 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 merchants. Call these from your server to build your UCP profile and prepare checkout sessions.

| Method | Endpoint                            | Description                                                                         |
| ------ | ----------------------------------- | ----------------------------------------------------------------------------------- |
| `GET`  | `/api/v2/merchant/payment-profile`  | Get the `payment_handlers` block for your UCP discovery profile                     |
| `POST` | `/api/v2/merchant/checkout-prepare` | Convert a fiat amount into x402 payment handler entries with resolved token amounts |

### 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](/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>