# GET /v1/xrpl/x402/preflight

Can this payer settle this x402 payment requirement right now?

## Purpose

Takes one x402 v2 `exact` requirement as an XRPL server states it (`asset` with its `issuer` from `extra.issuer`, `amount`, `pay_to`, and `destination_tag` from `extra.destinationTag`) plus the `payer` wallet, and answers one `verdict`: `block` on any blocker, `warn` with warnings only, else `ok`. `amount` is in drops for XRP and in token units for an issued currency; drops are converted to XRP and `destination_tag` is passed on before the payer's payment readiness is evaluated for that payment. `readiness` is what `/v1/xrpl/payment-readiness` answers for the same payer, recipient, asset and amount, without its `meta`, so both routes can be compared field by field; each readiness blocking reason becomes the blocker `payer_<code>` and each readiness warning the warning `payer_<code>`. A `pay_to` that is an AMM, vault or loan broker pseudo-account is the blocker `pay_to_not_wallet`, and `destination_is_pseudo_account` is then not repeated as `payer_destination_is_pseudo_account`; every other readiness code is still copied. A readiness `verdict` of `unknown` gives the warning `payer_readiness_unknown`, so never read a `warn` as a cleared payment. An issued `asset` that is not a canonical stablecoin of the registry gives the warning `asset_not_canonical`; `XRP` is not compared with the registry and never gives it. `pay_to` must differ from `payer`: the same address is a 400 naming `pay_to`, and nothing is read. The check makes exactly the readiness reads and no others.

| Code | What it states | Blocks or warns |
|---|---|---|
| `pay_to_not_wallet` | `pay_to` is an AMM, vault or loan broker pseudo-account | blocks |
| `asset_not_canonical` | `asset` is not the canonical stablecoin of the registry (never `XRP`) | warns |
| `payer_readiness_unknown` | the payer's readiness `verdict` is `unknown`, so the payment is not cleared | warns |
| `payer_*` | every applicable payer readiness blocker or reason appears with the prefix `payer_` (`payer_<code>`), and each readiness warning appears as the warning `payer_<code>`; the codes are those of `/v1/xrpl/payment-readiness` | blocks or warns, as the readiness code does |

## When to use

After an x402 server answered 402 with an XRPL `exact` requirement: to check, before signing, that this payer can settle that exact requirement to that recipient now.

## When not to use

For a payment that is not an x402 requirement (use `/v1/xrpl/payment-readiness`), or once the payment has settled (use `/v1/xrpl/payment/verify`).

## Parameters

| Name | In | Required | Description | Constraints | Example |
|---|---|---|---|---|---|
| `asset` | query | yes | Asset of the requirement: `XRP`, or the currency code of an issued asset, whose issuer goes in `issuer`. Standard codes are case-sensitive: `usd` and `USD` are different tokens. | `XRP`, a 3-character currency code (case-sensitive) or 40 hexadecimal characters; the 40-hex form of XRP is not accepted | `XRP` |
| `issuer` | query | no | Issuer of the asset (`extra.issuer` of the requirement); required unless the asset is `XRP`. | Valid classic XRPL address (r..., checksum verified) | `rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B` |
| `amount` | query | yes | Amount the requirement asks for: drops for XRP, token units for an issued asset. | Positive decimal string (no exponent); an XRP amount is a whole number of drops (digits only) | `10000000` |
| `pay_to` | query | yes | Account the requirement pays. | Valid classic XRPL address (r..., checksum verified) | `rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq` |
| `payer` | query | yes | Wallet that would pay. | Valid classic XRPL address (r..., checksum verified) | `rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B` |
| `destination_tag` | query | no | Destination tag the requirement states (`extra.destinationTag`); it is passed to the readiness check. | Integer from 0 to 4294967295 | `12345` |

## Request example

```sh
curl -s "https://api.criptonlabs.com/v1/xrpl/x402/preflight?asset=XRP&amount=10000000&pay_to=rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq&payer=rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
```

## Response example (200)

```json
{
  "verdict": "block",
  "blockers": [
    "payer_destination_tag_required"
  ],
  "warnings": [],
  "readiness": {
    "verdict": "not_ready",
    "reasons": [
      "destination_tag_required"
    ],
    "warnings": [],
    "checks_failed": [],
    "spendable_xrp": "412525.891965",
    "transfer_fee_pct": null,
    "required_source_balance": {
      "asset": "XRP",
      "value": "86.6"
    },
    "max_sendable": {
      "asset": "XRP",
      "value": "412525.891965"
    },
    "source": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
    "destination": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
    "asset": "XRP",
    "amount": "10",
    "destination_tag": null
  },
  "meta": {
    "ledger_index": 100234566,
    "as_of": "2026-10-06T12:00:03.000Z",
    "age_seconds": 2,
    "cache": "hit",
    "stale": false
  }
}
```

## Errors

- 400 [invalid-parameters](https://api.criptonlabs.com/errors/invalid-parameters.md)
- 400 [bad-request](https://api.criptonlabs.com/errors/bad-request.md)
- 429 [rate-limited](https://api.criptonlabs.com/errors/rate-limited.md)
- 503 [upstream-unavailable](https://api.criptonlabs.com/errors/upstream-unavailable.md)

## Caching

Fresh for 4 seconds; on upstream failure the last good value is served for up to 60 seconds (`meta.stale` is `true`), then the service answers 503. See the [freshness guide](https://api.criptonlabs.com/docs/guides/freshness.md).

## Rate limit

Tier `expensive`. See the [rate-limits guide](https://api.criptonlabs.com/docs/guides/rate-limits.md).

## MCP tool

The MCP tool `xrpl_x402_preflight` returns the same data. See the [MCP quickstart](https://api.criptonlabs.com/docs/guides/mcp-quickstart.md).
