# GET /v1/xrpl/paths

Multi-hop payment paths and their source cost.

## Purpose

Runs a live path search (`ripple_path_find`) on the validated ledger for delivering `amount` of `asset` from `source` to `destination`, and returns the `alternatives`: each with the estimated `source_amount` the source would spend (asset and decimal string), `paths_count` and the computed `paths` as compact steps (`account`, `currency`, `issuer`). A call can take up to about 20 seconds, because path finding is heavy for the node. Results are best effort: `paths_may_be_non_optimal` is always `true`, a cheaper path may exist and the amounts are estimates that can change by the time you submit. No alternative is a 200 with `alternatives: []`. A destination account that does not exist gives `alternatives: []` and the warning `destination_not_found`; a source account that does not exist is a 404. Answers are never cached: every call reads the ledger.

## When to use

Before a cross-currency or multi-hop payment: to see whether a route exists and how much the source would spend to deliver the amount. A call can take up to about 20 seconds and paths may be non-optimal.

## When not to use

To check whether a direct payment can succeed (use `/v1/xrpl/payment-readiness`), or for the single-hop cost of a trade on one pair (use `/v1/xrpl/slippage`, which compares the order book and the AMM).

## 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 | `rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B` |
| `asset` | query | yes | Asset the destination receives. | `XRP` or `CODE.issuer`: a 3-character or 40-hex code and a valid classic issuer address | `XRP` |
| `amount` | query | yes | Amount the destination receives, in units of `asset`. | Positive decimal string (no exponent); for `XRP` at most 6 decimals (1 drop) | `1` |
| `send_max_asset` | query | no | Asset of `send_max`. | `XRP` or `CODE.issuer`, as in `asset`; required with `send_max` | `XRP` |
| `send_max` | query | no | Most the source may spend, in units of `send_max_asset`. | Positive decimal string (for `XRP` at most 6 decimals); required with `send_max_asset`; not with `source_assets` | `2` |
| `source_assets` | query | no | Assets the source may spend, comma-separated. | 1 to 4 assets, comma-separated, each `XRP` or `CODE.issuer`; not with `send_max_asset`/`send_max` | `XRP` |

## Request example

```sh
curl -s "https://api.criptonlabs.com/v1/xrpl/paths?source=rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh&destination=rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B&asset=XRP&amount=1"
```

## Response example (200)

```json
{
  "paths_may_be_non_optimal": true,
  "warnings": [],
  "alternatives": [
    {
      "source_amount": {
        "asset": "USD.rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
        "value": "1.394"
      },
      "paths_count": 1,
      "paths": [
        [
          {
            "currency": "XRP"
          }
        ]
      ]
    }
  ],
  "meta": {
    "ledger_index": 100234566,
    "as_of": "2026-10-06T12:00:03.000Z",
    "age_seconds": 0,
    "cache": "miss",
    "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)
- 404 [not-found](https://api.criptonlabs.com/errors/not-found.md)
- 429 [rate-limited](https://api.criptonlabs.com/errors/rate-limited.md)
- 503 [upstream-unavailable](https://api.criptonlabs.com/errors/upstream-unavailable.md)

## Caching

Never cached: every call is a live read of the validated ledger (`meta.cache` is `miss`, `meta.stale` is `false`, `Cache-Control: no-store`), and no stale value is ever served; when no node answers, the service answers 503.

## Rate limit

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

## MCP tool

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