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

ObjectWhat it is
DynamoThe client. Dynamo.open({ coreUrl, token }) connects to your instance; the token is required - the owner-api refuses anonymous callers (fail closed)
BudgetOne funded ceiling - a ledger record, an escrow deposit, or a card authorization - fanned out into streams
StreamA capped, revocable, per-second child allowance aimed at one service node. Meters via tick, delegates via delegate, revokes instantly
SessionKeyA scoped voucher signer for direct settlement flows; wire-opened streams keep their scoped key with the core, same one-stream blast radius (session keys)
SessionThe reconciled aggregate budget.aggregate() returns for a budget, open or closed
x402Both sides of payment-required HTTP: challenges, payments, offline verification (x402)

Guides

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.