SDK - @dynamoprotocol/sdk
TypeScript-first, Node 22.12 or later. The SDK is a thin wire client (4.3.3): it holds credentials, manages budgets and streams through your instance's versioned owner-api (it speaks 1.1.0 through 1.11.0; the current core answers 1.11.0), signs and verifies what a client must sign and verify, and re-implements nothing - the engine and every enforcement decision live with the core it talks to. A method that needs a newer core checks the core's version first and refuses (UnsupportedByServer) rather than send a request the core cannot answer. See the generated reference for every export, pinned to that surface by the build. Version history, deprecation policy and migration guides: Changelog and release notes.
npm has an older August @dynamoprotocol/sdk (2.x). The v2.2.6 preview build is 4.3.3 and is not on npm - preview users install it from the tarball in their credentials blob (npm install @dynamoprotocol/sdk alone does not give you 4.3.3). From a clone, build it (in the repository it is the workspace package @dynamo/sdk-open in packages/sdk-open) and import the built file:
cd "$DYNAMO_REPO"
pwd
pnpm install --frozen-lockfile
pnpm --filter @dynamo/sdk-open... -r build
node --input-type=module -e "import('$DYNAMO_REPO/packages/sdk-open/dist/index.js').then((m) => console.log(m.SDK_INTERFACE_VERSION))"
In your own scripts, import from "$DYNAMO_REPO/packages/sdk-open/dist/index.js" (an absolute path) where the samples import @dynamoprotocol/sdk. That build does not include the x402 module, which is bundled only into the packaged SDK; from a clone, build @dynamo/sdk (pnpm --filter @dynamo/sdk... -r build) and import x402 from "$DYNAMO_REPO/packages/sdk/dist/index.js".
Every call needs your instance credentials. The SDK reads no environment variable itself; the samples pass DYNAMO_CORE_URL and OWNER_API_TOKEN to Dynamo.open({ coreUrl, token }). OWNER_API_TOKEN is the owner token the core was booted with, which the operator guide exports as DYNAMO_OWNER_TOKEN:
cd "$DYNAMO_REPO"
pwd
export DYNAMO_CORE_URL=http://127.0.0.1:8790
export OWNER_API_TOKEN="$DYNAMO_OWNER_TOKEN"
The object graph
| Object | What it is |
|---|---|
Dynamo | The client. Dynamo.open({ coreUrl, token }) connects to your instance; the token is required - the owner-api refuses anonymous callers (fail closed) |
Budget | One funded ceiling - a ledger record, an escrow deposit, or a card authorization - fanned out into streams |
Stream | A capped, revocable, per-second child allowance aimed at one service node. Meters via tick, delegates via delegate, revokes instantly |
SessionKey | A scoped voucher signer for direct settlement flows; wire-opened streams keep their scoped key with the core, same one-stream blast radius (session keys) |
Session | The reconciled aggregate budget.aggregate() returns for a budget, open or closed |
x402 | Both sides of payment-required HTTP: challenges, payments, offline verification (x402) |
Guides
- Budgets - open, fan out, close, reconcile.
- Streams - caps, rate envelopes, delegation, revocation, fail-closed metering.
- Session keys - scoped signing + offline allowance credentials.
- The holdback dial - per-stream refundability windows.
- Batch - atomic multi-stream open/close (engine only; not in the owner API or this SDK).
- Subscribe - recurring budgets (engine only; not in the owner API or this SDK).
Money is integers
Every amount is integer micro-USD held in bigint; every metered quantity is integer units; money crosses the wire as decimal digit strings only. The helpers usd("20"), microUsd(20_000_000n), and units(500_000n) construct branded values - floating point never enters an amount, a rate, or a fee. The metered quantity is deliberately called units and the payee a serviceNode: the protocol is payload-neutral and prices work, whatever the work is.
Versioning promise
Rule of the package: additive changes bump the minor version with a CHANGELOG entry; a breaking change without a written deprecation note is forbidden. 2.0.0 was the first wire-client surface; 3.0.0 was a major version (tolerant response parsing, typed errors), with a migration note in the package. No version is on npm yet.