https://github.com/forgesworn/toll-booth-announce
Bridge between toll-booth and 402-announce — announce your toll-booth service on Nostr for decentralised paid API discovery
https://github.com/forgesworn/toll-booth-announce
402 api-monetisation bitcoin decentralised kind-31402 l402 lightning nostr paid-api service-discovery toll-booth
Last synced: 2 months ago
JSON representation
Bridge between toll-booth and 402-announce — announce your toll-booth service on Nostr for decentralised paid API discovery
- Host: GitHub
- URL: https://github.com/forgesworn/toll-booth-announce
- Owner: forgesworn
- License: mit
- Created: 2026-03-15T11:46:54.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-18T17:55:10.000Z (3 months ago)
- Last Synced: 2026-03-19T02:33:06.197Z (3 months ago)
- Topics: 402, api-monetisation, bitcoin, decentralised, kind-31402, l402, lightning, nostr, paid-api, service-discovery, toll-booth
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/toll-booth-announce
- Size: 554 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# toll-booth-announce
**Nostr:** [`npub1mgvlrnf5hm9yf0n5mf9nqmvarhvxkc6remu5ec3vf8r0txqkuk7su0e7q2`](https://njump.me/npub1mgvlrnf5hm9yf0n5mf9nqmvarhvxkc6remu5ec3vf8r0txqkuk7su0e7q2)
Announce your [toll-booth](https://github.com/forgesworn/toll-booth) service on Nostr for decentralised paid API discovery.
Publishes a [kind 31402](https://github.com/forgesworn/402-announce) event so AI agents and clients can find your API without a centralised registry.
## Install
```bash
npm install toll-booth-announce 402-announce
```
## Usage
```typescript
import { Booth } from '@forgesworn/toll-booth'
import { phoenixdBackend } from '@forgesworn/toll-booth/backends/phoenixd'
import { announce } from 'toll-booth-announce'
// Your existing toll-booth config
const config = {
serviceName: 'sats-for-laughs',
pricing: {
'/api/joke': { default: 5, standard: 21, premium: 42 },
},
upstream: 'http://localhost:4444',
backend: phoenixdBackend({ /* ... */ }),
freeTier: { requestsPerDay: 3 },
}
const booth = new Booth(config)
// Announce on Nostr — pricing and name derived from config
const announcement = await announce(config, {
secretKey: process.env.NOSTR_SK,
relays: ['wss://relay.damus.io', 'wss://relay.primal.net'],
urls: ['https://jokes.trotters.dev'],
about: 'Lightning-paid joke API — cracker, standard, and premium jokes',
paymentMethods: [['l402', 'lightning']],
topics: ['jokes', 'humour', 'bitcoin', 'lightning'],
})
console.log(`Announced as ${announcement.pubkey} (event ${announcement.eventId})`)
// On shutdown
announcement.close()
```
**Multi-transport example** (clearnet + Tor — same service, different access paths):
```typescript
const announcement = await announce(config, {
secretKey: process.env.NOSTR_SK,
relays: ['wss://relay.damus.io', 'wss://relay.primal.net'],
urls: [
'https://jokes.trotters.dev', // clearnet
'http://jokesxyz...onion', // Tor hidden service
],
about: 'Lightning-paid joke API — cracker, standard, and premium jokes',
paymentMethods: [['l402', 'lightning']],
topics: ['jokes', 'humour', 'bitcoin', 'lightning'],
})
```
`urls` accepts 1–10 entries. Clients try them in order and use whichever they can reach.
## Multiple URLs vs multiple events
**Multiple URLs in one event** — use `urls: ['...', '...']` when the URLs are the **same service** on different transports (clearnet, Tor, Handshake). Pricing, macaroon key, and credits are shared. This provides censorship resistance and redundancy.
**Separate kind 31402 events** — publish a new announcement with a different `identifier` when you have **genuinely different services**: separate pricing, separate capabilities, or services that operate independently.
In short: same service + different network paths → one event with multiple URLs. Different services → separate events.
## What gets announced
The bridge reads your toll-booth config and publishes a Nostr event with:
| Field | Source |
|-------|--------|
| Service name | `config.serviceName` (defaults to `"toll-booth"`) |
| Pricing | `config.pricing` table — flat or tiered (uses default/lowest tier) |
| Identifier | Slugified service name (overridable) |
You provide the fields toll-booth can't know: your public URL, description, Nostr key, relays, and payment methods.
## Part of the 402-announce ecosystem
This is one of several bridges that publish kind 31402 events for paid API discovery:
- **toll-booth-announce** — for toll-booth services (TypeScript)
- **aperture-announce** — for Lightning Labs Aperture proxies (Go)
Any client querying Nostr for kind 31402 events can discover your service. See [402-mcp](https://github.com/forgesworn/402-mcp) for an AI agent that does this automatically.
## Licence
MIT