nips/31001.md

NIP-XXXX
======

messages specification for peer 2 peer
--------------------------------------

`draft` `optional` `author:XXXX`

Peer-to-peer is one of the most important applications needed in the Bitcoin space.

Nostr can enhance liquidity by enabling existing profiles to use their reputation to trade with other peers. Reputation is a key element that makes large P2P platforms like Paxful or Binance P2P easy to use and scale, because it's easy to find someone who is likely reliable. The drawback is that identity in those platforms is locked in, and reputation built on one of those platforms can't be reused on another. Using Nostr would solve that reputation problem.

Users could also choose to create a one-time identity and participate on the same based platform by simply creating a new key-pair for each trade. It would make it possible to merge currently separate use cases where platforms today are either relying on bonds (like RoboSats) or reputation (like Paxful, Binance P2P, HodlHodl).

An ecosystem where different clients use the same specification on how to create and settle trades would create a thriving environment where clients compete in their UX and product offerings, to the benefit of the users and the global liquidity of the network.

While it would be likely that clients are initially dedicated to this application, an ideal scenario would be that, over time, generic clients also integrate this NIP. This would incentivize a large group of users who would own Bitcoin, from zaps for instance, to trade with each other for local fiat currencies, without having the current barrier to entry of having a dedicated app.

## Data structure

an event looks like this:

```
let event = {
  kind: 31001,
  created_at: Math.floor(Date.now() / 1000),
  tags: [
    ["D", "BUY"],
    ["C", "BTC/NGN"],
    ["P", "10000000.00000000"], // price, 1 BTC = 10000000 NGN
    ["m", "0.0001"],
    ["M", "0.001"],
    ["E", String(Math.floor(Date.now() / 1000) + 3600)], // 24h expiration
    ["c", "lightning/ACH"] // payment methods
  ],
  content: "0 reputation are not allowed", // comment on the order. could be anything
  pubkey,
};
```

Optional tags are the following:
```
    ["e", "formerEventId" ], // used for replace order
```

### tag description:

D: "BUY" or "SELL"
C: Traded pair. For fiat currencies, use the ISO-4217 code.

"BUY" "BTC/USD" indicates that the trade initiator wants to "BUY BTC" and "SELL USD."

P: Price

m: Minimum amount
M: Maximum amount

For a fixed-amount offer, set the minimum (m) and maximum (M) amounts equal.

E: Expiration date in Unix format

e: Referring to a previous order. the client SHOULD remove the previous order from the list of order currently displayed.

c: Trading channels in use. Separate multiple channels with comma, e.g., "IBAN,Revolut,US Amazon Gift Card,UK Faster Payments" For specifying channels for both left and right currencies, use a "/", e.g., "Onchain,Lightning/IBAN,Revolut,US Amazon Gift Card,UK Faster Payments"

### replace and delete

NIP-09 allows for the removal of an offer, such as when a trade is completed and liquidity is no longer available. 
tag-e can be used to replace an offer, for example, when the price changes.


### Marketplace?

Although it's possible to build this on top of the draft marketplace, there are several reasons to create a dedicated NIP:

- Initially, P2P trading clients will probably dedicated to this application. By using a specific kind instead of the generic {kind: 1}, it improves discoverability.
- The data structure employs tags, allowing for native filtering across currencies, amounts, and expiration dates on existing relays.


### TODO:

- extend this nip with a kind for settled trades, __key__ extension, as it's the one needed to build reputation.
- nip for escrows (escrow could probably be the same than for the marketplace?)
- extend this nip with optional bonds (a la robosats)
- specify how trade can be deleted
- geo for in person trading

### Implementation

- soon (2 weeks, TM)