Protocol Specification

The DVM protocol is a turn-based conversation between a caller and a provider over HTTPS.

The DVM protocol is a turn-based conversation between a caller and a provider over HTTPS. The caller submits a job, the provider does work and sends messages, and control passes back and forth until the job completes. The transport is a REST API with SSE (Server-Sent Events) for streaming.

Future transport bindings (e.g. A2A) may be added later.

Client compatibility

Callers send the same compatibility metadata on every HTTP request:

HeaderValue
DVM-Clientdvm/<semver>, such as dvm/0.1.0
DVM-Protocol-Version1
DVM-Client-CapabilitiesA sorted, comma-separated list of lowercase kebab-case tokens, such as credit-recovery,request-resume

These headers are support and rollout metadata. They are not authenticated caller identity. A server parses and records valid client versions, protocol versions, and capability sets as structured request fields. Every server response carries DVM-Protocol-Version: 1.

Compatibility is additive and endpoint-specific. Missing headers remain valid on an endpoint that declares no requirement. A future protocol version is recorded but is not rejected by itself. An endpoint may require one or more capability tokens, a minimum dvm version, or both. The check runs before that endpoint's handler and its side effects.

When the caller cannot meet an endpoint's declaration, the server returns HTTP 426:

{
  "error": "client_upgrade_required",
  "required_capabilities": ["credit-recovery", "request-resume"],
  "minimum_client_version": "0.1.0",
  "current_client_version": "0.0.9",
  "display": "This request needs a newer dvm client.",
  "hint": "Upgrade or reinstall dvm with support for capabilities credit-recovery, request-resume and dvm 0.1.0 or newer, then retry this request."
}

required_capabilities is always present and sorted. minimum_client_version appears only when the endpoint declares one. current_client_version appears only when DVM-Client contains a valid dvm/<semver> value. A missing or malformed client version cannot satisfy a declared minimum. A missing, malformed, duplicated, or unsorted capability list satisfies no required capabilities.

Capability tokens are additive. Document a new token with the endpoint behavior that introduces it. Roll out a requirement in four stages: expand the server first, release and migrate the CLI, observe adoption, then contract the old behavior. A production endpoint must not require a capability or version that exists only in an unreleased CLI.

Conversation model

A job is a conversation. The provider and caller take turns. Each turn ends when the provider yields — sends a message that hands control to the caller.

Yield types

Five message types end the provider's turn:

Yield messageWhat it meansCaller's next action
promptProvider needs inputSend a response message
payment-requestProvider needs paymentSend a payment message
workingProvider is busy, will take a whileDisconnect, check back later
completeJob finishedDone
cancelJob failedDone

complete and cancel are terminal. The conversation is over. The other three are non-terminal yields where the provider expects the caller to act before work continues.

Non-yielding messages

text, progress, and artifact messages stream to the caller without ending the provider's turn. A provider can send any number of these before yielding. Use them for status text, structured progress heartbeats, intermediate results, and artifacts that precede the final complete.

Turn flow

Caller submits job
  |
  v
