Placing an offer

Placing an offer is like pinning a note to a board: "Selling 50 FOO for 500 XRP." The note costs a small deposit while it hangs there. On the ledger that deposit is 0.2 XRP of reserve. You get it back when the note comes down.

The note does not lock your FOO. You can still spend it. You can pin several notes that sell the same FOO. If someone takes a note and you no longer have the FOO, that note fills only as far as your balance goes. The rest is canceled.

You can ask for different handling:

• Normal. Fill what matches now. The rest waits.
• Immediate or cancel. Fill what matches now. Drop the rest.
• Fill or kill. Fill everything now, or do nothing.
• Passive. Do not take offers at exactly your rate. Wait in the book beside them.

You can also set an expiry time. After it passes, the offer can no longer fill.

A note comes down when:

• Someone fills it completely.
• You cancel it.
• You place a new offer that would trade against your own old one.
• The ledger finds it expired or without funds while processing another trade.

Dead offers are not swept up on a timer. An expired or unfunded offer stays in the ledger, and keeps its reserve locked, until some transaction touches it.

Buy and sell. By default an offer is a buy: it is done when the owner has received the full TakerPays amount, even if that took less than TakerGets. With tfSell (0x00080000), it is done when the full TakerGets amount is spent, even if that brings in more than TakerPays. The difference matters only when the offer first executes at a better rate than requested.

Other flags

tfImmediateOrCancel with tfFillOrKill is invalid (temINVALID_FLAG).

Funding. To sell a token, the owner must hold a positive amount of it or be its issuer. Otherwise the result is tecUNFUNDED_OFFER. To sell XRP, the owner needs XRP left over after all reserves, including the reserve for the new offer and for any trust line the trade would create. An offer cannot push a token balance below zero unless the owner is the issuer.

Trust lines. Trust line limits do not restrict offers. If the owner has no line for the token being bought, filling the offer creates one with a limit of 0. That line needs its own 0.2 XRP reserve.

Expiration. Expiration is in seconds since the Ripple Epoch. An offer is expired when that time is earlier than or equal to the close time of the previous ledger. A transaction whose Expiration has already passed fails with tecEXPIRED.

Unfunded offers stay in the ledger until a transaction removes them. An offer becomes unfunded when the owner runs out of the asset, the trust line is frozen, the owner lacks XRP for a needed trust line, or the offer expires.

Canceling. OfferCancel takes OfferSequence, the sequence number of the OfferCreate that made the offer. It returns tesSUCCESS even when no such offer exists. OfferCreate also accepts OfferSequence, which cancels the old offer and places a new one in a single transaction.

If the owner cannot cover the reserve for a new Offer entry and nothing traded, the result is tecINSUF_RESERVE_OFFER. If some amount traded, the transaction succeeds and no entry is created for the rest.

Related: Owner reserve, Freeze, Deep Freeze and Clawback.