Build for any Nostr store.

Production identity

Pin the hex pubkey. Verify signed discovery before sending secrets or trusting quotes.

Available today

Broad NWC links are accepted when they support invoice creation and status lookup, including links that advertise pay_invoice. BitUnlock never invokes extra methods. Use small amounts and a dedicated low-balance seller wallet; restricted permissions remain safest.

Browser ESM

import {
  createBitUnlockClient,
  buildBitUnlockProductEventTemplate
} from "/assets/bitunlock-sdk.js";

Machine-readable resources

• Agent guide (llms.txt)
• Product-event JSON Schema
• Signed product test vector
• Complete seller + buyer example
• OpenAPI 3.1 contract

Payment mode

direct-split (default): two legs, seller and BitUnlock, per the fee policy (100bps, 10-sat minimum). single-recipient: one leg, the full price, straight to the seller's own wallet — gated to tenants an operator has explicitly granted this for. Micro-ticket tenants on accrual billing keep the single leg while the platform fee accrues to a ledger, settled as one batched invoice via GET /v1/fee-ledger; overdue settlements suspend quoting only, never a buyer's paid order — and the service DMs the tenant's configured npubs when a settlement opens, three days before its deadline, and the day quoting pauses. Never hard-code a leg count; render whatever the quote returns.

Delivery mode: execution

A product doesn't have to be a static payload. deliveryMode: "execution" sells a bounded, server-run call to a third-party provider instead — pay, then get a real result computed on demand, billed per completed purchase. A Provider Connection can use Routstr conventions or an OpenAI-compatible API such as OpenRouter; its key is validated live, encrypted at rest, and never returned. Execution products are operator-gated.

Execution input, checked at quote time

An execution-mode quote takes an extra executionInput: {schema, ciphertextSha256, serviceEnvelope}, a NIP-44 payload (buyer → service pubkey) whose plaintext must match the product's own inputSchema. BitUnlock decrypts it, enforces the product's limits, and — for a blob-bearing input — actually fetches the referenced blob before minting an invoice. An unreachable host, a bad content type, a hash mismatch or an oversized input is refused with the specific cause — free, with no order to recover. A text-only input carries no blob, so that fetch and its failure modes do not apply.

Input schemas are implemented, not declared

inputSchema and outputSchema name a validator BitUnlock implements. They are not free-form identifiers: the platform parses and bounds every execution input and output itself, and a schema it does not know is refused at quote time with input_schema_unknown — so a product registered against an unrecognised name can never take a quote. That is what makes size and shape enforceable before an invoice exists, which is what keeps a bad input a free 422 instead of a paid order that fails. Adding a schema is a small platform change; ask for one before building against it.

Execution failure, at unlock time

What is left after payment is what could not be known before it: a provider error, a timeout, or a host that died between quote and unlock. Those surface as a generic execution_failed_permanently, execution_retryable_failure, or execution_retry_window_exhausted (the last two 503 with a retry-after, and neither terminal — a spent attempt budget refills). The specific internal cause is never exposed to the buyer.

Image-output products

A product whose outputSchema has a registered output transform is an image product: the provider is called with modalities: ["image","text"], the returned image is decoded by its actual magic bytes (PNG and JPEG both accepted — declared subtypes are not trusted), and the transform reduces it server-side to a compact JSON payload, e.g. a run-length-encoded 48×48 pixel-art object. The NIP-44 fulfillment envelope caps plaintext at 64KB; the transform is what makes an image deliverable at all. Buyer input for these products is text-only.

Companion stages: one invoice, two results

A product can bundle a second, image-producing execution into the same order — one quote, one invoice at the primary price, one envelope. After the primary output validates, a short text input is derived from it and the companion product runs with its own model, encrypted prompt, and provider connection; the result rides along as an extra payload field. Best-effort by contract: a companion failure never fails the paid order.

Generic tenant secrets

A separate write-only configuration vault for future tenant features: PUT /v1/tenant-secrets/{name} creates or rotates, GET lists names and timestamps only, DELETE removes. Values are AEAD-encrypted with the tenant id and secret name bound into the encryption context, capped at 8KB each and 64 per tenant, and no endpoint ever returns one. No production runtime feature consumes these values yet; execution API keys belong in Provider Connections.

Seller

1. Verify signed discovery and pin the service key.
2. Accept policy and register a compatible NWC wallet.
3. Build, sign, and publish the product event.
4. NIP-44 encrypt the delivery payload to BitUnlock.
5. Register the coordinate, epoch, type, and ciphertext.

Buyer

1. NIP-98 sign a quote request.
2. Pay every returned invoice — one or two, depending on payment mode.
3. Poll the order; refresh only expired unpaid legs.
4. Call unlock once every leg has settled.
5. NIP-44 decrypt and verify the fulfillment envelope.

Perpetual or time-boxed, per product

Registering a product is perpetual access by default — one purchase, access forever. Set accessTermSeconds to sell a rental or manually renewable term: access expires after that many seconds, and another completed purchase renews it. BitUnlock does not automatically or recurringly charge the buyer.

Recovery across devices

Authenticated buyers call GET /v1/access-entitlements to recover every entitlement they own — the signed receipt, an accessPolicy (perpetual or a term with its expiry), and an effective status: active, expired, or revoked.

Seller-initiated revocation

Sellers can revoke a specific buyer's entitlement with POST /v1/entitlements/:id/revoke. Revocation is never embedded in the signed receipt itself — changing signed content would invalidate its own signature — so a relying party that must honor revocation checks current status from the API rather than trusting a cached receipt indefinitely.

Machine-readable contract

• Entitlement-document JSON Schema
• Signed entitlement test vector

Validate a parsed entitlement document against the schema before trusting its shape.