NIP-69: Peer-to-Peer Trading
NIP-69 defines a shared event format for peer-to-peer bitcoin trade offers. When several platforms publish orders as kind:38383 events, one client can read all of them as a single orderbook while each platform keeps its own liquidity. The format makes offers visible across platforms and does not reserve funds, hold escrow or settle trades; taking an order, quoting a price, handling disputes and holding funds all stay with the platform that published the offer.
How it works
Orders are addressable events, identified by author, kind and d tag. When a platform updates an order’s status, it publishes a new event at the same address, and that event replaces the earlier version. An event from a different author that reuses the same d value is a separate order.
Clients should check each event’s NIP-01 id and signature. A valid signature identifies who broadcast the order, though it says nothing about whether that party has the funds or will trade honestly.
Order tags
The required tags are:
d: the order identifier, which must be unique among the author’s orders. Any unique string works, and a UUID is not required.k: the order type, eitherbuyorsell.f: the currency, given as an ISO 4217 code.s: the order status, described below.amt: the bitcoin amount in satoshis. A value of0does not make the order free; it means the platform quotes the amount from its price API when someone takes the order.fa: the fiat amount, given either as one value or as two values that form a range.pm: the accepted payment methods.premium: the percentage above or below the market price.network: the bitcoin network, such as mainnet, testnet, signet or regtest.layer: the settlement layer, such as onchain, lightning or liquid.expires_at: the time when a pending order stops being open.expiration: the time when relays may delete the event under NIP-40.y: the platform’s name.z: always the fixed valueorder.
The optional tags are:
source: a URI that links back to the order on its platform. It need not be HTTPS, and clients should treat it as a link the user chooses to follow and never run it as code.rating: a reputation score whose format and calculation each platform defines for itself, so scores from different platforms are not comparable.name: a display name.g: a geohash for face-to-face trades. Because the tag is public, a precise geohash can reveal where a trader plans to meet.bond: an advertised security deposit. The tag announces a deposit amount without enforcing the deposit or proving that anyone paid it.
Some live events differ from this tag set, so clients should parse orders defensively.
Status and time
The status values are:
| Status | Meaning |
|---|---|
pending | Open for a counterparty |
in-progress | A trade has started |
success | The trade completed |
canceled | The maker withdrew the order |
expired | The order passed its lifetime |
The two time tags do different jobs: expires_at sets how long a pending offer stays open, while expiration asks relays to delete the event under NIP-40.
Relays can deliver events late or return older versions that have since been replaced, so an orderbook should compare created_at, s and expires_at before showing an order as open.
Privacy
Fiat currency, payment methods, geohash and posting times are all public, and together they can reveal a trader’s habits.
Implementations
Each entry below describes source code at a pinned commit. The entries cover code paths only and make no claims about builds, live trades or whether the apps work with each other.
Mostro, at commit
2211a7e, publishes public orders with empty content and the order’s UUID asd, and records each event id. Because itscreated_atvalues always increase, a take or cancel in the same second as the first pending event still sorts after it under NIP-01 replacement rules. Before publishing, order validation:- rejects ranges that have only one end;
- checks fixed fiat amounts, non-negative sats and range limits;
- checks quote bounds.
RoboSats, at commit
babf62e, signs orders with the coordinator’s key and sends them to a local strfry relay. Thedvalue is a UUID derived from an MD5 hash of the coordinator alias and the order id. Alongside it, each order event carries:- buy/sell type, currency, and amount or range;
- payment methods, premium and source;
- expiration, bond, platform, network and layer;
- a geohash when coordinates exist.
Published orders are reported as
pendingand every other internal state assuccess, so not all five statuses are used. Thepmtag comes from splitting the payment-method text on spaces, which shows that platform formats can differ from the spec’s wording.lnp2pBot, at commit
6d91a79, signs and publishes an order event whenever a public order changes. The tag builder emits:d,k,f,s,amtandfa(one amount or a min/max range);pm,premiumandrating;- a Telegram
sourcelink, which points to the community channel for community orders; network=mainnet,layer=lightning,y=lnp2pbotandz=order;- an
expirationtaken from its configuration.
No
bondorexpires_attag is emitted, and theratingvalue combines the maker’s local rating, account age and review count. Each signed event is verified before the bot publishes it to its configured relays.
History
The order proposal that became NIP-69 was added as xx.md on 2024-06-27 in commit f57d559 by Francisco Calderón. On 2024-11-04 it was renamed to 100.md in f72a2f6, then to 69.md in bff61dd. The spec cites an earlier 31001.md proposal and n3xB as related work. Prior art outside the NIPs repository is not traced here.
Primary sources:
- NIP-69 Specification (pinned)
- Initial proposal commit f57d559
- Rename to 69.md, commit bff61dd
- Mostro Protocol Specification
- Mostro util.rs at 2211a7e
- RoboSats api/nostr.py at babf62e
- lnp2pBot events.ts at 6d91a79
Mentioned in:
- Newsletter #1: NIP Updates
- Newsletter #1: Releases
- Newsletter #2: News
- Newsletter #41: Stable order creation time
- Newsletter #49: NIP Deep Dive on public goals and peer-to-peer orders
See also: