Payments

How a single job gets quoted, paid, and settled, and what happens to your money when one fails.

Every job is quoted before it runs, in the currency you think in. Your agent puts the number in front of you and pays only if you approve, or automatically inside limits you set. A long job charges in pieces: you pay before each piece, and each is quoted the same way, unless you paid from prepaid credit and signed a standing limit, which lets the DVM take later pieces from your balance within it. If a job fails, you are charged only for the pieces that finished. To stop partway without paying for more, decline the next payment. A cancel stops the work at once, and the piece that was running stays charged.

A caller is whoever pays for a job: you, through the agent running dvm on your behalf. This page is about that side of the counter.

What a quote tells you

dvm quote asks a provider what a specific piece of work will cost, before anything is committed.

upfront.amount and upfront.currency are the number to put in front of your user. It is stated in real money, dollars or whatever the provider prices in, not in a crypto unit you would have to convert for them.

How to read it depends on shape:

shapeWhat the number is
fixedThe price. That is what the job costs.
rateA commitment collected with the request, plus metered billing on what gets measured: minutes transcribed, pages rendered, bytes stored. The quote carries the rate and, when the provider sets one, a ceiling.

When a quote sets a ceiling, it is a real bound, not an estimate: the final charge can land under it and never above it. A provider is not required to set one; scribe, the only rate-shaped DVM in the first-party catalog today, does.

Two more fields matter. expiresAt says how long the price holds. description is the provider's own plain-English summary of what it is about to do, which is usually the sentence to relay alongside the number.

Sats in a quote are advisory

--human renders an advisory satoshi figure next to the price, converted at the current rate. It is there for orientation, not for arithmetic. The binding amount is fixed later, at the payment handshake, and a rate that moved in between moves the sats with it. Quote in the fiat number; treat the sats line as a gloss.

What refundable does not mean

Every quote carries payment.refundable, a per-rail map, and it is false on every rail today. That is permanent and expected: it answers "can this rail send a per-job payment backwards?", and none of them can. Cashu proofs commit when the provider receives them, and Tempo and Base are final settlement. Card credit is a different path: cards never pay a job directly, and a drain of card-funded credit does refund to the card.

It is not the answer to "am I out the money if this job fails". That answer is below, and it is a better one.

Two ways to pay

Every paid job uses one of two customer modes. Per-call payment pays the job that is running now; it is the universal path and the right default for first contact or one-off work. Prepaid credit funds a small balance once and draws later jobs from it; it is the repeat-use path when one provider offers credit and the caller chooses it.

Card through Stripe-hosted checkout or Stripe Link (Stripe’s saved-payment wallet), x402, Tempo, Cashu, and Bitcoin Lightning describe how money funds those modes, not extra products a user must choose among. Stablecoin prepaid credit reuses one balance across top-ups by default, while x402 exact authorizations and Tempo charges remain available for individual calls. A builder can also admit those one-payment methods into credit, but only by taking on manual responsibility for returning whatever goes unspent. Funding and wallets cover how that balance actually works.

Card-funded credit

Where a provider offers Stripe-hosted checkout, callers anywhere can top up prepaid credit by card with CLI 0.19.0 or later. An agent with a browser and a saved card opens the checkout link and pays it itself, with the amount the human approves; without a browser or a card, it hands the link to the human. Stripe Link is another option for agents in the US and Canada: the human approves a top-up using a Shared Payment Token (SPT), a scoped payment credential. The current default card minimum is US$5. The provider advertises its card minimum; paying by card explains top-up amounts and approvals.

Unspent credit goes back to the card, less the proportional share of Stripe’s processing fee for the amount refunded. A credit spent in full costs you no fee; Stripe’s processing fee comes out of the builder’s side. Expired card credit is refunded the same way, never released to the builder. The builder is the merchant of record and handles card disputes. With the dvm CLI, dvm credit fund <dvm> --rail stripe walks the approval and dvm credit drain <dvm> --method stripe sends unspent credit back to the card. Credits covers what the human approves.

The handshake

Paying is a turn in the conversation rather than a separate step. No account exists, so there is nothing to log into and no key to have been issued in advance.

  1. Your agent posts the job with no payment attached.
  2. The provider answers 402 Payment Required, with a challenge for each payment method it accepts and, where it offers one, a menu for prepaying a balance instead.
  3. Your agent picks a method it can actually settle, settles it, and retries the same request carrying the credential.
  4. The provider verifies the credential, records the money, draws the job's cost against it, and runs the work.

A provider your agent has never contacted before is exactly one paid request away. That is the whole onboarding.

One-request x402 payment

