llms.txt

# toll-booth-dvm

> Connecting paid HTTP APIs to Nostr's AI marketplace is hard — you need to
> handle NIP-90 job events, relay Lightning invoices, poll for settlement, and
> publish results, all without holding funds. toll-booth-dvm is a TypeScript
> library that bridges any toll-booth-gated API to Nostr as a Data Vending
> Machine (DVM).

Operators who already gate their APIs with toll-booth can expose them to Nostr
clients with two function calls: `announce` (publish a NIP-89 discovery event)
and `serve` (start the relay loop). The DVM handles the full L402 payment flow
— relaying bolt11 invoices, polling for settlement, retrying with credentials —
without ever holding or forwarding funds.

## Getting Started

```bash
npm install toll-booth-dvm
```

```typescript
import { serve } from 'toll-booth-dvm'

const dvm = await serve({
  secretKey: process.env.NOSTR_SK,
  relays: ['wss://relay.damus.io'],
  endpoint: 'http://localhost:3000',
  announceOnStart: true,
  boothConfig: {
    serviceName: 'My API',
    pricing: { '/route': 10 },
  },
  about: 'Lightning-paid routing API',
})

process.on('SIGINT', () => dvm.close())
```

## Key Concepts

- **announce** — publishes a NIP-89 kind 31990 handler event so Nostr clients can discover your DVM
- **serve** — subscribes to kind 5800 job requests, proxies them to your toll-booth endpoint, and publishes kind 6800 results
- **L402 flow** — when the upstream returns HTTP 402, the DVM relays the Lightning invoice to the client via a kind 7000 feedback event, polls for settlement, then retries with the L402 credential
- **Non-custodial** — the DVM never holds funds; payments settle directly between client wallet and toll-booth backend
- **Path validation** — optional allowedPaths whitelist prevents clients from accessing unintended endpoints

## API Surface

- `announce(boothConfig, options)` — publish a NIP-89 discovery event to relays
- `serve(options)` — start the relay loop; returns a `DvmHandle` with `close()`
- `ServeOptions` — configuration: secretKey, relays, endpoint, allowedPaths, timeouts, limits
- `BoothConfigLike` — pricing configuration mapped from toll-booth's format
- `JOB_KIND` (5800), `RESULT_KIND` (6800), `FEEDBACK_KIND` (7000), `HANDLER_KIND` (31990) — Nostr event kind constants

## Examples

- `examples/local-demo.ts` — run the full L402 flow locally with a mock server (zero setup)
- `examples/announce.ts` — publish a NIP-89 discovery event
- `examples/serve.ts` — start the relay loop against a real endpoint