> ## 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.

# Endpoints

> Prism Gateway API endpoint reference for payment preparation, merchant checkout, and UCP gateway.

Reference for each Prism Gateway API endpoint. See [Introduction](/prism/api-reference/introduction) for base URLs, authentication, and error handling.

All authenticated endpoints require the `X-Project-Identify-Token` header. Request and response bodies are JSON.

***

## x402 Settlement

Facilitator endpoints for the x402 payment flow. The [server-side SDKs](/prism/sdk/overview) 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             |

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
curl -X POST https://prism-gw.fd.xyz/api/v2/payment/requirements \
  -H "X-Project-Identify-Token: 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`)

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

<Expandable title="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                         |
</Expandable>

<Expandable title="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                |
</Expandable>

**Response** (`VerifyResponse2`)

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "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](#verify-payment).

**Response** (`SettleResponse`)

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "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](/prism/api-reference/introduction#error-format) body if the on-chain transaction fails.

***

## Merchant

Endpoints for UCP merchants to build discovery profiles and prepare checkout sessions.

### 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/payment-profile
```

```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"
```

**Response** (`PaymentProfileResponse`)

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

**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        |

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
curl -X POST https://prism-gw.fd.xyz/api/v2/merchant/checkout-prepare \
  -H "X-Project-Identify-Token: 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`)

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

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

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
curl https://prism-gw.fd.xyz/ucp/prism.md
```

```
```