Last updated
Edit

Offer

[Source]

The Offer ledger entry describes an Offer to exchange currencies in the XRP Ledger's decentralized exchange. (In finance, this is more traditionally known as an order.) An OfferCreate transaction only creates an Offer entry in the ledger when the Offer cannot be fully executed immediately by consuming other Offers already in the ledger.

An Offer can become unfunded through other activities in the network, while remaining in the ledger. When processing transactions, the network automatically removes any unfunded Offers that those transactions come across. (Otherwise, unfunded Offers remain, because only transactions can change the ledger state.)

Example Offer JSON

{
    "Account": "rBqb89MRQJnMPq8wTwEbtz4kvxrEDfcYvt",
    "BookDirectory": "ACC27DE91DBA86FC509069EAF4BC511D73128B780F2E54BF5E07A369E2446000",
    "BookNode": "0000000000000000",
    "Flags": 131072,
    "LedgerEntryType": "Offer",
    "OwnerNode": "0000000000000000",
    "PreviousTxnID": "F0AB71E777B2DA54B86231E19B82554EF1F8211F92ECA473121C655BFC5329BF",
    "PreviousTxnLgrSeq": 14524914,
    "Sequence": 866,
    "TakerGets": {
        "currency": "XAG",
        "issuer": "r9Dr5xwkeLegBeXq6ujinjSBLQzQ1zQGjH",
        "value": "37"
    },
    "TakerPays": "79550000000",
    "index": "96F76F27D8A327FC48753167EC04A46AA0E382E6F57F32FD12274144D00F1797"
}

Offer Fields

In addition to the common fields, Offer entries have the following fields:

NameJSON TypeInternal TypeRequired?Description
AccountStringAccountIDYesThe address of the account that owns this Offer.
BookDirectoryStringHash256YesThe ID of the Offer Directory that links to this Offer.
BookNodeStringUInt64YesA hint indicating which page of the offer directory links to this entry, in case the directory consists of multiple pages.
ExpirationNumberUInt32NoIndicates the time after which this Offer is considered unfunded. See Specifying Time for details.
LedgerEntryTypeStringUInt16YesThe value 0x006F, mapped to the string Offer, indicates that this is an Offer entry.
OwnerNodeStringUInt64YesA hint indicating which page of the owner directory links to this entry, in case the directory consists of multiple pages.
PreviousTxnIDStringHash256YesThe identifying hash of the transaction that most recently modified this entry.
PreviousTxnLgrSeqNumberUInt32YesThe index of the ledger that contains the transaction that most recently modified this object.
SequenceNumberUInt32YesThe Sequence value of the OfferCreate transaction that created this offer. Used in combination with the Account to identify this offer.
TakerPaysCurrency AmountAmountYesThe remaining amount and type of currency requested by the Offer creator.
TakerGetsCurrency AmountAmountYesThe remaining amount and type of currency being provided by the Offer creator.

Offer Flags

Offer entries can have the following flags combined into the Flags field:

Flag NameHex ValueDecimal ValueCorresponding OfferCreate FlagDescription
lsfPassive0x0001000065536tfPassiveThe offer was placed as "passive". This has no effect after the offer is placed into the ledger.
lsfSell0x00020000131072tfSellThe offer was placed as a "Sell" offer. This has no effect after the offer is placed in the ledger, because tfSell only matters if you get a better rate than you asked for, which can only happen when the offer is initially placed.

Offer Reserve

Offer entries count as one item towards the owner reserve of the account that placed the offer, as long as the entry is in the ledger. Canceling or consuming the offer frees up the reserve. The reserve is also freed up if the offer is removed because it was found unfunded.

Offer ID Format

The ID of an Offer entry is the SHA-512Half of the following values, concatenated in order:

  • The Offer space key (0x006F)

  • The AccountID of the account placing the Offer

  • The Sequence number of the OfferCreate transaction that created the Offer.

    If the OfferCreate transaction used a Ticket, use the TicketSequence value instead.