SDK Reference

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.

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.

npm install --save-exact @dvmkit/sdk

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

npm install pg

Running it

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

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:

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

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(config) validates your config and returns a frozen DVMDescriptor. The flat single-capability shape becomes a one-entry capabilities map internally.

DVM-level fields

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

FieldTypeRequiredDescription
namestringyesDisplay name
descriptionstringDVM description. The first sentence becomes the public page title and search snippet: write the errand in words a caller would search (≤70 characters), and put the mechanism in later sentences.
tagstringOne discovery tag
tagsstring[]Discovery tags
currencystringLowercase ISO 4217 pricing currency. Defaults to "usd"
idleTimeoutnumberCaller response/payment window before automatic cancellation, in whole seconds. Default: 3600; range: 1–604800 (7 days)
processingWatchdognumberSeconds 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. 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
authDVMAuthSchemeRequire 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.

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:

FieldDefaultMinimumWhat it governs
minLocktimeSeconds604800 (7 days)90000Signed 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
unsignedMinLocktimeSecondsminLocktimeSeconds less 24 hours3600An 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:

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, 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

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

FieldTypeRequiredDescription
capabilitystringCapability name in the flat shape
descriptionstringCapability description
inputZod schemaParse and type ctx.input
stateobject literalPer-job state defaults
pricestringStatic USD upfront price such as "$0.05"
onQuoteQuoteConfigDynamic pricing handler
ratesCapabilityRate[]Published rate card for a priced capability. See Rate cards
onJob(ctx) => void | Promise<void>yesHandle 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 are free-form strings advertised in /v1/info. Clients use them to match providers to job types:

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

Pricing

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

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

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

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

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:

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

/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:

{
  "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

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

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

Use the flat shape for the common case:

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

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:

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

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

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

{
  "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

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

PropertyTypeDescription
jobIdstringServer-assigned job ID
tagsstring[]Tags from the descriptor
inputInputRaw input or parsed schema output
paramsRecord<string, string>Query-style job parameters
requesterIdstringOpaque requester identifier
paidMsatsnumberTotal payment received so far
auth{ pubkey, envelope } | undefinedVerified 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

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:

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 shows the caller's side of the check.

Flow control

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. 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.

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

Long-running work should observe ctx.signal:

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

Inside onJob(ctx), the SDK supplies:

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

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:

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

Linear async style

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

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

Use onResponse when explicit message routing fits the DVM better:

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

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

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

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

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

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

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

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

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

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 shows.

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 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

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

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:

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"
);
{
  "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

Request more payment after work has started:

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

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 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:

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 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

Opt in with a credit block and signed caller auth:

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

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:

EndingCharged
ctx.completeEvery paid piece
ctx.fail, a handler crash, or stale-job reapingThe finished pieces. The piece in progress is released
The caller declines an ask or lets it expireThe finished pieces. Nothing was paid for the next one
The caller cancelsEvery 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

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:

CallerWhere the release landsCan the caller use it
Signed, holding credit at your DVMTheir credit balanceYes, on the next job or by reclaiming it
Signed, at a DVM with auth but no credit blockA per-call balance for their key, kept 90 daysOnly 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 allowUnsignedPaidOne shared anonymous balanceNo. Nobody can prove it is theirs
Unsigned, paying with x402 through allowUnsignedPaid on a capability that sets maxRuntimeSecondsNowhere. The payment is verified before the job and settled only if it succeedsNothing 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 explains the same cases to callers.

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 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 and budgets describe the caller's side.

Caller view

Quotes can inspect the caller without spending the balance:

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

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 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

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

Funding shapeWho completes the reclaimBuilder action
Cashu or LightningBuilder's refund workerRun dvmctl melt-pending; it parks ecash locked to the caller's refund key
Reusable x402 or Tempo channelThe channelKeep the channel settlement and close observer healthy
One-shot x402 or Tempo paymentBuilder operatorReview 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:

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

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

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

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

{
  "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

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:

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

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:

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 marks it failed.

Testing

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

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

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

PropertyDescription
messagesOutbound messages with their type and content
completedWhether complete() was called
failedWhether fail() was called
summaryThe summary passed to complete()
failErrorThe error passed to fail()
refundRequestedWhether fail() requested a refund annotation

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

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

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

Register host.app routes before mounting DVMs:

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

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

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

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:

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

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

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 for x402 too.

Lower-level primitive: createSignedRequestVerifier

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

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

OptionDefaultDescription
driftSeconds300Allowed clock drift
domainnoneFixed audience, method, path, and capability
envelopeFields["signature"]Additional fields removed from canonical bytes
replayStorebounded in-memory FIFOCross-machine store, or null to disable replay checks
nowcurrent Unix secondsClock override for tests

Signing in tests

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

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

/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

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

sub_reasonCause
schema_invalidEnvelope or payload fields are missing or malformed
timestamp_driftThe timestamp is outside driftSeconds
signature_invalidBIP-340 signature verification failed
replay_detectedThe caller reused a nonce in the replay window
signature_requiredThe 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

onBoot(env)

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

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 runs in reverse mount order before the host closes. Use it to drain provider work and close resources:

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

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

Pass database to serve() or set DATABASE_URL:

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

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

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

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

// 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`);
    },
  });
}
// 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

