How to create time-locked XRP payments?
Last updated:
Time-locked XRP payments on the XRP Ledger can be created using the Escrow feature, which locks XRP until specific time conditions are met. Escrows support time-based locks (funds release after a certain time), conditional locks (funds release when cryptographic conditions are satisfied), or combinations of both, enabling sophisticated payment patterns for contracts, vesting schedules, and trust-minimized transactions.
Creating a time-locked escrow uses the EscrowCreate transaction, which transfers XRP from your account into escrow, where it's held until release conditions are met. The fundamental fields include Destination (who receives the XRP), Amount (how much XRP in drops), and timing parameters controlling when funds can be released.
The FinishAfter field specifies the earliest time the escrow can be finished, expressed in Ripple Epoch time (seconds since January 1, 2000, 00:00 UTC). Before this time, no one can execute the escrow. After this time, anyone can submit an EscrowFinish transaction to release the XRP to the destination account.
The CancelAfter field specifies when the escrow expires, also in Ripple Epoch time. After this time, the escrow can no longer be finished, and anyone can submit an EscrowCancel transaction to return the XRP to the original sender. This creates an expiration window: FinishAfter to CancelAfter defines the period when the escrow can be successfully completed.
A simple time-locked payment might use FinishAfter set to one week in the future without CancelAfter. The XRP is locked for a week, then can be claimed by the destination anytime afterward. This pattern works for delayed payments, vesting schedules, or trust-building mechanisms where you want to prove funds are committed but not immediately accessible.
Addition of CancelAfter creates time-bounded escrows. For example, FinishAfter set to 1 week and CancelAfter set to 2 weeks creates a 1-week window (days 7-14) when the escrow can be finished. Before day 7, it's too early. After day 14, it expires and returns to sender. This pattern suits time-limited offers or agreements with deadlines.
Escrow IDs uniquely identify each escrow, derived from the creating transaction's hash and source account. To finish or cancel an escrow, you reference this ID in EscrowFinish or EscrowCancel transactions. Tracking escrow IDs is important - you'll need them to interact with escrows later.
Finishing an escrow requires submitting an EscrowFinish transaction specifying the Owner (account that created the escrow), OfferSequence (sequence number of the EscrowCreate transaction), and Destination. Anyone can submit this transaction once the FinishAfter time passes - it doesn't require signatures from the escrow creator or destination.
Canceling an escrow similarly requires an EscrowCancel transaction with Owner and OfferSequence. Again, anyone can submit this once CancelAfter passes. This open-submission design means you don't need cooperation from other parties to release or cancel escrows when conditions permit.
Escrow reserves increase the account reserve requirement. Each escrow increases the owner's reserve by 2 XRP while it exists. These reserves are returned when the escrow is finished or canceled. For accounts with many escrows, reserve requirements can become significant.
Query escrows using the account_objects API method with type filter for "escrow". This returns all escrows created by or paid to an account, showing their amounts, timing parameters, and conditions. Wallet software can display pending escrows and enable finishing or canceling them when conditions allow.
Practical use cases for time-locked payments include: vesting schedules for employee compensation (regular escrows releasing over time), contract deposits that return if work isn't completed, trust-building in transactions where you prove funds are committed, and scheduled payments that execute automatically at future dates.
Combining multiple escrows creates complex release schedules. For monthly vesting over a year, create 12 escrows with FinishAfter times offset by month. Each month, one escrow becomes claimable. This provides transparent, enforceable vesting without requiring ongoing trust.
Time precision in escrows depends on ledger close times, not wall-clock time. The FinishAfter and CancelAfter times are compared against ledger close times. Since ledgers close every 3-5 seconds, escrow timing has similar precision - you can't time releases to the exact second, but 3-5 second precision is achievable.
Gas and fee considerations: EscrowCreate consumes a normal transaction fee. EscrowFinish and EscrowCancel also require transaction fees paid by whoever submits them. In some scenarios, the destination might need to finish escrows themselves, requiring they have XRP for fees.
Conditional escrows add cryptographic conditions using Condition and Fulfillment fields (discussed in the next FAQ). Time-locked escrows use only timing parameters without conditions, making them simpler but less flexible.
Error handling for time-locked payments: if FinishAfter is in the past when creating an escrow, it can be finished immediately. If CancelAfter is before FinishAfter, the escrow can never be finished - it's instantly cancelable. Wallet software should validate parameters before submission.
Monitoring escrows for management: applications should track created escrows, alert users when escrows become finishable, automatically submit finish transactions when appropriate, and handle cancellations for expired escrows. Automated escrow management improves user experience.
Security considerations: XRP in escrow is inaccessible until release conditions are met. Even the account owner cannot retrieve it early. This provides certainty for recipients but means mistakes (like setting FinishAfter far in the future) lock funds for extended periods.