At digital asset exchanges, the order book liquidity doesn't always allow a large amount of digital assets to be executed as a single trade. When this happens, the payment sender has to split their payment into smaller tranches. RippleNet's Smart Liquidation service resolves this problem by splitting large XRP liquidations into smaller liquidations over a specified time period.
Payment size determines whether a liquidation gets routed through Smart Liquidation or through the traditional one-to-one liquidation. Ripple sets that payment size or an exchange and trading pair threshold.
One-to-one liquidation means that the entire payment is liquidated at once instead of split into multiple liquidations.
The Smart Liquidation service provides the following features compared to the traditional one-to-one Liquidation service:
- Reduces or entirely eliminates the need to split up payments for liquidation manually.
- Facilitates reconciliation by decreasing the number of payments you have to make.
For more information, see Specifics.
The Smart Liquidation service supports the following use cases:
- The sender's wallet is set up to originate the payment in XRP and the receiver's wallet is set up to receive the payment in XRP. See also Example .
- The sender's wallet is set up to originate the payment in fiat currency and the receiver's wallet is set up to receive the payment in XRP.
The following example describes the two phases of a payment transaction and the point at which Smart Liquidation gets triggered:
Payment phase: A sender requests an On-Demand Liquidity (ODL) value payment of $1M USD and then originates a 1M XRP payment (according to the order book rate). The XRP is transferred from their wallet to the receiver's wallet. The receiver then confirms the XRP deposit, which puts the payment in the
Trade phase (from XRP to fiat): Smart Liquidation gets triggered automatically on the receiver side and splits the transfer into 100 equal-sized trades of 10K USD each. If no failures occur throughout the liquidation process, each of those trades is executed at 30 second-intervals resulting in a total of 50 minutes for the requested $1M USD to arrive in the receiver's wallet.
If you want to use the Smart Liquidation service, consider the following:
The liquidation triggers are the same with both Smart Liquidation and the traditional one-to-one liquidation; that is, once the XRP deposit is in the receiver's exchange wallet and the payment is in
EXECUTEDstate. However, to use the Smart Liquidation service, you need to change your liquidation configuration to use the
For more information, see "Liquidation Configuration operations" in the API reference.
- As the receiver of a payment, you must have a wallet set up to receive payments in XRP (instead of fiat currency).
Your setup may require further configuration changes to use the Smart Liquidation service. For more information, contact your RippleNet liaison.
The following sections describe the Smart Liquidation service's specifics, which are centered around the reconciliation of liquidation, the liquidation duration, and automatic retries.
Reconciliation is the process of matching internal transaction records against periodic statements from multiple sources, including partner financial institutions. Reconciliation ensures that both (or all) parties agree on the number and value of transactions. You can perform reconciliation at the transaction level or the balance level.
Since RippleNet is used by partners to make payments, both the sender and receiver should periodically reconcile internal transactions against RippleNet data to ensure that payments and balances match expectations.
The Smart Liquidation service includes the liquidation API operations Get liquidations and Get liquidation by ID that return records of liquidations. You can use this data to reconcile liquidations against your periodic statements. As a receiver, you can use the operation to reconcile data in one of the following ways:
On a daily basis:
You can use the
end_dateparameters to get all liquidations for the specified time period. You can then use this information to validate that the total fiat received in the exchange wallet matches those liquidations with the RippleNet fiat payouts as specified within the payment quote.
For more information, see Get liquidations in the API reference.
On a per-payment basis:
You can get all liquidations associated with a specific liquidation ID, which is tied to a subset of liquidation IDs.
For more information, see Get liquidation by ID in the API reference.
The liquidation duration depends on the liquidation amount and the crypto exchange used. On average, most liquidations make fiat deposits of $10-20K per minute, including a 30-second delay between each trade.
The Smart Liquidation service guarantees fiat delivery as it continuously executes liquidations until the fiat amount traded matches the fiat amount paid out by the receiver (based upon the RippleNet payment quote).
The Smart Liquidation service tracks liquidations as they occur to make an aggregate calculation of how much XRP has been successfully liquidated into fiat currency. All liquidations that fail with a known reason are pushed to the end of the queue and automatically retried at a later time. A known reason is any reason within the RippleNet liquidation management, for example, a timeout of the ODL service, or the exchange can't execute the trade. Failed liquidations are retried for up to eight hours, which is the maximum amount of time for liquidations to complete.
Ripple is currently working on a retry approach for liquidations that fail with an unknown reason.
Currently, if you're a treasury use case customer and you're using Bitso as your payout exchange, the payment is automatically directed to your designated beneficiary's bank account --- however, you must still specify
spei as the payout method. Other payout exchanges require a manual payout process, but will be added to the automatic payout process on an ongoing basis.