> For the complete documentation index, see [llms.txt](https://docs.cspr.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cspr.cloud/x402-facilitator-api/verify.md).

# Verify

Validates a client's signed payment payload against the resource server's payment requirements without submitting any transaction on-chain.

Resource servers can use this endpoint to confirm a payment is valid before serving a response, while deferring the on-chain settlement to a later step via [/settle](/x402-facilitator-api/settle.md).

```
POST /verify
```

## Request body

| Property              | Type     | Required | Description                                               |
| --------------------- | -------- | -------- | --------------------------------------------------------- |
| `paymentPayload`      | `object` | Yes      | The signed payment payload submitted by the client.       |
| `paymentRequirements` | `object` | Yes      | The payment requirements declared by the resource server. |

### `paymentPayload`

| Property      | Type      | Description                                               |
| ------------- | --------- | --------------------------------------------------------- |
| `x402Version` | `integer` | Protocol version. Must be `2`.                            |
| `payload`     | `object`  | Casper-specific signed authorization. See below.          |
| `resource`    | `object`  | Information about the resource being accessed. See below. |
| `accepted`    | `object`  | Accepted payment option. See below.                       |

### `accepted`

The accepted payment option:

| Property            | Type      | Description                                                                          |
| ------------------- | --------- | ------------------------------------------------------------------------------------ |
| `scheme`            | `string`  | Payment scheme. Must be `"exact"`.                                                   |
| `network`           | `string`  | CAIP-2 network identifier (e.g. `"casper:casper-net-1"`).                            |
| `asset`             | `string`  | CEP-18 contract package hash as a 64-character hex string.                           |
| `amount`            | `string`  | Required payment amount in token base units as a decimal string.                     |
| `payTo`             | `string`  | Casper account hash of the intended recipient (format: `00<64 hex chars>`).          |
| `maxTimeoutSeconds` | `integer` | Maximum number of seconds the authorization must remain valid from now. Minimum `6`. |
| `extra`             | `object`  | Optional token metadata (e.g. `name`, `version`) used to build the EIP-712 domain.   |

### `resource`

| Property      | Type     | Required | Description                                     |
| ------------- | -------- | -------- | ----------------------------------------------- |
| `url`         | `string` | Yes      | URL of the resource being accessed.             |
| `description` | `string` | No       | Human-readable description of the resource.     |
| `mimeType`    | `string` | No       | MIME type of the resource (e.g. `"text/html"`). |

The `payload` object contains:

| Property        | Type     | Description                                                                                        |
| --------------- | -------- | -------------------------------------------------------------------------------------------------- |
| `signature`     | `string` | 65-byte EIP-712 signature as a hex string (130 characters).                                        |
| `publicKey`     | `string` | Casper public key as a hex string with an algorithm prefix (`01` for ED25519, `02` for SECP256K1). |
| `authorization` | `object` | EIP-712 `TransferAuthorization` typed data. See below.                                             |

The `authorization` object contains:

| Property      | Type     | Description                                                           |
| ------------- | -------- | --------------------------------------------------------------------- |
| `from`        | `string` | Casper account hash of the payer (format: `00<64 hex chars>`).        |
| `to`          | `string` | Casper account hash of the payee (format: `00<64 hex chars>`).        |
| `value`       | `string` | Payment amount in token base units as a decimal string.               |
| `validAfter`  | `string` | Unix timestamp (seconds) before which the authorization is not valid. |
| `validBefore` | `string` | Unix timestamp (seconds) after which the authorization expires.       |
| `nonce`       | `string` | 32-byte random nonce as a hex string (64 characters).                 |

### `paymentRequirements`

An object describing the required payment. The facilitator validates the `authorization` against these requirements.

| Property            | Type      | Description                                                                          |
| ------------------- | --------- | ------------------------------------------------------------------------------------ |
| `scheme`            | `string`  | Payment scheme. Must be `"exact"`.                                                   |
| `network`           | `string`  | CAIP-2 network identifier. Must match the network in `paymentPayload`.               |
| `payTo`             | `string`  | Casper account hash of the intended recipient (format: `00<64 hex chars>`).          |
| `amount`            | `string`  | Required payment amount in token base units as a decimal string.                     |
| `asset`             | `string`  | CEP-18 contract package hash as a 64-character hex string.                           |
| `maxTimeoutSeconds` | `integer` | Maximum number of seconds the authorization must remain valid from now. Minimum `6`. |
| `extra`             | `object`  | Token metadata. Must include `name` and `version` to build the EIP-712 domain.       |

## Response

| Property         | Type      | Description                                                          |
| ---------------- | --------- | -------------------------------------------------------------------- |
| `isValid`        | `boolean` | `true` if the payload is valid, `false` otherwise.                   |
| `payer`          | `string`  | Account hash of the payer, present when `isValid` is `true`.         |
| `invalidReason`  | `string`  | Machine-readable error code, present when `isValid` is `false`.      |
| `invalidMessage` | `string`  | Human-readable error description, present when `isValid` is `false`. |
| `extensions`     | `object`  | Optional additional data returned by the facilitator.                |

### Error codes

| Code                                           | Description                                                          |
| ---------------------------------------------- | -------------------------------------------------------------------- |
| `unsupported_scheme`                           | The payment scheme is not `"exact"`.                                 |
| `network_mismatch`                             | Payload and requirements specify different networks.                 |
| `malformed_payload`                            | Missing or invalid fields, or malformed nonce/signature hex.         |
| `pay_to_mismatch`                              | `authorization.to` does not match `requirements.payTo`.              |
| `amount_mismatch`                              | `authorization.value` does not match `requirements.amount`.          |
| `invalid_pay_to`                               | `payTo` is not a valid Casper account hash.                          |
| `invalid_amount`                               | Amount is zero or empty.                                             |
| `invalid_asset`                                | Asset is not a valid 64-character hex CEP-18 package hash.           |
| `not_yet_valid`                                | Current time is before `validAfter`.                                 |
| `payload_expired`                              | Current time is past `validBefore`.                                  |
| `insufficient_time`                            | Less than 6 seconds remain before `validBefore`.                     |
| `missing_token_name` / `missing_token_version` | Required EIP-712 domain fields are absent from `extra`.              |
| `failed_to_hash`                               | Failed to compute the EIP-712 typed-data digest.                     |
| `invalid_signature`                            | Signature does not verify against the public key and EIP-712 digest. |

## Example

```bash
curl -X 'POST' \
  'https://x402-facilitator.cspr.cloud/verify' \
  -H 'authorization: 55f79117-fc4d-4d60-9956-65423f39a06a' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
    "paymentPayload": {
      "x402Version": 2,
      "resource": {
          "url": "http://127.0.0.1:3002/api/data"
      },
      "accepted": {
          "scheme": "exact",
          "network": "casper:casper-test",
          "asset": "9824d60dc3a5c44a20b9fd260a412437933835b52fc683d8ae36e4ec2114843e",
          "amount": "10000",
          "payTo": "0000000000000000000000000000000000000000000000000000000000000000",
          "maxTimeoutSeconds": 300
      },
      "payload": {
        "signature": "01a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f601",
        "publicKey": "0176197d7191ce519ed043221956a2227921abf30364d4362970229027ec828f04",
        "authorization": {
          "from":        "00048a54220799a48171743407c086668bdcc788e2a31e4185fe52d0682634f888",
          "to":          "009e5669b070545e2b32bc66363b9d3d4390fca56bf52a05f1411b7fa18ca311c7",
          "value":       "10000",
          "validAfter":  "1710000000",
          "validBefore": "1710000900",
          "nonce":       "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
        }
      }
    },
    "paymentRequirements": {
      "scheme": "exact",
      "network": "casper:casper-test",
      "payTo":  "009e5669b070545e2b32bc66363b9d3d4390fca56bf52a05f1411b7fa18ca311c7",
      "amount": "10000",
      "asset":  "9824d60dc3a5c44a20b9fd260a412437933835b52fc683d8ae36e4ec2114843e",
      "maxTimeoutSeconds": 900,
      "extra": {
        "name":     "Cep18x402",
        "version":  "1",
        "decimals": "2",
        "symbol":   "CSPR"
      }
    }
  }'
```

```json
{
  "isValid": true,
  "payer": "00048a54220799a48171743407c086668bdcc788e2a31e4185fe52d0682634f888"
}
```

When verification fails, the response includes `invalidReason` and `invalidMessage` instead of `payer`:

```json
{
  "isValid": false,
  "invalidReason": "invalid_signature",
  "invalidMessage": "Signature does not verify against the public key and EIP-712 digest."
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cspr.cloud/x402-facilitator-api/verify.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.