Quickstarts

Dynamo has two parts: a core (the engine that enforces caps and signs vouchers, served over HTTP) and a thin open client that talks to it. You can run a core on your own machine from a clone of the repository, or point the client at a hosted instance you were given. The client sends metering facts only (stream ids, unit counts, amounts), never the content of your requests. The flow, end to end:

  1. Get a core. Boot one locally (Control Mode shows the

command) or use a hosted instance's URL and owner token.

  1. Set two variables: DYNAMO_CORE_URL (the core's address) and

OWNER_API_TOKEN (the owner wire's bearer token). Gateway plugins use a second token on the metering wire: the core's PLUGIN_WIRE_TOKEN, given to the plugin as DYNAMO_ENGINE_TOKEN.

  1. Use the client. The TypeScript client in this repository is @dynamoprotocol/sdk 4.3.3 (its source version).

It is not on the npm registry yet; Control Mode runs it from the clone.

  1. Make your first capped call: Control Mode walks it.
  2. Witness the Spending Cap: spend a stream past its cap. The core

refuses, fails closed, and bills nothing past the ceiling.

A stream's spending allowance builds up per second from its open, so a payment in the same second as the open is refused with rate (nothing is billed). Open the stream before the work starts; on a rate refusal, wait a second and retry. See rate.

Funding modes

A core starts in Control Mode: the full protocol with no money anywhere. Caps, per-second rate envelopes, instant revocation, EIP-712 vouchers signed by per-stream session keys, checkpoints and reconciliation are the same machinery the money modes run. Money modes are off by default (CORE_ALLOWED_MODES defaults to none). A money mode turns on only when the operator adds it to that list, and a core whose money-mode settings are set while the mode is not listed refuses to boot.

ModeStatusPage
Control Mode (ledger only, no money)LiveYour first capped call
Stablecoin escrow on a local chain or a testnetLiveStablecoin escrow
Credit card rail with Stripe TEST keysLive (test mode only)Credit card sandbox
Credit card rail with live keysRelease-gatedCredit card sandbox

The object graph (budget → streams → vouchers → settlement) is the same in every mode; only the funding tag and the settlement layer differ. One thing changes in your code when you move from Control Mode to a money mode: a money mode requires own hops by default, so every stream open carries the delegator's signed hop intent and the payee's signed offer. The flagship sample opens unsigned streams, so it runs as written in Control Mode only.