The trade lifecycle and escrow

A trade is the only object in P2P that moves money. Everything about how it is built exists to guarantee one property: a trade's escrow is paid out at most once, no matter which of the six doors settles it.

The state machine

                 buyer confirms          seller releases
   PENDING ──────────────────────► PAYMENT_SENT ──────────────► COMPLETED
      │                                  │
      │ buyer cancels — or the seller,   │ either party disputes
      │ once the payment window passes   ▼
      ▼                              DISPUTED ──► COMPLETED  (admin)
  CANCELLED                              ├──────► CANCELLED  (admin)
      ▲                                  └──────► PAYMENT_SENT  (withdrawn)
      │ 24h after the payment window closes
   EXPIRED

The allowed transitions are exactly these — nothing else is accepted:

Opening a trade

The taker chooses an amount and one of the offer's payment methods. Before anything is locked, an unauthenticated pre-flight answers "can this person actually fund it" so a doomed request never takes the offer's write lock.

Then, under a Redis lock on the offer (p2p:initiate:<offerId>:lock, 30 s) and a SERIALIZABLE transaction:

The payment method snapshot matters: trade.paymentDetails is a copy of the name, icon, instructions, processing time and the method's metadata as they were at that instant. If the maker later edits their bank details, the running trade still shows what the buyer agreed to.

Escrow: one authority, one guard

All escrow movement goes through a single settlement function. Six callers use it — the seller's release, user cancellation, the expiry cron, admin trade resolution, admin trade cancellation and admin dispute resolution — and they all share one wallet idempotency namespace, p2p_settle_<tradeId>.

p2pTrade.escrowStatus is the guard, taken under a row lock and flipped to a terminal value in the same transaction as the money:

Four settlement outcomes exist. Their names date from when the escrow was always the asset leg and its owner was therefore always the seller; read them as holder-relative — a release pays whichever party is not holding the escrow, a refund returns it to whoever is:

The two spellings are the same outcome; the unambiguous ones exist so a caller does not have to name a role that is wrong half the time.

Amounts are clamped twice: to the escrow recorded on the trade, and to the escrow wallet's real inOrder. A drifted ledger can therefore settle what genuinely exists rather than throwing and stranding the trade.

The fee

One fee exists. There is no maker fee, no taker fee, no dispute fee.

It is computed at trade initiation from the trade amount and stored on the row, then charged at settlement. Three things constrain it:

• It comes out of the buyer's proceeds and can never exceed them.
• It is never charged on a refund — a seller getting their own funds back is not taxed for it.
• A floor of 0.0001 applies, but only while it stays under 5 % of the trade amount. Without that cap, the absolute floor was ten dollars' worth of BTC — enough to equal a legal minimum-size BTC trade, produce a zero buyer credit, be rejected by the wallet service, and leave the escrow permanently stuck.

Sellers who hold Super Admin are exempt from the fee entirely. Collected fees are booked as platform revenue and recorded in p2p_commissions.

The payment window

One definition, used by the expiry cron, the trade view, the WebSocket and the payment-confirmation endpoint. In precedence order:

1. offer.tradeSettings.autoCancel, when it is a finite number ≥ 0. A value of 0 means never auto-cancel and stops here — it does not mean "expire immediately" and does not fall through.
2. offer.tradeSettings.paymentWindow — a legacy alias with the same meaning.
3. The admin setting p2pDefaultPaymentWindow.
4. 30 minutes.

The window is measured from trade.createdAt. The admin switch p2pAutoCancelUnpaidTrades disables trade expiry altogether; it does not affect the stale-payment safety net below.

What the cron does, every minute

Expires unpaid trades. PENDING trades still unpaid 24 hours after their window closed are set to EXPIRED, their escrow returned to the parent offer, and the offer's advertised capacity restored by what settlement actually released. That grace is what makes a late payment possible at all, and it lives in the sweep rather than in the deadline: the window still closes exactly when the offer said it would, so the countdown a buyer is shown stays honest — only the sweep waits. Expiry is recorded on the cancellation columns (cancelledAt, cancellationReason: "Payment window elapsed") — there is no expiredAt column.

Auto-disputes stale payments. A trade sitting in PAYMENT_SENT for more than 24 hours is moved to DISPUTED with a high-priority dispute filed on the buyer's behalf. The escrow deliberately stays held; an admin settles it.

