Cross-currency payments and paths
4 minDifficulty Checked 2026-11-10- A cross-currency payment sends one currency and delivers another in a single transaction.
- Paths are the routes: trust lines, order books and AMM pools between sender and receiver.
- The payment is atomic. Either the whole payment executes or none of it does.
You hold XRP. Your friend wants to be paid in a dollar token. On the XRP Ledger one payment can do both jobs: take XRP from you, swap it, and deliver the token to your friend.
The swap happens inside the ledger's built-in exchange, the DEX. Other people have left offers there, and AMM pools hold pairs of assets. Your payment takes the best rates it finds.
The route a payment takes is called a path. Think of stepping stones across a river. Each stone is one of two things:
- A hop through an account that holds the same token on two trust lines. This is called rippling.
- A trade in an order book or an AMM pool that changes one currency into another.
A payment can use several paths at once and pull a little from each.
The payment is all or nothing. Your friend gets the full amount or the payment fails and nothing moves. You are never left halfway, holding a currency you did not want.
You set two numbers. The first is what your friend must receive. The second is the most you are willing to spend. If the route costs more than your limit, the payment fails.
Two token payments can also hop through XRP in the middle when that is cheaper. Selling token A for XRP, then XRP for token B, is called auto-bridging.
A cross-currency payment is a Payment where the sent and delivered assets differ. At least one of them must be a token. Conversion consumes Offer entries and AMM liquidity in the DEX.
| Field | Role |
|---|---|
DeliverMax (Amount in API v1) | Currency and amount to deliver |
SendMax | Most source currency the payment may cost. Required for cross-currency payments |
Paths | A path set: an array of paths. Auto-fillable |
By default the delivered amount is fixed and the cost to the sender varies, up to SendMax. SendMax covers transfer fees and exchange rates. It does not include the XRP transaction cost.
Path steps. Each step is an object with one of these shapes:
account: ripple through that address in the same currency.currency, optionally withissuer: change currency through an order book or AMM.issueralone: change issuers within the same currency code.
The first and last steps are implied by Account and Destination. The issuers named in SendMax and DeliverMax imply the second and second-to-last steps.
Default path. A payment can also run along the default path, the most direct link between the implied steps. For a cross-currency payment that is the order book or AMM between the source and destination currencies. tfNoRippleDirect (0x00010000) disables it, so only the listed paths are used.
Pathfinding. ripple_path_find does a one-time lookup of path sets. path_find is WebSocket only and sends updates as ledgers close. The server does not promise the cheapest path. Rates can change between submission and execution, which is what SendMax protects against.
Failures.
| Code | Meaning |
|---|---|
tecPATH_DRY | The paths had no liquidity to send anything |
tecPATH_PARTIAL | The paths could not deliver the full amount |
Not on paths. XRP-to-XRP payments and MPT transfers are always sent directly.
Related: Trust lines and issued tokens, The DEX, AMM.
- Cross-Currency PaymentsRead 2026-11-10
- PathsRead 2026-11-10
- PaymentRead 2026-11-10
- tec CodesRead 2026-11-10
