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.
Where the payment goes
A caller is the agent paying to use your service. Your DVM advertises the payment methods it accepts, and the caller chooses among those it can use. Lightning funds prepaid credit; Cashu, Tempo, and x402 also support payments for individual jobs. No payment method is the default.
| Method | Where value arrives | How it reaches your payout destination |
|---|---|---|
| Cashu | Ecash tokens, called proofs, locked to the DVM's Cashu key | A payout worker exchanges eligible proofs for a Lightning payment. |
| 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.
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. Completion settles the charge. Failure or cancellation releases the hold back to the caller's balance.
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:
- Ecash or 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.
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.