EscrowCreate
Set aside funds in an escrow that delivers them to a predetermined recipient when certain conditions are met. If the escrow has an expiration, the funds can also be returned to the sender after it expires.
To escrow fungible tokens you must take note of the following:
- Trust Line Tokens must have the Allow Trust Line Locking flag enabled on their account.
- Multi-Purpose-Tokens (MPTs) must have both the Can Escrow and Can Transfer flags enabled.
- All token escrows must specify a Cancel After time.
- If the token requires authorization, both sender and recipient must be pre-authorized by the issuer.
Requires the TokenEscrow amendment. Loading...
Example EscrowCreate JSON
{
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"TransactionType": "EscrowCreate",
"Amount": "10000",
"Destination": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
"CancelAfter": 533257958,
"FinishAfter": 533171558,
"Condition": "A0258020E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855810100",
"DestinationTag": 23480,
"SourceTag": 11747
}EscrowCreate Fields
In addition to the common fields, EscrowCreate transactions use the following fields:
| Field | JSON Type | Internal Type | Description |
|---|---|---|---|
Amount | Object or String | Amount | Amount of XRP, in drops, or fungible tokens to deduct from the sender's balance and escrow. Once escrowed, the payment can either go to the Destination address (after the FinishAfter time) or be returned to the sender (after the CancelAfter time). Requires the TokenEscrow amendment. Loading... |
Destination | String | AccountID | Address to receive escrowed funds. |
CancelAfter | Number | UInt32 | (Optional for XRP escrows, but mandatory for token escrows) The time, in seconds since the Ripple Epoch, when this escrow expires. This value is immutable; the funds can only be returned to the sender after this time. |
FinishAfter | Number | UInt32 | (Optional) The time, in seconds since the Ripple Epoch, when the escrowed funds can be released to the recipient. This value is immutable, and the funds can't be accessed until this time. |
Condition | String | Blob | (Optional) Hex value representing a PREIMAGE-SHA-256 crypto-condition. The funds can only be delivered to the recipient if this condition is fulfilled. If the condition is not fulfilled before the expiration time specified in the CancelAfter field, the funds can only revert to the sender. |
DestinationTag | Number | UInt32 | (Optional) Arbitrary tag to further specify the destination for this escrowed payment, such as a hosted recipient at the destination address. |
You must specify one of the following combinations of fields:
| Summary | FinishAfter | Condition | CancelAfter |
|---|---|---|---|
| Time-based (XRP only) | ✅ | ||
| Time-based with expiration | ✅ | ✅ | |
| Timed conditional (XRP only) | ✅ | ✅ | |
| Timed conditional with expiration | ✅ | ✅ | ✅ |
| Conditional with expiration | ✅ | ✅ |
It is not possible to create a conditional escrow with no expiration, but you can specify an expiration that is very far in the future.
Before the fix1571 amendment became enabled on 2018-06-19, it was possible to create an XRP escrow with CancelAfter only. These escrows could be finished by anyone at any time before the specified expiration.
Error Cases
Besides errors that can occur for all transactions, EscrowCreate transactions can result in the following transaction result codes:
| Error Code | Description |
|---|---|
tecNO_PERMISSION | The transaction failed because the necessary permissions for token escrow are not in place. For example, the issuer hasn't enabled the Allow Trust Line Locking flag for a Trust Line Token. |
tecNO_AUTH | The transaction failed because authorization requirements for the token were not met. For example, the sender lacks authorization when creating the escrow. |
tecUNFUNDED | The sender lacks sufficient spendable balance. For Trust Line Tokens, this means the sender's trust line with the issuer has insufficient available balance. For XRP escrows, this means the sender doesn't have enough XRP. |
tecOBJECT_NOT_FOUND | The sender does not hold the MPT. |
tecFROZEN | The token is frozen (for Trust Line Tokens) or locked (for MPTs) for the sender. |