Payments and payouts
Distinguish customer payments, earned revenue, refunds, and funds paid out to the builder.
A customer payment and a payout to you are separate events. Some payment methods send funds to your chosen address; others need a later payout step. A prepaid balance can include money the customer has not spent. That money may still need to go back to them. The platform records revenue, but it does not hold a builder balance for you to withdraw. If you accept ecash, you run the payout step yourself, on a machine you control.
Where the payment goes
Who can pay my DVM?
A caller is the agent paying to use your service. Callers pay through dvmkit's job protocol, using dvm or another client that implements it. A job can be paid in dollars with x402 (USDC on Base) or MPP (USDC.e on Tempo), or in Bitcoin ecash using Cashu. Your DVM advertises the methods it accepts; no method is the default.
If your DVM offers prepaid credit, callers can fund a balance using its accepted funding methods, then draw from it for jobs. Those methods can include card through Stripe-hosted checkout or Stripe Link, x402, MPP (Tempo), Cashu, and Bitcoin Lightning. Bitcoin Lightning funds prepaid credit only; it does not pay a job directly.
A capability can also be offered on the one-request x402 route. There, a stock x402 client pays in one request with no dvmkit identity, and the payment is collected only if the job succeeds. Offer a capability on x402 covers your side: declaring it, the facilitator key, the catalog listing, and what it costs. Payments covers the caller's side.
Some capabilities priced upfront accept one unsigned Cashu (NUT-24) payment. A wallet pays the HTTP 402 challenge, and a short job can return its result in the same paid response. Unsigned Cashu payers get no refund if a job fails. The scrape, discover, and satoshi-quotes pages list the supported inputs and the limits on inline results. Generic one-shot MPP (Tempo) clients still cannot pay your DVM without implementing the job protocol.
Offer Stripe-hosted checkout so callers anywhere can pay by card in a browser with CLI 0.19.0 or later. Stripe Link is another option for agents in the US and Canada. Stripe’s country list for Shared Payment Tokens (SPTs) is wider than where Link lets agents connect, so don’t read Link eligibility from it. Cards fund prepaid credit; they do not pay a job directly.
Where value arrives
| Method | Where value arrives | How it reaches your payout destination |
|---|---|---|
| Card through Stripe | Your Stripe account | Stripe pays out to your bank under your account’s payout schedule. Unspent credit remains owed to the caller. |
| Cashu | Ecash tokens, called proofs, locked to the DVM's Cashu key | A payout worker you run exchanges eligible proofs for a Lightning payment. |
| Bitcoin Lightning | The builder's connected Lightning wallet, in exchange for prepaid caller credit | The invoice payment reaches that wallet directly. Unused credit remains owed to the caller. |
| Tempo | Stablecoins paid to the configured recipient, or held in a payment channel | A direct payment transfers funds once. A channel pays out when settled or closed. |
| x402 | Stablecoins paid to the configured recipient, or held in a payment channel | A direct payment, called an exact payment, transfers funds once. A channel pays out when a batch is settled. |
A payment channel holds funds under a contract so repeated payments can share one deposit. The deposit, the charges against it, and the amount transferred to you are different figures.
The SDK reference specifies the supported payment configuration. The installed builder skill carries the setup and test procedures.
Accept card-funded credit
You are the merchant of record: the seller responsible for card payments, refunds, and chargebacks. On a UK Stripe account, a dispute costs £20, with another £20 to contest it manually. Stripe returns the contest fee if you win. See Stripe’s UK pricing for current fees.
You need a Stripe account and a Stripe profile. Put the profile’s Network ID in DVMKIT_STRIPE_NETWORK_ID (internal in test mode). Set DVMKIT_STRIPE_SECRET_KEY to a restricted key with exactly these dashboard permissions:
| Permission | Access |
|---|---|
| Payment Intents | Write |
| Charges and Refunds | Write |
| Balance | Read |
| Payment Disputes | Read |
Using SPTs accepts Stripe’s terms for them. For self-hosted card credit, also set DVMKIT_TEMPO_SECRET_KEY in your secret store to sign funding challenges, even if you do not offer Tempo payments. On dvmkit Cloud, the platform generates this secret automatically and overwrites any builder-set value. Keep the two Stripe settings in your deployment’s secret store. Deploying covers how to supply them.
A checkout top-up puts the caller's name and email address in your Stripe account; you are responsible for them under your own privacy policy.
Offer hosted checkout
Use SDK 0.36.0 or later with Postgres. First grant the restricted key Checkout Sessions: Write, alongside the permissions above. Then set DVMKIT_STRIPE_CHECKOUT_SUCCESS_URL=https://dvmkit.com/checkout/complete, or use your own HTTPS success page. The shared static page can be reused; it needs no session id, login, or balance. The menu advertises credit.stripe.checkout: true only when the card rail and this URL are configured.
Initialization creates two additive tables, stripe_checkout_sessions and stripe_checkout_store_identity. Upgrade every process sharing that store before enabling the URL. Keep Checkout-aware recovery running until recorded sessions resolve before rolling back. Callers poll their signed funding request to book payment; no Checkout webhook is needed. Paid sessions left unbooked are refunded by recovery after 24 hours.
Choose a card top-up minimum
Use @dvmkit/sdk 0.25.0 or later for this setting. Updating the platform does not upgrade the SDK pinned in your project. Card funding needs a USD credit menu. The card minimum defaults to US$5. Set DVMKIT_STRIPE_MIN_USD to a decimal dollar amount such as 1 or 2.50 to change it for card alone. Other funding methods and credit.min keep their own minimums.
On dvmkit Cloud, set it when deploying through .env or --env-stdin, or change a running DVM with dvmctl env my-dvm --set DVMKIT_STRIPE_MIN_USD=2.50. Self-hosted deployments set it in the service's environment or secret store before starting the host. If you construct the rail yourself, pass minUsd to createStripeCreditRail. Deployment settings explains how environment changes reach the running service.
An explicit setting must be at least US$0.50 and no greater than your credit maximum. Invalid amounts fail boot. The advertised card minimum is the larger of your setting and credit.min. With no setting, the US$5 default is capped at your credit maximum, so a DVM with a US$3 maximum still offers card top-ups from US$3. A credit maximum below US$0.50 cannot offer cards.
Small top-ups mostly pay the processor. At an illustrative US card rate of 2.9% plus 30 cents, Stripe's fee is about 63% of a US$0.50 top-up, 9% of US$5, and 4.4% of US$20. Your actual rate depends on your Stripe account and the card. You bear the fee on credit callers spend.
About ten jobs' worth is a sensible starting floor: US$1 for jobs priced at US$0.10, or US$20 for jobs priced at US$2. Set your credit maximum high enough to allow it. Lower minimums let callers try your service for less; higher ones waste less on processing fees.
Refund unused card credit
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 the caller no fee. Expired card credit is refunded the same way, never released to you. Keep the production host and its Postgres records running so the SDK’s hourly refund sweep can process expiry refunds and retry pending ones.
Lightning has separate receiving and refund roles
The DVM uses a receive-only wallet connection to issue Lightning invoices and check that they were paid. Nostr Wallet Connect (NWC) supplies that limited wallet access. This connection cannot spend from the wallet.
Returning unused Lightning-funded credit requires a separate path: the caller receives ecash. The refund worker can use available ecash or a separately authorized spending connection to buy it from a mint. Keep that spending credential on the refund worker, separate from the DVM's receiving credential.
The caller's own NWC connection pays the invoice. It is distinct from both builder connections. Receiving Lightning payments, funding caller refunds, and accepting Lightning payouts from ecash are three different operations.
Received is not the same as earned
A caller can fund a prepaid balance and spend it over several jobs. A credit draw reserves part of that balance for a job and grows with each payment the job asks for while it runs. When the job ends, the pieces of work that finished settle as the charge, and the rest of the hold goes back to the caller's balance. A caller's cancel also settles the piece that was running. Your revenue books what settled on every ending, so a job that fails after two finished pieces earns those two. Charging by the piece states the rule in full. The same rule holds for mid-job draws on the platform’s isolate tier. Isolate upfront payments still book revenue only on completion. Released mid-job funds remain on credit, with no caller-facing drain yet.
Releasing a hold does not reverse the original payment. Likewise, a stablecoin transfer to your address does not prove that every unit transferred has been earned. Some may still back unused caller credit.
Revenue reports describe earnings. Payment and payout records describe transfers. Use the relevant record for the question being answered; a revenue total is not a wallet balance or proof that a payout arrived.
What you owe back
Expiry stops new spending. The balance remains reclaimable until a recorded expiry release or another completed refund removes the obligation. Do not infer a release from the expiry timestamp alone. The SDK credit lifecycle specifies which balances its expiry sweep can release.
The refund path depends on how the credit was funded:
- Card funding: the SDK refunds the original card, less the refunded share of Stripe’s processing fee. Expired card credit follows this path too; it is never released to the builder.
- Ecash or Bitcoin Lightning funding: the refund worker prepares ecash for the caller. The Cashu payout worker holds your payout while ecash refunds remain unserviced or their state cannot be read.
- Stablecoin channel funding: the channel handles the return through its close and settlement process. A manual transfer recorded as a refund is not a substitute for that process.
- One-payment stablecoin funding: the builder must send the refund and record its transaction. Offering this kind of prepaid credit requires an explicit configuration choice and a working refund process.
An unpaid refund owed by the builder is a signed obligation, not a guarantee that the caller has received funds. The dvmctl reference documents the refund and reconciliation commands. The skill's recovery procedure determines which one applies.
Running the payout worker
The payout worker is dvmctl melt-pending. Each run parks the ecash refunds callers are owed, then exchanges your remaining Cashu revenue for a Lightning payment to your payout destination. Any DVM that accepts Cashu or Lightning-funded credit needs it running from the first paid job.
Who runs it
You do. dvmkit Cloud hosts the DVM but not this worker. The worker signs with keys derived from your builder mnemonic, and the platform does not hold that mnemonic. A DVM on Cloud therefore still needs a second machine of yours.
What its machine needs
- Your builder mnemonic (
builder.mnemonic). It derives the lock key for every DVM you deploy. - The DVM's entry in
builder.json. The deploy records it on the machine you deployed from. It carries the DVM's id, its current key rotation, and the default set bydvmctl set-payout. - Platform access: a
dvmctl authlogin orDVMKIT_API_KEY, so the worker can find the DVM. - A payout destination: a Lightning address from
set-payoutor--payout, or a wallet connection inDVMKIT_MELT_PAYOUT_NWC_URL. - For Lightning-funded credit, a send-capable wallet connection in
DVMKIT_REFUND_NWC_URL, so the worker can buy refund ecash. Set it in the worker's environment rather than passing it to--refund-nwc, which puts it in the command line.
The first two files live in the builder state directory, ~/.dvmkit unless DVMKIT_CONFIG_DIR says otherwise. State directories lists every file and the variable that moves it. To run the worker somewhere other than your deploy machine, copy both files there with mode 0600. Copy builder.json again after every dvmctl rotate: a worker holding the old entry cannot derive the new key, and its runs fail with admin_bad_signature.
Run one worker per DVM, on one machine. Its melt journal and refund log are local files, so a second machine would not know what the first has already submitted.
Where to run it
| Where | How | Trade-off |
|---|---|---|
| A machine you keep on, such as a home server or a desktop set never to sleep | melt-pending --watch under systemd or launchd | The mnemonic stays on hardware you own. The worker is down whenever that machine is. |
| A small rented server | --watch as a service, or a scheduled run | Always on. The mnemonic sits on someone else's hardware, and anyone who reads it can take the held revenue of every DVM it derives keys for. |
| Your laptop | A scheduled one-shot run from cron or launchd | Nothing new to rent or secure. It runs only while the laptop is awake, so refunds and payouts wait for the next run. |
The melt-pending reference has the flags for each.
What lapses when it stops
Nothing fails loudly. While the worker is not running:
- Revenue stays held. Cashu payments sit on the DVM as proofs locked to its key. None of it reaches your payout destination.
- Refunds wait. A caller reclaiming a balance gets nothing until a run parks their ecash.
- Old proofs go back to the payer. A Cashu payer can lock their payment with a refund path that opens after a set time. Once it opens, the payer can take back any proof you have not melted. The default floor is 7 days for signed payments and can be lower for unsigned ones. Cashu lock floors gives the exact values. Run the worker well inside the shortest floor your DVM accepts.
Alarm on it
Every clean run stamps a local record. dvmctl melt-status --max-age 30h exits non-zero when a DVM has not swept within that window. Run it from cron on the worker's machine, since the record lives there, and set the window a little longer than your run cadence. Let the worker succeed once before you add the alarm. melt-status explains the rest.
Set accepted Cashu mints
For a platform-hosted DVM, set accepted Cashu mints in Dashboard → Account → payout defaults, under Cashu. The prompt gives your agent the API instructions. An org admin can also read the list with GET or update it with PUT at this endpoint:
/api/v1/builder/orgs/:handle/mintsSend this body with PUT:
{ "mints": ["https://your-mint.example"] }The list accepts up to five HTTPS URLs, with no empty entries. Encode any commas inside a URL as %2C. Send { "mints": null } or { "mints": [] } to clear it, then redeploy to apply the change.
Without an accepted mint, your DVM's prepaid-credit menu omits Cashu and Lightning: reclaiming those credits returns ecash. A mint holds the Bitcoin backing its ecash, so choose operators you are willing to trust with that value. Setting mints does not create the recovery keys or connect a Lightning receive wallet.
Per-DVM rail preferences
An account admin or owner can decline Cashu, Tempo or Base for one hosted DVM with dvmctl payout-routing. This leaves the account defaults available to its other DVMs.
dvmctl payout-routing my-dvm --base falseUse false to decline a rail. Use null or true to inherit the account setting again; neither enables a rail the account disabled. Omitted flags leave the other preferences unchanged. Run the command without rail flags to read the stored preferences.
Redeploy the DVM to apply a change. The platform removes the declined rail's stored routing configuration at that deploy. Card and Lightning settings are separate, and recovery public keys and Base private keys stay stored. If the DVM accepts reusable x402 channels, read the channel earnings advice before declining Base.
Set the x402 Base recipient
A platform-hosted DVM takes its x402 recipient from your account, not from your local environment. x402 pays USDC on Base to that address. Set it before you deploy a DVM that accepts x402.
Where the hosted recipient comes from
At each Cloud deployment, the platform writes DVMKIT_X402_PAY_TO itself. A recipient recorded for that DVM wins; otherwise the account's Base recipient applies. When either exists, it replaces any value from your local .env. When neither exists, the platform removes your local value and the deployment log prints a warning. The account's x402 toggle must also be on (it is by default), and the DVM must not have declined Base through its rail preferences. Disabling either removes the address whatever else is set. Removing it also unsets an address an earlier deployment stored, so the DVM stops taking x402 payments to it once redeployed.
An inherited Base recipient can enable x402 even if you intended only prepaid credits funded through Bitcoin Lightning. The platform can add DVMKIT_FAIL_FAST=true and preserves it when supplied in your deployment environment. If you want x402, explicitly choose a compatible network and facilitator, the service that verifies and settles payments. Review the SDK strict-startup caveat before deploying.
A GET to this endpoint reports the toggle as accept_base, with base_configured saying whether a recipient is set:
https://api.dvmkit.dev/api/v1/builder/orgs/:handle/payout-routingTo disable inherited x402, an account admin or owner can GET the payout-routing endpoint above, then PUT all three current booleans (accept_cashu, accept_tempo, and accept_base) back to the same endpoint, changing only accept_base to false. Preserve the other two values; omitting any boolean returns 400 bad_request. Org API keys are also accepted for payout routing. Make this choice deliberately: it disables x402 for every DVM in the account when each is redeployed.
A local DVMKIT_X402_PAY_TO affects only a process you run yourself. Setting it does not configure hosted payouts.
Switching Base off with reusable channels
If any of your DVMs accepts reusable x402 channels, its last few minutes of x402 channel earnings not yet collected depend on one final collection when it stops. SDK 0.35.2 and newer try that final collection, but it can fail. If it does not land, callers can withdraw that money after the channel's withdrawal delay. A collection that times out may still land later; a timeout alone does not mean the earnings were lost. Ordinary x402 payments are collected per job and have no channel earnings left to collect.
Earnings collected but not yet paid out stay in the channel contract while Base is off. To avoid relying on the final collection, stop new x402 channel payments, wait one collection interval (5 minutes by default), then switch Base off for the account or the DVM. If collected earnings are still waiting for payout later, switch Base back on, restore DVMKIT_X402_BATCH_SETTLEMENT=true, and redeploy the DVM. The platform keeps your private keys when Base is off, but removes reusable-channel activation.
Releases and recovery
These routing changes apply to deployments from the CLI, git push or dashboard, redeployments without a build, rollbacks, and automatic or secret recovery. A rollback uses the account's current routing, not its old payout destinations. A machine restart or resume does not apply routing changes.
An old SDK image may still refuse to start without x402. In that case recovery reports the startup failure and asks you to deploy a current image; it does not restore a removed payout destination. If stored secrets cannot be inspected or removed, the platform refuses the release.
Read, set, and clear it
Only the account owner can use this route, with their own builder API key. The dvmctl key from dvmctl auth works; send it as Authorization: Bearer dvmk_…. An org API key is refused with 403 forbidden, even in its own org. A member or admin of a shared org also gets 403, and a non-member gets 404.
For your personal account, :handle is your builder handle: builder.handle in dvmctl whoami. dvmctl handle set claims one if it is null. For a shared org, use its handle from dvmctl orgs.
Every request below uses this endpoint:
https://api.dvmkit.dev/api/v1/builder/orgs/:handle/base- Read the current value with
GET. The response is{ "baseAddress": "0x…" }, or{ "baseAddress": null }when none is set. - Choose the address yourself. It must be a Base address you control that can receive USDC. Neither dvmkit nor your agent should pick one for you.
- Set it with
PUTand the body{ "baseAddress": "0x…" }. A successful response repeats the stored value as{ "baseAddress": "0x…" }. - Read it again and compare it to the address you meant to set.
- Redeploy every DVM that should use it. A running DVM keeps the address it was deployed with.
The address must be 0x followed by 40 hexadecimal characters; surrounding spaces are trimmed. Anything else is refused with 400 invalid_base_address, and a value that is not a string or null with 400 bad_request. The platform does not check the checksum or whether the address is on Base. Send { "baseAddress": null } or { "baseAddress": "" } to clear it, then redeploy. Each change is recorded in the account's audit log.
What proves it worked
Three things are separate:
- The account default is what
GET …/basereturns. A redeploy uses it only when that DVM has no recipient of its own and the account's x402 toggle is on. The response does not show either of those. - The recipient a deployed DVM actually uses is
x402.pay_toin its/v1/info. Check it after the redeploy. - Money arriving is a USDC transfer or channel settlement to that address on Base. Neither of the first two proves that a payment arrived.
What makes a payout ready
Cashu payouts need a running payout worker, an available mint, and enough value to cover the payment and fees. They also need the Cashu recovery keys. The builder signing identity and those recovery keys have different jobs; preserving one does not replace backing up the other.
Stablecoin proceeds follow the configured network, recipient, and payment method. Check the transfer or channel settlement evidence before reporting that the builder has received them.
Before deployment, settle the payment destinations and recovery arrangements using the skill's deployment procedure. Before shutdown, resolve outstanding caller funds using its retirement procedure. Stopping the service does not discharge its obligations.