XRP Ledger Claimable Balances

A claimable balance is how Fordefi surfaces the XRP Ledger's Check mechanism when sending a Trust Line Asset to a recipient who does not yet have a trust line for that asset. Fordefi works with claimable balances in two scenarios:

1. Automatically creating a claimable balance when a Trust Line Asset transfer targets a recipient that has no trust line for that asset.
2. Cashing the Check for a claimable balance the vault holds.

When you send a Trust Line Asset to a recipient that has not yet established a trust line for that asset, a normal Payment would fail. To prevent this, Fordefi automatically checks the recipient's trust lines before building the transaction:

• If the recipient has a trust line, Fordefi builds a standard Payment transaction.
• If the recipient does not have a trust line, Fordefi builds a CheckCreate transaction instead, with the recipient as the destination. The funds stay in the sender's vault, and only leave it when the recipient establishes a trust line and cashes the Check. In the meantime, a 0.2 XRP owner reserve is locked on the sender's account.

This behavior is fully automatic: the request body is the same as any other Trust Line Asset transfer. No caller changes are required.

Fordefi does not support canceling a Check once created.

When your vault is the recipient of a Check, you can cash it with a ripple_cash_check request, referencing the Check-creating transaction by transaction_id. In the UI, such a transaction shows a gray completed status and a Cash Check action until it's cashed; you can also filter transaction history by claimed/unclaimed to find pending Checks.

If the vault does not yet have a trust line for the asset, Fordefi automatically prepends a TrustSet transaction. These are two separate ledger transactions, each with its own fee, presented as a single flow to the signer (a single signature on mobile; two separate entries in transaction history on web).

{
  "vault_id": "your_xrp_vault_id",
  "signer_type": "initiator",
  "type": "ripple_transaction",
  "details": {
    "type": "ripple_cash_check",
    "transaction_id": "source-checkcreate-tx-id",
    "fail_on_prediction_failure": true,
    "skip_prediction": false,
    "push_mode": "auto"
  }
}