Alimenter votre agent
La commande propre à l'éditeur. Ce n'est pas un endpoint PlugMCP.
Host a copy with our keys and logs.
npx -y [email protected]Claude Code n'a pas de lien d'installation pour une commande locale. Copiez la commande ci-dessous et exécutez-la dans un terminal.
claude mcp add 402-announce -- npx -y 402-announce@2.3.1À exécuter dans un terminal.
{ "mcpServers": { "402-announce": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}claude_desktop_config.json
URL distante ou commande sur votre machine ? Ce qui distingue les deux installations
Exécuter sur PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
LancerDe l'éditeur
Experimental storage discovery now has a separate, key-free API for public paid packages and free mirror shelter. See the version-1 contract, JSON Schema and . creates an unsigned event for an external signer; verifies the exact returned event, and preserves expired/withdrawn replacement records. These APIs do not publish, contact storage nodes or purchase storage. The existing paid-API contract is unchanged.
Announce HTTP 402 services (L402 and x402) on Nostr for decentralised discovery. Kind 31402 parameterised replaceable events.
buildStorageAnnouncementacceptSignedStorageAnnouncementselectStorageAnnouncementsannounceServiceAnnounce HTTP 402 services on Nostr for decentralised discovery. Supports both L402 and x402 payment protocols.
Publishes kind 31402 parameterised replaceable events so that AI agents (and any Nostr client) can discover paid APIs without a central registry.
Live Dashboard — see every service announcing on the network right now.
flowchart LR
A[Your API] -->|"npm install<br/>402-announce"| B[402-announce]
B -->|"kind 31402<br/>signed event"| C[(Nostr Relays)]
C -->|subscribe & filter| D[402-mcp]
D -->|discover + pay| A
style B fill:#f59e0b,color:#000
style C fill:#8b5cf6,color:#fff
style D fill:#3b82f6,color:#fff
Your API publishes a service announcement to Nostr relays. AI agents (via 402-mcp) discover it, pay the invoice, and consume the API. No central registry required.
npm install 402-announce
402-announce is ESM-only. It ships no CommonJS build and its exports map has no require condition, so require('402-announce') fails with ERR_PACKAGE_PATH_NOT_EXPORTED. Use import, or await import('402-announce') from CommonJS.
import { announceService } from '402-announce'
const handle = await announceService({
secretKey: '64-char-hex-nostr-secret-key',
relays: ['wss://relay.damus.io', 'wss://relay.primal.net'],
identifier: 'jokes-api',
name: 'Jokes API',
urls: ['https://jokes.example.com'],
about: 'A joke-telling service behind an L402 paywall',
pricing: [
{ capability: 'get_joke', price: 1, currency: 'sats' },
],
paymentMethods: [['l402', 'lightning'], ['cashu'], ['xcashu']],
topics: ['comedy', 'ai'],
capabilities: [
{ name: 'get_joke', description: 'Returns a random joke' },
],
version: '1.0.0',
})
console.log('Published event:', handle.eventId)
console.log('From pubkey:', handle.pubkey)
// Later, when shutting down:
handle.close()
Multi-transport example (clearnet + Tor + Handshake — same service, different access paths):
const handle = await announceService({
secretKey: '64-char-hex-nostr-secret-key',
relays: ['wss://relay.damus.io', 'wss://relay.primal.net'],
identifier: 'jokes-api',
name: 'Jokes API',
urls: [
'https://jokes.example.com', // clearnet
'http://jokesxyz...onion', // Tor hidden service
'https://jokes.example.hns', // Handshake domain
],
about: 'A joke-telling service behind an L402 paywall',
pricing: [{ capability: 'get_joke', price: 1, currency: 'sats' }],
paymentMethods: [['l402', 'lightning']],
topics: ['comedy', 'ai'],
})
Each 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. Not every parseable URL is accepted: see URL and relay validation.
See the examples/ directory in the GitHub repository for runnable scripts. It is not included in the npm package.
flowchart LR
subgraph "Your Server"
API[Your API]
TB[toll-booth<br/>L402 paywall]
AN[402-announce]
end
subgraph "Nostr Network"
R1[(Relay 1)]
R2[(Relay 2)]
end
subgraph "AI Agent"
MCP[402-mcp<br/>discovery + payment]
end
API --> TB
TB -->|"protects"| API
AN -->|"kind 31402"| R1
AN -->|"kind 31402"| R2
R1 -->|"subscribe"| MCP
R2 -->|"subscribe"| MCP
MCP -->|"HTTP + L402 token"| TB
style TB fill:#ef4444,color:#fff
style AN fill:#f59e0b,color:#000
style MCP fill:#3b82f6,color:#fff
announceService)close() handle for clean disconnectionannounceService(config): Promise<Announcement>High-level function that builds, signs, and publishes the event to multiple relays.
Returns an Announcement handle:
eventId: the ID of the signed Nostr eventpubkey: the Nostr pubkey derived from your secret keyclose(): disconnect from all relays (synchronous; call it on shutdown to avoid leaking WebSockets)Rejects (it is an async function, so these are promise rejections) when the config is invalid: a secretKey that is not 64 hex characters, an empty relay list, more than 50 relays, a relay URL that is not ws:// or wss://, has credentials or points at a private or loopback host, a service urls list with no public URL, or any buildAnnounceEvent validation failure.
Relay failures never reject. Each relay is tried in parallel with a 10-second connect timeout, and a failure is logged with console.warn. If every relay fails, announceService still resolves with the eventId of the signed event, even though no relay accepted it, and logs [402-announce] No relays accepted the event. The Announcement handle does not report how many relays accepted the event, so the warning is the only signal. If you need to know that at least one relay stored the event, call buildAnnounceEvent and publish it yourself, checking each relay.publish() result.
buildAnnounceEvent(secretKey, config): VerifiedEventLower-level function that builds and signs the event without publishing. Useful if you manage relay connections yourself. config is an AnnounceConfig without relays. It throws synchronously on invalid input and does not apply the "at least one public URL" rule.
isPrivateHost(hostname): booleanThe SSRF guard that announceService applies to relay and service URLs, exported for your own use. It takes a bare hostname (not a URL) and returns true for:
localhost, *.localhost::1, ::, link-local fe80::/10, unique-local fc00::/7, Teredo 2001:0000::/32, and IPv4-mapped, IPv4-compatible or 6to4 forms that embed a private IPv4 address0.0.0.0/8, 10.0.0.0/8, 100.64.0.0/10, 127.0.0.0/8, 169.254.0.0/16, 172.16.0.0/12, 192.0.0.0/24, 192.0.2.0/24, 192.88.99.0/24, 192.168.0.0/16, 198.18.0.0/15, 198.51.100.0/24, 203.0.113.0/24 and 240.0.0.0/40x7f000001, 2130706433, 127.1)It inspects the string only and never resolves DNS. It does not flag multicast addresses such as 224.0.0.1.
L402_ANNOUNCE_KIND: the event kind, 31402AnnounceConfig, Announcement, PricingDef, CapabilityDef: type-only exportsinterface PricingDef {
capability: string // 1-64 characters, no control characters
price: number // finite and non-negative
currency: string // any non-blank string up to 32 characters, no control characters
}
interface CapabilityDef {
name: string // up to 128 characters
description: string // up to 4096 characters
endpoint?: string // starts with '/', 'http://' or 'https://'; up to 2048 characters
schema?: unknown // JSON Schema for the input
outputSchema?: unknown // JSON Schema for the output
}
currency is a free-form label, not an enumeration: the library does not check it against a list of allowed values, and 'sats' is simply the value used throughout this documentation. Whether a client understands another unit is up to that client. pricing takes 1–100 entries and capabilities at most 100. The whole event content may be at most 64 KiB and 20 levels of nesting.
Both buildAnnounceEvent and announceService reject a urls entry that:
new URL(), is longer than 2048 characters or contains control charactersdata:, file:, javascript:, blob: or vbscript:buildAnnounceEvent stops there and accepts private hosts, because it only serialises. announceService also requires at least one public URL: an http: or https: URL whose hostname isPrivateHost does not match, a .onion hostname, or any other scheme (the last two skip the host check). The remaining entries may be private.
Relay URLs are stricter: ws:// or wss:// only, no embedded credentials, no private or loopback host, and at most 50 after de-duplication. A ws:// relay logs a warning.
These checks read the hostname text only. There is no DNS resolution, so DNS rebinding is not caught; deploy behind network-level egress controls.
The storage extension described at the top of this README is key-free: it builds unsigned events, verifies events that an external signer returns, and selects between them. It does not publish, contact storage nodes or purchase storage, and it is separate from announceService. Do not pass a storage description to announceService or buildAnnounceEvent.
Import path. The six functions are exported from the 402-announce/storage subpath and also from the package root:
import { buildStorageAnnouncement } from '402-announce/storage'
// or: import { buildStorageAnnouncement } from '402-announce'
The subpath carries only the six functions and the ParsedStorageAnnouncement type. The constants (STORAGE_PROFILE, STORAGE_SERVICE_PATH, STORAGE_MAX_EVENT_BYTES, STORAGE_MAX_TTL_SECONDS, STORAGE_DEFAULT_MAX_AGE_SECONDS) and the description types (such as StorageServiceDescription and StorageReadOptions) are exported from the root only.
StorageReadOptions is { now: number; maxAgeSeconds?: number; clockSkewSeconds?: number }, with now in Unix seconds. The functions throw Error('Invalid storage service profile.') on invalid input. selectStorageAnnouncements skips invalid records instead, but still throws for invalid options or more than 512 records.
The flow is build, sign externally, accept, select, then bind to the endpoint. The example below uses a throwaway local key as the stand-in for the external signer (nostr-tools is a dependency of this package). In production the key never enters this code.
import { finalizeEvent, generateSecretKey, getPublicKey } from 'nostr-tools/pure'
import {
acceptSignedStorageAnnouncement,
buildStorageAnnouncement,
selectStorageAnnouncements,
validateStorageEndpointBinding,
} from '402-announce/storage'
const now = Math.floor(Date.now() / 1000)
const signerKey = generateSecretKey() // stand-in for an external signer
const description = {
profile: 'forgesworn-storage-service-v1',
service_pubkey: getPublicKey(signerKey),
identifier: 'open-shelter-node',
name: 'Open shelter node',
about: 'Best-effort mirror shelter for signed blobs.',
origins: ['https://storage.example/'],
max_blob_bytes: 1073741824,
observed_at: now,
expires_at: now + 7200,
state: 'published',
checkout: null,
services: [{
id: 'open-shelter',
type: 'free-mirror',
revision: 1,
availability: 'accepting',
operation: 'mirror',
authorisation: 'bud-11',
retention: 'best-effort',
eviction_policy: 'Guest mirrors can be evicted under storage pressure.',
}],
}
// 1. Build the unsigned event. No key or network access.
const requested = buildStorageAnnouncement(description)
// 2. Sign it externally. The signer must not change the template.
const signed = finalizeEvent(requested, signerKey)
// 3. Accept the returned event. Throws if the signature, freshness or template differ.
const accepted = acceptSignedStorageAnnouncement(signed, requested, { now })
// Publishing accepted.event to relays is a separate step that you perform.
// 4. Later, a reader selects the newest record per listing from relay results.
const listings = selectStorageAnnouncements([accepted.event], { now })
const [listing] = listings
// Keep `listings` as watermarks. Show only current, published, accepting services.
// 5. After separately fetching the node's description (GET /services/v1, here reusing
// `description`), check it matches the signed listing and the chosen origin.
const fetched = description
const current = validateStorageEndpointBinding(fetched, listing, 'https://storage.example/', { now })
console.log(current.identifier)
Paid storage listings add a checkout object and paid-storage services. See the version-1 contract for every field and the signed fixtures for paid, combined, withdrawn and expired examples.
flowchart TD
A[announceService config] --> B{Validate}
B -->|"secretKey: 64-char hex"| C[Derive pubkey]
B -->|"relays: wss:// URLs"| C
C --> D[Build kind 31402 event]
D --> E[Sign with secret key]
E --> F[Zeroise key bytes]
F --> G["Connect relays (parallel, 10s timeout)"]
G --> H{Each relay}
H -->|success| I[Publish event]
H -->|failure| J[Log warning, continue]
I --> K["Return { eventId, pubkey, close() }"]
J --> K
Each 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.
graph TB
subgraph "Kind 31402 Event"
direction TB
subgraph Tags
D["d: jokes-api"]
N["name: Jokes API"]
U1["url: https://jokes.example.com"]
U2["url: https://jokesapi.example.onion (optional)"]
AB["about: A joke-telling service"]
PMI1["pmi: l402, lightning"]
PMI2["pmi: cashu"]
P["price: get_joke, 1, sats"]
T["t: comedy"]
end
subgraph Content["Content (JSON)"]
CAP["capabilities: [{ name, description }]"]
VER["version: 1.0.0"]
end
end
style Tags fill:#1e293b,color:#e2e8f0
style Content fill:#1e293b,color:#e2e8f0
Each paymentMethods entry is an array where the first element is the rail identifier and subsequent elements are rail-specific parameters.
The event content is a JSON object with optional fields. Each capability may also carry endpoint, schema and outputSchema (see CapabilityDef above):
{
"capabilities": [
{ "name": "get_joke", "description": "Returns a random joke", "endpoint": "/api/joke" }
],
"version": "1.0.0"
}
This distinction is important for operators:
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.
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.
In short: same service + different network paths → one event with multiple url tags. Different services → separate events.
announceService and buildAnnounceEvent)announceService still resolves with the eventId of the signed event and logs [402-announce] No relays accepted the eventForgeSworn builds open-source cryptographic identity, payments, and coordination tools for Nostr.
Announce HTTP 402 services (L402 and x402) on Nostr for decentralised discovery. Kind 31402 parameterised replaceable events.
{ "mcpServers": { "402-announce": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}Outils
Pas encore de liste d'outils. Les serveurs distants en obtiennent une après le premier contrôle d'état.
FAQ
Copiez sur cette page la configuration stdio pour Cursor, Claude Desktop, Claude Code ou VS Code. Elle utilise l'installation de l'éditeur, pas un proxy PlugMCP.
Aucune variable d'environnement requise n'est indiquée sur cette fiche.
402 Announce s'exécute en local via stdio.
Dernière vérification : 2026-11-14. Announce HTTP 402 services (L402 and x402) on Nostr for decentralised discovery. Kind 31402 parameterised replaceable events.