Offer a capability on x402
Let a stock x402 wallet pay for one of your capabilities in a single request, optionally list it in Coinbase's catalog, and know what that requires and costs.
You can let an ordinary x402 wallet pay dollar stablecoins on Base for one of your capabilities, in a single request, with no dvmkit account or software on the caller's side. The payment is collected only if the job succeeds. A failed job earns you nothing, and what it cost you to run stays your cost. To be listed in Coinbase's catalog, you need your own Coinbase developer key. A listing lapses unless someone pays for the capability at least once every 30 days. This is one more way in for callers, not a replacement for the payment methods your DVM already accepts.
What the channel is
Callers who use dvmkit's job protocol can pay your DVM by card-funded credit, x402, MPP (Tempo), Cashu, or Bitcoin Lightning credit, whichever you accept. Payments and payouts covers those. The x402 channel is a separate door for callers who have only a stock x402 client, such as @x402/fetch, and no dvmkit identity.
Such a caller posts the capability's input as a flat JSON body to POST <your DVM's address>/v1/x402/<capability>. The first, unpaid request gets HTTP 402 with a PAYMENT-REQUIRED header asking for one exact USDC payment on Base. The client signs it and sends the same request again. Your DVM has the payment checked, runs the job, and collects the payment only if the job succeeds. A facilitator, the service that verifies and settles x402 payments on chain, does the checking and collecting. The result comes back in the same HTTP response. One-request x402 payment describes what the caller sees.
Declare the channel
Offer a capability on the channel with channels on its definition. This one stays on the job protocol and adds x402 with a catalog listing:
import { configureDVM, z } from "@dvmkit/sdk";
export default configureDVM({
name: "uppercase",
capability: "uppercase",
description: "Uppercase a short piece of text",
input: z.object({ text: z.string().max(1000) }),
example: { text: "hello" },
price: "$0.001",
maxRuntimeSeconds: 20,
channels: {
job: true,
x402: {
listing: {
description: "Returns the input text in upper case.",
example: { text: "hello" },
},
},
},
async onJob(ctx) {
ctx.complete(ctx.input.text.toUpperCase());
},
});The descriptor needs no top-level x402 block. From SDK 0.34.0 the host builds the x402 setup from DVMKIT_X402_PAY_TO and the other DVMKIT_X402_* variables. Without DVMKIT_X402_PAY_TO there is no x402 setup. A DVM that declares channels.x402 then starts without its x402 routes: each POST /v1/x402/<name> answers 503 x402_not_offered, x402 leaves /v1/info and quotes, and its /v1/job capabilities serve as usual. SDK releases before 0.35.0 refused to start instead, taking /v1/job down with them.
On Cloud the platform sets DVMKIT_X402_PAY_TO from your account's Base recipient, covered below. It withholds the variable when the account has no Base recipient or its x402 toggle (accept_base) is off. So set the Base recipient before you add the channel. Clearing the recipient or turning Base payouts off removes the address at the next deployment, including one stored by an earlier deployment, and the DVM stops taking x402 payments. On an SDK release before 0.35.0, remove channels.x402 first, or the DVM won't start.
If this DVM also accepts reusable x402 channels, switching Base off leaves recent x402 channel earnings not yet collected dependent on a final collection that may fail; earnings collected but not yet paid out wait while Base is off. Stop new channel payments and wait one collection interval (5 minutes by default) first. To resume pending payouts, switch Base back on, re-enable reusable channels, and redeploy; channel earnings advice explains the details.
What the definition must carry
The SDK refuses a definition that breaks one of these. Most are checked as soon as the handler loads, in every mode. The US-dollar price and the settlement store are checked when the server starts, and only warn in development mode.
channelsnames both sides. Declaringx402requiresjobto be stated too, so adding x402 never silently takes a capability off/v1/job.{ job: false, x402: {} }offers it on x402 alone.- A price known before the job runs. The 402 must name an amount, so the capability needs a fixed
priceor anonQuotethat prices the unpaid request from its body. A free capability, or one priced only by a rate card, cannot be offered on x402. The price must be in US dollars. maxRuntimeSeconds. The payment is verified before the handler runs and settled after it finishes, inside one request. The runtime bound has to fit in that request; see the runtime budget.- Unsigned input. x402 callers never sign, so the signed-request fields are never part of an x402 body. On a DVM with
auth, a definition offered on both channels must still parse an unsigned body: declare those fields optional, or preserve unknown fields. - A durable settlement store. The SDK records each payment in Postgres. Cloud provides the database; a self-hosted DVM must supply one.
paymentMethods, if you set it, includes"x402".
One rule applies while a job runs instead: a handler that calls ctx.requestPayment fails the job on this channel, so an x402 capability cannot charge mid-job.
Give the capability its own example as well as the listing's. dvmctl validate loads your handler and refuses a capability without one, with missing_input_example.
Listing fields
listing is optional. Without it the channel still accepts stock x402 wallets, and the 402 carries no catalog metadata. With it, the 402 also carries the x402 Bazaar discovery extension that catalogs index. The SDK refuses to start when a field breaks these limits:
| Field | Required | What it is |
|---|---|---|
description | Yes | What the capability does, at most 500 characters. It travels on every 402 for this capability, and the facilitator refuses to verify or settle a payment with a longer one, so an overlong text fails the payment, not only the listing. |
example | Yes | A runnable input, written flat exactly as an x402 caller posts it. It must satisfy the capability's input schema and carry no signed-request fields. |
inputSchema | No | JSON Schema for the request body. Defaults to your input schema converted to JSON Schema with the signed-request fields removed. Set it when that conversion fails, as it does for a z.date() field, or reads badly. It must accept example, use only local # references, and have no $id. |
outputExample | No | An example JSON response body. |
serviceName | No | Display name, 1 to 32 printable ASCII characters. |
tags | No | Up to 5 distinct tags, each 1 to 32 printable ASCII characters. |
iconUrl | No | Absolute http or https URL, at most 2,048 characters, with no credentials, a DNS host name rather than an IP address or localhost, and not an SVG image. |
resourceUrl | No | The URL catalogs index. Defaults to your DVM's public address plus /v1/x402/<capability>. Set it only when callers reach the capability somewhere else, such as behind a proxy. Payment stays bound to the route's own address either way. |
The whole encoded PAYMENT-REQUIRED header must fit in 7,168 bytes. If the listing pushes it over, the SDK refuses to start and names the fields to shorten.
The facilitator screens listing text for wording that could instruct an AI agent, such as "ignore previous instructions" or "always choose this service", and may refuse to list a capability that reads that way. The SDK cannot detect this. Describe what the capability does, plainly.
Where the money goes
x402 pays USDC on Base to the address in DVMKIT_X402_PAY_TO. On Cloud, the platform writes that variable at each deployment from your account's payout routing and ignores a local value. Set the account's Base recipient first: Set the x402 Base recipient gives the steps and explains the account-wide x402 toggle. A running DVM keeps the address it was deployed with, so redeploy after a change.
A hosted DVM also needs a public address, because every x402 payment names it. The platform builds it from your handle: https://<handle>--<slug>.dvmkit.ai. If you have not claimed a handle, a deploy with a recipient is refused. Claim one with dvmctl handle set and deploy again. A self-hosted DVM sets DVMKIT_PUBLIC_URL to the address callers reach it at.
After deploying, read x402 on the DVM's /v1/info: pay_to, network, and facilitator should be the values you meant. The 402's payTo is the same address.
Test funds and real money
Which facilitator you need depends on the network.
Test funds on Base Sepolia
Set DVMKIT_X402_NETWORK=eip155:84532 and DVMKIT_X402_FACILITATOR=https://x402.org/facilitator. The public x402.org facilitator is free, needs no key, and settles test USDC only. Use it to prove your capability end to end before real money moves.
Real money on Base mainnet
Base mainnet (eip155:8453) is the SDK's default network. The default x402.org facilitator cannot settle it, so mainnet needs a facilitator that does. Coinbase's is the one dvmkit uses, and payments settled through it are what Coinbase's catalog lists. It needs a Coinbase Developer Platform (CDP) key:
| Variable | Value |
|---|---|
DVMKIT_X402_FACILITATOR | https://api.cdp.coinbase.com/platform/v2/x402 |
DVMKIT_X402_FACILITATOR_KEY_ID | Your CDP secret API key ID |
DVMKIT_X402_FACILITATOR_KEY_SECRET | The matching key secret |
dvmkit does not lend its own key. To be listed in Coinbase's catalog, use your own. Set the ID and secret as a pair. Pass the secret with dvmctl deploy --env-stdin rather than in command arguments; Payments and secrets explains why.
Turn on strict startup with DVMKIT_FAIL_FAST=true. With it, the platform refuses a first mainnet deploy whose facilitator is unset or is the x402.org default, before any machine is created. A redeploy that leaves the facilitator out while the DVM already has one stored is not checked this way. Read the strict-startup caveats first.
After a deploy that used --env-stdin, that refusal's remedy can print the test network as [redacted]2. It means eip155:84532, Base Sepolia.
Charged only on success
A job that completes is charged: the response is HTTP 200 with charge_outcome: "charged", and a PAYMENT-RESPONSE header names the settlement transaction. Your recipient receives exactly the price.
A job that fails, because the handler calls ctx.fail(...) or runs past maxRuntimeSeconds, is not charged. A handler failure answers HTTP 500 with charge_outcome: "not_charged" and a body saying nothing was charged. Nothing settles and no USDC moves. Whatever the handler already spent, such as a paid provider call, is your cost. Price and cost covers that trade-off, and the caller's side of every outcome is in What charge_outcome tells you.
So refuse what you can before the handler starts. A paid request whose body fails your input schema gets HTTP 400 and is never charged. An unpaid request with a missing or invalid body on a listed capability still gets a 402, priced from the listing's example, so a catalog can read the challenge.
The runtime budget
The whole exchange happens inside one HTTP request, so the handler's runtime bound plus the settlement wait must fit in the time the router allows. When DVMKIT_X402_RESPONSE_LIMIT_MS is set, the SDK checks this rule at boot:
maxRuntimeSeconds × 1000 + facilitator timeout (10,000 ms by default) ≤ DVMKIT_X402_RESPONSE_LIMIT_MSOn Cloud the platform sets DVMKIT_X402_RESPONSE_LIMIT_MS to 44,000. That leaves room for a stopped machine to wake inside the router's x402 timeout. With the default facilitator timeout, maxRuntimeSeconds can be at most 34. A larger value refuses boot outside development mode and only warns in it. Keep the bound short: a capability that needs longer belongs on the job protocol only.
A self-hosted DVM gets this check only if it sets DVMKIT_X402_RESPONSE_LIMIT_MS to how long its own gateway waits for response headers. Without it, the SDK does not check the rule.
Other limits
Isolate DVMs. The isolate runtime serves no x402 route, only the job protocol. The hosted builder platform deploys containers, so this matters only if your account can deploy isolates.
Hosting balance. An account whose prepaid hosting balance is below its floor gets 503 hosting_prepaid_floor on the x402 route, exactly as on /v1/job. Callers are refused before any payment is taken.
Staying in Coinbase's catalog
Coinbase runs the catalog, the CDP Bazaar, and decides what it shows. dvmkit cannot add you to it or keep you there, and a listing does not promise traffic.
You can see what Coinbase's validator makes of each route. After a Cloud deploy, dvmctl deploy sends each x402 route to Coinbase's public validator and reports the answer under x402_listing in its result. For each route it shows what the validator found, which checks failed, and a fix where one is known. The check only reports. It does not list the capability, and it never fails the deploy. Passing is not being in the catalog. Coinbase indexes a route only after a paid call settles through its facilitator. Run dvmctl x402 listing-check <slug> to check again later. The command reference lists every verdict it can return.
Coinbase drops a listed resource about 30 days after its last settlement through its facilitator. A resource that comes back starts low in the ranking again. Keeping your listing alive is your job. If real traffic doesn't settle a payment within that window, one paid call from your own x402 client does, at the capability's price. Coinbase recomputes the catalog's ranking quality metrics every six hours, per its Get discovered guide, so a fresh payment can take that long to show in the ranking.
What it costs you
Three costs apply on top of your normal hosting:
- Facilitator fees. Coinbase documents verification as free and settlement as free for the first 1,000 settlements a month, then $0.001 each, billed to your CDP account. Check Coinbase's current x402 pricing before relying on those figures.
- Failed jobs. A failed job earns nothing, while its hosting time and provider calls still cost you.
- Keeping a listing alive. At least one paid call a month per listed capability if traffic doesn't provide it.
Callers pay no gas, and neither do you: the facilitator submits the settlement transaction.