Nostr Marketplace Builder

Overview

Construct correct Nostr marketplace events for commerce applications. This skill handles the non-obvious parts: stall/product relationships, shipping cost calculations, auction lifecycle rules, checkout message sequencing via NIP-04, and P2P order tag structures from NIP-69.

When to Use

• Creating a merchant stall with shipping zones (kind:30017)
• Listing products with categories and specs (kind:30018)
• Setting up auctions with bidding (kind:30020, kind:1021, kind:1022)
• Building checkout flows (NIP-04 order → payment → status)
• Creating P2P buy/sell orders for bitcoin trading (NIP-69 kind:38383)
• Configuring a custom marketplace UI (kind:30019)
• Calculating shipping costs across zones and products

Do NOT use when:

• Building generic Nostr events (use nostr-event-builder)
• Implementing relay WebSocket logic
• Working with NIP-19 encoding/decoding

Workflow

1. Identify What to Build

2. Build the Event

Stall (Kind:30017) — Addressable

The stall is the merchant's store. Products belong to stalls. Shipping zones are defined at the stall level with base costs.

{
  "kind": 30017,
  "tags": [["d", "my-stall-001"]],
  "content": "{\"id\":\"my-stall-001\",\"name\":\"Satoshi's Electronics\",\"description\":\"Quality electronics for sats\",\"currency\":\"USD\",\"shipping\":[{\"id\":\"us-domestic\",\"name\":\"US Domestic\",\"cost\":5.99,\"regions\":[\"US\"]},{\"id\":\"worldwide\",\"name\":\"Worldwide\",\"cost\":15.00,\"regions\":[\"EU\",\"AS\",\"SA\"]}]}"
}

Rules:

• d tag value MUST equal the id in content JSON
• id should be a UUID or descriptive slug — sequential IDs (0, 1, 2) are discouraged
• currency is a string (e.g., "USD", "BTC", "EUR")
• shipping array defines zones; customer must choose exactly one zone at checkout
• Each zone has a base cost in the stall's currency

Product (Kind:30018) — Addressable

Products belong to a stall via stall_id. They can add per-product shipping costs on top of the stall's base shipping cost.

{
  "kind": 30018,
  "tags": [
    ["d", "product-xyz-789"],
    ["t", "electronics"],
    ["t", "gadgets"]
  ],
  "content": "{\"id\":\"product-xyz-789\",\"stall_id\":\"my-stall-001\",\"name\":\"Lightning Node Kit\",\"description\":\"Pre-configured Bitcoin node\",\"images\":[\"https://example.com/node.jpg\"],\"currency\":\"USD\",\"price\":299.99,\"quantity\":25,\"specs\":[[\"processor\",\"ARM Cortex-A72\"],[\"storage\",\"1TB SSD\"],[\"connectivity\",\"Ethernet + WiFi\"]],\"shipping\":[{\"id\":\"us-domestic\",\"cost\":10.00},{\"id\":\"worldwide\",\"cost\":25.00}]}"
}

Rules:

• d tag value MUST equal the id in content JSON
• stall_id MUST reference an existing stall's id
• quantity: integer for limited stock, null for unlimited (digital goods/services)
• t tags are searchable categories — use multiple for discoverability
• specs is an array of [key, value] pairs for structured display
• Product shipping[].id MUST match a zone id from the parent stall
• Total shipping = stall base cost + (product shipping cost × quantity)

Marketplace UI (Kind:30019) — Addressable

Custom marketplace configuration grouping merchants together:

{
  "kind": 30019,
  "tags": [["d", "my-marketplace"]],
  "content": "{\"name\":\"Bitcoin Bazaar\",\"about\":\"A curated marketplace for Bitcoin products\",\"ui\":{\"picture\":\"https://example.com/logo.png\",\"banner\":\"https://example.com/banner.jpg\",\"theme\":\"dark\",\"darkMode\":true},\"merchants\":[\"pubkey1hex...\",\"pubkey2hex...\"]}"
}

Auction (Kind:30020) — Addressable

Auctions are similar to products but with bidding mechanics:

{
  "kind": 30020,
  "tags": [["d", "auction-rare-item-001"]],
  "content": "{\"id\":\"auction-rare-item-001\",\"stall_id\":\"my-stall-001\",\"name\":\"Signed Hal Finney Print\",\"description\":\"Limited edition signed print\",\"images\":[\"https://example.com/print.jpg\"],\"starting_bid\":50000,\"start_date\":1719391096,\"duration\":86400,\"specs\":[[\"condition\",\"mint\"],[\"authentication\",\"verified\"]],\"shipping\":[{\"id\":\"worldwide\",\"cost\":20.00}]}"
}

Rules:

• starting_bid is in the stall's currency (integer)
• start_date is a Unix timestamp; omit if start date is unknown
• duration is seconds the auction runs (excluding extensions)
• Actual end = start_date + duration + SUM(all duration_extended from confirmations)
• Cannot edit auction after receiving first bid — bids reference the event ID (not product UUID), so editing creates a new event ID and loses all bids

