io.github.ptrinh/freeport-nostr

Official5 tools

by ptrinh · TypeScript

Search Freeport Nostr events by kind, tag & geohash radius (rides, services, reputation).

Search Nostr events by kind, tag, and geohash for rides, services, and reputation data.

Captured live from the server via tools/list.

nostr_search_intents

Search Freeport ride/service/product intents (offers & requests). Filter by side, category/area topic tags, and an optional geographic radius. Results are decoded, expiry-filtered, and sorted nearest-first when a point is given.

Parameters (9)

sidestring
offer = drivers/providers/sellers; request = riders/buyers; any = both
topicsarray
Topic `t` tags to require (category/subcategory/area keys, e.g. "vn_hanoi", "ridesharing").
nearobject
Filter & sort by distance from this point.
relaySideGeohashboolean
Also narrow at the relay via a #g cover of the radius. Only effective if posts carry geohash-prefix tags; off by default.
sinceinteger
Only events created at/after this unix-seconds time.
untilinteger
Only events created at/before this unix-seconds time.
includeExpiredboolean
limitinteger
relaysarray
Override the relay set for this call (ws/wss URLs, max 10). Defaults to the server relays.

nostr_search_reputation

Fetch reputation signals for a pubkey: karma ratings (kind 32103) it received and deal receipts (kind 32104). Returns proven-deal count (both receipt halves present) and a karma summary. Note: scores are subjective and un-weighted here; do not treat as Sybil-proof.

Parameters (3)

pubkeystringrequired
Subject pubkey (hex) to look up reputation for.
limitinteger
relaysarray
Override the relay set for this call (ws/wss URLs, max 10). Defaults to the server relays.

nostr_get_event

Fetch one or more events by id. Returns the raw signed events.

Parameters (2)

idsarrayrequired
relaysarray
Override the relay set for this call (ws/wss URLs, max 10). Defaults to the server relays.

nostr_profile

Fetch NIP-01 profile metadata (kind 0) for one or more pubkeys — name, about, picture, nip05, lud16, etc. Optionally include each author's most recent notes (kind 1). General-purpose: works for any Nostr user, not just Freeport.

Parameters (3)

pubkeysarrayrequired
Hex pubkeys to fetch profiles for.
recentNotesinteger
If >0, also fetch up to this many recent text notes (kind 1) per pubkey.
relaysarray
Override the relay set for this call (ws/wss URLs, max 10). Defaults to the server relays.

nostr_query_raw

Escape hatch: run an arbitrary NIP-01 filter (kinds/authors/ids/tags/since/until/limit). Use the typed tools above when they fit. Returns raw signed events.

Parameters (8)

kindsarray
authorsarray
idsarray
tagsobject
Tag filters, e.g. {"t":["vn_hanoi"],"g":["w3gv"]}. Keys are single tag letters.
sinceinteger
untilinteger
limitinteger
relaysarray
Override the relay set for this call (ws/wss URLs, max 10). Defaults to the server relays.

README.md5 KBView on GitHub

Freeport

Decentralized P2P marketplace over Nostr. Users broadcast trade intents into topic-scoped markets; personal agents discover counterpart intents and negotiate automatically. Humans confirm final deals. No central operator, no matching server — relays are dumb pub/sub, all logic is client-side.

App: https://freeport.trinh.uk (web/PWA) · iOS · Android
Whitepaper: PDF
Self-host the optional notification server: packages/nostr-mcp — docker compose up -d (MCP + push notifier + optional Telegram bridge). The app needs no backend; this only adds push/Telegram on top of the public relays.

Layout