Some capabilities can also be paid by a stock x402 client, such as @x402/fetch, with no dvm CLI and no dvmkit identity. Two first-party capabilities offer it today:

  • discover's natural-language search, at POST https://discover.dvmkit.ai/v1/x402/search, for $0.01.
  • scrape's bounded markdown fetch, at POST https://scrape.dvmkit.ai/v1/x402/fetch, for $0.003.

The client posts a flat JSON body. A request the provider refuses outright, such as a URL that scrape won't fetch, gets HTTP 400 with no challenge and no charge. Otherwise the unpaid request gets HTTP 402 with a PAYMENT-REQUIRED header asking for one exact USDC payment on Base. The client signs that payment and sends the same request again. The provider checks the signature, runs the job, and collects the payment only if the job succeeds. The result comes back in the same HTTP response, so there is no job to poll in the usual case. Both capabilities return their result as a JSON artifact in messages, whose data is a JSON string to parse; the capability pages list its fields. Both are listed in Coinbase's x402 catalog, the CDP Bazaar.

What charge_outcome tells you

Every answer to a paid request that names a job carries charge_outcome:

charge_outcomeWhat happenedWhat to do
chargedThe job completed and the payment went through. The response has status: "completed", the result, a signed receipt if the provider issues them, and a PAYMENT-RESPONSE header naming the settlement transaction.Use the result.
not_chargedThe job failed or ran out of time, or the payment did not go through. A failed job's body has status: "failed", a reason, a display, and a hint. No result is returned.Read the display and hint. To try again, send the request with a new payment signature.
unknownThe request's time ran out before the provider knew whether the payment would go through. The response is HTTP 202 with a job_id, a job_token, and a Retry-After header.Do not pay again. After Retry-After, poll GET /v1/job/:id with the X-Job-Token header until the job finishes. A job whose payment never goes through reads failed. A completed job's result is in summary, or, when payload_in is "messages", at GET /v1/job/:id/messages with the same header.

unknown is the one to handle with care. A fresh signature is a second payment, and both can be collected. Reconcile by reading the job; never retry blind. The job read itself never includes messages, so fetch them separately when payload_in says the result is there.

Let the HTTP client wait at least 60 seconds. The provider sends nothing until the job has finished and the payment has gone through, and a stopped machine may need waking first. A client that hangs up early is still charged if the job succeeds, and never gets the job_token that would let it read the result. The full response table is in the protocol reference.

Paying up front, and paying mid-job

Most jobs are paid once, at submission. The upfront amount doubles as the spam gate, which is why it exists even on jobs that are otherwise metered, and on a fixed-price job it is simply the price.

Longer jobs can ask again while running. Each request is new money for the next piece of work: the upfront payment never covers it. When that happens the response carries next_action of type pay, and the job stays alive waiting for it. Approve with dvm pay <job-id>, then resume the same job with dvm messages <job-id>. Do not re-submit the request: the job is still open, and a fresh submit creates a second job and a second charge.

Two flags bound this without you watching:

  • --max-payments <n> caps how many separate payments one job may ask for. The default is 5, and 0 means free jobs only.
  • --max-increment <amount> caps how large any single one of them may be.

Both are per-job. The caps that bound a day or a month live on the budgets page.

A standing limit for later pieces

A job paid from prepaid credit can carry a standing limit, signed once at submission: the most the job may cost in total (the upfront payment included), the most any one later piece may cost, and an end time no more than 7 days away. A DVM that advertises credit.standing_mandate: true then pays each later piece from your balance as it asks, without waiting for your agent, so a long job keeps running while your agent is not. Each such payment appears in the job's messages, marked as paid under the limit. A piece the limit does not cover, because it costs too much, the balance is short, or the end time has passed, waits for an ordinary payment instead. The dvm CLI signs a standing limit when you set --budget and --auto-pay-below and pay from credit, unless you pass --no-mandate; --mandate-until sets the end time, and the default is 24 hours. The protocol has the wire format.

Which rail actually pays

Your agent picks from the intersection of what the provider accepts and what you hold, and the choice is per job. You do not configure a preference for it to follow, though dvm wallet set-default-rail exists if you want one.

A connected Bitcoin Lightning wallet does not pay jobs directly. It funds the things that do. That distinction and the four funding paths are on the wallets page.

One thing can surprise you: the same job can cost slightly different amounts on different rails. A price quoted in dollars converts to a whole number of satoshis by rounding up, so on a sub-cent job that rounding is visible. A one-cent job might settle at eleven satoshis, about 7% over, while the stablecoin caller is asked for exactly one cent. The dollar figure is the advertised price; the satoshi figure is that price plus whatever the rounding adds.

If a job fails

A charge is a hold. It is placed when the job is accepted and grows with each payment the job asks for while it runs. When the job ends, the provider charges the pieces of work that finished and releases the rest.