Provider's turn
  |
  |-- text: "Working on it..."           (non-yielding, streams to caller)
  |-- artifact: { data: "...", ... }     (non-yielding)
  |-- prompt: "Which option?"            (YIELD — provider's turn ends)
  |
  v
Caller's turn
  |
  |-- response: "Option B"              (caller sends, provider's turn resumes)
  |
  v
Provider's turn
  |
  |-- text: "Refining option B..."       (non-yielding)
  |-- complete: "Done"                   (YIELD, terminal)

A yield closes the SSE stream. The caller reconnects (opens a new stream) to resume the conversation after acting on the yield.

When the provider needs a long time

If the provider has a long stretch of work ahead (minutes to hours), it yields with a working message rather than holding the connection open:

Provider: text "Got it, I'll design three concepts."
Provider: working { estimate_seconds: 1800, hint: "Check back in ~30 min" }
(connection closes)

The caller disconnects and checks back later. The provider continues working and persists messages to its store. When the caller reconnects (with ?after=<last_seq>), it picks up where it left off.

Messages

Every message has these base fields:

FieldTypeDescription
seqnumberMonotonic sequence number
from"requester" or "provider"Which side sent the message
timestampnumberUnix timestamp (seconds)
typestringMessage type (see below)
contentobjectType-specific payload

The wire value for the caller's side is "requester". This spec calls that party the caller throughout its prose; "requester" is the same role's name on the wire.

Provider to client

text

Free-form status or progress text. Non-yielding.

{ "type": "text", "content": { "text": "Fetching page content..." } }
FieldTypeRequiredDescription
textstringyesMessage text

prompt

Request input from the caller. Yields.

{
  "type": "prompt",
  "content": {
    "id": "p1",
    "text": "Which concept do you prefer?",
    "options": ["A — Modern", "B — Classic", "C — Minimal"],
    "expires_at_ms": 1790000900000
  }
}
FieldTypeRequiredDescription
idstringyesUnique prompt ID (for matching responses)
textstringyesHuman-readable question
optionsstring[]noSimple choice list
schemaobjectnoJSON Schema for structured responses
expires_at_msnumbernoCaller response deadline in integer Unix milliseconds

SDK 0.14.2 and later stamp every prompt and payment request with expires_at_ms. Older servers may omit it. Caller agents should relay this deadline to the human answering the question or approving payment.

When schema is present, the caller should respond with structured data conforming to the schema. The text field remains the human-readable question — shown to humans and gives LLM agents context for what's being asked.

{
  "type": "prompt",
  "content": {
    "id": "p2",
    "text": "Provide your brand assets and preferences",
    "expires_at_ms": 1790000900000,
    "schema": {
      "type": "object",
      "properties": {
        "primary_color": { "type": "string", "description": "Hex color code" },
        "tone": { "type": "string", "enum": ["professional", "playful", "bold"] }
      },
      "required": ["primary_color"]
    }
  }
}

artifact

Job output — inline data or a URL reference. Non-yielding (send before complete).

{
  "type": "artifact",
  "content": {
    "data": "# Extracted Content\n\nThe page says...",
    "mime_type": "text/markdown",
    "name": "extracted-content.md"
  }
}
FieldTypeRequiredDescription
namestringnoHuman-readable name
mime_typestringnoMIME type
datastringnoInline data (text or base64)
encodingstringno"utf-8" or "base64" for inline data
urlstringnoURL to fetch
size_bytesnumbernoSize in bytes (for URL-referenced artifacts)
sha256stringnoSHA-256 hash for integrity verification

Either data (inline) or url (by reference) should be present. For small outputs (<256 KB), inline is simpler. For large files, use a URL.

payment-request

Request payment to continue. Yields.

{
  "type": "payment-request",
  "content": {
    "amount_msats": 50000,
    "reason": "Design exploration: 3 concept directions",
    "expires_at_ms": 1790000900000,
    "mints": ["https://mint.example"]
  }
}
FieldTypeRequiredDescription
amount_msatsnumberyesAmount requested in millisatoshis
reasonstringyesHuman-readable explanation
expires_at_msnumbernoPayment deadline in integer Unix milliseconds
mintsstring[]noCashu mint URLs accepted
min_locktime_secondsnumbernoMinimum P2PK locktime required
fiat_amountobjectno{ amount, currency } — the operator's fiat-denominated intent when this charge was priced in fiat. Absent when priced in sats directly
lock_pubkeystringnoNUT-11 P2PK lock pubkey to lock Cashu outputs to. Falls back to /v1/info's cashu.lock_pubkeys[0] when absent
x402objectnoThe x402 stablecoin option — see below
tempoobjectno{ challenges: [...] } — the Tempo option, see below
charged_if_declined_micronumbernoWhat the caller is charged if it declines this request or lets it expire: the pieces of work finished so far, at full price, in integer micro-units of the job's credit currency. Absent on jobs accepted before piece charging
mandate_skippedobjectno{ reason } when the standing mandate will leave this ask open for ordinary payment

x402 carries { pay_to, network, asset, facilitator?, required_usdc_micro?, payment_required?, nonce? }. payment_required is the full v2 challenge (a PAYMENT-REQUIRED envelope, same shape as the 402 challenge); its absence selects legacy v1. nonce, when present, is the server-issued EIP-3009 bytes32 nonce the caller must sign into TransferWithAuthorization for this payment-request — it binds the credential to this job. Reply with content.x402_payment on the payment message (see below).

tempo carries { challenges: [...] } — one challenge per method/intent this DVM accepts for a mid-job Tempo payment. Pick the entry matching your wallet's method and construct a Credential against it; reply with content.tempo_credential.

working

Signal that the provider is busy and will take a while. Yields. The caller should disconnect and check back later.

{
  "type": "working",
  "content": { "estimate_seconds": 1800, "hint": "Generating designs, check back in ~30 min" }
}
FieldTypeRequiredDescription
estimate_secondsnumbernoRough time estimate
hintstringnoHuman-readable hint

progress

A structured progress heartbeat. Non-yielding — unlike working, the SSE stream stays open across heartbeats so the caller can render live progress without reconnecting.

{
  "type": "progress",
  "content": { "percent_complete": 40, "current_phase": "transcribing", "hint": "12 of 30 minutes" }
}
FieldTypeRequiredDescription
percent_completenumberyesEstimated completion, 0–100
current_phasestringnoCoarse phase label (DVM-defined, e.g. transcribing)
hintstringnoHuman-readable hint about what's happening now

complete

Job finished. Terminal yield.

{
  "type": "complete",
  "content": {
    "summary": "Landing page design completed"
  }
}
FieldTypeRequiredDescription
summarystringnoHuman-readable summary

After complete, no more messages should be sent.

cancel (provider-initiated)

Job failed. Terminal yield.

{ "type": "cancel", "content": { "reason": "Invalid URL: expected http:// or https://" } }
FieldTypeRequiredDescription
reasonstringnoError message

Client to provider

response

Caller's answer to a prompt.

{
  "type": "response",
  "content": {
    "prompt_id": "p2",
    "text": "Here are my brand details",
    "data": { "primary_color": "#1B3A5C", "tone": "professional" }
  }
}
FieldTypeRequiredDescription
prompt_idstringyesMatches the prompt's id field
textstringyesFree-form text answer
dataobjectnoStructured data conforming to the prompt's schema

When the prompt included a schema, data should be present and conform to it. If validation fails, the provider can re-prompt with the same schema and explain what was wrong.

payment

Caller sends payment proof.

{
  "type": "payment",
  "content": {
    "cashu_token": "cashuAeyJ...",
    "mint": "https://mint.example",
    "amount_msats": 50000
  }
}
FieldTypeRequiredDescription
cashu_tokenstringnoCashu ecash token
mintstringnoMint URL
amount_msatsnumbernoAmount in millisatoshis
cashu_request_idstringnoUUIDv4 per-call id for the agent-wallet accumulator path — the mid-job equivalent of the upfront flow's X-Cashu-Request-Id header
x402_paymentstringnoBase64-encoded x402 PaymentPayload — the mid-job equivalent of the upfront PAYMENT-SIGNATURE (v2) or X-PAYMENT (v1) header
tempo_credentialobjectnoStructured Tempo Credential ({ challenge, payload, source? }) answering a payment-request's tempo.challenges entry
creditobjectnoSigned balance authorization or provider-written mandate payment (see below); cannot accompany rail credentials
reasonstringnoOnly for provider-sent: "change" or "refund"

A provider paying an ask under a standing mandate writes a payment from requester on the caller's behalf:

{
  "from": "requester",
  "type": "payment",
  "content": {
    "credit": {
      "mandate": true,
      "credit_id": "example-credit",
      "draw_id": "example-draw",
      "payment_id": "mandate:b760d987033f4635e36af50da52021993b89d7f2c85f2b0a09fe1236d43f09c0",
      "request_seq": 3,
      "amount_micro": 550000,
      "currency": "usd"
    }
  }
}

request_seq identifies the paid payment-request; amount_micro and currency repeat its credit price. The mandate is the authorization, so this variant has no signature. payment_id is mandate: followed by the lowercase SHA-256 hex of compact JSON ["mandate", job_id, request_seq]; this example uses job ID example-job. Callers cannot submit this unsigned variant. An inbound credit payment still requires a signed balance authorization. Code reading PaymentContent.credit.signature must first distinguish the mandate variant by its mandate: true field.

The payment type can also flow provider to caller with reason: "change" or "refund" for overpayment change or refunds.

approval

Caller approves a proposed action.

{ "type": "approval", "content": { "ref_seq": 7, "comment": "Looks good, proceed" } }
FieldTypeRequiredDescription
ref_seqnumbernoSeq of the message being approved
commentstringnoOptional comment

cancel (client-initiated)

Caller cancels the job. The job ends at once and the provider's handler is told to stop. Every piece of work the caller has paid for is charged, including the one in progress, which delivers no result. DELETE /v1/job/:id does the same.

{ "type": "cancel", "content": { "reason": "No longer needed" } }

decline (client-initiated)

Caller declines the open payment-request or prompt, which ends the job as cancelled, ended by the caller. Unlike a cancel, the piece of work in progress is released rather than charged, so the caller pays only for finished pieces and keeps what they delivered. Output delivered before the ask remains readable from GET /v1/job/:id/messages after the decline. Without a mandate and with nothing open to decline, the provider answers 409 no_open_ask.

On a job with a standing mandate, a decline between asks records a stop rather than ending the running piece. HTTP 201 returns { "seq": <current seq>, "stop_requested": true, "display": "The job will stop at its next payment ask. Only finished pieces will be charged." }. Job status includes the same stop_requested and display while the stop is pending. Repeating the decline keeps the same stop without adding a message. The stop survives a provider restart. At the next payment ask, the provider applies the stop before paying: the job ends as cancelled, ended by the caller, and only finished pieces are charged. A payment committed before the stop remains paid. An already open ask or prompt is declined immediately as before.

If automatic mandate settlement is disabled or unavailable, the pending-stop response and status instead say Stop recorded. Decline the next open payment ask to stop the job. The stop stays recorded, but the caller must decline the next open ask unless a host with mandate settlement enabled applies it.

The piece rule also applies to mid-job payments on DVMs the platform hosts on its isolate tier. Their upfront payments still use a separate path: upfront revenue books only on completion, and unfinished upfront work does not release a credit balance. Released mid-job funds remain on credit; the isolate tier does not yet offer a caller-facing drain.

{ "type": "decline", "content": { "reason": "Too expensive" } }

Provider text provenance in CLI output

The dvm CLI wraps provider-supplied free-text fields (names, descriptions, prompt text, payment reasons, etc.) as { "_source": "provider", "text": "..." } in its JSON output. This is a CLI output convention, not a wire-format change — messages on the wire use plain strings as documented above. See Provider text provenance for the full field list and a worked example.

Payment

Upfront payment

When a provider requires payment before starting work, the caller attaches an X-Cashu header to POST /v1/job. The server verifies the token, checks the amount, and returns 402 if missing or insufficient. Overpayment is kept and nothing is returned on the response: the full amount presented funds the caller's credit, and an unsigned request then draws all of it for the job, so a caller who sends more than the price is charged what they sent. A signed request carrying a credit envelope draws only the price and leaves the excess as available balance.

Paying without a request id (NUT-24). On a request that needs no signature, the 402 also carries an X-Cashu header holding a NUT-18 payment request, so a generic Cashu wallet can pay without reading the JSON body (see The 402 challenge). The wallet resends the same body with X-Cashu: cashuB… and nothing else. From SDK 0.21.0, this unsigned paid submit waits up to 10 seconds by default. If the job completes in that window, it returns HTTP 200 with the result inline, including job_id, job_token, status: "completed", the summary or artifact metadata, content fields, and job identity headers. For a job that produced artifacts, when the complete messages array is at most 1,048,576 bytes of serialised UTF-8 JSON, the body also carries messages in the same shape as GET /v1/job/:id/messages. Above that cap, messages is omitted and payload_in: "messages" points callers to that endpoint with X-Job-Token. The cap does not truncate messages. A job still running returns HTTP 202 with job_id and job_token to poll. A job awaiting input returns immediately; failed and cancelled jobs keep their existing status mapping. Builders can set cashu.unsignedResultWaitSeconds to an integer from 0 to 20; 0 disables the wait. An identical retry takes the same wait without charging twice. Signed requests, prepaid credit, x402, Tempo, and Cashu with an explicit request id keep their existing response timing. With no X-Cashu-Request-Id, the provider binds the payment to nut24- followed by the hex SHA-256 of the JSON-encoded, sorted proof secrets, and uses that id wherever a request id would go, including the derived credit id imp:cashu:nut24-…. Resending the same token with the same body returns the original job, job_token included, and charges nothing more; the same token with a different body gets 409 replay_rejected. A refusal the payer can fix answers 400 instead of 402 on this path: invalid_token, not_p2pk_locked, wrong_lock_pubkey, lock_not_exclusive, and payment_insufficient. Other refusals keep their usual status. A header-less payment that covers the price at the exchange rates the provider just replaced, but not at the current ones, is accepted at the earlier rates while those last priced a quote or a 402 less than 10 minutes ago. A payment sent with X-Cashu-Request-Id gets no such hold, and an X-Cashu-Request-Id starting nut24- is refused with 400 reserved_request_id, because those ids are derived.

Mid-job payment

The provider sends a payment-request message (a yield) specifying the amount and reason. Work pauses until the caller sends a payment message. This supports incremental billing for multi-step jobs.

Each payment buys the next piece of work: the upfront payment buys the first, and each paid payment-request buys the one after it. The upfront payment never covers a later request; every request asks for new money. A provider should deliver a piece's output (artifacts, partial results) before asking for the next payment, so a caller who declines keeps what it paid for. A payment that arrives after the job ended, after its request expired, or with no request open buys nothing and lands on the caller's credit as balance.

Mid-job rail envelopes ride the payment message's body, not request headers — the SSE message channel is the transport, so the per-rail credential goes inside content. The mid-job equivalent of the upfront X-Cashu header is content.cashu_token (+ content.cashu_request_id for the agent-wallet accumulator); the upfront x402 header — PAYMENT-SIGNATURE (v2, the default generation) or X-PAYMENT (v1) — becomes content.x402_payment (base64-encoded PaymentPayload); and the upfront Authorization: Payment … (Tempo) becomes content.tempo_credential (a structured Credential.Credential).

Cashu

The primary payment method. Callers send Cashu ecash tokens (cashu_token field in payment messages). The provider specifies accepted mints in its info endpoint and in payment-request messages.

The value a provider accepts from a Cashu token is the decoded proofs' gross face minus the standalone NUT-02 input fee for that exact proof set. Each proof is priced against its own loaded keyset, including mixed or inactive keysets. A conformant caller uses includeFees(true) when creating the provider-locked token, so the extra face reserved for the provider's eventual spend makes the net value equal the advertised amount; that reserve is processing-fee allowance, not caller principal. Payment gates, paidMsats, prepaid balance, refunds, and draw revenue all use the net value, while the accumulator and deposit reporting retain gross face and the fee allocation for reconciliation.

Prepaid credit

A credit is a per-provider prepaid balance belonging to one authenticated caller: fund it once, draw from it across many jobs. It amortises payment overhead over N jobs and converts "the wallet must be reachable when the job runs" into "the wallet must be reachable sometime this funding window."

Per-call payment is unchanged and remains the universal floor. A request that attaches a payment and names no credit is an implicit N=1 funding: the provider funds a single-use credit and draws it in the same request, so the legacy request shape stays valid byte-for-byte.

Per-call payment and prepaid credit are the two customer payment modes. Rail-native values such as exact, batch-settlement, charge, session, and channel are instruments underneath them: one-shot stablecoin authorizations fund per-call payment, while reusable stablecoin channels fund prepaid credit by default. A builder may explicitly admit one-shot stablecoin authorizations to prepaid credit and accept the resulting manual refund obligation; the channel is custody and settlement underneath credit rather than a third mode.

Credit is opt-in per provider. A provider that offers it advertises a credit block on /v1/info, /v1/quote, and every 402. A provider that doesn't offer it omits the block entirely and answers /v1/credit with credit_not_supported. Amounts are always micro-units: 1e-6 of the block's currency, never sats or msats.

Credit requires the caller to be authenticated (a credit belongs to a verified pubkey), so only providers declaring a signed-request auth scheme advertise it. Every first-party container DVM (cast, narrate, scrape, scribe) does.

Card-funded credit

Card funding through Stripe-hosted checkout or Stripe Link is a prepaid-credit funding leg only. With CLI 0.19.0 or later, callers anywhere can pay a checkout link when the provider advertises credit.stripe.checkout: true. Stripe Link is another option for agents in the US and Canada. Paying by card covers the caller flow. A USD credit menu can list stripe in credit.funding with credit.stripe: { network_id, min_micro, currency: "usd" }; it never appears in payment.methods. The card minimum defaults to US$5, capped at the credit maximum. Builders can change it for card alone through DVMKIT_STRIPE_MIN_USD or createStripeCreditRail({ minUsd }). Explicit settings must be at least US$0.50 and no greater than the credit maximum. The advertised min_micro respects the credit minimum and Stripe’s US$0.50 floor; callers use that advertised value. A stripe drain refunds the original card, less the proportional share of Stripe’s processing fee for the amount refunded. A credit spent in full costs the caller no fee. Expired card credit follows the same refund path and is never released to the provider. Card amounts use the credit’s currency, not sats or msats.

The funding menu

The sizing and funding terms are present on /v1/info, /v1/quote, and 402 bodies from /v1/job:

{
  "credit": {
    "min_micro": 100000,
    "max_micro": 5000000,
    "ttl_ms": 7776000000,
    "currency": "usd",
    "funding": ["cashu", "x402", "lightning"],
    "lightning_min_micro": 2300000,
    "x402": {
      "schemes": [
        { "scheme": "batch-settlement", "network": "eip155:84532" }
      ]
    },

    "credit_id": "b1f0…",
    "balance_micro": 750000,
    "remaining_micro": 620000,
    "expiry_ms": 1795200000000
  }
}
FieldTypeDescription
min_micronumberSmallest funding accepted
max_micronumberCeiling on the caller's residual balance, not a funding amount (see below)
ttl_msnumberCredit lifetime, measured from the most recent funding
currencystringDenomination of every *_micro field here and of the resulting credit
standing_mandatebooleanOptional. true on /v1/info when standing credit mandates are supported
mandate_skippedbooleanOptional. true on /v1/info when payment asks report why the standing mandate could not pay
fundingstring[]Rails a top-up may arrive on. lightning is funding-only (see below)
lightning_min_micronumberOptional. The lightning rail's own minimum, above min_micro (see below)
tempoobjectOptional. { methods: [{ method, intent }], withheld? }: Tempo funding methods, see below
x402objectOptional. { schemes: [{ scheme, network }] }: which x402 flavours fund a credit, see below
credit_idstringEcho only. Which credit the balance fields describe
balance_micronumberEcho only. Funded balance, pending holds not subtracted
remaining_micronumberEcho only. Spendable balance: what a draw is checked against
expiry_msnumberEcho only. When the echoed credit stops accepting new draws

The four echo fields never appear on /v1/info, which is unauthenticated and cacheable. They appear on /v1/quote and 402 responses only when the request carried a verified caller pubkey and that caller holds a live credit in currency, so a single quote answers both "what does this cost?" and "what do I have left?". A caller holding several credits gets the one with the largest spendable balance.

currency is a per-provider constant: the currency the provider prices in, identical on /v1/info, /v1/quote, every 402, and POST /v1/credit, and the same one the quote's upfront is denominated in. A caller can therefore compare min_micro / max_micro / remaining_micro against upfront with no conversion, and can top up against terms learned from any discovery or payment surface knowing the credit it mints is the one their next job will draw from. A provider that changes what it prices in changes this field. An existing balance in the old denomination stays the caller's and stays visible on the balance op, but no longer pays for jobs; the drain op is how it comes back.

max_micro binds the residual balance, not the funding amount. A job priced above max_micro still clears, because funding and drawing happen in the same request and the residual delta is zero. The ceiling is enforced only on POST /v1/credit, where a top-up leaves money sitting. It applies to the caller's total spendable balance at this provider, summed across every credit they hold in currency, so opening extra credits doesn't raise it. Expired credits don't count against it.

Minimums are per-rail (DVM-1519). min_micro is the menu-wide floor; a rail may carry a higher one of its own, stated as a <rail>_min_micro sibling. Today only lightning_min_micro exists: a Lightning deployment's receive channel has a physical routing floor, and an invoice below it fails every payment attempt. The advertised figure carries a safety margin over the raw floor (the floor is sats-physical, the menu is fiat, and rates drift), so funding exactly it always clears; a funding below it is refused with below_rail_minimum naming the rail, the minimum, and the alternatives that carry any amount. A rail with no entry has no floor beyond min_micro. The field is absent from providers that predate it: treat absence as "no per-rail floor stated", not zero.

tempo and x402 name their funding mechanics. Both can fund prepaid credit through a durable channel, so their entry in funding is not on its own enough to fund against: the caller has to know what the provider will accept. Each carries a sub-block, and they answer different questions without creating additional customer payment modes.

tempo.methods lists the Tempo methods that can fund the credit. A session opens or reuses a durable channel; a charge makes one ordinary payment into the durable ledger and needs no channel close watcher. Providers admit session by default. charge appears only when the builder explicitly accepts one-payment stablecoin credit and its manual refund obligation. tempo appears in funding only when at least one admitted method is currently offered — methods non-empty — not merely admitted. A session-only provider whose observer is observer_unhealthy withholds its one method entirely, so tempo drops out of funding even though tempo.withheld still lists it as the capability signal described below. When both Tempo intents are present, callers prefer session to amortize later top-ups. They fall back to charge only when session funding is withheld and the credit isn't already bound to a channel: a channel-bound credit keeps using session even while withheld, per the exception below, since a one-shot charge against it is refused.

tempo.withheld names a method the provider is configured for and is not offering at this instant, each with a reason. observer_unhealthy means the chain watcher that protects a session channel is not confirmed running; settlement_unhealthy means the hosted provider's public operator account is below its configured fee-token reserve or a settlement transaction was rejected for insufficient fee funds. It is advisory: attempt only what methods lists. Its value is that a withheld method is a temporary absence, so a caller can retry later rather than concluding the provider never offered it, and can say as much to whoever is waiting. The provider refuses a withheld instrument at issuance and at acceptance too, so presenting a session credential for a channel it has never seen earns a refusal rather than a channel.

One exception, and it is the case that matters most: a credit already bound to a Tempo session channel may still be topped up over tempo/session while it is withheld. Both health reasons pause new channels. An existing channel's deposit is already exposed, and a channel-bound credit can be funded no other way, since a one-shot charge against it is refused. So a caller holding an open channel should send its POST /v1/credit regardless of the withholding: the provider issues that credit a session challenge, and the acceptance check keys on the channel the credential names rather than on the credit. The menu itself cannot say this: it is one advertisement for every caller, and the exception is per-credit.

x402.schemes lists which x402 flavours a top-up may arrive on, each with the CAIP-2 chain it rides. batch-settlement is the default credit instrument: a reusable channel a voucher is signed against. exact joins it only when the builder explicitly accepts one-payment stablecoin credit and its manual refund obligation. An exact-only deployment therefore omits x402 from credit.funding while keeping x402 exact under /v1/info for per-call payment. Read the scheme and the network before choosing; treat a rail listed with no sub-block (an older provider) as offering neither.

This is a prepaid-credit policy, not a stablecoin payment switch. Tempo charge and x402 exact remain available per call whenever their rail is configured. Existing charge- or exact-funded credits remain readable, drawable and drainable after a provider adopts the reusable-only default, and a retry of a funding the provider already committed still returns its recorded outcome. Only a new one-payment top-up is refused.

cashu and lightning carry no such block: funding over them needs no prior instrument.

The menu degrades rather than failing: a rail whose backing wallet is unreachable drops out of funding, and a provider that can't state its bounds in the quote's currency omits the whole block. A provider that can't currently render a rail's minimum drops that rail rather than advertising it unstated. An absent block means "no credit here", never "credit is broken".

Drawing against a credit

A job draws by carrying two fields inside the signed request body on POST /v1/job:

FieldTypeRequiredDescription
credit_idstringyesThe credit to draw from
draw_idstringyesCaller-generated; the provider's idempotency key for this draw
fundobjectno{ amount_micro, commitment } when a payment rides the same request
mandateobjectno{ max_total_micro, max_ask_micro, expires_at_ms } standing limits for later asks (see below)

draw_id is what makes a lost response safe: re-submitting the identical request with the same draw_id returns the original job and never debits twice. Reusing a draw_id for a different request is refused with draw_conflict.

fund.commitment is the SHA-256 hex of the raw payment artifact attached on the header. It binds the header-borne payment (which sits outside the signed body) to the credit its sender intended.

fund.amount_micro is the provider's valuation of that artifact, and the provider recomputes it rather than trusting it: price_micro × paid_msats / required_msats, rounded half-up, where paid_msats is the artifact's own value and an exact payment returns price_micro unrounded. Both other inputs must be provider-authored, and both are stated as exact integers on the 402 being answered: price_micro beside required_msats, resolved against one fx snapshot. Take them from there. /v1/quote's upfront.amount_micro is the same figure for a caller that quoted first; a figure derived from a caller-side rate, or reconstructed by multiplying a rendered decimal price by a million, will not match. On x402 the same ratio is taken in the rail's own units instead of millisatoshis, for the reason given below.

A caller that can't reproduce it exactly is not stuck, but what to do about it depends on the rail. Every amount mismatch is refused with funding_commitment_mismatch carrying expected_micro: the provider's own valuation of the artifact attached. Whether that figure is a retry instruction or a reconciliation record depends on where the rail's amount check sits relative to its commit.

On Cashu the check runs after the provider has decoded the token and valued its proof-set fee, but before any proof or ledger row is committed, so nothing was captured: re-sign the same token with fund.amount_micro set to expected_micro and resubmit. The commitment doesn't change, because the artifact didn't. expected_micro values the token's net principal, not its gross fee-reserved face. A caller signing off price_micro should not need this: the exact figure and required_msats come off one envelope, so a provider that prices in sats is as reproducible as one that prices in dollars. What survives is the window the wire cannot close: the provider re-resolves both figures when the payment arrives, so a rate that rotates between the 402 and the submit moves them, and this is the corrective path back.

On x402 and tempo the check runs only after the facilitator has settled or the credential has been consumed, so the refusal is fail-closed: the money moved, no job ran, and no credit was minted. expected_micro is a reconciliation figure there, not a retry instruction: the credential is spent, re-presenting it cannot land, and only the provider's operator can reconcile it from the settlement reference in its log. How the valuation is reached differs between the two, though. tempo compares against the quoted fiat price directly, so fund.amount_micro is that price in micro-units unmodified and the only way to mismatch is to sign something else. x402 values the settled authorization in the rail's own units, against the maxAmountRequired the 402 advertised: sign price_micro unmodified when the authorization's value equals maxAmountRequired, and price_micro × value / maxAmountRequired rounded half-up when it deliberately pays more. Millisatoshis never enter that valuation. Deriving them back from the settled USDC is not the inverse of the conversion that produced maxAmountRequired, so it used to read high and value an exact payment above the quoted price. Nor do they enter the advertisement: on a USD-priced DVM maxAmountRequired is price_micro, because USDC is a six-decimal USD stablecoin and the price is already an exact USD micro figure. No rate takes part, so it is the same number on the 402 and at the submit whatever the provider's fx cache did in between. Both inputs therefore come off the 402 alone, and a payment of exactly the advertised amount lands, full stop. x402 is offered only by USD-priced DVMs. A DVM priced in a currency other than USD omits x402 from discovery and from HTTP 402 responses. It does not derive a USDC amount through an exchange rate.

Re-sending after a commitment mismatch is pointless on every rail: the artifact and the hash simply disagree. That's why expected_micro is present only on the amount branch.

A draw is a pending hold placed at accept time and grown by each mid-job payment. When the job ends, the provider settles the pieces of work that finished, plus the piece in progress if the caller cancelled, and releases the rest. A piece is the work bought by one payment; it finishes when the provider sends its next payment request or completes the job.

Standing mandate

Check /v1/info for credit.standing_mandate: true before relying on automatic payments. Older providers may silently strip unknown fields. A supported provider accepts mandate inside the signed POST /v1/job data, beside credit_id and draw_id:

{
  "credit_id": "example-credit",
  "draw_id": "example-draw",
  "mandate": {
    "max_total_micro": 1100000,
    "max_ask_micro": 550000,
    "expires_at_ms": 1795000000000
  }
}

Both limits are positive safe integers in millionths (1e-6) of the credit's currency. max_total_micro includes the upfront price and must cover it. max_ask_micro caps each later ask and must not exceed the total. expires_at_ms is an integer Unix timestamp in milliseconds, strictly in the future and at most seven days from acceptance. Choose a fresh expiry; the example timestamp is illustrative. Only these three mandate keys are accepted, and both credit identifiers are required.

The caller signs the original data including the mandate. data.mandate is reserved protocol metadata: the provider strips it before handler input parsing, even if the capability schema declares that key. The accepted mandate is stored immutably with the job. Malformed or unsigned mandates, missing credit identifiers, invalid expiry, and a total below the upfront return HTTP 400 invalid_mandate with a caller-facing message. A zero-upfront mandate requires existing credit owned by the signed caller in the job currency and an unused intended draw; an unavailable credit, currency mismatch, or draw owned by another job also returns invalid_mandate.

Each later ask is paid from that credit if its price, the job total, expiry, and available balance allow it. The draw grows by the ask and buys the next piece under the usual piece rules. A zero-upfront job's first paid ask creates its draw. Expiry is rechecked immediately before committing the payment, including after a credit-lock wait. An expired mandate, exceeded limit, short balance, currency mismatch, unavailable credit, unpriced ask, or draw belonging to another job leaves the ask open for ordinary payment and emits mandate_payment_skipped.

If /v1/info advertises credit.mandate_skipped: true, the open payment-request carries content.mandate_skipped.reason (for example, mandate_ask_cap). The caller can pay that ask immediately with a signed balance payment or another offered rail. A between-asks decline records a stop as described under decline.

Retries must preserve the mandate because changing it changes the signed request's identity. The expiry window is checked again on submit retries and request resumes. After expiry, these return invalid_mandate; read the existing job by its ID and token instead.

POST /v1/credit

Signed-request envelope and replay protection, same as /v1/job. The operation is named inside the signed body, so it can't be rewritten in flight. Payment artifacts ride the same headers as /v1/job (X-Cashu + X-Cashu-Request-Id; PAYMENT-SIGNATURE (x402 v2, default) or X-PAYMENT (x402 v1); or Authorization: Payment …) and failures return the same 402 envelope.

{
  "op": "fund",
  "credit_id": "b1f0…",
  "fund": { "amount_micro": 2000000, "fund_id": "9c22…", "commitment": "<sha256 hex>" },
  "pubkey": "…",
  "signature": "…",
  "timestamp": 1790000000,
  "nonce": "…"
}
OpPurpose
fundTop up with no job attached. Omit credit_id to open a new credit
balanceRead the caller's credits. Omit credit_id for all of them
drainReclaim the unspent balance. Request, poll, and pickup are all this one op (see drain)

fund_id is the caller-generated idempotency key for a top-up, exactly as draw_id is for a draw: repeating a top-up with the same fund_id credits once and returns the original outcome with "replayed": true. This holds for a first top-up too: when credit_id is omitted the provider derives the new credit's id deterministically from the caller's pubkey and fund_id, so a retry after a lost response lands on the same credit instead of opening a second one and re-presenting a spent artifact.

fund.commitment works exactly as it does on a job draw, and is checked before any payment rail is touched: a top-up whose attached artifact doesn't hash to the signed commitment is refused with funding_commitment_mismatch and nothing is captured.

Tempo top-ups also sign their intended instrument before a credential exists: fund: { amount_micro, fund_id, commitment, method: "tempo", intent: "charge" | "session" }. The same fields stay on the paid retry. This lets the provider refuse a charge against a session-bound credit, or a session against a charge-funded credit, on the unpaid discovery request rather than after the credential broadcasts.

If an x402 channel deposit is in doubt after the payment terms change, first retry the same funding operation with the original PAYMENT-SIGNATURE and fund.commitment. From SDK 0.43.0, the provider can recover the deposit from the stored attempt even if the terms have changed.

On a changed-terms refusal, HTTP 402 carries error: "payment_invalid" in the JSON body. Decode the PAYMENT-REQUIRED header and check its error field. If it says requirements_mismatch and the new terms still use the original channel, you can refresh an eligible prepared deposit after the stored authorization's validBefore has passed. Keep the same credit and fund_id. Sign the replacement credential under the current terms and send it as PAYMENT-SIGNATURE. Sign the request body with a new fund.commitment set to the SHA-256 hex of the replacement header value.

If the new terms require a different channel, such as when the receiver or network changes, the same fund_id cannot be reused for the replacement. Resolve the original attempt first. If it did not settle, start a new funding operation with a fresh fund_id and omit credit_id to open a separate credit on the new channel. If the original outcome is still in doubt, continue recovery with the original credential before funding again.

A new Tempo charge or x402 exact top-up at a reusable-only provider is refused with one_shot_credit_not_supported before a credential settles or the ledger changes. The structured copy says that reusable channels still fund prepaid credit, the one-payment instrument still pays per call, and nothing moved. A provider that previously advertised only Tempo charge or x402 exact loses that stablecoin rail from credit.funding under the new default; its per-call advertisement and acceptance do not change.

That credit-policy conflict returns 409 from POST /v1/credit. one_shot_credit_not_supported is credit-only and is never returned by POST /v1/job.

fund.amount_micro does not work as it does on a job draw: here it is the amount being asked for, not a valuation to be reproduced, so there is no equality to fail and this route never answers funding_commitment_mismatch over an amount. An over- or under-payment credits pro rata instead (see fund below). A funding_commitment_mismatch on /v1/credit is therefore always the commitment branch, and re-sending the same body cannot fix it.

One credit, one funding instrument. A credit's balance carries the rail-native value that funded it, and two rails' native units don't sum, so topping up a credit over a rail other than the one that opened it is refused with payment_invalid before the payment, with credit_rail naming the one it does take. Reusable channels add an identity inside their rail: a Tempo charge and Tempo session are distinct instruments, as are exact x402 and an x402 batch-settlement channel. A Tempo session top-up must return to the channel stored on its target credit; an x402 batch-settlement channel additionally cannot fund two credits. Instrument refusals also carry credit_instrument, credit_channel_id when applicable, and bound_credit_id when another credit owns an x402 channel. They are terminal responses, not corrective 402s: top up through the named instrument and channel, or omit credit_id to open a separate credit.

Funding over Lightning

lightning appears in funding when the provider can issue its own invoices. It is a funding rail only: no request ever attaches a bolt11, and lightning never appears in a quote's payment.methods.

Lightning has no artifact to be recognised by, so it names itself differently from the attach rails: send fund: { amount_micro, fund_id, method: "lightning" } and omit commitment (sending one is refused). There is nothing to commit to: the provider mints the invoice for the credit_id, fund_id and amount in the signed body, which is the same binding by other means.

The leg is interactive and takes two round trips:

  1. The first request returns 402 lightning_settlement_pending carrying the invoice to pay.

    {
      "error": "lightning_settlement_pending",
      "credit_id": "fnd:35ba…",
      "fund_id": "9c22…",
      "lightning": {
        "invoice": "lnbc…",
        "payment_hash": "…",
        "amount_msats": 300000,
        "expires_at_ms": 1790000900000
      }
    }
  2. Pay it, then re-send the same request (same fund_id) to be credited. Any other authenticated request works too: a balance read, or a job submit naming the credit. Providers check for settlement on caller contact rather than watching for it, so the balance appears on the next thing you do, not on a timer.

Re-polling before payment returns the same invoice, never a new one; a provider that issued a second would leave two payable invoices against a top-up that can only be credited once. Polling after crediting returns the ordinary "replayed": true fund response.

An invoice belongs to the caller who asked for it. Naming a credit_id + fund_id pair someone else is already funding is refused with credit_id_unavailable: never answered with their invoice, which anyone could then pay onto a balance that isn't theirs.

A funding below the provider's lightning_min_micro is refused with 400 below_rail_minimum before any invoice is issued: a sub-floor invoice could never route, so refusing is the honest answer. The body carries rail, min_micro (the advertised minimum that always clears), alternatives (the rails that carry any amount), and currency. Resize to the minimum or fund over an alternative rail; re-sending the same amount can never succeed. An invoice that was already issued is never re-gated: re-polls and settlement work unchanged if the provider raises its floor while one is outstanding.

An invoice that expires unpaid is refused with lightning_invoice_expired and has no effect on any balance; start again with a fresh fund_id. A provider whose wallet is unreachable drops lightning from funding and answers lightning_unavailable: the other rails in funding still work.

Reuse a fund_id across rails and one of the two payments has nowhere to land: (credit_id, fund_id) keys a top-up exactly once, so if an attach-rail payment claims the pair after the invoice was minted, an invoice paid afterwards can never be credited. The provider answers credit_funding_unrecorded: do not pay again, and do not treat it as pending. Only its operator can reconcile from there. Keep polling the same fund_id: if the operator does credit the payment, that poll turns into a 200 carrying reconciled: true and a credit block naming the credit the balance landed on, which will not be the credit_id you asked for. Use a fresh fund_id per top-up and the case cannot arise.

Credit ids beginning imp: or fnd: are derived by the provider: the first for a per-job payment, the second for a top-up that named no credit. A caller may name one it already holds, which is how later top-ups stack onto it and how a job draws from it. Naming one it doesn't hold is refused with credit_id_unavailable on both /v1/credit and /v1/job, and the refusal is identical whether or not a credit exists at that id. Both halves of that follow from a derived id being computable from public inputs (imp: from the rail's payment id, fnd: from the caller's pubkey and fund_id): if a caller could open one, anyone could pre-open the id a provider will later derive for someone else, whose next top-up would then settle on the rail and be refused as belonging to another caller. And if the refusal varied with existence, the namespace could be walked to discover which credits a provider holds.

A caller-chosen credit_id is claimed by whoever funds it first and refused to everyone else, so pick one nobody else would guess: a UUID, not acme-prod.

fund → 200. funded_micro is what was actually credited, which is the requested amount_micro for the exact payment every conformant caller sends; an over- or under-payment credits pro rata at the quoted rate, so compare the two if the rail can pay approximately. For Cashu this is the token's net principal after its exact NUT-02 proof-set fee, even though the provider physically accumulates the larger gross token created by includeFees(true).

funding_receipt is signed under the same receipt key the builder attests on /v1/info. It fixes the credit, funding id, credited amount, funding-time balance and ledger sequence, issuance time, and caller pubkey. A retry returns the original persisted artifact byte-for-byte even when later draws changed the live credit projection. An explicit fund-and-draw on /v1/job carries the same funded_micro, credit, and funding_receipt fields on its job response.

{
  "op": "fund",
  "funded_micro": 2000000,
  "replayed": false,
  "funding_receipt": {
    "v": 1,
    "kind": "credit_funding",
    "credit_id": "b1f0…",
    "fund_id": "5c77…",
    "funded_micro": 2000000,
    "balance_after_micro": 2620000,
    "ledger_seq": 4,
    "issued_at": 1790000000,
    "caller_pubkey": "02ab…",
    "dvm_id": "dvm_01…",
    "dvm": "example",
    "receipt_pubkey": "03cd…",
    "signature": "a9f1…"
  },
  "credit": {
    "credit_id": "b1f0…",
    "currency": "usd",
    "balance_micro": 2750000,
    "remaining_micro": 2620000,
    "expiry_ms": 1795200000000,
    "expired": false,
    "ledger_seq": 4
  }
}

balance → 200 with credits[] (every credit the caller holds, including expired ones: expiry ends spending, not ownership) and credit (the one a draw would use, absent when none qualifies). Every credit projection carries drainable: true whenever unspent value remains to reclaim, expired or not.

The response also carries menu: the same funding menu block /v1/quote and every 402 advertise, so one read answers both "what do I hold?" and "what may I add?". It rides under menu rather than credit because on this endpoint credit is the credit projection, and it omits the credit_id / balance_micro / remaining_micro / expiry_ms echo, which credits[] already states in more detail. Treat its absence as "this provider said nothing" (an older provider), never as "this provider has no menu".

drain reclaims the unspent balance (expiry ends spending, never ownership: an expired credit drains identically to a live one). The signed body names the credit, a caller-generated drain_id, and, on the first request, the payout rail and destination:

{
  "op": "drain",
  "credit_id": "b1f0…",
  "drain": {
    "drain_id": "5c77…",
    "method": "cashu",
    "payout": { "refund_pubkey": "02ab…" }
  },
  "pubkey": "…",
  "signature": "…",
  "timestamp": 1789000000,
  "nonce": "…"
}

Per-method payout targets:

  • cashu → refund_pubkey: a 33-byte compressed secp256k1 key the refund notes are P2PK-locked to (your Cashu wallet's lock key, not the x-only request-signing key).
  • x402 / tempo → address (0x-prefixed EVM address).

A credit funded through a channel (an x402 batch-settlement channel, or a Tempo session channel) is bound to that channel's rail: method must be x402 / tempo respectively, and any other is refused drain_conflict. The destination is the channel's own payer rather than anything the caller names, so tempo may omit the payout block entirely, and a channel-bound x402 drain does not read it.

A credit funded by a one-off stablecoin payment (an x402 exact authorization, a Tempo charge) has no channel, so address is required on both rails: a drain that omits it is refused invalid_request (400) naming the field and the rails that do work.

The two stablecoin rails are not interchangeable either. An x402 or tempo payout on a credit funded over a different rail is refused invalid_request (400), since an address on a chain the money never came from is a liability nobody can pay. cashu reclaims a one-payment credit's balance the ordinary way, and is also how a Lightning-funded credit comes back: lightning is a funding rail only, never a payout one, so naming it as a drain method is refused drain_method_unsupported (400) before anything is reserved.

The first accepted request debits the credit's entire available balance (in-flight job holds stay put; when they release, the remainder is reclaimed with a fresh drain_id) into a drain liability and answers status: "pending". The channel rails are the exception: they settle inside the request instead (below). Re-sending the same drain_id (with or without the drain.method/payout block) is the poll/pickup: it never debits twice, and it returns the drain's current state until (and after) the refund lands:

  • pending: approved, not yet fulfilled. Cashu refunds are prepared by the provider's batch job (a down mint delays parking; the money stays owed). A one-payment stablecoin drain (an x402 exact authorization or a Tempo charge) has no automated sender at all on either rail, and is settled by the provider's operator by hand.
  • parked / picked_up (cashu): the response carries token, notes P2PK-locked to your refund_pubkey, redeemable at the mint. Polling again returns the same token; only your key can claim it.
  • sent (x402/tempo): the response carries sent with the settlement reference (e.g. the on-chain transaction hash). On the channel rails this is the first answer, not a later one.
  • released (tempo, channel-bound only): the channel could not complete this cooperative refund, so the service restored the amount to your prepaid balance instead of paying it out. Terminal: run dvm wallet tempo-exit <dvm> to recover the channel on-chain, and don't poll this drain_id again.

Credits funded through reusable stablecoin channels drain cooperatively, in the request. A drain on one is answered 402 carrying the channel's own challenge (batch-settlement refund requirements on x402, a session-close challenge on tempo), and the resubmit attaching the caller's signed refund voucher (PAYMENT-SIGNATURE) or close credential (Authorization: Payment) settles on-chain and answers sent with the settlement evidence. Nothing is queued, no provider spending key takes part, and the money lands at the payer the channel was opened from. Every in-flight draw on the credit must have finished first, which drain_conflict says explicitly. The payout figure is the provider's to derive from its own ledger rather than the payer's to choose: an x402 refund voucher naming an amount is refused outright, and the tempo close reconciles against chain state rather than against the request. Because the provider's claim job never claims past what the credit's settled draws have earned, the unspent remainder is still in escrow whenever the caller asks for it, including when the provider has stopped answering. That is exactly what the caller's own timed on-chain withdrawal reaches, with no cooperation at all.

A cooperative x402 refund can return a reconciliation error when the provider cannot establish a safe outcome. settlement_not_on_chain means a chain scan found no matching refund and the attempt is back in a safe retry state, so resend the same drain_id; chain_unreachable means the provider cannot read the chain, and settlement_unbookmarked means it has no submission checkpoint to scan. Neither of those says that the payment failed, so do not re-sign repeatedly or create a new drain while the operator restores or repairs the service. facilitator_channel_state_unavailable means the refund was found on chain but the provider could not confirm the matching channel state; keep the same drain_id and retry after the provider restores its settlement service.

A channel refund that reached the chain and hasn't finished settling on the provider's books holds the credit: new draws, further top-ups, and any other drain_id are refused settlement_pending (409) naming the settlement, while re-sending that drain's own id still goes through, which is how the reclaim completes. Every one of those refusals names that id in settlement_drain_id while the refund is genuinely unresolved, and the two drain refusals also keep drain_registered: true, so a caller who no longer holds it re-posts the named one rather than minting another into the same refusal. Once the provider has closed the refund out without paying it, draws and top-ups stay refused. The balance is reclaimable but not spendable, and that id is withheld, because a fresh drain_id is what reclaims from then on; settlement_status is what tells the two states apart. The top-up refusal lands before anything is charged, so a deposit is never taken against a channel in this state, and it reads for a funder: it says the deposit was refused and points at reclaiming the balance already there rather than at paying per call. The balance stays yours throughout. Spending pauses; ownership doesn't.

Re-stating a different method/payout under a recorded drain_id is refused with drain_conflict: the destination the money moved for is immutable. Use a fresh drain_id for the next reclaim.

When the provider signs receipts, every reclaim event (requested, parked, picked_up, sent, released) is countersigned into a DrainReceipt (kind: "credit_drain", signed by the attested receipt key) returned in the drain's receipts[]. Your signed drain request plus the provider's requested receipt form a portable IOU: an unfulfilled drain is provable from artifacts both sides already hold.

Credit failures are not a separate family: they use the same envelope and appear in the same code list as every other payment failure. See Payment errors.

Payment errors

Every payment failure (on POST /v1/job, on POST /v1/job/:id/messages, and on POST /v1/credit) answers with one flat body. There is no nesting and no per-rail shape: a caller parses the same five fields whichever rail it paid on and whichever endpoint refused it.

{
  "error": "payment_insufficient",
  "message": "expected 100000 msats, received 50000",
  "display": "The payment was less than the amount required, so it didn't cover the request. The full amount is still owed.",
  "hint": "Retry with a single payment of required_msats — a partial payment does not reduce what is owed.",
  "retryable": true,
  "required_msats": 100000,
  "received_msats": 50000
}
FieldTypeRequiredDescription
errorstringyesMachine code: the value to branch on. See Error codes
messagestringyesOperator-facing detail for logs. Its wording is not part of the contract
displaystringyesOne sentence to relay to a human verbatim
hintstringyesThe actionable next step, also for a human. May be situational
retryablebooleanyesWhether re-sending the same request could ever succeed

Code-specific fields are merged in after these and vary by code: required_msats / received_msats above, remaining_micro / shortfall_micro on a credit shortfall, fundable_micro on a top-up over the ceiling, expected_micro on a funding-amount mismatch. The five fields are always present.

display and hint are prose written for the human an agent is relaying to: no rail names the caller didn't choose, no protocol jargon. Relay them, don't branch on them: error and retryable are the machine surface, and a caller that pattern-matches on copy breaks when the copy improves. hint is situational by design: a sick-mint refusal names the mints that are healthy right now, and a short mid-job payment names the credit its money landed on.

retryable says whether the identical request could ever succeed, not that it should be re-sent immediately. insufficient_credit is retryable because topping up first makes the same draw work, not because an immediate retry would.

The 402 challenge

payment_required is the one 402 body that is not an error report. It is the challenge a provider answers an unpaid request with (nothing failed, the caller simply hasn't paid yet), so it deliberately carries no display, hint, or retryable, and it is not in the code list below.

{
  "error": "payment_required",
  "required_msats": 100000,
  "price_micro": 100000,
  "price_currency": "usd",
  "mints": ["https://mint.example"]
}

required_msats is the canonical settlement number. mints is present when the provider takes Cashu. A provider offering prepaid credit also attaches the funding menu, so one round trip tells a caller both what this job costs and that it could prepay instead.

On a request that needs no signature, a provider that takes P2PK-locked Cashu also sets an X-Cashu response header on this 402: a NUT-18 creqA payment request with a set to required_msats / 1000 rounded up, u set to "sat", m set to the cashu.mints list, and nut10 set to { kind: "P2PK", data: cashu.lock_pubkeys[0], tags: [] }. From SDK 0.33.0, a provider can opt in to a refund_delay tag, and tags is then [["refund_delay", "<seconds>"]]. The value is the lock floor that payment is held to, plus the 600-second exchange-rate hold described under Paying without a request id. The floor is cashu.unsigned_min_locktime for a request without X-Cashu-Request-Id, and cashu.min_locktime less 24 hours for one that sends it. It is how long the provider needs before the payer's refund path may open, so a wallet that reads it can set its locktime at least that far ahead. The wallet may also copy the tag into the proof secret. A provider that has not opted in sends tags: []. a is what the provider must receive after the mint's NUT-02 input fee, so the wallet adds that fee on top; at a mint with no input fee the two are equal. The request names no id, transport, or locktime, so payment is in-band on the retry. No other response carries X-Cashu: not a refused payment, not a 409, not POST /v1/credit, and not a signed request's 402, which still pays with X-Cashu-Request-Id. An unsigned request to a provider that also accepts signed ones is offered Cashu, plus x402 accepts on a capability that takes unsigned x402 (see None), with no Tempo challenge and no funding menu.

price_micro is the same job's price in 1e-6 units of price_currency: the provider's exact integer, resolved against the same fx snapshot as required_msats beside it. It is what a draw values its funding payment against, so both inputs to that derivation come off this one envelope and first contact needs no /v1/quote hop. Both fields are absent on a free job and on providers that predate them.

Two rails extend the challenge rather than replacing it, and x402 does so two different ways depending on which generation the caller speaks. x402 v1 (legacy) merges x402Version and accepts straight into the JSON body shown above, but only while v1 exact is being served alongside it. x402 v2 (the default generation; /v1/info#x402.dual_serve serves both at once) carries the same information in a PAYMENT-REQUIRED response header instead, an encoded { x402Version, accepts, resource, extensions, error? } envelope. Writing that header never touches the JSON body: a v2-only facilitator, or a batch-settlement-only 402 such as a /v1/credit refund challenge, carries no x402Version/accepts fields in the body at all. Pay a v2 challenge by signing PAYMENT-SIGNATURE on the retry; a v1 challenge signs X-PAYMENT. Tempo adds one WWW-Authenticate: Payment <challenge> header per advertised method. Every extension also sets Cache-Control: no-store.

Error codes

CodeStatusRetryableMeaning
payment_invalid402noPayment present but unusable: unverifiable, or a top-up on a rail the credit wasn't funded on
payment_insufficient402yesPaid less than required_msats. The retry owes the full amount, never the difference
payment_unapplied500yesPayment verified and held as prepaid balance, but a provider fault stopped it being applied to the job
x402_not_offered400/402/503varies402 for non-USD pricing; 503 when the x402 route has no rail or cannot take payment; 400 when the request prices at zero. Use an advertised payment method or, for a free request, /v1/job where offered. retryable is false for non-USD pricing and an unconfigured rail, and omitted on the other branches
cashu_unavailable402noProvider can't accept Cashu right now: misconfiguration, not a caller problem
cashu_not_p2pk_locked402noProvider requires P2PK-locked tokens and the request carried an unlocked one
invalid_token402noToken was malformed or from an unsupported mint
not_p2pk_locked402noToken was unlocked, or its lock had already expired
wrong_lock_pubkey402noToken locked to a key this provider doesn't hold: re-read cashu.lock_pubkeys from /v1/info
lock_not_exclusive402noLock isn't in the canonical shape that only this provider's keys can spend for cashu.min_locktime (or cashu.unsigned_min_locktime on the unsigned path), or its secret is longer than 1,024 characters, the most a Nutshell mint redeems by default: hint states the accepted lock. One single-valued refund_delay tag in the secret is accepted and ignored; one that repeats, or that does not carry exactly one value, is refused
proof_not_unspent402noProofs were already spent at the mint
proof_pending402yesProofs are still settling at the mint
missing_request_id402noThe accumulator path requires an X-Cashu-Request-Id header on a signed request, or on any request to a provider without NUT-24 payment requests
missing_lock_pubkey402noProvider has no lock key wired: misconfiguration, not a caller problem
replay_rejected409noThese proofs already landed under this request id. Don't re-send: the money is not lost
request_id_reused409noThis X-Cashu-Request-Id already belongs to other proofs. Nothing was charged: send these proofs under a new id
reserved_request_id400noIds starting nut24- are derived for payments sent without a request id. Send a fresh UUIDv4
payment_method_requires_signature402noAn unsigned request carried a Tempo payment, or an x402 payment for a capability with no runtime bound. Nothing settled: pay with Cashu or sign the request
mint_unreachable402yesThe mint didn't respond, or returned an invalid response
mint_health_pending503yesProvider just started and is still validating its mints
cashu_mint_sick503yesThe token's mint is unhealthy. hint names the mints that are currently healthy
insufficient_credit402yesDraw exceeds spendable balance. Carries remaining_micro, balance_micro, shortfall_micro
credit_expired402yesPast TTL; refuses new draws. The balance is preserved and stays drainable
credit_unbacked409noThis credit's Tempo channel finalized before the service could collect the value it had accepted. No drawable or reclaimable balance remains: don't retry, top up, or drain it
credit_not_found402/404yesNo such credit for this caller
tempo_channel_closing409noThe Tempo channel for this credit has started closing; it cannot accept a new job
credit_not_supported501noThis provider doesn't offer credit: pay per call
one_shot_credit_not_supported409noThis provider takes prepaid credit on a reusable stablecoin channel only. Nothing moved: fund a channel, or pay per call with the one-payment method
credit_below_min400yesTop-up under min_micro
below_rail_minimum400noUnder this rail's own floor. Carries rail, min_micro, alternatives: resize or switch rail
credit_over_max400yesTop-up would push the residual over max_micro. Carries fundable_micro
credit_id_unavailable400/402/409yesNot available to this caller: a reserved namespace, or an id someone else holds
draw_conflict409nodraw_id reused for a different request
funding_commitment_mismatch402noArtifact doesn't hash to fund.commitment, or its value isn't fund.amount_micro
lightning_settlement_pending402yesAn invoice is outstanding for this fund_id. Pay it and re-send the same request
lightning_invoice_expired402noThe invoice expired unpaid. Nothing was charged: start over with a fresh fund_id
lightning_unavailable503yesProvider can't issue an invoice right now. Carries the funding rails that still work
nothing_to_drain409yesNo spendable balance to reclaim (zero, or fully held by in-flight jobs)
drain_below_dust409noReal balance remains, but at the rate it was funded it is worth no more than it costs to send back, so there is nothing payable. The balance is untouched: a top-up makes the whole amount reclaimable, and it stays spendable either way
drain_not_found404yesPolled a drain_id this credit has never seen
drain_method_unsupported400noNot a payout rail this provider reclaims over. Carries supported_methods: reclaim as ecash with cashu, or on a channel-funded credit its own rail
drain_conflict409variesThe refund was refused, and which refusal it is decides whether to retry: the response's own retryable is authoritative. It clears on its own when another job on the credit is still running, or when the balance moved while the refund was settling (nothing was recorded, so retry with a fresh drain_id once the jobs finish). It never clears when the drain_id was reused with a different method or payout: recorded destinations are immutable. It also never clears when a cooperative channel refund reached the chain and paid less than the balance being reclaimed: that money arrived, nothing was booked here, and only the provider's operator can reconcile the difference. Keep the drain_id (drain_registered is true) and report it to them, since a fresh one lands on the same refusal
tempo_channel_exit_required409noThe Tempo channel cannot close cooperatively; use its on-chain exit instead
x402_settlement_ambiguous503yesThe stablecoin authorization may already have settled, but the service has not yet recovered the exact chain result. Retry the same request with the same signed payment; do not sign or pay again
x402_settlement_submission_failed503yesSubmitting the channel deposit to the chain failed, so the outcome is unknown. Resend the same signed request with the original PAYMENT-SIGNATURE; a provider on SDK 0.42.0 or later can recover a deposit that landed instead of submitting it again.
settlement_not_on_chain402 or 503yesOn a drain (402), no matching x402 refund was found on chain and the balance remains in the channel; retry the same drain_id. On a channel deposit (503), the provider confirmed the deposit did not land and prepared it for another attempt; resend the same signed request
chain_unreachable402yesThe service cannot read the chain to determine whether the x402 refund moved. Keep the same drain_id
settlement_unbookmarked402noThe x402 refund has no chain checkpoint, so its outcome cannot be checked safely. Contact the operator
facilitator_channel_state_unavailable402yesThe x402 refund is on chain, but the service cannot confirm the matching channel state. Keep the same drain_id
settlement_pending409noAn earlier channel refund on this credit hasn't finished settling, so the balance can be reclaimed but neither spent nor topped up. Carries settlement_id and settlement_status, plus settlement_drain_id: the one drain_id still admitted, absent once the refund has been closed out and only a fresh one reclaims
credit_funding_unrecorded500noThe payment settled but the provider recorded no balance. Don't retry: contact the operator

funding_commitment_mismatch is retryable: no on both its branches, and that stays true of the Cashu corrected re-sign described under Drawing against a credit: the retry that lands carries a different fund.amount_micro, so it isn't the same request. Its amount branch carries expected_micro; its commitment branch carries nothing, which is how a caller tells the two apart without reading message.

A Tempo charge whose broadcast is not confirmed. The provider broadcasts the signed transaction a Tempo charge credential carries. If that call fails after the transaction went out, the provider reads the chain for up to five seconds and accepts a transfer it finds there as an ordinary payment. Otherwise it answers 402 payment_invalid with rail: "tempo", a reason and a fresh challenge. Branch on reason before reading the challenge. not_broadcast comes with retryable: true: the node reported the transaction neither mined nor pooled, so resend the same request with the same credential. Don't build a new payment, because the signed transaction is still valid and a second one could settle beside it. settlement_unconfirmed comes with retryable: false: the chain gave no verdict in time, the transfer may still land, and the provider refuses the credential if it comes back. Don't pay again; the provider's operator reconciles it. A provider without a durable charge replay store answers settlement_unconfirmed in both cases. Mid-job Tempo payments answer the same way. A transaction the chain shows as reverted, or as paying a different recipient, amount, token or challenge, keeps the plain payment_invalid with no reason. This holds from SDK 0.44.1; an older provider answers a failed broadcast with a plain payment_invalid and books nothing, even when the transfer landed.

Every code above credit_funding_unrecorded belongs to the provider SDK's PaymentErrorCode union, and every member of that union appears in the table. The union is exhaustive by construction: a new code can't ship without its display / hint / retryable copy. credit_funding_unrecorded is raised outside that union and supplies the four fields by hand, so it's the one code whose copy no compiler guards.

HTTPS transport

Endpoints

MethodPathPurpose
GET/healthHealth check (no auth required)
GET/v1/infoProvider metadata
POST/v1/quotePrice quote for a job
POST/v1/jobSubmit a job
POST/v1/request-result/:request-idRead one authenticated request result
POST/v1/request-resume/:request-idMaterialize one committed acceptance
GET/v1/job/:idJob status
GET/v1/job/:id/messagesMessages (SSE stream or JSON snapshot)
POST/v1/job/:id/messagesCaller sends a message
DELETE/v1/job/:idCancel a job
POST/v1/creditPrepaid credit: top up, check balance, drain
POST/v1/x402/:capabilityOne-request x402 payment for a capability

GET /v1/info

Returns provider metadata. A DVM runs on one of two compute tiers: container, the builder's own Dockerfile-based SDK server deployed as a standalone machine, or isolate, a handler-only deploy with no Dockerfile that runs inside dvmkit's shared platform runtime. /v1/info differs by tier in a few fields, marked below.

{
  "name": "Web Extract DVM",
  "description": "Extracts clean markdown from web pages",
  "tags": ["web", "extraction"],
  "auth": ["secp256k1-schnorr-v2"],
  "auth_audience": { "dvm_id": "web-extract", "builder_pubkey": "3f9c…" },
  "protocol_version": 1,
  "sdk_sha": "9f2c1ab4d0e7",
  "receipts": true,
  "request_recovery": true,
  "credit": {
    "min_micro": 100000,
    "max_micro": 5000000,
    "ttl_ms": 7776000000,
    "currency": "usd",
    "funding": ["cashu", "x402"]
  },
  "owner": { "handle": "acme", "display_name": "Acme Labs", "avatar_url": null, "type": "org" },
  "builder": {
    "pubkey": "3f9c…",
    "attestation": { "dvm_id": "web-extract", "deployed_at": 1790000000 },
    "signature": "a41b…"
  },
  "mints": ["https://mint.example"],
  "payment": { "methods": ["cashu", "x402"] },
  "capabilities": {
    "extract": {
      "description": "Extract clean markdown from one URL",
      "input_schema": {
        "type": "object",
        "properties": { "url": { "type": "string" } },
        "required": ["url"]
      },
      "example": { "url": "https://example.com" },
      "pricing": { "max": { "amount": 0.05, "currency": "usd" } }
    }
  },
  "x402": { "pay_to": "0xab…", "network": "base", "asset": "USDC", "dual_serve": true },
  "cashu": {
    "mints": ["https://mint.example"],
    "lock_pubkeys": ["02c4…"],
    "lock_pubkey_grace_seconds": 3600,
    "min_locktime": 604800,
    "canonical_id": "web-extract"
  }
}
FieldTypeRequiredDescription
namestringyesDisplay name
tagsstring[]yesFreeform tags describing capabilities
authstring[]yesAdvertised auth schemes: "secp256k1-schnorr-v2", "none", or both. See Authentication
auth_audienceobjectno{ dvm_id, builder_pubkey } target for v2 caller proofs; both values match the attested builder block
protocol_versionnumberyesProtocol version (currently 1)
sdk_shastringyesGit SHA the deployed image was built from; "unknown" when unavailable
descriptionstringnoHuman-readable description. Omitted when empty
ownerobjectno{ handle, display_name, avatar_url, type } — who operates this provider
builderobjectno{ pubkey, attestation, signature } — builder identity attestation. Omitted when unsigned
receiptsbooleannotrue when the provider signs a receipt for every terminal job. Omitted — never false — otherwise
request_recoverybooleannotrue when authenticated request-id result and guarded resume routes are durably backed
creditobjectnoPublic prepaid-credit terms: { min_micro, max_micro, ttl_ms, currency, funding, tempo?, x402?, lightning_min_micro? }. Container tier only; never carries a caller ID or balance
mintsstring[]noCashu mint URLs accepted
paymentobjectno{ methods } — rails accepted, from "cashu", "x402", "tempo". Emitted by both tiers
capabilitiesobjectnoPer-capability advertisement, keyed by capability name (see below)
x402_capabilitiesobjectnoCapabilities offered on the x402 channel, keyed by name, each with its route url (see below). Container tier only
pricingobjectno{ max: { amount, currency } } — fiat ceiling. Isolate tier only
input_schemaobjectnoMirror of the sole capability's input schema. Isolate tier only, single-capability
quoteobjectno{ schema } — mirror of the sole capability's quote schema. Isolate tier only, single-capability
x402objectno{ pay_to, network, asset, facilitator?, dual_serve }. Container tier only
tempoobjectno{ methods: [{ method, intent }], chain_id, withheld?, realm }. chain_id is the positive integer chain every advertised Tempo challenge uses. Container tier only
cashuobjectno{ mints, lock_pubkeys, lock_pubkey_grace_seconds, min_locktime, unsigned_min_locktime?, canonical_id }. min_locktime is the shortest refund lock, in seconds, a payer should use; the provider enforces it less 24 hours. unsigned_min_locktime, present when the provider sets a cashu block and accepts unsigned paid calls, is the floor for an unsigned POST /v1/job paid without X-Cashu-Request-Id, enforced exactly. Container tier only

When receipts: true, builder.attestation.dvm_id is the provider's immutable trust identity. Every signed job receipt and credit-drain receipt carries the same required dvm_id; its dvm field remains signed display metadata, not an identity. A verifier must reject a receipt whose ID differs from the attestation before accepting its receipt key.

Each entry under capabilities describes one capability:

FieldTypeRequiredDescription
descriptionstringnoHuman-readable summary of what this capability does
input_schemaobjectnoJSON Schema for the capability's job input
exampleobjectnoA runnable example input, preferred by callers over schema-derived placeholders
pricingobjectno{ max: { amount, currency }, rates? } when statically priced, { quote: { schema }, rates? } when dynamic

Where the price lives depends on the tier. A container-tier provider advertises its fiat ceiling per capability at capabilities.<name>.pricing.max and never emits a top-level pricing. The isolate tier emits top-level pricing.max instead, and for a single-capability provider also mirrors that capability's input_schema and quote schema to the top level. A caller should read capabilities first and fall back to the top-level fields — in practice that fallback is where an isolate-tier reader lands for a statically-priced capability, since the isolate tier's own capabilities entries carry a quote schema but essentially never a pricing.max of their own.

Whichever tier serves it, max is the advertised ceiling, not a promise about a given input: a dynamic-priced capability omits max, carries pricing.quote.schema instead, and lets /v1/quote answer with the real upfront per input. A free capability omits pricing entirely.

Container tier only. Either pricing form may also carry rates, the capability's rate card: 1 to 5 entries of { label?, amount, currency, per }, where amount is a decimal USD string and currency is "USD". Providers publish the declared array unchanged, in order. The rates are descriptive: for a dynamic-priced capability they explain how the quote is computed, and /v1/quote remains the price. The limits are in Rate cards.

x402 capabilities. x402_capabilities lists the capabilities offered on the x402 channel, keyed by published name. It sits apart from capabilities, which holds only the /v1/job definitions, because one name may be a different definition on each channel. Each entry has the capabilities entry shape, with the route's flat body schema as input_schema, plus url: the route's address, including any path prefix the provider is mounted under. The key is absent when no capability is offered on x402. A provider that offers every capability on x402 alone lists no capabilities.

POST /v1/quote

Request body: { "input": "https://example.com" }

{
  "upfront": { "amount": 0.05, "amount_micro": 50000, "currency": "usd" },
  "description": "scrape https://example.com — $0.005 base + worst-case $0.009 size + worst-case $0.034 extract",
  "shape": "fixed",
  "mints": ["https://mint.example"]
}

The fiat-first envelope (DVM-250):

  • upfront — the protocol-enforced fiat commitment the caller commits to before submitting the job. The SDK derives sats from this and a snapshot fx rate at settlement time. amount is the rendered decimal; amount_micro is the same price as an exact integer in 1e-6 units of currency, and it is the provider's own ledger figure rather than a restatement of the decimal. Prefer it wherever the exact price matters — a provider that renders amount at a coarser precision than it charges at (four decimals is common) cannot be reproduced from the decimal at all. It is absent on a free quote and on providers that predate it.
  • description — prose explanation of what the upfront buys and how pricing works. LLM agents read this directly.
  • hint (optional) — follow-up prose (e.g. "After the transcription completes, you'll be charged the per-minute rate × actual minutes.").
  • shape (optional) — "fixed" for fully-known prices, "rate" for metered.
  • rate (optional, when shape === "rate") — { per_unit: { amount, currency }, unit, max_units? }.

Sats binding happens at the /v1/job 402 handshake — required_msats in the 402 envelope is the canonical settlement number; the upfront figure on /v1/quote is indicative within the 5-minute cache window.

An input the capability's schema rejects comes back 400 invalid_input here, the same answer POST /v1/job gives the same body — so a caller can correct against the quote and know the submit will get past the same gate. See Signed requests. A body carrying no input at all is a price probe rather than a violation, and still quotes: reading what a capability costs must not require having assembled a request for it yet. POST /v1/job refuses that body, since a submit with nothing to run is a mistake.

Providers that offer prepaid credit also return a credit block here. Unlike /v1/info, a signed quote may append the caller's credit ID and balance echo. See Prepaid credit.

POST /v1/job

Submit a job for processing.

Request body:

{
  "input": "https://example.com",
  "params": { "format": "markdown" }
}

Payment (if required): attach X-Cashu: <token> header.

Response codes:

  • 200 — job completed inline. Unsigned NUT-24 paid submits use the configurable wait described under Paying without a request id. Other submits wait one tick after the handler starts, and if the job went terminal in that tick, a further bounded wait for the receipt to finish signing. Whatever the job's status is once that resolves is what decides the code. { "job_id": "...", "summary": "...", "receipt": { ... } } when the DVM signs receipts — see Job receipts
  • 202 — job accepted for async processing: { "job_id": "..." }
  • 402 — payment required, invalid, or insufficient. An unpaid request gets the 402 challenge; a payment that fails verification gets a payment error
  • 400: a payment sent without X-Cashu-Request-Id that the payer can fix, or a reserved request id: see Paying without a request id
  • 409 — the payment or the idempotency key was already used for a different request: replay_rejected, draw_conflict, request_id_reused
  • 503 — the provider can't verify payments right now: mint_health_pending, cashu_mint_sick

The 200 and the 202 also carry the job ID in the DVM-Job-Identity-V1 response header.

Overpayment is kept, not returned — nothing comes back on the response. On an unsigned request the whole amount presented is drawn against the job, so a caller who overpays is charged what they sent. On a signed request carrying a credit envelope only the quoted price is drawn and the excess stays as available balance, spendable on later jobs or reclaimable with drain. Either way, send the quoted price.

A 402 from a credit-offering provider also carries the credit funding menu, so a caller learns at the same moment that it could prepay instead. Signed bodies may additionally carry credit_id / draw_id / fund / mandate to pay from a standing balance — see Prepaid credit.

Job identity field

A provider states the job ID of each successful submission in a response header, DVM-Job-Identity-V1. Its value is the bare job ID, the same string as the body's top-level job_id. A router in front of the provider learns the job ID from this header, without reading the body.

The header belongs on every 200 or 202 response to these four requests:

  • POST /v1/job
  • POST /v1/request-resume/:request-id
  • POST /v1/request-result/:request-id
  • POST /v1/x402/:capability

On POST /v1/x402/:capability it is also on every answer that names a job: the 500, both 503 rows and both 402 rows of its response table. It is never on that route's 400, 404 or 429. Send it on no other status and no other endpoint. It goes in the response head. An HTTP trailer with the same name never counts as job identity.

HTTP/1.1 202 Accepted
Content-Type: application/json
DVM-Job-Identity-V1: job-3f9a1c2b-7

{ "job_id": "job-3f9a1c2b-7", "status": "processing" }

The value must match ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$. That is 1 to 128 ASCII letters, digits, dots, underscores, colons, and hyphens, starting with a letter or digit. It must equal the body's job_id byte for byte, with no added whitespace and no change of case. A reader treats the header as invalid when:

  • it appears more than once, even if the copies are equal;
  • it is empty;
  • it is longer than 128 bytes;
  • it contains any other character, including whitespace.

A provider whose job IDs fall outside this grammar cannot send the header.

A router mints its feedback claim and records its acceptance witness only from a valid DVM-Job-Identity-V1 on a 200 or 202 whose Content-Type is application/json or another +json type. The feedback claim is a signed token the router adds to the response so the caller can later leave verified feedback on that job. The acceptance witness is the router's record that the provider accepted the job, which counts toward the provider's delivery record. A routed job without a valid header gets neither, and the caller still gets the provider's response. A hosting route that funds the provider's runtime from a prepaid balance adds stricter rules, set out in Funded hosting routes.

The router forwards the header to the caller unchanged, including an invalid value. It never writes one of its own.

The header is the provider's own statement. It does not prove:

  • who the caller is. Caller identity comes from the signed request;
  • that the header equals the body. A router that takes the job ID from the header does not read the body to check;
  • that the caller received the body, or any part of it;
  • that the job exists, ran, completed, or was paid for.

Funded hosting routes

A hosting route can fund the provider's runtime from a prepaid balance. On such a route the router ties every paid job to the request that paid for it, so it holds both sides to stricter rules:

  • The route opens only after the provider's runtime reports that it sends DVM-Job-Identity-V1.
  • A paid submit must be a signed JSON request with a request_id in its signed data. That gives every paid job a recovery route through POST /v1/request-result/:request-id. A submit that draws on a prepaid credit may leave request_id out.
  • If the provider answers a submit or a recovery request with 200 or 202 but no valid header, the router forwards that answer to the caller unchanged and records no acceptance. It then answers new paid submits to that provider with 503 hosting_identity_unproven. A request the provider already accepted can still be recovered.
  • If the provider names a different job for a request it already accepted, the router refuses that answer with 409 hosting_job_identity_conflict.

These errors come from the router, not the provider, and use a nested envelope. error is an object carrying code, message, display, and hint, instead of the flat string a provider's payment errors use. Branch on code, and relay display and hint to the human.

StatuscodeWhenWhat to do
400hosting_request_id_requiredA paid submit is unsigned, is not JSON, or has no request_id in its signed data. Refused before any payment is taken or anything is forwardedSign the request with a request_id and send it again
409hosting_job_identity_conflictThe provider named a different job for a request it had already accepted. The error also carries accepted_job_id, and request_id when the request had oneDo not pay again. Recover the accepted job with POST /v1/request-result/:request-id
503hosting_identity_unprovenThe provider has not proven that it sends a valid DVM-Job-Identity-V1. Refused before any payment is taken or anything is forwardedTry another DVM, or try again later. Recovery of an accepted request still works
{
  "error": {
    "code": "hosting_job_identity_conflict",
    "message": "The provider returned a different job for a request it had already accepted",
    "display": "This request was already accepted as job job-abc-1. The service then answered with a different job, so that answer was refused.",
    "hint": "Do not pay again. Run `dvm request-result agent-run-018f` to recover job job-abc-1.",
    "accepted_job_id": "job-abc-1",
    "request_id": "agent-run-018f"
  }
}

POST /v1/x402/:capability

A capability the provider offers on the x402 channel is served to stock x402 clients at POST /v1/x402/<capability>. One unsigned HTTP request pays for the job and returns its result, with no /v1/quote call and no job polling in the usual case. GET /v1/info lists these capabilities under x402_capabilities. A name not offered on the channel answers 404 unknown_capability, and POST /v1/job answers the same for a name offered only on x402.

The request. The body is the capability's input as flat JSON, with no { capability, data } envelope. The route takes unsigned callers only and needs no auth scheme: a body carrying pubkey, signature, timestamp, nonce or auth_statement answers 400 signed_fields_not_accepted. Only x402 pays here, with PAYMENT-SIGNATURE (v2) or X-PAYMENT (v1, where the facilitator serves it). X-Cashu or Authorization: Payment answers 400 payment_method_not_accepted, with a hint pointing to /v1/job. A paid request whose body fails the input schema answers 400 before the payment is verified.

The unpaid request. An unpaid request gets HTTP 402 with a PAYMENT-REQUIRED header quoted from its body. The challenge's resource is the provider's public origin, then any path prefix the provider is mounted under, then /v1/x402/<capability>. It never echoes the request's query string or path spelling. A capability with a catalog listing quotes an empty or invalid unpaid body (a discovery validator sends {}) from the listing's example and runs nothing; its v2 header also carries the listing's description and an extensions.bazaar entry. Without a listing, such a body answers 400.

One deadline. A paid request is answered once, within one budget measured from its arrival: the capability's runtime bound (maxRuntimeSeconds) for verifying the authorization and running the job, then the facilitator timeout (10 seconds by default) for settling it. The authorization is verified before the job and settled only if the job succeeds, so a failed or timed-out job is not charged. A gateway that stops waiting for response headers before this deadline answers 504 while the job may still settle, so a provider behind a gateway keeps the sum under the gateway's wait. The answers are:

CaseStatusBodyHeaders
Completed and settled200status: "completed", charge_outcome: "charged", job_id, job_token, payload_in ("summary" or "messages", naming where the result is), and messages when the serialised array is at most 1,048,576 bytes; a larger result omits messages, so read it from GET /v1/job/:id/messagesPAYMENT-RESPONSE and X-PAYMENT-RESPONSE, naming the transaction and network
Job failed500status: "failed", charge_outcome: "not_charged", job_id, reason, display, hint; no job_token and no messagesnone; nothing settled
Runtime bound reached503the samenone; nothing settled
Completed with no time left to settle503the same, with a display saying the work finished and the result was withheldnone; nothing settled
Settlement refused402error: "x402_settlement_refused", charge_outcome: "not_charged", job_id, display, hint; no job_token, messages or summaryPAYMENT-RESPONSE and X-PAYMENT-RESPONSE with success: false
Authorization lost402error: "authorization_unavailable", the same fieldsPAYMENT-RESPONSE and X-PAYMENT-RESPONSE with success: false and errorReason: "authorization_unavailable"
Outcome unknown at the deadline202status: "processing", content_available: false, content_withheld: "payment_pending", charge_outcome: "unknown", job_id, job_token, a hint not to pay again; no messages or summaryRetry-After

A caller that gets 202 must not pay again. After Retry-After it polls GET /v1/job/:id with the X-Job-Token header until the job is terminal; each read retries the settlement. That read never carries messages. A completed job's result is in summary, or, when payload_in is "messages", at GET /v1/job/:id/messages with the same header. A job whose payment never settles reads failed. 502 and 504 come only from gateways. A wallet that already has a job running gets 429 x402_payer_busy with Retry-After. An authorization whose validBefore would lapse before the runtime bound is refused with 402 payment_authorization_too_short before the facilitator is called, and an authorization presented a second time answers 409 replay_rejected without running or settling again. Every response that names a job carries the DVM-Job-Identity-V1 header, beside the headers in the table.

Client timeouts. Nothing is sent until the job has finished and settled, so the caller's HTTP client must wait that long. Python's httpx, and the x402 httpx client built on it, give up after 5 seconds with no data by default. A caller that hangs up early is still charged when the job settles, and never receives the job_token that would let it read the result. Against a DVM hosted by dvmkit, wait at least 60 seconds: the router can spend up to 11 seconds waking a stopped machine and dialling it before the job starts, and it answers within 55 seconds of the request's arrival, because Fly's proxy closes a connection that carries no bytes for 60 seconds. Against a server you host yourself, wait at least its own bound: the capability's maxRuntimeSeconds plus the facilitator timeout, plus whatever your gateway adds. Fetch, axios, Go's net/http, and requests have no shorter default. Work that takes longer than a hosted DVM allows belongs on POST /v1/job.

Public request recovery

A provider advertising request_recovery: true accepts an optional request_id inside the signed data object on POST /v1/job. It is a protocol field rather than capability input, so the server verifies it as part of the caller's Schnorr-signed bytes and then strips it before capability-schema parsing. A public id is 1–128 characters from letters, digits, dot, underscore, colon, and hyphen.

Before pricing, payment verification, a credit draw, or handler execution, the provider atomically binds (caller pubkey, request_id) to the full request fingerprint, resolved requester identity, and a stable preallocated job id. That pair is unique in durable storage and a live database lock serializes the complete paid-accept path across server processes. A concurrent request cannot reach a payment verifier or handler. A different caller, body fingerprint, or requester identity cannot adopt the binding.

An unpaid 402 discovery response releases the live lock but retains the durable binding and stable job id. The exact caller and body may then submit the original payment once; a mismatch or concurrent holder receives 409 request_id_exists. If a payment or draw commits before the job row can be saved, its acceptance draw is linked to that stable job id so guarded recovery can finish the original job without consuming money again.

POST /v1/request-result/:request-id is strictly read-only. Its JSON body is the original POST /v1/job body with the same request_id and a fresh signed-request envelope. The URL id, signed id, caller pubkey, resolved requester identity, capability, and complete request fingerprint must all match the saved job. A missing record or any mismatch returns the same 404 request_not_found body with status: "unknown"; absence is never converted into failure and never creates a replacement.

An exact result returns 200 for a terminal job or 202 for a non-terminal job. Both carry the DVM-Job-Identity-V1 response header:

{
  "request_id": "agent-run-018f",
  "job_id": "job-abc-1",
  "status": "completed",
  "transaction_hash": "0x8e5a…",
  "summary": "Done",
  "receipt": { "v": 1, "job_id": "job-abc-1", "outcome": "completed", "signature": "…" }
}

job_token is optional and may be returned only after the same caller and fingerprint checks. Clients must validate the echoed request_id, a non-empty job_id, one of processing, awaiting-input, completed, failed, or cancelled, the 200/202 status pairing, and the shape and job binding of every optional transaction hash, token, artifact field, and receipt before persisting caller state. A malformed response leaves the outcome unknown.

POST /v1/request-resume/:request-id is the only public mutating repair. It takes the same fresh signed body but no payment, wallet, bearer, or chain credential. The provider may acquire only an existing exact request binding; it may create and run the job only from the sole still-pending acceptance draw already linked to that binding's stable job id. The route does not read current pricing, invoke dynamic quoting, settle Lightning, verify payment, debit credit, or enter a handler unless that committed draw exists. A later price change, including a change to free, cannot authorize work.

No existing exact binding or no committed acceptance draw returns 409 without mutation:

{
  "error": "request_not_accepted",
  "request_id": "agent-run-018f",
  "server_acceptance": "absent",
  "payment_state": "unknown"
}

This generic route does not replace Cashu's proof-bearing pending-submission replay. If an initial paid POST never reached the provider, direct x402 and Tempo authorizations are not reconstructed or replaced by request resume, and Cashu proof recovery stays in its separate caller wallet journal. If the server already saved or completed the job, clients should stop at request-result; calling resume is unnecessary and must not repeat work.

GET /v1/job/:id

Job status check.

{
  "job_id": "job-abc-1",
  "status": "completed",
  "summary": "...",
  "receipt": { "v": 1, "job_id": "job-abc-1", "outcome": "completed", "seq": 482, "receipt_pubkey": "8a1b…", "signature": "c92e…" }
}

Status values: "processing", "completed", "failed", "awaiting-input", "cancelled", "working". receipt rides this response too, on the same terms as the POST /v1/job 200 — see Job receipts.

Job receipts

When a provider signs receipts (/v1/info#receipts is true), every job that reaches a terminal status carries a receipt block: on the synchronous POST /v1/job 200 and on every later GET /v1/job/:id. It is signed once, at the terminal transition, by the per-DVM receipt key — the same bytes are served on every read, never recomputed.

{
  "v": 1,
  "job_id": "job-abc-1",
  "dvm_id": "web-extract",
  "dvm": "web-extract",
  "capability": "extract",
  "outcome": "completed",
  "reason": null,
  "seq": 482,
  "issued_at": 1790000000,
  "requester_pubkey": "3f9c…",
  "paid": {
    "msats": 50000,
    "rail": "cashu",
    "native_amount": 50000,
    "native_asset": "sat",
    "tx_hash": "…",
    "mint": "https://mint.example"
  },
  "result_hash": "…",
  "receipt_pubkey": "8a1b…",
  "signature": "c92e…"
}
FieldTypeDescription
vnumberReceipt schema version. Currently always 1
job_idstringThe job this receipt attests
dvm_idstringImmutable DVM identity bound into the /v1/info#builder attestation — the trust anchor
dvmstringDVM slug, as bound in the same attestation. Signed display metadata, not identity
capabilitystringCapability the job dispatched to
outcomestringTerminal outcome: completed, failed, or cancelled
reasonstring | nullTerminal reason on failed/cancelled (e.g. worker_died_mid_job). null on success
seqnumberPer-DVM monotonic terminal counter. A gap exposes receipt suppression
issued_atnumberUnix seconds when the receipt was signed
requester_pubkeystring | nullCaller's x-only pubkey when signed-request auth was used; null otherwise
paidobjectWhat the caller paid — msats, rail, native_amount, native_asset, tx_hash, mint. Every other field is null where it doesn't apply
result_hashstring | nullHash over the delivered result; null when nothing was delivered
receipt_pubkeystringx-only secp256k1 pubkey that signed this receipt (64 hex chars)
signaturestringBIP-340 Schnorr signature over the canonical receipt minus signature (128 hex chars)
creditobjectOptional. Credit-draw countersignature, present when the job's payment funded/drew the credit ledger: { credit_id, draw_id, amount, balance_after, ledger_seq }

New receipts include optional signed timing: { accepted_at_ms, terminal_at_ms, caller_wait_ms }: acceptance and terminal timestamps are Unix milliseconds, and caller wait is the accumulated time awaiting input, including payment. Time spent awaiting the caller is excluded when computing provider processing time. Legacy receipts may omit timing; missing values are not reconstructed.

Failed and cancelled receipts also include optional signed ended_by: "caller" | "provider". Caller cancellation or a timeout while awaiting input is attributed to the caller. Handler failures, processing timeouts and other unsuccessful provider endings are attributed to the provider. Completed receipts omit ended_by. These fields retain receipt version 1; verification includes every field that is present.

Verify dvm_id against the attestation before trusting receipt_pubkey — dvm is signed display metadata, not identity, so a rename doesn't change which key a receipt has to chain to. Credit-drain reclaims are countersigned the same way, into a separate DrainReceipt under the same receipt key — see the drain op under Prepaid credit above.

GET /v1/job/:id/messages

Two modes based on the Accept header:

SSE streaming (Accept: text/event-stream). Opens a persistent connection. Sends existing messages from the backlog first (those with seq > after parameter), then pushes new messages in real time. The stream closes when the provider sends a yield message.

GET /v1/job/job-abc-1/messages?after=0 HTTP/1.1
Accept: text/event-stream

event: message
data: {"seq":1,"from":"provider","type":"text","content":{"text":"Working..."}}

event: message
data: {"seq":2,"from":"provider","type":"complete","content":{"summary":"Done"}}

JSON snapshot (default). Returns all messages after the cursor and closes immediately. Use for non-blocking check-ins after a working yield.

{ "messages": [{ "seq": 3, "type": "text", "content": { "text": "Still working..." } }] }

Pages. From SDK 0.42.0, a JSON read can add limit, an integer from 1 through 50, to bound how many messages one response carries: GET /v1/job/:id/messages?after=0&limit=50. The paged response adds next_after, the last sequence delivered (or the input cursor on an empty page), and has_more. Pass next_after as the next request's after. A running job can publish more after has_more is false, so keep the cursor to resume polling. A large artifact can still make one page large. An invalid limit or after returns 400 invalid_query. Without limit, the response is the full history after after with no paging fields, and SSE ignores limit.

POST /v1/job/:id/messages

Caller sends a message into the conversation. The sender must be the original job requester (verified by auth token).

{ "type": "response", "content": { "prompt_id": "p1", "text": "Option B" } }

Returns 201 { "seq": N } on success.

For payment messages, the server verifies the token/preimage before processing. Returns 402 on failure.

A short mid-job payment is kept, not discarded: the amount lands on a credit the payer owns, and the 402 names it — { "error": "payment_insufficient", "required_msats": …, "received_msats": …, "credit_id": "…", "credited_micro": …, "credit_currency": "usd" }. That balance is not progress on the ask, so the retry still owes the full required_msats; the held amount is reclaimable with op drain at POST /v1/credit (see Prepaid credit). The three credit fields appear only when the payment actually funded a credit — a provider with no credit ledger omits them.

A mid-job payment that a provider verifies but cannot apply to the job answers 500 { "error": "payment_unapplied", "credit_id": "…", "credited_micro": …, "credit_currency": "usd" }. The money was received and is held as prepaid balance the payer owns. The job's request is simply still outstanding. Satisfying it takes a new payment; re-sending this one is rejected as already used. Unlike the short-payment case above, the held amount is not immediately drainable: it stays allocated to the job until the job reaches a terminal status, and op drain reclaims it after that. One case is deliberately less definite: when the provider could not read the job row back either, both display and hint say the outcome is unknown rather than telling the payer to pay again. Read the job's status first: a payment that did reach the job leaves nothing outstanding and a second one is charged on top. A provider that holds no prepaid balances omits the credit_* fields and says so in the copy: there is nothing to reclaim, whatever the job ends up charging.

The success response carries the same three fields under a credit key — 201 { "seq": N, "credit": { "credit_id": …, "credited_micro": …, "credit_currency": … } } — when a payment funded a credit the job did not end up drawing from. That happens when two payments for one request land at once, or when one arrives after the request has already been met: all of them are credited to the payer, one pays the job and the rest stay the payer's balance. Don't re-send a payment that comes back with a credit block — the job's request was already satisfied. A job is never charged more than it asked for in total, so an amount above the request is balance rather than a charge.

When that balance is reclaimable depends on which case it is, and the hint says which. Money the job never charged for is available at once — spend it on a later request, or reclaim it with op drain at POST /v1/credit immediately. Money a payment placed against the job before losing the race is held until the job reaches a terminal status, and op drain reclaims it after that. Neither field set is ever the only record: every credit a payment opens is listed by op balance at POST /v1/credit under the payer's key.

DELETE /v1/job/:id

Cancel a job. Optional body: { "reason": "No longer needed" }.

Returns { "status": "cancelled" }.

Authentication

The server declares its supported authentication schemes in the auth array of the /v1/info response. Two values are defined: "secp256k1-schnorr-v2" and "none". The retired payload-only "secp256k1-schnorr" format is not accepted.

Signed requests (secp256k1-schnorr-v2)

The protocol's authenticated scheme. A caller is identified by a secp256k1 keypair and proves possession by signing the request itself, so identity is bound to the payload rather than to a credential that could be replayed against a different body.

The signature is BIP-340 Schnorr over secp256k1 — the same key class the builder attestation on /v1/info uses, and a protocol invariant rather than an implementation detail.

The envelope is five fields carried inside the request body, never in an HTTP header: within data on POST /v1/job and POST /v1/quote, and at the top level on POST /v1/credit and custom signed routes.

FieldTypeDescription
pubkeystringx-only public key, 32 bytes hex (64 characters)
signaturestringSchnorr signature, 64 bytes hex (128 characters)
timestampnumberUnix seconds when the request was signed
noncestringCaller-generated, unique per signed envelope
auth_statementobjectVersioned audience and operation fields covered by the signature
{
  "op": "balance",
  "pubkey": "3f9c…",
  "signature": "a41b…",
  "timestamp": 1790000000,
  "nonce": "kQ7yTn2fV1xR",
  "auth_statement": {
    "v": 2,
    "protocol": "dvmkit",
    "protocol_version": 1,
    "auth": "secp256k1-schnorr-v2",
    "audience": { "dvm_id": "web-extract", "builder_pubkey": "3f9c…" },
    "method": "POST",
    "path": "/v1/credit",
    "capability": null
  }
}

What gets signed. Remove signature and auth_statement from the wire body to obtain the exact input, then canonicalise { ...auth_statement, input }: object keys sorted lexicographically at every depth, no whitespace, array order preserved, UTF-8 encoded. The audience is the DVM ID and builder pubkey from the verified /v1/info#builder attestation; the method is uppercase; the path is the concrete mounted pathname without query or fragment; the capability is the outer request capability, or null where none exists. Changing any audience, method, path, capability, or input byte invalidates the proof.

Freshness. A request whose timestamp is more than 300 seconds from the server's clock in either direction is rejected. Callers should sign immediately before sending rather than reusing an envelope.

Replay. The server records (pubkey, timestamp, nonce) and refuses a repeat. On POST /v1/job the tuple is committed only after payment verifies, so an unpaid discovery submit does not burn its nonce and the same job proof may be re-sent with payment. /v1/quote and /v1/job require separate proofs because their signed paths differ. POST /v1/credit commits the tuple up front for balance and drain, which take no payment.

Failures return 401 with a flat body:

{
  "error": "auth_error",
  "sub_reason": "timestamp_drift",
  "display": "Request timestamp is outside the 5-minute drift window",
  "hint": "Regenerate the request with the current timestamp + a fresh nonce; sign with secp256k1+BIP-340 Schnorr over the canonical JSON form of the input."
}
sub_reasonCause
signature_requiredNo signing envelope was supplied to a job or quote endpoint that requires one
signature_invalidSignature didn't verify against pubkey — or the envelope was malformed
schema_invalidThe signed body violated the endpoint's own request schema — /v1/credit only
timestamp_drifttimestamp outside the 300-second window
replay_detectedThis (pubkey, timestamp, nonce) was already accepted

On /v1/job and /v1/quote, a request with no signing envelope returns signature_required. Its hint explains how to initialize the caller CLI and use dvm request, or implement the published signing contract. A malformed envelope is reported as signature_invalid: the response does not distinguish a wrong pubkey, a bad signature, a key that does not match, or a partial envelope.

A violation of the capability's input schema is a different failure, and on /v1/quote and /v1/job it is not a 401 at all: both answer it with 400 invalid_input, naming the offending fields in message and display and pointing the hint at /v1/info. One caller mistake, one answer, whichever endpoint they hit — a caller discriminates on the code alone rather than matching a status and a sub-reason per endpoint. Disclosing it is not an oracle: that schema is published on /v1/info, so a caller can determine offline — sending no request at all — whether their input satisfies it, and the check runs over the raw body independent of key validity, so it is reachable with any pubkey, valid or not. A body that is both misshapen and badly signed gets the input answer first, because that is the one the caller has to fix before the signature can be judged; a failure naming only the envelope fields is a signing failure and returns the 401 above. schema_invalid survives as a sub_reason on POST /v1/credit, whose schema is the request envelope itself rather than a capability input.

Credit requires this scheme — a prepaid balance belongs to a verified pubkey, so only providers advertising secp256k1-schnorr-v2 offer it.

None

When auth includes "none", requests do not require authentication. This is the default in devMode (local development). The server assigns a default requester identifier.

Listed after the signed scheme, as ["secp256k1-schnorr-v2", "none"], it means less: the provider also accepts an unsigned POST /v1/job whose job needs a per-call payment, in Cashu or, on a capability that sets a runtime bound (maxRuntimeSeconds), in exact x402. Everything else stays signed: free capabilities, /v1/quote, POST /v1/credit, prepaid credit, and request recovery. An unsigned x402 payment is verified before the job and settled only if the job completes, so a job that fails is not charged. Until the settlement lands, the job's output is withheld and marked content_withheld: "payment_pending". An unsigned request paid with Tempo, or with x402 on a capability without a runtime bound, is refused with 402 payment_method_requires_signature before anything settles, and a mid-job payment-request on an unsigned job offers Cashu alone. The x402 channel is separate: it takes unsigned callers only, whatever auth lists. The unsigned job's job_token is its only handle. If it fails after payment, the released amount stays on an anonymous credit no caller can drain, because a drain must be signed by the credit's owner.

Bearer tokens are identification, not authentication

A provider may read an Authorization: Bearer <token> header to derive a stable requesterId that follows the caller through the job. That is identification only — the token is opaque to the protocol and is never treated as proof of identity — so "bearer" is not an auth value and never appears in /v1/info. A provider that needs authenticated callers advertises secp256k1-schnorr-v2.

Job credentials (X-Job-Token)

Authentication decides who may submit a job. A second, narrower credential decides who may read one back.

POST /v1/job from an unauthenticated caller returns a job_token alongside the job_id:

{ "job_id": "job-abc-1", "job_token": "9f2c…", "status": "processing" }

It is issued once and never repeated. Present it as an X-Job-Token header on every /v1/job/:id and /v1/job/:id/messages request — status, message reads (JSON and SSE), message writes, and cancel:

GET /v1/job/job-abc-1/messages?after=0 HTTP/1.1
X-Job-Token: 9f2c…

Without it, one anonymous caller could read another's transcript by guessing a job id. Providers that identify callers some other way — a signed submit, or a Bearer token — gate on that identity instead and issue no job_token.

A request that presents no credential at all answers 401:

{
  "error": "job_credential_required",
  "message": "This job requires the X-Job-Token returned by POST /v1/job.",
  "display": "Couldn't retrieve your result — the request was missing its job credential.",
  "hint": "Send the job_token from the POST /v1/job response as the X-Job-Token header. The token is minted once, at submit, and the DVM cannot reissue it — a job submitted from another machine, or by a caller that never stored it, can't be read here. If your caller never sends X-Job-Token at all, upgrade: npm install --global @dvmkit/dvm-cli, then retry the same command with --endpoint <url> --job-token <hex> (or set DVM_JOB_ENDPOINT and DVM_JOB_TOKEN)."
}

display stays cause-neutral because two different callers reach this refusal — one that never learned to send the token, and a current one reading a job whose local state doesn't hold it. The conditional advice lives in hint. A provider that identifies callers by Bearer names that alternative in both message and hint.

A request that presents the wrong credential answers 404 {"error":"Job not found"} — deliberately identical to a job id that doesn't exist. A wrong credential must never confirm that a job exists, or the endpoint becomes an id-guessing oracle.

The two are safe to tell apart because the 401 is decided before the job is looked up: it is the same response whether or not the id is real, so it discloses nothing. That split is what makes a stale or misconfigured caller diagnosable — it was an opaque 404 that once left paid results unretrievable with no indication that the fix was "send the token".