Path	What
`docs/protocol.md`	Protocol spec: intent event kinds (32101/32102), negotiation envelopes, state machine
`packages/protocol`	Spec as code: event build/parse, negotiation state machine, matching, geohash
`packages/agent`	CLI personal agent (`freeport run`): subscribe, auto-match, negotiate, human confirm
`packages/nostr-mcp`	Read-only MCP server for agents + self-hostable notifier: Web Push / Expo push and the Telegram bridge (feed, listen mode, pings, guest mode)
`apps/mobile`	Expo/React Native + PWA client (post intent, negotiate, confirm deals, key backup, 55 locales incl. RTL)
`relay/`	Self-hosted strfry relay (docker-compose, Proxmox-LXC-sized, Uptime-Kuma health)
`demo/`	Two-agent rideshare demo configs + script

Stack decisions

TypeScript + nostr-tools (over Rust): mature NIP coverage (01/04/19/40/44/49), same language across protocol/agent/mobile so the protocol package is shared verbatim, fastest iteration to demo.
Demo vertical: sg-rideshare (Singapore rideshare) — the protocol is vertical-agnostic; verticals are payload schemas (rideshare/1) plus a client-side matcher.
Intents public, negotiations encrypted (NIP-04 now, NIP-17 next).
Settlement out of scope for v1: deals end with contact exchange; a reserved payment field lands Lightning later without breaking changes.

Quick start

npm install
npm run build && npm test           # protocol unit tests
cd packages/agent && npm test       # e2e: 2 agents + in-process relay

# live demo over public relays (driver bg + rider fg, answer y to confirm):
bash demo/run-demo.sh

Two-machine demo (the real thing):

# machine B (driver)
npx tsx packages/agent/src/cli.ts run --config demo/driver.config.json
# machine A (rider) — different relay set, overlaps on one relay
npx tsx packages/agent/src/cli.ts run --config demo/rider.config.json --post demo/ride-request.json

Agent A posts a 15:45 ride request → B discovers it, counters 16:00 (its configured window) → A's owner answers y → both print the confirmed deal with exchanged contacts. Verified end-to-end over damus.io / nos.lol / primal.net / nostr.band / nostr.mom.

CLI

code

freeport whoami                          show/create identity (silent keygen)
freeport backup --passphrase <pw>        NIP-49 encrypted key backup
freeport restore --blob <ncryptsec> --passphrase <pw>
freeport post --intent <file.json>       publish an intent
freeport listen --market <topic>         watch a market
freeport run --config <agent.json>       full agent loop [--post intent.json] [--yes]

Status

Distribution: live on the Apple App Store; Google Play in review.
Reputation: implemented — karma ratings (PoW-backed, apps/mobile/src/karma.ts), deal receipts, proven-deal counts, per-viewer web-of-trust weighting, and a nostr_search_reputation MCP tool. What remains open is sybil resistance: a new keypair is free, so zero-history identities should be treated with visible caution by clients.
Notifications & Telegram: content-blind Web Push / Expo push, plus a Telegram bridge — relay a market feed into groups, parse organic "hitcher" posts into a one-tap broadcast, send personal activity pings, and (optional, custodial) let Telegram-native users post and deal without the app. All self-hostable in packages/nostr-mcp — see its README to enable.
Localization: 55 languages with plural-aware strings and full RTL (Arabic, Hebrew, Persian, Urdu).

Non-goals (v1)

Payments/escrow, dispute resolution, vetting, anti-sybil — all deliberately deferred.

License & forking

MIT (LICENSE). Freeport exists to be forked: any community can stand up its own market — own name, city, vertical, relays and services — by changing configuration, not architecture. FORKING.md lists every deployment-specific value; CONTRIBUTING.md covers dev setup and style.

Install

Configuration

Environment variables

FREEPORT_RELAYS

Comma-separated relay websocket URLs. Defaults to the Freeport public relay set.

claude_desktop_config.json

{
  "mcpServers": {
    "freeport-nostr": {
      "command": "npx",
      "args": [
        "-y",
        "freeport-nostr-mcp@0.5.0"
      ],
      "env": {
        "FREEPORT_RELAYS": "<YOUR_FREEPORT_RELAYS>"
      }
    }
  }
}