Smart Liquidation

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 on an exchange and trading pair threshold.

Note

One-to-one liquidation means that the entire payment is liquidated at once instead of split into multiple liquidations.

Features

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.

Use cases

The Smart Liquidation service supports the following use cases:

  1. 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 .
  2. 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.

Example

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 EXECUTED state.

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.

Prerequisites

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 EXECUTED state.
  • 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.

Specifics

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 of liquidation

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 start_date and end_date parameters 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 payment, which is tied to a subset of liquidation IDs.
    Note:

    One or more failed payment liquidations show a status of PARTIALLY_COMPLETED. If a liquidation continues to fail after repeated automatic retries, the Ripple Payment Operations team manually re-triggers the failed liquidation(s) for this payment. When you then run the Get liquidations by payment ID operation, an array with two or more liquidations is returned. The first liquidation shows a status of PARTIALLY_COMPLETED and the second and subsequent liquidation(s) show a status of COMPLETED. Combined, those statuses indicate that the liquidations have completed and that the payment was successful.

    For more information, see Get liquidations by payment ID in the API reference.

Liquidation duration

The execution window of Smart Liquidation transactions starts after the payment initiation. If a liquidation can't be completed within eight hours, you must split the payment into smaller payments. Currently, the largest transaction that can be completed within eight hours is approximately $10M. For details, contact your RippleNet liaison.
Note

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.

Automatic retries

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.

Note

Ripple is currently working on a retry approach for liquidations that fail with an unknown reason.

Automatic payout

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.