Container

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

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

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.

OptionTypeDefaultDescription
portnumberPORT or 8080HTTP listen port
databasestringDATABASE_URLPostgres connection string
envRecord<string, string>process environmentValues available as ctx.env
builderBuilderIdentityenvironment-derivedBuilder identity in /v1/info
ownerOwnerDisplayenvironment-derivedOwner display identity in /v1/info
platformReporterPlatformReporterOptsenvironment-derivedRevenue reporting connection
fxFxFetcherenvironment-configuredFX source override
healthHandler(c) => ResponseSDK health responseCustom /health handler
storeKVStorePostgres-backedKV store override
jobStoreJobStoredatabase-backedExplicit job store
poolPoolnoneReuse an existing Postgres pool; the caller owns its lifecycle
mintsstring[]DVMKIT_CASHU_MINTSAccepted Cashu mints
cashuModeCashuModeexplicitCashu receive mode, including p2pk-accumulator
mppMppxServerenvironment-resolvedTempo/MPP payment handle override
x402X402Configenvironment-resolvedx402 payment configuration override
paymentMethodsPaymentMethod[]Derived from railsAdvertised payment methods
lightningReceiveLightningReceiveConfigenvironment-resolvedReceive-only Lightning leg for credit funding
devModebooleanfalseLocal/test behavior and in-memory fallback

Payment-rail environment variables

The SDK reads these server environment variables:

VariableEffect
DATABASE_URLPostgres connection string. Required in production
PORTListen port. Defaults to 8080
DVMKIT_CASHU_MINTSComma-separated Cashu mint URLs
DVMKIT_CASHU_LOCK_PUBKEYP2PK lock key for accumulator-mode Cashu
DVMKIT_DVM_IDStable DVM identity used by durable payment and receipt records
DVMKIT_STRIPE_SECRET_KEYStripe account key for USD card-funded prepaid credit. Prefer a restricted key with the card setup permissions. Requires DVMKIT_STRIPE_NETWORK_ID and DVMKIT_TEMPO_SECRET_KEY
DVMKIT_STRIPE_NETWORK_IDStripe profile’s Network ID (profile_…; internal in test mode). Set together with DVMKIT_STRIPE_SECRET_KEY
DVMKIT_STRIPE_MIN_USDCard-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
DVMKIT_NWC_RECEIVE_URIReceive-only wallet connection for Bitcoin Lightning credit funding
DVMKIT_NWC_RECEIVE_ALLOW_SPENDExactly 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_SATSAdvertised Lightning receive floor
DVMKIT_TEMPO_RECIPIENTTempo settlement recipient
DVMKIT_TEMPO_OPERATOR_KEYFee-funded operator key for reusable Tempo sessions
DVMKIT_TEMPO_SECRET_KEYHMAC 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_URLTempo RPC endpoint
DVMKIT_TEMPO_METHODSTempo method allowlist
DVMKIT_X402_PAY_TOx402 settlement recipient
DVMKIT_X402_NETWORKx402 chain identifier
DVMKIT_X402_FACILITATORx402 facilitator URL. Choose a provider that settles the configured network
DVMKIT_PLATFORM_URLPlatform reporter endpoint and hosted-DVM signal
DVMKIT_PLATFORM_TOKENPlatform reporter credential
DVMKIT_FX_SOURCEFX source override
DVMKIT_RECEIPT_KEYReceipt-signing key
DVMKIT_FAIL_FASTEscalate 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

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

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 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

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

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 shows the createMyDVM factory side of this pattern.

Local development

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

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

Point a dev server at a local test mint:

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

Fund a local caller wallet and submit normally:

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

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