Edge cases

The standard happy-path of a swap is described in Quote display and user preferences and Transaction status. This page lists the edge cases a partner integration must handle, with the contracts each side is expected to honour.

For the meaning of terms used here (payinNetworkFees, fixed/floating quote, OnHold, …) see the Exchange glossary.

Refund: transaction cannot complete

The user has sent the FROM crypto to the partner but the swap can no longer be completed (for example the destination side fails). The partner sends the funds back to the user’s source address.

Behaviour	Detail
Funds returned	Partner refunds the FROM crypto, minus `payinNetworkFees`.
User-visible status	Maps to Refunded in transaction status, final and not retried.
Partner guidance	Refuse swaps where the input amount does not cover `payinNetworkFees` at least twice over, otherwise the refund will arrive with a near-zero or negative balance.

OnHold: extra information needed from the user

The partner has received the funds but cannot complete the swap until the user provides additional information (for example a KYC step triggered by the amount or destination). The funds are not at risk; they are paused on the partner’s side.

Behaviour	Detail
Display	Ledger Wallet shows the transaction as OnHold in the history tab.
Action	The user must contact the partner’s support, using the Swap ID the partner returned at swap creation.
Partner guidance	Surface the contact channel on the partner’s status page so it is one click away from the Swap ID.

Quote unavailability

Before showing a quote, Ledger Wallet calls the partner’s quote endpoint. The endpoint must reply with one of the Region / Token / Amount checks so the right error message is surfaced. Specifically:

Region NOT AVAILABLE: the user’s region is unsupported by this partner.
Token NOT AVAILABLE: the FROM/TO pair is unsupported.
Amount TOO LOW / TOO HIGH: the input amount is outside the partner’s bounds.

If the partner does not reply within 5 seconds, the partner’s quote is dropped from the result list. The user can either trigger a new quote or wait for another partner.

Fixed quote expiry

A fixed quote must be guaranteed for at least 60 seconds. If the user takes longer than the partner’s window to confirm on the device, the quote becomes invalid and Ledger Wallet returns the user to the quote selection step. The partner must then return a fresh quote, and never silently re-rate at acceptance time.

Floating quote slippage

A floating quote is not guaranteed. The user can receive less than the displayed amount according to market fluctuations, but the partner must enforce a maximum slippage so the executed rate cannot drift arbitrarily far. Surface this maximum slippage in the partner’s UI so the user knows the worst-case receiving amount before signing.

Single sign-on across Buy and Swap

If the same partner is integrated in both Buy and Swap (or other Exchange flows), a user who logs in for Buy is expected to remain logged in for Swap during the session window the partner sets, and vice versa. Asking the user to log in twice in the same Ledger Wallet session is an integration bug.