{"id":47963012,"url":"https://github.com/forgesworn/402-announce","last_synced_at":"2026-04-04T10:03:50.310Z","repository":{"id":344467257,"uuid":"1181933777","full_name":"forgesworn/402-announce","owner":"forgesworn","description":"Announce HTTP 402 services on Nostr for decentralised discovery. Kind 31402 parameterised replaceable events.","archived":false,"fork":false,"pushed_at":"2026-03-25T10:51:32.000Z","size":424,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-26T04:13:35.127Z","etag":null,"topics":["402","ai-agents","cashu","discovery","http-402","l402","lightning","machine-payments","nostr","typescript","x402"],"latest_commit_sha":null,"homepage":"https://402.pub","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/forgesworn.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"custom":["https://strike.me/thedonkey"]}},"created_at":"2026-03-14T20:27:22.000Z","updated_at":"2026-03-25T10:51:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/forgesworn/402-announce","commit_stats":null,"previous_names":["thecryptodonkey/l402-announce","forgesworn/402-announce"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/forgesworn/402-announce","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forgesworn%2F402-announce","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forgesworn%2F402-announce/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forgesworn%2F402-announce/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forgesworn%2F402-announce/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/forgesworn","download_url":"https://codeload.github.com/forgesworn/402-announce/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forgesworn%2F402-announce/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31395450,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T09:13:02.600Z","status":"ssl_error","status_checked_at":"2026-04-04T09:13:01.683Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["402","ai-agents","cashu","discovery","http-402","l402","lightning","machine-payments","nostr","typescript","x402"],"created_at":"2026-04-04T10:03:49.444Z","updated_at":"2026-04-04T10:03:50.297Z","avatar_url":"https://github.com/forgesworn.png","language":"TypeScript","funding_links":["https://strike.me/thedonkey"],"categories":[],"sub_categories":[],"readme":"# 402-announce\n\n**Nostr:** [`npub1mgvlrnf5hm9yf0n5mf9nqmvarhvxkc6remu5ec3vf8r0txqkuk7su0e7q2`](https://njump.me/npub1mgvlrnf5hm9yf0n5mf9nqmvarhvxkc6remu5ec3vf8r0txqkuk7su0e7q2)\n\nAnnounce HTTP 402 services on Nostr for decentralised discovery. Supports both L402 and x402 payment protocols.\n\n[![CI](https://github.com/forgesworn/402-announce/actions/workflows/ci.yml/badge.svg)](https://github.com/forgesworn/402-announce/actions/workflows/ci.yml)\n[![Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen.svg)](./README.md)\n[![MIT Licence](https://img.shields.io/badge/licence-MIT-blue.svg)](./LICENSE)\n\nPublishes **kind 31402** parameterised replaceable events so that AI agents (and any Nostr client) can discover paid APIs without a central registry.\n\n**[Live Dashboard](https://402.pub)** — see every service announcing on the network right now.\n\n## How it works\n\n```mermaid\nflowchart LR\n    A[Your API] --\u003e|\"npm install\u003cbr/\u003e402-announce\"| B[402-announce]\n    B --\u003e|\"kind 31402\u003cbr/\u003esigned event\"| C[(Nostr Relays)]\n    C --\u003e|subscribe \u0026 filter| D[402-mcp]\n    D --\u003e|discover + pay| A\n\n    style B fill:#f59e0b,color:#000\n    style C fill:#8b5cf6,color:#fff\n    style D fill:#3b82f6,color:#fff\n```\n\nYour API publishes a service announcement to Nostr relays. AI agents (via [402-mcp](https://github.com/forgesworn/402-mcp)) discover it, pay the invoice, and consume the API. No central registry required.\n\n## Quick start\n\n```bash\nnpm install 402-announce\n```\n\n```typescript\nimport { announceService } from '402-announce'\n\nconst handle = await announceService({\n  secretKey: '64-char-hex-nostr-secret-key',\n  relays: ['wss://relay.damus.io', 'wss://relay.primal.net'],\n  identifier: 'jokes-api',\n  name: 'Jokes API',\n  urls: ['https://jokes.example.com'],\n  about: 'A joke-telling service behind an L402 paywall',\n  pricing: [\n    { capability: 'get_joke', price: 1, currency: 'sats' },\n  ],\n  paymentMethods: [['l402', 'lightning'], ['cashu'], ['xcashu']],\n  topics: ['comedy', 'ai'],\n  capabilities: [\n    { name: 'get_joke', description: 'Returns a random joke' },\n  ],\n  version: '1.0.0',\n})\n\nconsole.log('Published event:', handle.eventId)\nconsole.log('From pubkey:', handle.pubkey)\n\n// Later, when shutting down:\nhandle.close()\n```\n\n**Multi-transport example** (clearnet + Tor + Handshake — same service, different access paths):\n\n```typescript\nconst handle = await announceService({\n  secretKey: '64-char-hex-nostr-secret-key',\n  relays: ['wss://relay.damus.io', 'wss://relay.primal.net'],\n  identifier: 'jokes-api',\n  name: 'Jokes API',\n  urls: [\n    'https://jokes.example.com',                  // clearnet\n    'http://jokesxyz...onion',                    // Tor hidden service\n    'https://jokes.example.hns',                  // Handshake domain\n  ],\n  about: 'A joke-telling service behind an L402 paywall',\n  pricing: [{ capability: 'get_joke', price: 1, currency: 'sats' }],\n  paymentMethods: [['l402', 'lightning']],\n  topics: ['comedy', 'ai'],\n})\n```\n\nEach URL becomes a separate `url` tag in the kind 31402 event. Clients try them in order and use whichever they can reach. `urls` accepts 1–10 entries; any parseable URL is valid.\n\nSee [`examples/`](./examples) for runnable scripts.\n\n## How it fits together\n\n```mermaid\nflowchart LR\n    subgraph \"Your Server\"\n        API[Your API]\n        TB[toll-booth\u003cbr/\u003eL402 paywall]\n        AN[402-announce]\n    end\n\n    subgraph \"Nostr Network\"\n        R1[(Relay 1)]\n        R2[(Relay 2)]\n    end\n\n    subgraph \"AI Agent\"\n        MCP[402-mcp\u003cbr/\u003ediscovery + payment]\n    end\n\n    API --\u003e TB\n    TB --\u003e|\"protects\"| API\n    AN --\u003e|\"kind 31402\"| R1\n    AN --\u003e|\"kind 31402\"| R2\n    R1 --\u003e|\"subscribe\"| MCP\n    R2 --\u003e|\"subscribe\"| MCP\n    MCP --\u003e|\"HTTP + L402 token\"| TB\n\n    style TB fill:#ef4444,color:#fff\n    style AN fill:#f59e0b,color:#000\n    style MCP fill:#3b82f6,color:#fff\n```\n\n1. **[toll-booth](https://github.com/forgesworn/toll-booth)** wraps your API with an L402 paywall\n2. **402-announce** publishes a kind 31402 event describing the service, pricing, and payment methods\n3. **[402-mcp](https://github.com/forgesworn/402-mcp)** discovers the announcement, pays the invoice, and calls your API\n\n## What it does\n\n- Builds and signs kind 31402 Nostr events\n- Publishes to one or more Nostr relays in parallel\n- Zeroises secret key bytes after use\n- Degrades gracefully when individual relays fail\n- Provides a `close()` handle for clean disconnection\n\n## What it does not do\n\n- Does not run an L402 paywall (use [toll-booth](https://github.com/forgesworn/toll-booth) for that)\n- Does not subscribe to or search for announcements (use [402-mcp](https://github.com/forgesworn/402-mcp) for that)\n- Does not handle payments or token verification\n\n## API\n\n### `announceService(config): Promise\u003cAnnouncement\u003e`\n\nHigh-level function that builds, signs, and publishes the event to multiple relays.\n\n**Returns** an `Announcement` handle:\n- `eventId` — the published Nostr event ID\n- `pubkey` — the Nostr pubkey derived from your secret key\n- `close()` — disconnect from all relays\n\n### `buildAnnounceEvent(secretKey, config): VerifiedEvent`\n\nLower-level function that builds and signs the event without publishing. Useful if you manage relay connections yourself.\n\n### Config options\n\n| Field            | Type              | Required | Description                                    |\n|------------------|-------------------|----------|------------------------------------------------|\n| `secretKey`      | `string`          | yes      | 64-char hex Nostr secret key                   |\n| `relays`         | `string[]`        | yes      | Relay URLs (`wss://` or `ws://`)               |\n| `identifier`     | `string`          | yes      | Unique listing ID (Nostr `d` tag)              |\n| `name`           | `string`          | yes      | Human-readable service name                    |\n| `urls`           | `string[]`        | yes      | HTTP endpoints for the service (1–10 entries, any parseable URL) |\n| `about`          | `string`          | yes      | Short description                              |\n| `pricing`        | `PricingDef[]`    | yes      | Per-capability pricing                         |\n| `paymentMethods` | `string[][]`      | yes      | Accepted payment methods (each entry is `[rail, ...params]`) |\n| `picture`        | `string`          | no       | Icon URL                                       |\n| `topics`         | `string[]`        | no       | Topic tags for filtering                       |\n| `capabilities`   | `CapabilityDef[]` | no       | Capability details (stored in event content)   |\n| `version`        | `string`          | no       | Service version (stored in event content)      |\n\n## Announce flow\n\n```mermaid\nflowchart TD\n    A[announceService config] --\u003e B{Validate}\n    B --\u003e|\"secretKey: 64-char hex\"| C[Derive pubkey]\n    B --\u003e|\"relays: wss:// URLs\"| C\n    C --\u003e D[Build kind 31402 event]\n    D --\u003e E[Sign with secret key]\n    E --\u003e F[Zeroise key bytes]\n    F --\u003e G[\"Connect relays (parallel, 10s timeout)\"]\n    G --\u003e H{Each relay}\n    H --\u003e|success| I[Publish event]\n    H --\u003e|failure| J[Log warning, continue]\n    I --\u003e K[\"Return { eventId, pubkey, close() }\"]\n    J --\u003e K\n```\n\n## Event format\n\nEach announcement is a **kind 31402** parameterised replaceable event. The combination of `pubkey` + `d` tag uniquely identifies a listing — publishing again with the same values updates the existing listing.\n\n```mermaid\ngraph TB\n    subgraph \"Kind 31402 Event\"\n        direction TB\n        subgraph Tags\n            D[\"d: jokes-api\"]\n            N[\"name: Jokes API\"]\n            U1[\"url: https://jokes.example.com\"]\n            U2[\"url: https://jokesapi.example.onion (optional)\"]\n            AB[\"about: A joke-telling service\"]\n            PMI1[\"pmi: l402, lightning\"]\n            PMI2[\"pmi: cashu\"]\n            P[\"price: get_joke, 1, sats\"]\n            T[\"t: comedy\"]\n        end\n        subgraph Content[\"Content (JSON)\"]\n            CAP[\"capabilities: [{ name, description }]\"]\n            VER[\"version: 1.0.0\"]\n        end\n    end\n\n    style Tags fill:#1e293b,color:#e2e8f0\n    style Content fill:#1e293b,color:#e2e8f0\n```\n\n### Tags\n\n| Tag       | Required | Description                                  | Example                           |\n|-----------|----------|----------------------------------------------|-----------------------------------|\n| `d`       | yes      | Unique identifier for this listing           | `jokes-api`                       |\n| `name`    | yes      | Human-readable service name                  | `Jokes API`                       |\n| `url`     | yes      | HTTP endpoint (one tag per URL; repeatable)  | `https://jokes.example.com`       |\n| `about`   | yes      | Short description                            | `A joke-telling service`          |\n| `pmi`     | yes      | Payment method identifier (repeatable, multi-element) | `l402`, `lightning`        |\n| `price`   | yes      | Capability pricing (repeatable)              | `get_joke`, `1`, `sats`           |\n| `t`       | no       | Topic tag for search/filtering (repeatable)  | `comedy`                          |\n| `picture` | no       | Icon URL                                     | `https://example.com/icon.png`    |\n\n### Recognised Payment Method Rails\n\nEach `paymentMethods` entry is an array where the first element is the rail identifier and subsequent elements are rail-specific parameters.\n\n| Rail | Example | Description |\n|------|---------|-------------|\n| `l402` | `['l402', 'lightning']` | L402 protocol (Lightning BOLT-11 invoices) |\n| `cashu` | `['cashu']` | Cashu ecash (generic) |\n| `xcashu` | `['xcashu']` | Cashu ecash via NUT-24 (X-Cashu header) |\n| `x402` | `['x402', 'base', 'usdc', '0xabc...']` | x402 stablecoin payments (chain, token, receiver address) |\n| `payment` | `['payment', 'lightning']` | IETF Payment protocol |\n\n### Content\n\nThe event content is a JSON object with optional fields:\n\n```json\n{\n  \"capabilities\": [\n    { \"name\": \"get_joke\", \"description\": \"Returns a random joke\" }\n  ],\n  \"version\": \"1.0.0\"\n}\n```\n\n## Multiple URLs vs multiple events\n\nThis distinction is important for operators:\n\n**Multiple URLs in one event** — use `urls: ['...', '...']` when the URLs represent the **same service** on different transports (clearnet, Tor, Handshake). The pricing, credentials, and macaroon signing key are identical. Clients pick whichever URL they can reach. This is for censorship resistance and redundancy.\n\n**Separate kind 31402 events** — publish a new event (different `identifier`) when you have **genuinely different services**: different pricing tiers per transport, different capabilities, or services that operate independently. A single event should describe one logical service.\n\nIn short: same service + different network paths → one event with multiple `url` tags. Different services → separate events.\n\n## Security\n\n- Secret key bytes are zeroised immediately after signing (in both `announceService` and `buildAnnounceEvent`)\n- Never log or persist the secret key — pass it in and let the library handle cleanup\n- Relay connections use a 10-second timeout to prevent hanging\n- Individual relay failures are logged as warnings but don't reject the promise\n\n## Ecosystem\n\n| Package | Purpose |\n|---------|---------|\n| [toll-booth](https://github.com/forgesworn/toll-booth) | L402 middleware — any API becomes a toll booth in minutes |\n| [toll-booth-announce](https://github.com/forgesworn/toll-booth-announce) | Bridge — announce toll-booth services with one function call |\n| [satgate](https://github.com/forgesworn/satsgate) | Production L402 gateway with Lightning and Cashu support |\n| [402-mcp](https://github.com/forgesworn/402-mcp) | MCP server for AI agents to discover, pay, and consume 402 APIs |\n| [Live Dashboard](https://402.pub) | See every service announcing on the network |\n\n## Licence\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fforgesworn%2F402-announce","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fforgesworn%2F402-announce","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fforgesworn%2F402-announce/lists"}