Bid (Kind:1021) — Regular

{
  "kind": 1021,
  "content": "75000",
  "tags": [["e", "<auction-event-id>"]]
}

Rules:

• content is the bid amount as a string (in the auction's currency)
• The e tag references the event ID of the auction, not the product UUID
• This is why editing an auction after bids destroys those bids

Bid Confirmation (Kind:1022) — Regular

Sent by the merchant to validate bids:

{
  "kind": 1022,
  "content": "{\"status\":\"accepted\",\"message\":\"Bid received and validated\",\"duration_extended\":300}",
  "tags": [
    ["e", "<bid-event-id>"],
    ["e", "<auction-event-id>"]
  ]
}

Status values: accepted, rejected, pending, winner

• winner is sent to the winning bid after auction ends
• duration_extended (optional): seconds added to auction duration
• Clients must verify the confirmation pubkey matches the merchant's pubkey

3. Checkout Flow (NIP-04 DMs)

Checkout uses encrypted direct messages. See references/checkout-flow.md for full details.

Step 1 — Customer sends order (type:0):

{
  "id": "order-uuid-123",
  "type": 0,
  "name": "Alice",
  "address": "123 Bitcoin St, Miami, FL",
  "message": "Please ship ASAP",
  "contact": {
    "nostr": "<customer-pubkey-hex>",
    "phone": null,
    "email": "alice@example.com"
  },
  "items": [
    { "product_id": "product-xyz-789", "quantity": 2 }
  ],
  "shipping_id": "us-domestic"
}

Step 2 — Merchant sends payment request (type:1):

{
  "id": "order-uuid-123",
  "type": 1,
  "message": "Payment required within 15 minutes",
  "payment_options": [
    { "type": "ln", "link": "lnbc..." },
    { "type": "btc", "link": "bc1q..." },
    { "type": "url", "link": "https://pay.example.com/order-123" }
  ]
}

Step 3 — Merchant sends status update (type:2):

{
  "id": "order-uuid-123",
  "type": 2,
  "message": "Payment confirmed, shipping tomorrow",
  "paid": true,
  "shipped": false
}

4. P2P Orders (NIP-69 Kind:38383)

For peer-to-peer bitcoin trading. See references/marketplace-events.md for full tag reference.

{
  "kind": 38383,
  "tags": [
    ["d", "order-uuid-456"],
    ["k", "sell"],
    ["f", "USD"],
    ["s", "pending"],
    ["amt", "100000"],
    ["fa", "50"],
    ["pm", "zelle", "cashapp"],
    ["premium", "3"],
    ["network", "mainnet"],
    ["layer", "lightning"],
    ["name", "SatoshiTrader"],
    ["bond", "1000"],
    ["expires_at", "1719391096"],
    ["expiration", "1719995896"],
    ["y", "my-platform"],
    ["z", "order"]
  ],
  "content": ""
}

Required tags: d, k, f, s, amt, fa, pm, premium, network, layer, expires_at, expiration, y, z

Status flow: pending → in-progress → success | canceled | expired

5. Validate Before Publishing

• d tag matches content id (for kinds 30017, 30018, 30020)
• Product stall_id references a valid stall
• Product shipping zone IDs match stall shipping zone IDs
• quantity is integer or null (not string, not undefined)
• Auction starting_bid is an integer
• Bid e tag references auction event ID (not product UUID)
• Bid confirmation has two e tags (bid + auction)
• Checkout messages use correct type values (0, 1, 2)
• P2P order has z tag set to "order"
• P2P order f tag uses ISO 4217 currency code
• P2P order k tag is "buy" or "sell"
• All timestamps are Unix seconds (not milliseconds)
• Content is stringified JSON where required

Shipping Cost Calculation

Total shipping for an order:

base_cost = stall.shipping[chosen_zone].cost
per_product = SUM(product.shipping[chosen_zone].cost × quantity) for each item
total_shipping = base_cost + per_product

Example: Stall base shipping $5.99, buying 2 units of a product with $10 extra shipping per unit → total shipping = $5.99 + (2 × $10) = $25.99.

Common Mistakes

Quick Reference

Key Principles

1. IDs must be consistent — The d tag and the id field inside content JSON must always match. This is how addressable events are located.

2. Shipping is hierarchical — Stalls define base shipping zones and costs. Products add per-unit costs on top. The customer picks one zone at checkout.

3. Auctions are immutable after bids — Because bids reference the event ID (not a UUID), editing an auction creates a new event and orphans existing bids. Design auctions carefully before publishing.

4. Checkout is sequential — Order (type:0) → Payment request (type:1) → Status update (type:2). Each message references the same order ID. All messages are NIP-04 encrypted DMs.

5. P2P orders are self-contained — All trade parameters live in tags, not content. The z tag must be "order" for client discovery. Status transitions follow: pending → in-progress → success/canceled/expired.