@dvmkit/sdk
Build Digital Vending Machines: pay-per-use HTTPS services that AI agents can find, pay, and call with no account or API key.
Pre-1.0 alpha: pin the version you install; see the release notes for breaking changes and the compatibility policy.
Requirements
Node.js 22.18 or later for the TypeScript quickstart; see runtime support.
Install
Create a project and install the current release, recording its exact version:
mkdir hello-dvm && cd hello-dvm
npm init -y
npm pkg set type=module
npm install --save-exact @dvmkit/sdk
Quickstart: a free DVM
Save this as handler.ts:
import { configureDVM, z } from "@dvmkit/sdk";
export const inputSchema = z.object({ text: z.string().min(1) });
export default configureDVM({
name: "hello",
description: "Return the supplied text",
capability: "echo",
input: inputSchema,
example: { text: "hello" },
async onJob(ctx) {
ctx.artifact({ mime_type: "text/plain", data: ctx.input.text });
ctx.complete("Echoed the input");
},
});
Save this as server.ts:
import { serve } from "@dvmkit/sdk/server";
import dvm from "./handler.ts";
const server = await serve(dvm, { devMode: true });
for (const signal of ["SIGINT", "SIGTERM"]) {
process.once(signal, () => {
void server.close().then(() => process.exit(0));
});
}
Start the server:
node server.ts
Leave it running. In another terminal, submit a job:
curl -sS http://localhost:8080/v1/job \
-H 'content-type: application/json' \
--data '{"capability":"echo","data":{"text":"hello"}}'
The response includes a generated job_id and job_token, "status":"completed", and "summary":"Echoed the input". The server listens at http://localhost:8080; stop it with Ctrl-C. devMode lets this free example run without Postgres.
The files above are copied verbatim from examples/quickstart. See the runnable authenticated custom route and payments and lifecycle examples for the next step.
What's in the package
| Import | Purpose |
|---|---|
@dvmkit/sdk | DVM descriptors, handler context, bundled Zod, pricing, signing, and safe-fetch helpers |
@dvmkit/sdk/server | Node hosting, Postgres stores, signed-request auth, and payment infrastructure |
@dvmkit/sdk/testing | Deterministic handler contexts and in-memory stores |
The generated API reference lists the supported declarations.
Next steps
- SDK guide: add authentication, custom routes, payments, and persistence.
- Protocol guide: understand the HTTP contract callers use.
- Builder guide: scaffold and deploy a service; install the builder CLI with
npm install --global @dvmkit/dvmctl.
Operating a DVM covers production setup, verified development payments, credit liabilities, diagnostics, retention, content holds, and financial exports. Protocol notes cover compatibility, job credentials, identity, terminal evidence, costs, and rate cards.
Contributing
Issues and discussions are welcome. Unsolicited pull requests are closed; read CONTRIBUTING.md and the Code of Conduct before participating.
Security
Report vulnerabilities privately as described in SECURITY.md.
Support
Use SUPPORT.md to find the right place for questions and bug reports.
Trademarks
The Apache License grants no rights in the dvmkit name or branding; identify your own products and forks without implying endorsement. Permission requests go through support; descriptive use of “digital vending machine” or “DVM” is not restricted.