The deadline is anchored on paymentConfirmedAt — the instant the buyer declared payment — not on updatedAt. Every chat message rewrites the trade row, which bumped updatedAt and reset the safety net indefinitely: a seller who kept the conversation alive could hold a buyer's escrow forever.

Expires dead offers. See Offers.

Each scan is capped at 500 rows per tick and drains across ticks. The trade scan is deliberately newest-first: offers with autoCancel: 0 never expire and so never leave the candidate set, and an oldest-first batch would be permanently occupied by exactly those rows.

An admin can trigger the whole handler by hand from the trades screen if a window has clearly lapsed and nothing has happened.

Who may do what

Two of these deserve spelling out to support staff:

• A seller cannot cancel a pending trade until the payment window has passed. Before it they are refused and pointed at the trade chat, the buyer being the only party who can end it until the deadline: the offer promised a window, and taking the escrow back inside it would make that promise worthless. The refusal used to send them to pause the offer instead, which was a dead end — an offer cannot be edited while a trade is running against it, so the advice produced a second refusal and no way out. Once it has passed the seller may cancel on demand — the deadline's job is to release them from waiting, not to end the trade by itself. An offer whose autoCancel is 0 has no window to pass, so on that offer a pending trade can only be cancelled by the buyer.
• Neither trader can cancel after PAYMENT_SENT. The buyer cancelling would lose their money; the seller cancelling would be a straight theft — keep the fiat, get the crypto back. Both parties are directed to open a dispute. An admin is not held to that: the admin cancellation door (permission edit.p2p.trade) accepts PENDING, PAYMENT_SENT and DISPUTED alike and settles the escrow through the same authority. No dispute has to be open first.

A cancellation reason of at least 10 characters is required, and is stored on the trade.

Release

Whoever's crypto is held presses release — the seller on an ordinary trade, and on a fiat-denominated one the asset buyer, since they are the party who paid the coin and received the cash. In one transaction: the escrow settles to the other party net of the fee, the trade goes COMPLETED with completedAt set, the activity log is written, and the offer's attributed escrow is drawn down.

After the commit: audit entries, notifications, a WebSocket status broadcast, and — if the MLM addon is installed — affiliate rewards for both parties' referrers, calculated from what settlement actually moved rather than a second local fee calculation.

Releasing is idempotent by two independent mechanisms. A Redis key caches the result for an hour, and the escrow authority's escrowStatus guard settles a trade at most once regardless.

Chat and attachments

Every trade has a private conversation between the two parties, stored as MESSAGE entries on the trade timeline and delivered over a WebSocket subscription rather than by polling.

• Messages are capped at 1000 characters and 100 per hour.
• The room outlives the trade for a while. On a COMPLETED, CANCELLED or EXPIRED trade both parties can keep writing — text and images alike — until Chat After a Trade Ends (p2pPostTradeChatHours, 168 hours by default) has passed since the trade ended, or since Support last wrote on it, whichever is later. So Support can pick up any finished trade's conversation just by writing into it, however old the trade is. Outside that window a message is refused with a 400 that says when the trade ended and when its chat closed, and the room's composer is disabled with the same reason; set the setting to 0 and the chat closes the moment the trade ends, with Support's messages reopening nothing. A DISPUTED trade's room is never closed by this, so the parties can keep talking while an admin arbitrates.
• A message sent after the trade ended travels like any other: it reaches the other trader's room and notifications, and the admin trade screen. When Support has written on that trade it also alerts your P2P admins — in-app and by push, quoting the line — so whoever asked hears the answer without having to reopen the room (notifications). Support here means an admin who is not one of the two traders.
• Images can be attached, up to 5 MB each.
• An attachment can be read only by the buyer and the seller of that trade.
• Admins can post into the conversation from the dispute or trade screen; those messages are marked as admin messages and both parties are notified.

Message text is sanitised on the way in: line breaks and tabs survive, control characters and the characters that could open a tag do not. It is rendered as plain text.

Reviews

After a trade completes, each party may review the other. The UI submits a single 1–5 star rating; the storage is three independent 0–100 dimensions — communication, speed and trust — and a star rating is spread across all three. A caller can send the dimensions individually instead.

Feedback text is capped at 2000 characters. Review averages feed the hourly reputation job and the trader cards on the market board.