A piece is the work one payment bought. The upfront payment buys the first piece, and each payment the job asks for while running buys the next. A piece finishes when the provider asks for the next payment or completes the job.

So a failed job is charged only for what finished. A one-piece job that fails is not charged at all. A job that fails during its third piece is charged for the first two and releases the third. The same holds when you decline a payment request, when one expires, and when the job is reaped after its worker dies. That is arithmetic in a ledger rather than an operation on a payment rail, which is why it holds identically on every rail, including the ones that cannot send value backwards.

The SDK tells providers to send what a piece produced, such as files or partial results, before asking for the next payment. A provider that does so leaves you holding what the finished pieces delivered, whatever ends the job.

Decline or cancel

There are two ways to stop a job partway, and they cost different amounts.

Decline says no to a payment request. The job ends, the finished pieces are charged, and nothing more is. Letting a payment request expire does the same. This is the way to stop when what you want to stop is the spending. On a job with a standing limit you can decline at any time, not only at a payment request: the piece already running finishes, and the job ends before the next one is charged.

Cancel stops the work at once, wherever it is. It charges every piece you have paid for, including the one in progress, which delivers no result. Use it when the work itself has to stop now: a job that acts in the world, one that could run without end, or one started on the wrong input. A cancel spends no new money. It only keeps payments you already made.

In the CLI, dvm decline <job-id> declines the open payment request and dvm cancel <job-id> cancels. A client that speaks the protocol directly sends a decline message instead.

Where released money lands

The harder question is what you can then do with the released money, and the answer turns on whether the provider authenticates callers:

At a provider that...The release lands onAnd you can
does not authenticate callersa shared anonymous identitynothing. There is no key to claim it with, so in practice the payment is gone.
authenticates callersyour own keyspend it on your next job there. Your receipt names the balance it sits on.
authenticates and offers prepaid credityour own key, and advertisedspend it, top it up, or take it back out as money.

For signed requests, all five first-party DVMs sit in the bottom row: cast, narrate, scrape, scribe, and discover authenticate callers and offer prepaid credit. A failed job's money lands on your own balance and can be drained back out. Discover's keyword search and browse remain free. Its mid-job natural-language charge can be paid from an existing balance where it advertises credit.balance_payment: true; see discover.

An unsigned Cashu payment on /v1/job is the table's first row: its release lands on one shared anonymous balance, so in practice the payment is final.

Unsigned x402 payments sit outside the table, both on /v1/job where a DVM offers them and on the one-request x402 route. The payment is verified before the job and collected only if the job completes. If the job fails, the authorization is released uncollected, so there is no paid balance to recover.

This is the reason refundable: false is not the answer to the failure question. The rail never reverses; the ledger is what makes you whole. Credits covers the balance itself.

If the connection drops after paying

A definite failure is not the only way a job can go sideways. The provider can accept the paid job and hand back a job id, and then your agent's own connection can drop, or time out, before it learns how that job ended. The money is out and the job exists, you just have not heard which way it went. This is not the same as a failed job: nothing has failed, you just have not heard back yet.

dvm request tries once to poll the provider before giving up, in case the job actually finished while the connection was closing. If that poll also comes up empty, the response reports status: "paid-timeout" with next_action of type poll, rather than guessing at an outcome.

The rule is the same one that governs a mid-job payment: check, do not resubmit. Run dvm status <job-id> to pick the job back up. If it completed, you get the result and nothing further is charged. If it is still running, you keep polling. Resubmitting the original request starts a second job and a second charge on top of the one already in flight.

A connection can also drop earlier than that, during the paid submit itself, before any job id ever comes back. That is a narrower case specific to ecash: dvm wallet show tries to resume it automatically the next time you run it, and so does the next paid dvm request. dvm wallet submissions shows what is still unresolved.

When a price cannot be stated

Rails priced in dollars need a Bitcoin exchange rate to quote in satoshis, and that rate comes from an outside provider. If it is unreachable, a running DVM keeps quoting off the last rate it saw. A DVM refuses outright in two cases: it has never seen a rate at all, having started up during an outage, or it reads a shared rate snapshot that the platform has itself marked too old to serve — which refuses even if that DVM quoted off a recent rate minutes ago.

That refusal is a 503 and not a 402, deliberately. Your payment is not the problem, and nothing was charged. It is marked retryable and carries text your agent can pass to you as it stands. A provider that can quote in satoshis keeps serving payable quotes right through such an outage.

Where to go next

  • Budgets: every limit on what your agent can spend, and which of them it cannot raise.
  • Credits: prepaid balances, and the full answer to what happens to money at a failed job.
  • Wallets: where the money is and how it gets there.
  • dvm CLI reference: every field on a quote and a job response.