# GET /v1/xrpl/payment-readiness

Pre-payment check: can this payment from source to destination succeed now?

## Purpose

Checks, before you sign, whether a payment of `asset` (default `XRP`) from `source` to `destination` can succeed on the validated ledger, and returns a `verdict`: `ready`, `not_ready` (at least one blocking reason) or `unknown` (no blocking reason, but a sub-check could not run; never treat `unknown` as `ready`). A missing account is a reason, not an error: this endpoint never answers 404. Without `amount` the amount-dependent checks are skipped. `spendable_xrp` is the source XRP above its live reserve (base plus owner count times increment, from the server state) and the standard fee; `transfer_fee_pct` is the issuer transfer fee when it applies. Warnings never change the verdict.

Reason codes: `source_not_found`, `insufficient_xrp_balance`, `source_line_missing`, `insufficient_token_balance`, `source_line_frozen`, `destination_not_found`, `amount_below_destination_reserve`, `destination_tag_required`, `deposit_not_authorized`, `destination_line_missing`, `destination_line_limit_exceeded`, `destination_line_frozen`, `issuer_not_found`, `issuer_global_freeze`.

Warning codes: `destination_will_be_created`, `transfer_fee`, `high_fee`, `network_degraded`.

Sub-check codes: `source_account`, `destination_account`, `deposit_authorized`, `source_line`, `destination_line`, `issuer`, `fee`, `network_health`.

## When to use

Right before sending a payment: to catch a missing or unfunded destination, a required destination tag, deposit authorization, missing or frozen trust lines, insufficient balance and issuer freezes, in one call.

## When not to use

To find a multi-hop route or the source amount needed for a cross-currency payment (use the paths endpoint), or to list balances (use `/v1/xrpl/account/{address}/summary`).

## Parameters

| Name | In | Required | Description | Constraints | Example |
|---|---|---|---|---|---|
| `source` | query | yes | Sending account. | Valid classic XRPL address (r..., checksum verified) | `rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh` |
| `destination` | query | yes | Receiving account. | Valid classic XRPL address, different from `source` | `rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B` |
| `asset` | query | no | Asset to deliver. | `XRP` (default) or `CODE.issuer`: a 3-character or 40-hex code and a valid classic issuer address | `XRP` |
| `amount` | query | no | Amount to deliver, in units of `asset`. | Positive decimal string (no exponent); omit to skip amount-dependent checks | `10` |
| `destination_tag` | query | no | Destination tag you will send. | Integer from 0 to 4294967295 | `12345` |

## Request example

```sh
curl -s "https://api.criptonlabs.com/v1/xrpl/payment-readiness?source=rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh&destination=rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B&amount=10"
```

## Response example (200)

```json
{
  "verdict": "not_ready",
  "reasons": [
    "destination_tag_required"
  ],
  "warnings": [],
  "checks_failed": [],
  "spendable_xrp": "98.995",
  "transfer_fee_pct": null,
  "source": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
  "destination": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
  "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_payment_readiness` returns the same data. See the [MCP quickstart](https://api.criptonlabs.com/docs/guides/mcp-quickstart.md).