Reading an order book

An order book is two lists facing each other. One list holds people selling FOO for XRP. The other holds people selling XRP for FOO. Each list is sorted so the best deal is on top.

Explorers and trading apps draw this as a table of prices and sizes. Underneath, they all ask a server the same question: "Show me the offers for this pair."

Three things help when you read a book:

• Check the issuer. "USD" from one issuer and "USD" from another are different books.
• Size on screen is not a promise. Offers do not lock funds. An owner may hold less than the offer says. Servers report how much is funded.
• The book moves every ledger. A new ledger closes every 3 to 5 seconds. What you saw may be gone when your trade lands.

Your trade is settled only when the ledger that holds it is validated. Until then the result is tentative. Other transactions in the same ledger can run before yours and change what is left for you.

The DEX knows nothing about who is behind an account. Anyone can trade in the open books. Issuers who must restrict their token use tools such as authorized trust lines and freezes.

book_offers returns the offers for one direction of a pair.

Request fields:

• taker_gets: the asset the taker would receive, as a currency without an amount.
• taker_pays: the asset the taker would pay.
• taker (optional): an address to use as a perspective. That account's own offers are included even if unfunded.
• limit (optional): the maximum number of offers to return.
• domain (optional): a permissioned domain ID. Returns that permissioned DEX's book instead of the open one.

Swap taker_gets and taker_pays to read the other side.

The response omits unfunded offers. Each remaining offer includes the Offer entry's fields plus:

XRP amounts are strings in drops. Token amounts are objects with currency, issuer and value.

account_offers lists the offers one account has placed.

Identifying an offer. An Offer entry is identified by its Account and the Sequence of the OfferCreate that made it. That sequence number is what OfferCancel takes.

Tracking. The ledger does not proactively remove unfunded or expired offers. A client that needs a precise book can load it with book_offers, subscribe to the transactions stream and apply the changes from transaction metadata.

Finality. Transactions in one ledger apply in a canonical order that differs from the order they were sent. Tentative results can change. Read the validated result before treating a trade as done.

Related: Permissioned Domains and DEX, Placing an offer.