> Documentation index: fetch https://dvmkit.com/llms.txt to find every page before exploring further.

# SDK Reference (/docs/sdk)

Build DVMs with @dvmkit/sdk. Declare capabilities, inputs, pricing, and handlers. The SDK handles transport, payment, streaming, and persistence.



`@dvmkit/sdk` is the recommended way to build a DVM. You declare what each capability does, and the SDK handles the HTTP protocol, payment, streaming, persistence, and discovery surfaces.

```typescript
import { configureDVM } from "@dvmkit/sdk";

export default configureDVM({
  name: "echo",
  capability: "echo",
  tags: ["text"],

  onJob(ctx) {
    ctx.complete(ctx.input);
  },
});
```

Install an exact version in a Node.js 22 or later project. `@dvmkit/sdk` is pre-1.0 alpha software: pin the version you install and review it before upgrading.

```bash
npm install --save-exact @dvmkit/sdk
```

Add `pg` when the DVM will use the built-in Postgres stores in production:

```bash
npm install pg
```

Running it [#running-it]

Use `serve()` for the usual one-DVM process:

```typescript
import { serve } from "@dvmkit/sdk/server";
import dvm from "./handler.js";

await serve(dvm, {
  database: process.env.DATABASE_URL,
});
```

The server listens on `PORT` or `8080`. Production needs Postgres unless you supply an explicit `jobStore`. `devMode: true` is the local and test escape hatch.

Test a running DVM with the caller CLI:

```bash
dvm request --endpoint http://localhost:8080 -i "hello" --human
```

`serve(dvm, options)` is a convenience around `createDVMHost(options)`, `host.mount(dvm)`, and `host.serve()`. Use `createDVMHost` when you need host-level routes or several DVM descriptors in one process.

A real DVM: web content extraction [#a-real-dvm-web-content-extraction]

```typescript
import { configureDVM } from "@dvmkit/sdk";

export default configureDVM({
  name: "scrape",
  description: "Extract clean markdown from any URL",
  capability: "extract",
  tags: ["web", "extraction"],
  price: "$0.01",

  async onJob(ctx) {
    const url = typeof ctx.input === "string" ? ctx.input.trim() : "";
    if (!url.startsWith("http")) {
      ctx.fail("Input must be a valid URL");
      return;
    }

    ctx.text("Fetching content...");

    const response = await ctx.fetch(`https://r.jina.ai/${url}`);
    if (!response.ok) {
      ctx.fail(`Fetch failed: ${response.status.toString()}`);
      return;
    }

    const markdown = await response.text();
    ctx.artifact({ data: markdown, mime_type: "text/markdown" });
    ctx.complete("Content extracted");
  },
});
```

The wire request names the capability. The SDK assigns the job ID and streams messages:

```
Client: POST /v1/job { capability: "extract", data: "https://example.com" }
Server: 202 { job_id: "job-abc-1" }
Client: GET /v1/job/job-abc-1/messages (SSE)
Server: { seq: 1, type: "text",     content: { text: "Fetching content..." } }
Server: { seq: 2, type: "artifact", content: { data: "# Example...", mime_type: "text/markdown" } }
Server: { seq: 3, type: "complete", content: { summary: "Content extracted" } }
```

configureDVM [#configuredvm]

`configureDVM(config)` validates your config and returns a frozen `DVMDescriptor`. The flat single-capability shape becomes a one-entry `capabilities` map internally.

DVM-level fields [#dvm-level-fields]

These fields stay at the top level in both descriptor shapes:

| Field                | Type                                                                                                      | Required | Description                                                                                                                                                                                                                                                                                                                   |
| -------------------- | --------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`               | `string`                                                                                                  | yes      | Display name                                                                                                                                                                                                                                                                                                                  |
| `description`        | `string`                                                                                                  |          | DVM description                                                                                                                                                                                                                                                                                                               |
| `tag`                | `string`                                                                                                  |          | One discovery tag                                                                                                                                                                                                                                                                                                             |
| `tags`               | `string[]`                                                                                                |          | Discovery tags                                                                                                                                                                                                                                                                                                                |
| `currency`           | `string`                                                                                                  |          | Lowercase ISO 4217 pricing currency. Defaults to `"usd"`                                                                                                                                                                                                                                                                      |
| `idleTimeout`        | `number`                                                                                                  |          | Caller response/payment window before automatic cancellation, in whole seconds. Default: `3600`; range: `1–604800` (7 days)                                                                                                                                                                                                   |
| `processingWatchdog` | `number`                                                                                                  |          | Seconds without a worker heartbeat before a working job is failed as `worker_died_mid_job`. Default: `300`                                                                                                                                                                                                                    |
| `paymentMethods`     | `("cashu" \| "x402" \| "tempo")[]`                                                                        |          | Override the set derived from configured rails                                                                                                                                                                                                                                                                                |
| `credit`             | `{ min?, max?, ttl?, allowOneShotStablecoin? }`                                                           |          | Offer prepaid credit; one-payment stablecoin funding is opt-in                                                                                                                                                                                                                                                                |
| `cashu`              | `{ minLocktimeSeconds?, unsignedMinLocktimeSeconds?, unsignedResultWaitSeconds?, advertiseRefundDelay? }` |          | Shortest refund lock a Cashu payment may carry, and whether the unsigned 402 advertises it; see [Cashu lock floors](#cashu-lock-floors). `unsignedResultWaitSeconds` (integer `0–20`, default `10`) is how long an unsigned paid submit without `X-Cashu-Request-Id` waits to return the result inline; `0` disables the wait |
| `auth`               | `DVMAuthScheme`                                                                                           |          | Require signed caller requests                                                                                                                                                                                                                                                                                                |
| `routes`             | `(app: Hono, context: DVMRouteContext) => void \| Promise<void>`                                          |          | Register DVM-scoped HTTP routes; context includes signed-route and compatibility helpers                                                                                                                                                                                                                                      |
| `onBoot`             | `(env) => void \| Promise<void>`                                                                          |          | Run before the listener opens                                                                                                                                                                                                                                                                                                 |
| `onShutdown`         | `() => void \| Promise<void>`                                                                             |          | Run during host shutdown                                                                                                                                                                                                                                                                                                      |

Since `@dvmkit/sdk` 0.14.2, `idleTimeout` is a deadline on each question, not on the job. The window starts when a prompt or payment request is emitted and ends when the awaited response or payment arrives. The SDK stamps it on the message as `content.expires_at_ms` (emission time plus `idleTimeout`), so the caller can see it. Text messages and answers to other prompts do not extend it. With several prompts open, the earliest deadline governs. When it passes, the job is cancelled and the cancellation is attributed to the caller. Time spent working with no question open has no idle limit.

Size `idleTimeout` to the longest a caller may need to answer or pay. A question that waits for a person overnight needs `43200` (12 hours) or more; the default `3600` gives them one hour.

`processingWatchdog` is the separate limit for a job that is working. The SDK records a heartbeat for each running job every 30 seconds, so a handler that runs for hours stays alive as long as its process does. The watchdog fails a job whose heartbeat is older than the limit, which means its worker died or was frozen. A process blocked by synchronous work records no heartbeats, so raise the watchdog only if your handler can block the event loop for close to the limit, five minutes by default. On hosted DVMs, a long job also needs its Machine kept up; see [long-running jobs](/docs/resources#long-running-jobs).

Cashu lock floors [#cashu-lock-floors]

A Cashu payer can lock its proofs with a refund path that opens after a `locktime`. Once that time passes, the payer can take back any proof you have not melted yet. So the SDK refuses a lock that opens too soon, with `lock_not_exclusive`. Since `@dvmkit/sdk` 0.18.0 you set those floors with `cashu`:

| Field                        | Default                            | Minimum | What it governs                                                                                                                                                             |
| ---------------------------- | ---------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `minLocktimeSeconds`         | `604800` (7 days)                  | `90000` | Signed payments, mid-job payments, `POST /v1/credit`, and any payment sent with `X-Cashu-Request-Id`. Advertised as `cashu.min_locktime`; the SDK enforces it less 24 hours |
| `unsignedMinLocktimeSeconds` | `minLocktimeSeconds` less 24 hours | `3600`  | An unsigned `POST /v1/job` paid without `X-Cashu-Request-Id`, which is how a generic NUT-24 wallet pays. Enforced exactly. It may not exceed the default                    |

A DVM that sets `cashu` and accepts unsigned paid calls advertises the unsigned floor as `/v1/info.cashu.unsigned_min_locktime`. A generic wallet cannot read it before paying unless you advertise it (see below), and Nutshell locks a 1-day refund path by default, so a DVM that wants those payments sets the unsigned floor under a day:

```ts
configureDVM({
  // ...
  auth: secp256k1Auth({ allowUnsignedPaid: true }),
  cashu: { unsignedMinLocktimeSeconds: 43_200 }, // 12 hours
});
```

Lower a floor only if you melt more often than it. A proof still unmelted when its lock opens can be taken back by the payer. `configureDVM` throws on a value below the minimum or an unsigned floor above the default.

A generic wallet can learn how long to lock before paying if you set `advertiseRefundDelay: true` (from `@dvmkit/sdk` 0.33.0, default `false`). The NUT-18 payment request on an unsigned 402 then carries a `refund_delay` tag. Its value is the floor that payment is held to plus the 600-second [exchange-rate hold](/docs/protocol#upfront-payment), in seconds: how long you need before the payer's refund path may open. That floor is the unsigned floor for a request without `X-Cashu-Request-Id`, and `minLocktimeSeconds` less 24 hours for one that sends it. A wallet that reads the tag can lock for at least that long. Leave it off until the mints and wallets your callers use support the tag. With the option off, the payment request is unchanged. Either way, the SDK accepts a proof whose secret carries one `refund_delay` tag and judges the lock as if the tag were absent.

Per-capability fields [#per-capability-fields]

In the flat shape these fields sit at the top level. In the multi-capability shape they sit inside each `capabilities[name]` entry:

| Field         | Type                                      | Required | Description                                                                |
| ------------- | ----------------------------------------- | -------- | -------------------------------------------------------------------------- |
| `capability`  | `string`                                  |          | Capability name in the flat shape                                          |
| `description` | `string`                                  |          | Capability description                                                     |
| `input`       | Zod schema                                |          | Parse and type `ctx.input`                                                 |
| `state`       | object literal                            |          | Per-job state defaults                                                     |
| `price`       | `string`                                  |          | Static USD upfront price such as `"$0.05"`                                 |
| `onQuote`     | `QuoteConfig`                             |          | Dynamic pricing handler                                                    |
| `rates`       | `CapabilityRate[]`                        |          | Published rate card for a priced capability. See [Rate cards](#rate-cards) |
| `onJob`       | `(ctx) => void \| Promise<void>`          | yes      | Handle a new job                                                           |
| `onResponse`  | `(ctx, content) => void \| Promise<void>` |          | Handle a prompt response                                                   |
| `onPayment`   | `(ctx, content) => void \| Promise<void>` |          | Handle a client payment                                                    |
| `onApproval`  | `(ctx, content) => void \| Promise<void>` |          | Handle a client approval                                                   |
| `onCancel`    | `(ctx, content) => void \| Promise<void>` |          | Handle cancellation                                                        |
| `onMessage`   | `(ctx, message) => void \| Promise<void>` |          | Handle an unrecognized message                                             |

Tags [#tags]

Tags are free-form strings advertised in `/v1/info`. Clients use them to match providers to job types:

```typescript
tag: "text";
tags: ["web", "extraction"];
```

Pricing [#pricing]

Static prices are USD literals. The SDK resolves them at request time through its FX source:

```typescript
price: "$0.05";
```

The accepted static range is `"$0.0001"` through four decimal places. A raw msat price is invalid. Use `onQuote` when the price depends on the input or needs more precision. Free capabilities omit `price`.

Pricing in a currency other than USD [#pricing-in-a-currency-other-than-usd]

Set a DVM-level currency when quotes and credit should use another supported currency:

```typescript
currency: "eur";
```

The bundled FX source supports `usd`, `eur`, `gbp`, and `jpy`. A dynamic quote must return the declared currency. A static `price` is always a USD literal, so a non-USD DVM must price through `onQuote`.

The quote carries both the display amount and the exact `amount_micro` integer. Use the integer when a caller or credit ledger must reproduce the charge exactly.

Rate cards [#rate-cards]

A rate card lists what a priced capability charges per unit. Callers' agents and the builder dashboard storefront read it from `/v1/info`, so an agent can explain the price before it asks for a quote. `rates` needs `@dvmkit/sdk` 0.7.0-rc.7 or later. Earlier versions do not support it.

Declare `rates` next to `price` or `onQuote`, at the top level in the flat shape or inside a `capabilities[name]` entry:

```typescript
configureDVM({
  name: "voice",
  capability: "synthesise",
  onQuote: { schema: z.object({ text: z.string() }), handler: quoteByLength },
  rates: [
    { label: "standard", amount: "0.00005", currency: "USD", per: "character" },
    { label: "balanced", amount: "0.00015", currency: "USD", per: "character" },
    { label: "expressive", amount: "0.0003", currency: "USD", per: "character" },
  ],
  async onJob(ctx) {
    /* ... */
  },
});
```

What callers see [#what-callers-see]

`/v1/info` publishes the list at `capabilities.<name>.pricing.rates`, exactly as declared: same order, same strings. A capability without `rates` publishes nothing extra. Isolate-runtime DVMs do not publish rates. The quoted capability above publishes:

```json
{
  "pricing": {
    "quote": {
      "schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": { "text": { "type": "string" } },
        "required": ["text"]
      }
    },
    "rates": [
      { "label": "standard", "amount": "0.00005", "currency": "USD", "per": "character" },
      { "label": "balanced", "amount": "0.00015", "currency": "USD", "per": "character" },
      { "label": "expressive", "amount": "0.0003", "currency": "USD", "per": "character" }
    ]
  }
}
```

A static capability can carry a single rate that restates its price in units, such as `price: "$1.25"` with `rates: [{ amount: "1.25", currency: "USD", per: "episode" }]`.

On a quoted capability, the rates describe how your `onQuote` handler computes its price. They change nothing about quoting: the SDK does not compute quotes from them or check quotes against them, so keep the two in step yourself.

Limits [#limits]

The server refuses to start when a rate card breaks a limit, and the error names the capability and the field:

* 1 to 5 entries, on a capability with `price` or `onQuote`. A free capability cannot declare rates.
* Each entry has only the keys `label`, `amount`, `currency`, and `per`.
* `amount` is decimal dollars as a string, above zero and at most 12 characters: `"0.00015"`, not `0.00015`, `"$0.00015"`, or `"1e-4"`.
* `currency` is exactly `"USD"`, whatever the DVM's pricing currency.
* `per` names the unit (`"character"`, `"episode"`, `"GB per day stored"`). The optional `label` names a tier. Each is 1 to 24 characters with no leading or trailing whitespace.

Capabilities [#capabilities]

The capability is the unit a builder offers and a caller selects. Every DVM has at least one. `/v1/info` lists each capability with its description, input schema, and pricing.

Single-capability DVMs [#single-capability-dvms]

Use the flat shape for the common case:

```typescript
import { configureDVM, z } from "@dvmkit/sdk";

export default configureDVM({
  name: "uppercase",
  capability: "uppercase",
  input: z.object({ text: z.string() }),
  price: "$0.01",

  async onJob(ctx) {
    ctx.complete(ctx.input.text.toUpperCase());
  },
});
```

Multi-capability DVMs [#multi-capability-dvms]

Put each handler, input schema, price, and state shape in `capabilities`. DVM-level fields such as `name`, `tags`, `auth`, `routes`, `onBoot`, and `onShutdown` remain shared:

```typescript
configureDVM({
  name: "cast",
  tags: ["podcast", "rss"],

  capabilities: {
    "add-episode": {
      description: "Add an episode to a private RSS feed",
      input: addEpisodeSchema,
      price: "$0.02",
      async onJob(ctx) {
        /* ... */
      },
    },
    "delete-episode": {
      description: "Delete an episode from a feed",
      input: deleteEpisodeSchema,
      async onJob(ctx) {
        /* ... */
      },
    },
  },
});
```

Capability names [#capability-names]

Names use lowercase letters, digits, and hyphens. They must start with a letter or digit and match `/^[a-z0-9][a-z0-9-]*$/`. `add-episode` is valid. `Add Episode` and `cast/add-episode` are not.

Wire dispatch [#wire-dispatch]

The caller sends `capability` in the request body. The remaining payload is in `data`:

```json
{
  "capability": "add-episode",
  "data": {
    "feed_slug": "morning-news",
    "audio_url": "https://example.com/episode.mp3"
  }
}
```

The SDK selects the matching capability before payment and input validation. A missing or unknown capability returns a structured `400` response.

The job context [#the-job-context]

`onJob` receives an `SDKJobContext`. It exposes the job input, caller identity available to the handler, message methods, flow control, state, storage, environment, and logging.

Identity [#identity]

| Property      | Type                                | Description                       |
| ------------- | ----------------------------------- | --------------------------------- |
| `jobId`       | `string`                            | Server-assigned job ID            |
| `tags`        | `string[]`                          | Tags from the descriptor          |
| `input`       | `Input`                             | Raw input or parsed schema output |
| `params`      | `Record<string, string>`            | Query-style job parameters        |
| `requesterId` | `string`                            | Opaque requester identifier       |
| `paidMsats`   | `number`                            | Total payment received so far     |
| `auth`        | `{ pubkey, envelope } \| undefined` | Verified signed-request identity  |

`ctx.auth` is present only when the descriptor declares signed-request auth. Its `pubkey` is trusted after the SDK verifies the request.

Messaging [#messaging]

```typescript
ctx.text("Working on it...");
ctx.artifact({ data: markdown, mime_type: "text/markdown" });
ctx.sendMessage("custom-type", { value: 1 });
```

A large file goes out by URL instead of inline. Set `sha256` (lowercase hex) and `size_bytes` from the exact bytes the URL serves:

```typescript
import { createHash } from "node:crypto";

const bytes = await renderReport(ctx.input);
const url = await upload(bytes, `${ctx.jobId}/report.pdf`);

ctx.artifact({
  url,
  name: "report.pdf",
  mime_type: "application/pdf",
  sha256: createHash("sha256").update(bytes).digest("hex"),
  size_bytes: bytes.byteLength,
});
```

The signed receipt covers each artifact message, so these two fields put the file itself under the receipt. Without them the receipt binds only the URL, and whatever that URL serves later is unproven. [Receipts](/docs/receipts#checking-a-downloaded-file) shows the caller's side of the check.

Flow control [#flow-control]

```typescript
const response = await ctx.prompt("language", "Which language?", {
  options: ["Spanish", "French", "German"],
});

await ctx.requestPayment(
  { amount: 0.1, currency: "usd" },
  "Processing fee"
);

ctx.working(30, "Generating output...");
ctx.progress(45, "transcribing", "Halfway through transcription");

ctx.complete("Done");
ctx.fail("Something went wrong");
```

`prompt()` and `requestPayment()` suspend the handler until the caller responds. Each prompt or payment request they emit carries `content.expires_at_ms`, the emission time plus the DVM's [`idleTimeout`](#dvm-level-fields). If the caller has not answered by then, the job is cancelled. A numeric payment amount is raw msats. A `{ amount, currency }` envelope is converted through the SDK FX source.

Code before a `prompt()` or `requestPayment()` can run twice. While the job stays in memory, the caller's answer simply resolves the awaited promise. After a restart, or when the answer reaches a different machine, the SDK runs `onJob` again from the top. Recorded answers, payments, and `ctx.step` results come back instantly on that replay, but any other code runs again. Put external calls and anything nondeterministic before a prompt inside [`ctx.step`](#durable-steps).

`working()` closes the SSE stream and tells the caller to return later. `progress()` keeps the stream open and emits a non-yield heartbeat. Its percentage is clamped to `0` through `100`.

Cancellation [#cancellation]

Long-running work should observe `ctx.signal`:

```typescript
const response = await ctx.fetch(providerUrl);
```

`ctx.fetch` is instrumented and already carries `ctx.signal`, so the request is traced and aborted when the caller cancels or the job becomes stale. Pass `ctx.signal` separately to provider SDKs or other work that accepts an `AbortSignal`.

Platform services [#platform-services]

Inside `onJob(ctx)`, the SDK supplies:

```typescript
ctx.state.progress = 50;
await ctx.store.set("rate:btcusd", 65_000, { ttl: 300 });
const cached = await ctx.store.get<number>("rate:btcusd");
ctx.env.API_KEY;
ctx.log.info("Processing", { jobId: ctx.jobId });
const result = await ctx.step("fetch", async () => {
  const response = await ctx.fetch("https://api.example.com/data");
  return response.json();
});
ctx.signal;
```

On Postgres, a key with a `ttl` is deleted after it expires: within a minute while the DVM runs, and within a minute of its next start otherwise. You can state a TTL as a retention period.

Report builder costs [#report-builder-costs]

Call `ctx.cost()` where your handler incurs a vendor or compute cost. The amount is in major currency units, like other handler-facing money values:

```typescript
const transcript = await ctx.step("transcribe", async () => {
  const result = await whisper(audio);
  ctx.cost({ amount: result.seconds * 0.0001, currency: "usd" });
  return result;
});
```

Repeated declarations add. The SDK sums the major-unit amounts and rounds the job total once to a millionth of the currency, so fine per-token charges are not individually rounded away. Use one lowercase ISO currency throughout a job; mixing currencies makes the total unreportable rather than converting at an invented rate.

No declaration means “unknown”, while `ctx.cost({ amount: 0, currency: "usd" })` explicitly reports that the job was free to serve. Declarations inside `ctx.step()` are stored with the step and replayed exactly once when the body is skipped. Paid completions send the cost with revenue; free completions, failures, and cancellations report it separately, so a cost never invents a sale.

Multi-turn conversations [#multi-turn-conversations]

Linear async style [#linear-async-style]

Use an async handler when the work reads naturally from top to bottom:

```typescript
configureDVM({
  name: "translator",
  capability: "translate",
  async onJob(ctx) {
    const language = await ctx.prompt("language", "Translate to?");
    const result = await translate(ctx.input, language.text);
    ctx.complete(result);
  },
});
```

Event-driven style [#event-driven-style]

Use `onResponse` when explicit message routing fits the DVM better:

```typescript
configureDVM({
  name: "translator",
  capability: "translate",
  state: { original: "" },

  onJob(ctx) {
    ctx.state.original = ctx.input;
    ctx.prompt("language", "Translate to?");
  },

  async onResponse(ctx, content) {
    ctx.complete(await translate(ctx.state.original, content.text));
  },
});
```

Both styles produce the same wire protocol.

Per-job state [#per-job-state]

`ctx.state` is inferred from the `state` config field. Each job receives its own copy:

```typescript
configureDVM({
  name: "counter",
  capability: "count",
  state: { step: 0, language: "" },

  async onJob(ctx) {
    ctx.state.step += 1;
    ctx.state.language = "English";
    ctx.complete(ctx.state.step.toString());
  },
});
```

With a database, state is persisted at action boundaries and terminal states. A restart can resume from the last persisted snapshot.

Cross-job storage [#cross-job-storage]

`ctx.store` is an async key-value store scoped to the DVM. Use it for caches, preferences, or data that outlives one job:

```typescript
import { configureDVM } from "@dvmkit/sdk";

type UserPrefs = { topics: string[] };

export default configureDVM({
  name: "preferences",
  capability: "preferences",
  async onJob(ctx) {
    const key = `user:${ctx.requesterId}`;
    const prefs = await ctx.store.get<UserPrefs>(key);
    if (!prefs) {
      await ctx.store.set(key, { topics: ["technology"] });
    }

    await ctx.store.set("rate:btcusd", 65_000, { ttl: 300 });
    ctx.complete("Preferences loaded");
  },
});
```

Do not use `ctx.store` for credit balances. The SDK credit ledger uses database locks and idempotency rules that a last-write-wins key-value record cannot provide.

Input validation with Zod [#input-validation-with-zod]

The SDK exports its bundled Zod instance. Pass a schema as `input` to receive parsed, typed input:

```typescript
import { configureDVM, z } from "@dvmkit/sdk";

const inputSchema = z.object({
  prompt: z.string(),
  width: z.number().default(1024),
  height: z.number().default(1024),
});

export default configureDVM({
  name: "image-generator",
  capability: "generate",
  input: inputSchema,

  async onJob(ctx) {
    ctx.text(`Generating ${ctx.input.width}x${ctx.input.height} image`);
    ctx.complete(ctx.input.prompt);
  },
});
```

The schema appears in `/v1/info` as JSON Schema. Invalid input is rejected before `onJob` runs.

Dynamic pricing with onQuote [#dynamic-pricing-with-onquote]

Use `onQuote` when cost depends on the request. Return an upfront fiat envelope and describe what it covers:

```typescript
const quoteInput = z.object({ duration_seconds: z.number() });

configureDVM({
  name: "video-transcriber",
  capability: "transcribe",
  onQuote: {
    schema: quoteInput,

    async handler(ctx) {
      const { duration_seconds } = quoteInput.parse(ctx.data);
      const usd = duration_seconds * 0.0005;
      return {
        upfront: { amount: Number(usd.toFixed(4)), currency: "usd" },
        description: `${duration_seconds.toString()}s video at $0.0005 per second`,
        shape: "fixed",
      };
    },
  },

  async onJob(ctx) {
    /* ... */
  },
});
```

The quote context [#the-quote-context]

When `schema` is a Zod schema, the SDK validates `ctx.data` against it before your handler runs, but the type of `ctx.data` is `Record<string, unknown>`. Parse it again with the same schema to get typed fields.

The quote context carries `data`, the raw `input` and `params`, `env`, an instrumented `fetch`, and, for signed callers, `callerPubkey` and a read-only `credit` snapshot. It has no database handle. To read your own tables while quoting, capture the pool in a closure, as [Your own tables](#your-own-tables) shows.

Pricing shapes [#pricing-shapes]

The two pricing shapes are:

* `fixed`: the upfront covers the complete job.
* `rate`: the price depends on units the job measures. Add `rate: { per_unit, unit, max_units? }` so typed callers can derive a ceiling.

`shape` and `rate` are labels for callers. The SDK echoes them on `/v1/quote` and does nothing else with them: it does not measure units, settle a rate, or enforce `max_units`. Money moves only through the upfront and through [`ctx.requestPayment`](#mid-job-payment) calls your handler makes.

The SDK converts the upfront at the 402 handshake. `/v1/quote` gives the caller the input-specific amount before submission.

Zero quotes [#zero-quotes]

A quote may return `upfront: { amount: 0, currency }`. The job then starts without a 402 and can still charge with `ctx.requestPayment` once it knows the cost. Describe that in `description` or `hint`, so the caller's agent knows money will be asked for. One exception: a DVM using `secp256k1Auth({ allowUnsignedPaid: true })` refuses a job priced at zero from an unsigned caller.

Refusing a quote [#refusing-a-quote]

Throw from the quote handler to refuse a request before any money moves. An error that carries string `code`, `display`, and `hint` properties becomes a structured `400`:

```typescript
class QuoteRefusal extends Error {
  constructor(
    readonly code: string,
    readonly display: string,
    readonly hint: string
  ) {
    super(display);
  }
}

throw new QuoteRefusal(
  "unknown_document",
  `No document with id ${doc_id}`,
  "Upload the document first, then ask for a quote again"
);
```

```json
{
  "error": {
    "code": "unknown_document",
    "display": "No document with id d-42",
    "hint": "Upload the document first, then ask for a quote again"
  }
}
```

`/v1/quote` and the pricing step of `POST /v1/job` return the same body. A string `sub_reason` is copied too. All three of `code`, `display`, and `hint` must be strings, on the error or on its `cause`. An error missing any of them is treated as a plain error: `/v1/quote` returns `500` with `code: "internal"`, and `POST /v1/job` returns `400` with `error: "quote_failed"`.

`onJob` does not read these properties. A throw from `onJob` fails the job with the error's message as the reason, and `ctx.fail()` takes a string. Write that reason as a sentence the caller's agent can pass on.

Mid-job payment [#mid-job-payment]

Request more payment after work has started:

```typescript
configureDVM({
  name: "assessor",
  capability: "assess",
  price: "$0.01",

  async onJob(ctx) {
    const assessment = await ctx.step("assess", () => assessInput(ctx.input));

    await ctx.requestPayment(
      { amount: assessment.cost, currency: "usd" },
      assessment.description
    );

    ctx.complete(await processInput(ctx.input));
  },
});
```

The handler yields a `payment-request` and resumes after the caller pays.

Every ask is new money [#every-ask-is-new-money]

Each payment buys the next piece of work. The upfront payment buys the first piece, and each `requestPayment()` asks the caller for the piece after it. An ask is never taken from the upfront payment, so ask for exactly what the next piece costs. Sending the ask finishes the piece in progress and charges it, so emit what that piece produced before you ask. [Charging by the piece](#charging-by-the-piece) has what each ending charges, and how to lower a metered piece's charge when it finishes.

A metering DVM measures with its first piece and asks before it does the metered work:

```typescript
const input = z.object({ audio_url: z.string().url() });

configureDVM({
  name: "transcriber",
  capability: "transcribe",
  input,
  onQuote: {
    schema: input,
    async handler() {
      return {
        upfront: { amount: 0.05, currency: "usd" },
        description: "$0.05 covers the first 10 minutes of audio",
        hint: "Audio past 10 minutes is charged at $0.005 per minute, asked for before transcription starts",
      };
    },
  },
  async onJob(ctx) {
    const minutes = await ctx.step("probe", () => probeMinutes(ctx.input.audio_url));
    ctx.text(`The file is ${minutes.toString()} minutes long.`);

    const extraMinutes = Math.max(0, Math.ceil(minutes) - 10);
    if (extraMinutes > 0) {
      await ctx.requestPayment(
        { amount: extraMinutes * 0.005, currency: "usd" },
        `${extraMinutes.toString()} minutes past the first 10, at $0.005 per minute`
      );
    }

    const transcript = await ctx.step("transcribe", () => transcribe(ctx.input.audio_url));
    ctx.complete(transcript.text);
  },
});
```

A 7-minute file costs the caller $0.05 and makes no ask. A 14-minute file costs $0.07: the upfront $0.05, then $0.02 for 4 extra minutes, asked for before any of them is transcribed. A caller who declines that ask is charged the $0.05 for the finished probe and keeps its result. If transcription fails after the caller paid the $0.02, the $0.02 piece is released and the caller is charged the $0.05.

This pattern needs `ctx.requestPayment`. On a capability that sets `maxRuntimeSeconds`, a job an unsigned caller paid with x402 through `allowUnsignedPaid` settles only if it succeeds, and `ctx.requestPayment` throws there and fails the job. Leave `maxRuntimeSeconds` unset on any capability that charges mid-job.

Prepaid credit [#prepaid-credit]

Prepaid credit lets a caller fund a balance once and draw from it across jobs. Every payment still goes through the SDK credit ledger. A normal per-job payment is the implicit one-job case.

Credit configuration and lifecycle [#credit-configuration-and-lifecycle]

Opt in with a `credit` block and signed caller auth:

```typescript
import { configureDVM } from "@dvmkit/sdk";
import { secp256k1Auth } from "@dvmkit/sdk/server";

export default configureDVM({
  name: "assessor",
  capability: "assess",
  price: "$0.01",
  auth: secp256k1Auth(),
  credit: {
    min: "$0.10",
    max: "$5.00",
    ttl: 90 * 24 * 60 * 60,
    allowOneShotStablecoin: false,
  },

  async onJob(ctx) {
    /* ... */
  },
});
```

`min` and `max` use the same USD literal grammar as `price`. `max` limits the residual balance a caller may hold. It does not limit a job whose payment funds and draws in one request. Credit requires descriptor-level auth and a durable Postgres-backed host. Isolate-runtime DVMs do not offer credit.

The SDK owns the credit ledger, `POST /v1/credit`, funding menu, balance reads, draw idempotency, and receipts. Do not store balances in `ctx.store`.

`credit_id`, `draw_id`, and `fund` are reserved top-level fields in the signed request data. The SDK removes them before capability-schema parsing. Do not declare them in your schema or use those names for your own fields.

Charging by the piece [#charging-by-the-piece]

Draws are holds, settled by the piece. Each payment buys the next piece of work: the upfront payment buys the first, and each paid `ctx.requestPayment` buys the one after it. Every ask is new money, because the upfront payment never covers an ask. A piece finishes when your handler sends its next `ctx.requestPayment` or calls `ctx.complete`. When the job ends, the SDK settles the finished pieces and releases the rest:

| Ending                                            | Charged                                                |
| ------------------------------------------------- | ------------------------------------------------------ |
| `ctx.complete`                                    | Every paid piece                                       |
| `ctx.fail`, a handler crash, or stale-job reaping | The finished pieces. The piece in progress is released |
| The caller declines an ask or lets it expire      | The finished pieces. Nothing was paid for the next one |
| The caller cancels                                | Every paid piece, including the one in progress        |

`ctx.fail(error, { refund: true })` is only a caller-fault annotation for the terminal record and test inspection. It moves no money on any rail and does not change what settles.

**Deliver before you ask.** Sending the next ask finishes the piece in progress and charges it, so emit what that piece produced (artifacts, partial results) before you call `ctx.requestPayment`. A caller who declines then keeps what it paid for.

**Lower a charge when its piece finishes.** For metered work whose cost is known only afterwards, such as an LLM call billed by tokens, ask at the cap. Then pass `finishedChargeMicro` to the call that finishes the piece: `ctx.requestPayment(amount, reason, { finishedChargeMicro })` for the next ask, or `ctx.complete(summary, { finishedChargeMicro })`. The figure is integer micro-units of the job's credit currency, at most that piece's price. Above the price, `ctx.requestPayment` rejects and `ctx.complete` throws, both with a `RangeError`. The difference is released when the job ends. It can only lower a charge, never raise one.

**One ask at a time.** A second `ctx.requestPayment` while one is open rejects with `ask_already_open`. `ctx.complete` with an ask open withdraws it, and a payment that arrives afterwards lands on the caller's credit as balance.

Where released money goes [#where-released-money-goes]

No rail sends money backwards. A release returns the hold to a balance on your ledger, and who can use that balance depends on how the caller reached you:

| Caller                                                                                               | Where the release lands                                                         | Can the caller use it                                                                                                        |
| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Signed, holding credit at your DVM                                                                   | Their credit balance                                                            | Yes, on the next job or by reclaiming it                                                                                     |
| Signed, at a DVM with auth but no `credit` block                                                     | A per-call balance for their key, kept 90 days                                  | Only toward later jobs here, when the caller's client spends it. Without a `credit` block there is no endpoint to reclaim it |
| Unsigned, at a DVM with no auth or through `allowUnsignedPaid`                                       | One shared anonymous balance                                                    | No. Nobody can prove it is theirs                                                                                            |
| Unsigned, paying with x402 through `allowUnsignedPaid` on a capability that sets `maxRuntimeSeconds` | Nowhere. The payment is verified before the job and settled only if it succeeds | Nothing to use. A failed job costs this caller nothing                                                                       |

So refuse every request you can before money moves. A refusal in `onQuote` charges nothing. A refusal inside `onJob` comes after the upfront payment, and an unsigned caller loses it, unless they paid with x402 on a capability that sets `maxRuntimeSeconds`. The same holds for anything taken by an earlier `ctx.requestPayment`. [Credits](/docs/credits#am-i-out-the-money-if-a-job-fails) explains the same cases to callers.

New callers and the trust ladder [#new-callers-and-the-trust-ladder]

The `dvm` CLI never opens credit on first contact. A caller pays per job until they hold at least one completed [signed receipt](#signed-receipts) from you, so a DVM without a receipt key never has credit opened with it automatically. After that, the CLI caps how much a caller keeps on deposit at one DVM: $0.50 until 3 of their jobs have completed, $2 until 15 have completed over at least a week, and your `max` after that. The SDK does not enforce any of this. It is a caller-side default, and a caller can go past it by saying so.

Size `credit.min` with it in mind. A minimum above $0.50 means a new caller's agent refuses to open credit with you unless its operator overrides the cap, so new callers pay per job instead. [Credits](/docs/credits#the-trust-ladder) and [budgets](/docs/budgets) describe the caller's side.

Caller view [#caller-view]

Quotes can inspect the caller without spending the balance:

```typescript
const pagesInput = z.object({ pages: z.number() });

// Inside configureDVM:
onQuote: {
  schema: pagesInput,
  async handler(ctx) {
    const { pages } = pagesInput.parse(ctx.data);
    const covered = ctx.credit && ctx.credit.availableMicro >= pages * 10_000;
    return {
      upfront: { amount: pages * 0.01, currency: "usd" },
      description: covered
        ? "This request is covered by your existing credit"
        : "This request costs $0.01 per page",
    };
  },
}
```

`ctx.callerPubkey` is the verified caller key when auth is enabled. `ctx.credit` is a read-only snapshot with `creditId`, `currency`, `balanceMicro`, `availableMicro`, `expiryMs`, and `expired`.

Funding credit over Lightning [#funding-credit-over-lightning]

Set `DVMKIT_NWC_RECEIVE_URI` to a receive-only Nostr Wallet Connect connection. The SDK then adds `lightning` to the credit funding menu. The connection may make invoices and look them up. It must not pay invoices.

Some wallets, such as CoinOS, cannot issue a receive-only connection. For those, set `DVMKIT_NWC_RECEIVE_ALLOW_SPEND=true`. It is off by default, and only the exact value `true` turns it on. The DVM then accepts the connection and logs `lightning_receive_allow_spend_enabled` once, naming the extra methods. The risk is real: anyone who gets that connection string can spend the wallet. Keep only what you can afford to lose in a wallet you connect this way.

The caller flow is interactive:

1. The caller signs `POST /v1/credit` with `op: "fund"` and a Lightning funding method.
2. The SDK returns a `402` containing a bolt11 invoice bound to the credit, funding ID, and amount.
3. The caller pays the invoice out of band.
4. A later poll, balance read, or job submit checks the invoice and credits the ledger in one transaction.

There is no background watcher. A wallet outage delays recognition of a paid invoice; it does not discard the invoice-to-credit binding.

The receive channel has a smallest routable amount. Set `DVMKIT_LIGHTNING_FUNDING_MIN_SATS` to state it, or keep the default of `2000` sats until you measure the channel. The menu publishes a rate-adjusted `lightning_min_micro` floor. A funding below the raw floor is refused as `below_rail_minimum` before an invoice exists. If the FX source cannot render the floor, Lightning is removed from the menu.

Expiry and reclaim [#expiry-and-reclaim]

Expiry stops new draws. The balance remains visible and can be reclaimed until the DVM's expiry sweep releases it. The sweep releases eligible undrawn balances only when no pending draw remains, records the release, and sets the balance to zero. Tempo-funded and Tempo-channel-backed credits are excluded from that sweep. A caller that funds an expired credit revives it; the ledger can reverse a prior expiry release when restoring the credit.

Rail-specific delivery [#rail-specific-delivery]

Reclaim is a builder obligation on the rail that holds the caller's value:

| Funding shape                  | Who completes the reclaim | Builder action                                                               |
| ------------------------------ | ------------------------- | ---------------------------------------------------------------------------- |
| Cashu or Lightning             | Builder's refund worker   | Run `dvmctl melt-pending`; it parks ecash locked to the caller's refund key  |
| Reusable x402 or Tempo channel | The channel               | Keep the channel settlement and close observer healthy                       |
| One-shot x402 or Tempo payment | Builder operator          | Review `dvmctl credit drains-owed`, then record `dvmctl credit drain-settle` |

A Lightning-funded credit is reclaimed as P2PK-locked ecash. The DVM's receive-only NWC credential cannot fund that refund. The separate refund worker uses existing ecash or a spending connection supplied through `DVMKIT_REFUND_NWC_URL` to buy ecash from an accepted mint. Its `--refund-nwc` option names the same role; keep secret values out of command arguments. The worker holds the builder payout while an ecash refund is outstanding or drain state cannot be read.

One-shot stablecoin credit is disabled by default. Set `allowOneShotStablecoin: true` only when you have a manual refund process:

```bash
dvmctl credit drains-owed <handle>
dvmctl credit drain-settle <handle> <credit-id> <drain-id> --tx <hash>
```

An unfulfilled reclaim is a signed IOU. The caller holds the signed request and the DVM's countersigned drain receipt. The receipt makes the obligation inspectable; it is not a promise that bypasses the builder's payout process.

The reclaim amount is fixed when the caller requests it. For ecash funding, the SDK tracks funding lots and returns the corresponding asset value less the fixed delivery reserve. Amounts below dust are refused as `drain_below_dust` because there is no spendable output to send.

Tempo session channels [#tempo-session-channels]

Reusable Tempo session funding uses an on-chain channel. A caller can request a close and wait through the grace period, so the channel must be observed and settled for the value already consumed.

Platform-hosted DVMs receive close events from the platform observer. The SDK re-reads the event from the configured Tempo RPC before acting. Self-hosted DVMs must watch their escrow for `CloseRequested` and POST the event locator to `/_internal/tempo-close-event` inside the grace period. If you do not operate an observer, advertise `tempo/charge` rather than `tempo/session`.

An existing channel remains usable while new session channels are withheld during an observer or fee-balance problem. The SDK keeps that distinction so a caller's open balance is not stranded.

Retried paid submits are idempotent [#retried-paid-submits-are-idempotent]

A paid submit can reach the DVM even when the caller loses the response. Retry with the same `X-Cashu-Request-Id` and identical request. The SDK returns the original job response, without creating another job or booking payment twice.

The retry fingerprint includes capability, parameters, and input. A DVM with signed auth also requires the same caller pubkey. Possession of an already-spent payment token alone does not grant access to the job.

Signed receipts [#signed-receipts]

When a receipt key and compatible job store are configured, each terminal job response carries a DVM-signed receipt:

```json
{
  "v": 1,
  "job_id": "job-a7571b-1",
  "dvm_id": "dvm-wordcount",
  "capability": "count",
  "outcome": "completed",
  "reason": null,
  "seq": 4213,
  "issued_at": 1789300000,
  "requester_pubkey": null,
  "paid": { "msats": 19000, "rail": "cashu" },
  "result_hash": "<sha256 hex>",
  "receipt_pubkey": "<64-hex>",
  "signature": "<128-hex>"
}
```

The same receipt appears on the submit response, job read, and later reads. It is signed once and persisted. `/v1/info` advertises `receipts: true` when issuance is available.

The signature is BIP-340 Schnorr over canonical JSON. A verifier checks the receipt signature, the DVM ID and receipt key against `/v1/info`, and the builder attestation against the builder identity. Free jobs can receive receipts too. Paid receipts may carry a `credit` block with the credit ID, draw ID, amount, balance after, and ledger sequence.

Receipt issuance does not fail a job. If signing or persistence fails, the SDK logs the failure and can retry on a later read. A custom job store must support receipt sequence allocation and write-once receipt storage to advertise receipts.

Durable steps [#durable-steps]

`ctx.step(id, fn)` caches an async result. When a job resumes after waiting on the caller and its handler replays, the SDK returns the cached result instead of calling `fn` again:

```typescript
const analysis = await ctx.step("analyze", () =>
  classifyInput(ctx.input, ctx.env.ANTHROPIC_API_KEY)
);

if (analysis.type === "code") {
  await ctx.prompt("language", "Which language?");
}
```

Step external API calls and nondeterministic model calls. Plain formatting and arithmetic do not need steps. Step ids must be unique within a job.

With Postgres configured, `ctx.step` writes the result durably before it returns. The write is attempted up to three times. If every attempt fails, the SDK logs `step_persist_failed` and returns the result anyway, because the external action may already have happened. The in-memory store keeps nothing across a process death.

Steps run at least once [#steps-run-at-least-once]

Treat every step body as one that can run more than once. One way it happens: if all three writes fail (`step_persist_failed`) and no later save captures the result, a replay after the caller answers finds no cached result and runs the body again. For anything irreversible, such as a booking, a charge, or a message to a person, pass `${ctx.jobId}:${stepId}` as an idempotency key to an API that honours one, or check that system for an earlier result before acting:

```typescript
const stepId = "reserve-instrument";
const reservation = await ctx.step(stepId, () =>
  instrument.reserve({ idempotencyKey: `${ctx.jobId}:${stepId}` })
);
```

The job id and step id are the same on every replay, so the external system receives the same key and can refuse the repeat.

Replay applies to a job resumed after a prompt or payment request. A job whose process dies while it is working is not replayed. The [`processingWatchdog`](#dvm-level-fields) marks it failed.

Testing [#testing]

`createTestContext()` gives you an in-memory context for handler tests:

```typescript
import { describe, expect, it } from "vitest";
import { createTestContext } from "@dvmkit/sdk/testing";
import dvm from "./handler.js";

describe("echo", () => {
  it("completes a job", async () => {
    const ctx = createTestContext({ input: "hello" });
    await dvm.capabilities.echo.onJob(ctx);

    expect(ctx.completed).toBe(true);
    expect(ctx.summary).toBe("hello");
  });
});
```

Test context options [#test-context-options]

```typescript
createTestContext({
  input: "test input",
  tags: ["text"],
  params: { format: "markdown" },
  env: { API_KEY: "test-key" },
  state: { step: 0 },
  paidMsats: 10000,
  responses: { language: { text: "Spanish" } },
  payment: { cashu_token: "cashuA..." },
});
```

Test inspection [#test-inspection]

| Property          | Description                                    |
| ----------------- | ---------------------------------------------- |
| `messages`        | Outbound messages with their type and content  |
| `completed`       | Whether `complete()` was called                |
| `failed`          | Whether `fail()` was called                    |
| `summary`         | The summary passed to `complete()`             |
| `failError`       | The error passed to `fail()`                   |
| `refundRequested` | Whether `fail()` requested a refund annotation |

Custom HTTP routes [#custom-http-routes]

Use custom routes for HTTP endpoints beside the protocol routes. Keep DVM-owned endpoints on the descriptor. Keep cross-DVM or host maintenance endpoints on `host.app`. The descriptor callback receives `(app, context)`, where `context.authAudience` is the audience for signed custom routes and `context.requireClientCompatibility` is the compatibility middleware factory.

DVM-scoped routes [#dvm-scoped-routes]

The callback runs on the DVM's Hono sub-router and inherits its mount prefix:

```typescript
function createCastDVM(runtime: CastRuntime) {
  return configureDVM({
    name: "cast",
    capabilities: {
      /* ... */
    },

    routes(app) {
      app.get("/feeds/:owner/:slug", async (c) => {
        const feed = await runtime.db.renderFeed(c.req.param("owner"), c.req.param("slug"));
        return c.body(feed, 200, { "Content-Type": "application/rss+xml" });
      });
    },
  });
}
```

Host-scoped routes [#host-scoped-routes]

Register `host.app` routes before mounting DVMs:

```typescript
import { createDVMHost } from "@dvmkit/sdk/server";

const host = createDVMHost();
host.app.get("/health", (c) => c.json({ ok: true }));
host.mount(createCastDVM(runtime));
await host.serve();
```

Endpoint compatibility requirements [#endpoint-compatibility-requirements]

`routes(app, context)` receives `requireClientCompatibility`. Apply it only to the endpoint that needs a released caller capability:

```typescript
routes(app, { requireClientCompatibility }) {
  app.post(
    "/request-resume",
    requireClientCompatibility({
      requiredCapabilities: ["request-resume"],
      minimumClientVersion: "0.1.0",
    }),
    async (c) => c.json({ ok: true })
  );
}
```

The SDK parses compatibility headers for telemetry and adds `DVM-Protocol-Version` to responses. Do not reject every request globally for a route-specific feature.

Authentication: signed requests [#authentication-signed-requests]

Use signed requests when a DVM owns caller-specific state such as feeds, accounts, or subscriptions. The SDK uses secp256k1 with BIP-340 Schnorr signatures. The signed statement covers the exact raw input, attested DVM audience, HTTP method, concrete path, and capability.

Open access is the default. A DVM that does not need caller ownership can omit auth and use the opaque `requesterId`.

The capability schema includes the caller payload and signed envelope:

```typescript
import { z } from "@dvmkit/sdk";

const addEpisodeSchema = z.object({
  feed_slug: z.string(),
  audio_url: z.string().url(),
  pubkey: z.string(),
  signature: z.string(),
  timestamp: z.number(),
  nonce: z.string(),
});
```

Canonical pattern: secp256k1Auth on the descriptor [#canonical-pattern-secp256k1auth-on-the-descriptor]

Declare auth once on the descriptor. It covers every capability and advertises `secp256k1-schnorr-v2` in `/v1/info`:

```typescript
import { secp256k1Auth } from "@dvmkit/sdk/server";

configureDVM({
  name: "cast",
  tags: ["podcast", "rss"],
  auth: secp256k1Auth({
    replayStore: runtime.replays,
    driftSeconds: 300,
  }),
  capabilities: {
    "add-episode": {
      input: addEpisodeSchema,
      async onJob(ctx) {
        const pubkey = ctx.auth!.pubkey;
        const { feed_slug } = ctx.auth!.envelope as { feed_slug: string };
        await checkFeedOwnership(pubkey, feed_slug);
        /* ... */
      },
    },
  },
});
```

Unsigned, stale, replayed, and wrong-domain envelopes return `401` before payment or handler execution. The nonce is recorded only after upfront payment verifies, so an unpaid 402 discovery response can be followed by a paid retry using the same signed job proof.

Use a cross-machine replay store in a multi-instance deployment. With a Postgres host, the SDK wires `PostgresReplayStore` when you omit `replayStore`. The bounded in-memory store is suitable for a single instance. Set `DVMKIT_FAIL_FAST=true` if an unsafe fallback should stop production boot; review the [strict-startup caveats](#dvmkit_fail_fast) for x402 too.

Lower-level primitive: createSignedRequestVerifier [#lower-level-primitive-createsignedrequestverifier]

Use the verifier directly when a custom route needs signed callers:

```typescript
import {
  createSignedRequestVerifier,
  secp256k1Auth,
  SignedRequestError,
} from "@dvmkit/sdk/server";

const verifier = createSignedRequestVerifier(addEpisodeSchema, {
  driftSeconds: 300,
});

configureDVM({
  name: "cast",
  capability: "add-episode",
  input: addEpisodeSchema,
  auth: secp256k1Auth(),
  onJob(ctx) {
    ctx.complete("Route-ready");
  },
  routes(app, { authAudience }) {
    if (!authAudience) throw new Error("signed route requires descriptor auth");

    app.post("/private/feed", async (c) => {
      try {
        const verified = verifier.checkAuth(await c.req.json(), {
          audience: authAudience,
          method: c.req.method,
          path: new URL(c.req.url).pathname,
          capability: null,
        });
        await verifier.recordReplay(verified);
        return c.json({ owner: verified.pubkey });
      } catch (error) {
        if (error instanceof SignedRequestError) {
          return c.json({ error: "auth_error", sub_reason: error.sub_reason }, 401);
        }
        throw error;
      }
    });
  },
});
```

Call `checkAuth()` synchronously to validate schema, timestamp, and signature. Call `recordReplay()` separately to commit the nonce. This keeps validation from consuming a nonce before the operation is accepted.

Options [#options]

| Option           | Default                | Description                                             |
| ---------------- | ---------------------- | ------------------------------------------------------- |
| `driftSeconds`   | `300`                  | Allowed clock drift                                     |
| `domain`         | none                   | Fixed audience, method, path, and capability            |
| `envelopeFields` | `["signature"]`        | Additional fields removed from canonical bytes          |
| `replayStore`    | bounded in-memory FIFO | Cross-machine store, or `null` to disable replay checks |
| `now`            | current Unix seconds   | Clock override for tests                                |

Signing in tests [#signing-in-tests]

The verifier exposes `signRequest()` with the same canonicalization as `checkAuth()`:

```typescript
import { schnorr } from "@noble/curves/secp256k1.js";

const { secretKey } = schnorr.keygen();
const signed = verifier.signRequest(secretKey, {
  feed_slug: "morning-news",
  audio_url: "https://example.com/episode.mp3",
}, undefined, {
  audience: authAudience,
  method: "POST",
  path: "/private/feed",
  capability: null,
});
```

Quote paths [#quote-paths]

`/v1/quote` and the 402 discovery hop run `checkAuth()` without consuming the nonce. Quote and submit use separate proofs because the signed path differs. Do not call `recordReplay()` from `onQuote()`.

Failure taxonomy [#failure-taxonomy]

Authentication errors use `SignedRequestError` with `code: "auth_error"`. The raw verifier and the SDK’s auth scheme distinguish these reasons:

| `sub_reason`         | Cause                                                                |
| -------------------- | -------------------------------------------------------------------- |
| `schema_invalid`     | Envelope or payload fields are missing or malformed                  |
| `timestamp_drift`    | The timestamp is outside `driftSeconds`                              |
| `signature_invalid`  | BIP-340 signature verification failed                                |
| `replay_detected`    | The caller reused a nonce in the replay window                       |
| `signature_required` | The SDK auth scheme received no signing envelope; see the note below |

The SDK’s auth scheme adds `signature_required` when a required signing envelope is absent. On `/v1/job` and `/v1/quote`, that returns `401 auth_error` with a hint to initialize the caller CLI and use `dvm request`, or implement the published signing contract. A malformed envelope returns `401 signature_invalid`. Capability input errors are separate: a bad capability payload returns `400 invalid_input`.

Lifecycle hooks [#lifecycle-hooks]

onBoot(env) [#onbootenv]

`onBoot` runs once per mounted DVM after stores initialize and before the HTTP listener opens. Throw to refuse boot on missing configuration:

```typescript
configureDVM({
  name: "narrate",
  capability: "synthesise",
  onBoot(env) {
    if (!env.ELEVENLABS_API_KEY && !env.OPENAI_API_KEY) {
      throw new Error("Missing TTS provider keys");
    }
  },
});
```

onShutdown() [#onshutdown]

`onShutdown` runs in reverse mount order before the host closes. Use it to drain provider work and close resources:

```typescript
configureDVM({
  name: "scrape",
  capability: "fetch",
  async onShutdown() {
    await pool.shutdown();
  },
});
```

Job content retention [#job-content-retention]

The SDK defaults to `jobRetentionDays: 730`. Set a shorter or longer non-negative whole number of days in `configureDVM`, or `0` to disable automatic age expiry. The clock starts at the job's final activity and stays fixed after completion, failure, or cancellation. Reading status or messages never renews it.

Authenticated job responses expose `content_expires_at` as epoch milliseconds or `null`, and `content_available` separately. A null deadline means no current automatic age expiry; it does not promise permanent storage. An older service that omits these fields has unknown retention. Content expiry removes input, parameters, results, messages, temporary state, and replay-only authentication material. It preserves the terminal outcome, payment links, and full signed receipt.

The container/Postgres adapter supports signed service-admin content holds. A support or dispute hold applies to one job and records an actor, reason, and review date. Multiple holds compose. The effective expiry is null while any hold is active, while the original baseline deadline stays visible to admins. An overdue review never clears a hold. Explicitly clearing the last hold restores the original deadline, which may already have passed. Redaction and hold mutations serialize on the same job. A hold cannot restore content already removed.

Use `dvmctl content-holds` to list, place, renew, or clear these holds. The service verifies the builder's signing identity; a platform token alone is insufficient. Hold reasons and actor identities are admin-only. Unsupported custom stores return an unavailable-controls response. Isolate stores do not gain these controls merely by upgrading the SDK.

The SDK package supplies `recipes/postgres/financial-export-v1.sql` for a builder-owned minimized financial export. It is a SQL recipe, not a content archive endpoint. Save and verify it before destruction if you want that evidence. Active-service content retention does not extend trial recovery or the maximum 90-day lifetime of hosted copies after destruction.

Persistence [#persistence]

Pass `database` to `serve()` or set `DATABASE_URL`:

```typescript
await serve(dvm, { database: process.env.DATABASE_URL });
```

The SDK creates Postgres-backed job and KV stores. It persists job status, per-job state, durable-step results, and `ctx.store` data. Tables are created at boot.

Postgres is required for production unless you provide a compatible `jobStore`. `MemoryJobStore` is for tests and development. To create tables of your own at boot, see [Your own tables](#your-own-tables).

Your own tables [#your-own-tables]

A DVM can keep its own tables in the same Postgres database as the SDK, using the host's connection pool instead of opening a second one.

Getting the pool [#getting-the-pool]

`createDVMHost()` exposes the pool as `host.pool`, typed `Pool | undefined` from `pg`. It is set while `host.serve()` boots, after the SDK's own stores are ready and before any `onBoot` runs. It stays `undefined` when there is no database, as in dev mode without `DATABASE_URL`, and when you pass your own `jobStore`.

`onBoot` belongs to the descriptor, but the pool belongs to the host, and `onBoot` receives only the environment. So make the handler a factory that takes a `getPool` callback, and call it inside `onBoot`. You cannot add an `onBoot` to a finished descriptor: `configureDVM` freezes it, and the host reads `onBoot` only from the config you passed in.

Creating tables safely [#creating-tables-safely]

Wrap your `CREATE TABLE IF NOT EXISTS` statements in `withSdkInitLock` from `@dvmkit/sdk/server`. Two machines booting against a fresh database can otherwise both try to create the same table, and one fails on a duplicate-key error. The lock is the Postgres advisory lock the SDK holds for its own boot DDL. It holds one connection while your callback runs on another, so the pool must allow at least two connections (`pg` defaults to 10). A nested call on the same pool runs straight through. Keep network calls out of the callback.

A complete example [#a-complete-example]

```typescript
// handler.ts
import { configureDVM, z } from "@dvmkit/sdk";
import { withSdkInitLock } from "@dvmkit/sdk/server";
import type { Pool } from "pg";

const docInput = z.object({ doc_id: z.string() });

export function createNotesDVM(opts: { getPool: () => Pool | undefined }) {
  let db: Pool | undefined;
  const requireDb = (): Pool => {
    if (!db) throw new Error("notes: database not ready");
    return db;
  };

  return configureDVM({
    name: "notes",
    capability: "summarise",
    input: docInput,

    async onBoot() {
      const pool = opts.getPool();
      if (!pool) throw new Error("notes needs DATABASE_URL");
      await withSdkInitLock(pool, async () => {
        await pool.query(`
          CREATE TABLE IF NOT EXISTS notes_docs (
            doc_id TEXT PRIMARY KEY,
            pages  INTEGER NOT NULL
          )
        `);
      });
      db = pool;
    },

    onQuote: {
      schema: docInput,
      async handler(ctx) {
        const { doc_id } = docInput.parse(ctx.data);
        const { rows } = await requireDb().query<{ pages: number }>(
          "SELECT pages FROM notes_docs WHERE doc_id = $1",
          [doc_id]
        );
        const pages = rows[0]?.pages ?? 1;
        return {
          upfront: { amount: pages * 0.01, currency: "usd" },
          description: `${pages.toString()} pages at $0.01 per page`,
        };
      },
    },

    async onJob(ctx) {
      const { rows } = await requireDb().query<{ pages: number }>(
        "SELECT pages FROM notes_docs WHERE doc_id = $1",
        [ctx.input.doc_id]
      );
      ctx.complete(`Summarised ${String(rows[0]?.pages ?? 0)} pages`);
    },
  });
}
```

```typescript
// serve.ts
import { createDVMHost } from "@dvmkit/sdk/server";
import { createNotesDVM } from "./handler.js";

const host = createDVMHost({ database: process.env.DATABASE_URL });
host.mount(createNotesDVM({ getPool: () => host.pool }));
await host.serve();
```

`onBoot` throws when there is no pool, so the process refuses to start instead of failing its first job. The quote handler reads the same table through the captured pool, because the quote context has no database handle of its own.

Deployment [#deployment]

Container [#container]

Use a production entry point that imports the handler and reads deployment configuration from the environment:

```typescript
import { serve } from "@dvmkit/sdk/server";
import dvm from "./handler.js";

await serve(dvm, {
  database: process.env.DATABASE_URL,
  mints: process.env.DVMKIT_CASHU_MINTS?.split(",").filter(Boolean),
});
```

The same process can advertise Cashu, x402, or Tempo according to the rails you configure. Keep payment secrets out of source files and logs.

Builder-facing `serve()` options [#builder-facing-serve-options]

`serve(dvm, options)` and `createDVMHost(options)` accept the same host options:

This is the builder-facing subset of the public `DVMHostOpts` type. The omitted `consumedCredentialStore`, `mintHealthTracker`, and `wrapRouteClientCompatibility` fields are test or platform integration seams. The payment overrides are included here because they are the programmatic path when environment-derived rail wiring is not enough.

| Option             | Type                     | Default                | Description                                                    |
| ------------------ | ------------------------ | ---------------------- | -------------------------------------------------------------- |
| `port`             | `number`                 | `PORT` or `8080`       | HTTP listen port                                               |
| `database`         | `string`                 | `DATABASE_URL`         | Postgres connection string                                     |
| `env`              | `Record<string, string>` | process environment    | Values available as `ctx.env`                                  |
| `builder`          | `BuilderIdentity`        | environment-derived    | Builder identity in `/v1/info`                                 |
| `owner`            | `OwnerDisplay`           | environment-derived    | Owner display identity in `/v1/info`                           |
| `platformReporter` | `PlatformReporterOpts`   | environment-derived    | Revenue reporting connection                                   |
| `fx`               | `FxFetcher`              | environment-configured | FX source override                                             |
| `healthHandler`    | `(c) => Response`        | SDK health response    | Custom `/health` handler                                       |
| `store`            | `KVStore`                | Postgres-backed        | KV store override                                              |
| `jobStore`         | `JobStore`               | database-backed        | Explicit job store                                             |
| `pool`             | `Pool`                   | none                   | Reuse an existing Postgres pool; the caller owns its lifecycle |
| `mints`            | `string[]`               | `DVMKIT_CASHU_MINTS`   | Accepted Cashu mints                                           |
| `cashuMode`        | `CashuMode`              | explicit               | Cashu receive mode, including `p2pk-accumulator`               |
| `mpp`              | `MppxServer`             | environment-resolved   | Tempo/MPP payment handle override                              |
| `x402`             | `X402Config`             | environment-resolved   | x402 payment configuration override                            |
| `paymentMethods`   | `PaymentMethod[]`        | Derived from rails     | Advertised payment methods                                     |
| `lightningReceive` | `LightningReceiveConfig` | environment-resolved   | Receive-only Lightning leg for credit funding                  |
| `devMode`          | `boolean`                | `false`                | Local/test behavior and in-memory fallback                     |

Payment-rail environment variables [#payment-rail-environment-variables]

The SDK reads these server environment variables:

| Variable                            | Effect                                                                                                                                                                                                                                                                          |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DATABASE_URL`                      | Postgres connection string. Required in production                                                                                                                                                                                                                              |
| `PORT`                              | Listen port. Defaults to `8080`                                                                                                                                                                                                                                                 |
| `DVMKIT_CASHU_MINTS`                | Comma-separated Cashu mint URLs                                                                                                                                                                                                                                                 |
| `DVMKIT_CASHU_LOCK_PUBKEY`          | P2PK lock key for accumulator-mode Cashu                                                                                                                                                                                                                                        |
| `DVMKIT_DVM_ID`                     | Stable DVM identity used by durable payment and receipt records                                                                                                                                                                                                                 |
| `DVMKIT_STRIPE_SECRET_KEY`          | Stripe account key for USD card-funded prepaid credit. Prefer a restricted key with the [card setup permissions](/docs/builder-payments#accept-card-funded-credit). Requires `DVMKIT_STRIPE_NETWORK_ID` and `DVMKIT_TEMPO_SECRET_KEY`                                           |
| `DVMKIT_STRIPE_NETWORK_ID`          | Stripe profile’s Network ID (`profile_…`; `internal` in test mode). Set together with `DVMKIT_STRIPE_SECRET_KEY`                                                                                                                                                                |
| `DVMKIT_STRIPE_MIN_USD`             | Card-only top-up minimum in decimal USD. Defaults to `5`, capped at `credit.max`; explicit settings must be from `0.50` through `credit.max`. The effective minimum also respects `credit.min`. See [choosing the minimum](/docs/builder-payments#choose-a-card-top-up-minimum) |
| `DVMKIT_NWC_RECEIVE_URI`            | Receive-only wallet connection for Bitcoin Lightning credit funding                                                                                                                                                                                                             |
| `DVMKIT_NWC_RECEIVE_ALLOW_SPEND`    | Exactly `true` accepts a connection that can also spend, for wallets without receive-only connections. Off by default. A leaked connection string can spend the wallet                                                                                                          |
| `DVMKIT_LIGHTNING_FUNDING_MIN_SATS` | Advertised Lightning receive floor                                                                                                                                                                                                                                              |
| `DVMKIT_TEMPO_RECIPIENT`            | Tempo settlement recipient                                                                                                                                                                                                                                                      |
| `DVMKIT_TEMPO_OPERATOR_KEY`         | Fee-funded operator key for reusable Tempo sessions                                                                                                                                                                                                                             |
| `DVMKIT_TEMPO_SECRET_KEY`           | HMAC secret for Tempo and card-credit challenge binding. Self-hosted builders must set it when either is configured; generate with `openssl rand -hex 32`. dvmkit Cloud generates it automatically and overwrites builder-set values                                            |
| `DVMKIT_TEMPO_RPC_URL`              | Tempo RPC endpoint                                                                                                                                                                                                                                                              |
| `DVMKIT_TEMPO_METHODS`              | Tempo method allowlist                                                                                                                                                                                                                                                          |
| `DVMKIT_X402_PAY_TO`                | x402 settlement recipient                                                                                                                                                                                                                                                       |
| `DVMKIT_X402_NETWORK`               | x402 chain identifier                                                                                                                                                                                                                                                           |
| `DVMKIT_X402_FACILITATOR`           | x402 facilitator URL. Choose a provider that settles the configured network                                                                                                                                                                                                     |
| `DVMKIT_PLATFORM_URL`               | Platform reporter endpoint and hosted-DVM signal                                                                                                                                                                                                                                |
| `DVMKIT_PLATFORM_TOKEN`             | Platform reporter credential                                                                                                                                                                                                                                                    |
| `DVMKIT_FX_SOURCE`                  | FX source override                                                                                                                                                                                                                                                              |
| `DVMKIT_RECEIPT_KEY`                | Receipt-signing key                                                                                                                                                                                                                                                             |
| `DVMKIT_FAIL_FAST`                  | Escalate warning-level boot checks to failures                                                                                                                                                                                                                                  |

`DVMKIT_*` variables configure the server. `DVM_*` variables configure the caller. Unprefixed legacy names are not read.

The revenue-reporter boot check [#the-revenue-reporter-boot-check]

When `DVMKIT_PLATFORM_URL` is set, the SDK requires `DVMKIT_PLATFORM_TOKEN`, `DVMKIT_DVM_ID`, `DATABASE_URL`, and the reporter's required stores. Partial platform wiring fails boot instead of silently accepting payments without a reporting path. `devMode` is exempt.

The reporter queues payout and pending-balance facts after the SDK's payment work. It does not change payment settlement or handler behavior.

DVMKIT_FAIL_FAST [#dvmkit_fail_fast]

Set `DVMKIT_FAIL_FAST=true` in production when a warning-level boot check should stop the process. This catches an in-memory replay store on a multi-instance signed DVM. For facilitator-settled x402, it stops startup when a responding facilitator advertises no settleable option for the configured network. A startup support-check timeout instead warns and assumes support; strict mode does not guarantee facilitator reachability.

A hosted DVM can inherit an account Base recipient even when you intended only prepaid credits funded through Bitcoin Lightning. See [where the hosted recipient comes from](/docs/builder-payments#where-the-hosted-recipient-comes-from) for the account-wide toggle and the choice to keep or disable inherited x402.

The SDK defaults to Base mainnet (`eip155:8453`) and the x402 facilitator `https://x402.org/facilitator` (the service that verifies and settles payments). For facilitator-settled payments, an advertisement with no settleable Base mainnet option causes strict startup to refuse boot. The facilitator's runtime support advertisement is the authority. For mainnet, explicitly set `DVMKIT_X402_FACILITATOR` to a provider that supports your `DVMKIT_X402_NETWORK`. If it requires credentials, set both `DVMKIT_X402_FACILITATOR_KEY_ID` and `DVMKIT_X402_FACILITATOR_KEY_SECRET`. For test funds, explicitly pair `DVMKIT_X402_NETWORK=eip155:84532` (Base Sepolia) with `DVMKIT_X402_FACILITATOR` set to `https://x402.org/facilitator`.

Partial platform reporter wiring and incomplete or contradictory production receipt-signing identity remain fatal regardless of this flag.

createDVMHost for advanced wiring [#createdvmhost-for-advanced-wiring]

Use `createDVMHost` for host routes, several mounted DVMs, shared pool access, or custom shutdown ordering:

```typescript
import { createDVMHost } from "@dvmkit/sdk/server";

const host = createDVMHost();
host.app.get("/health", (c) => c.json({ ok: true }));
host.mount(createMyDVM({ getPool: () => host.pool }));

await host.serve();
```

[Your own tables](#your-own-tables) shows the `createMyDVM` factory side of this pattern.

Local development [#local-development]

`dvmctl dev handler.ts` starts a hot-reloading server with `devMode: true`:

```bash
dvmctl dev handler.ts
```

Without configured mints, dev mode skips payment verification and uses an in-memory store when no database is set. It sets `requesterId` to `dev-anonymous`. Set `DVMKIT_CASHU_MINTS` when you want to exercise the payment path against a test mint.

The dev server resolves a default export first, then a named `dvm` export, then the first DVM descriptor it finds. Port priority is `--port`, `.env PORT`, `process.env.PORT`, then `3000`.

Testing payments locally [#testing-payments-locally]

Point a dev server at a local test mint:

```bash
DVMKIT_CASHU_MINTS=http://localhost:3338 dvmctl dev handler.ts
```

Fund a local caller wallet and submit normally:

```bash
dvm wallet init
dvm wallet mint-add http://localhost:3338
dvm wallet fund 100 --sats --mint http://localhost:3338 --test-skip-lightning
dvm request --endpoint http://localhost:3000 -i "hello" --human
```

`--test-skip-lightning` is for local test mints only. It is not a production funding method.

What the framework handles [#what-the-framework-handles]

You do not need to hand-build these parts:

* Capability dispatch for `/v1/job`, `/v1/quote`, and `/v1/info`.
* Input-schema parsing before `onJob`.
* Upfront 402 payment gating.
* Cashu, x402, and Tempo payment verification for configured rails.
* SSE messages, sequence numbers, yields, and terminal states.
* Credit funding, draw holds, release-on-failure, and idempotency.
* Durable jobs, state, steps, and KV storage when Postgres is configured.
* Signed receipts when a receipt key and compatible job store are available.
* Platform revenue reporting when `DVMKIT_PLATFORM_*` is configured.

Further reading [#further-reading]

* [Build a DVM](/docs/build): builder access and the current release path.
* [Protocol specification](/docs/protocol): wire formats, yields, and transport.
* [Funding](/docs/funding): how payment rails move and return value.
* [Credits](/docs/credits): caller-facing prepaid balances and reclaim.
* [Caller quickstart](/docs/quickstart): run a paid job with the `dvm` CLI.

{/*
  Reference audit:

  Published or condensed: Running it; A real DVM; configureDVM, including DVM-level fields, per-capability fields, tags, pricing, and non-USD pricing; Capabilities, including single-capability DVMs, multi-capability DVMs, capability names, and wire dispatch; The job context, including identity, messaging, flow control, cancellation, and platform services; Multi-turn conversations; Per-job state; Cross-job storage; Input validation with Zod; Dynamic pricing with onQuote, including zero quotes and refusing a quote; Mid-job payment, including asks against the upfront; Prepaid credit, including the trust ladder, where released money goes, Lightning funding, expiry and reclaim, and Tempo session channels; Retried paid submits; Signed receipts; Durable steps; Testing, including test options and inspection; Custom HTTP routes, including DVM-scoped routes, host-scoped routes, and endpoint compatibility; Authentication, including descriptor auth, the lower-level verifier, options, signing tests, quote paths, and failure taxonomy; Lifecycle hooks; Persistence; Your own tables; Deployment, including serve options, payment-rail environment variables, prefix rules, reporter boot behavior, fail-fast, and advanced host wiring; Local development; Testing payments locally; What the framework handles; Further reading.

  Deliberately omitted: the canonical reference's live provider-contract matrix, because it names repository CI tests and vendor credentials rather than an SDK surface; and the reporter's full payout payload examples, because they describe platform bookkeeping rather than builder configuration. The page keeps the builder-facing reporter contract and environment variables above.
  */}
