Developers: the hosted tier

A Dynamo deployment started with CORE_TENANCY=multi serves many accounts from one URL. Each account (a tenant) has its own stores, signer, keys, limits, events and dashboard session; nothing in an answer reveals another tenant. This page takes you from sign-up to a first metered request.

Working locally instead? Start with Boot a local instance: one single-tenant core on your machine, owner token instead of sign-up. These pages need a single-tenant local core: Getting paid as a payee (its stablecoin steps), Contract version 2 (the multi-tenant tier serves only user-owned budgets, and only when its operator sets CORE_TENANCY_USDC=adopt) and A stablecoin core on a local chain. The rest of this page is the hosted, multi-tenant tier.

The HTTP request and response shapes of every owner route are in the core's OpenAPI document, GET /owner/v1/openapi.json.

1. Sign up

Open the dashboard at <base>/console/, enter your email and choose Create an account, or call the API:

cd ~
pwd
export DYNAMO_BASE_URL=https://dynamo.example.com
curl -s -X POST "$DYNAMO_BASE_URL/signup" -H 'content-type: application/json' -d '{"email":"you@example.com"}'

The answer is 202 {"status":"verification_sent"} whether or not the address already has an account (a known address gets a sign-in link instead). Open the emailed link in your browser. It creates the account, signs you in to the dashboard, and shows your first test key (dk_test_…) once. Copy it then: keys are stored hashed and cannot be shown again. An example Control Mode budget with a 5000000 micro-USD cap is ready in the account.

Called without a browser, the same link answers JSON: {tenantId, defaultVersion, apiKey: {id, secret, prefix, scope, env, shownOnce}, exampleBudgetId, csrf}.

Sign in later with Email me a sign-in link on the dashboard (or POST /login {email}); links expire after one hour and work once.

2. Your first request

Every API call carries exactly one key as a Bearer token:

cd ~
pwd
export DYNAMO_API_KEY=dk_test_…
curl -s -H "Authorization: Bearer $DYNAMO_API_KEY" "$DYNAMO_BASE_URL/owner/v1/budgets"

The routes behind the key are those of your own tenant: the owner API (/owner/v1/…), the plugin wire (/plugin/v1/…), the merchant API (/merchant/v1/…) and the payee surface (/payee/v1/…), the same shapes a single-tenant deployment answers.

3. Run a starter

Four starters ship in the repository under examples/starters/. Each is one run.mjs file for Node 22.12 or later and reads the two variables above. capped-agent, research-crew and paid-mcp need nothing else; pay-per-use has its own package.json with two dependencies, @dynamoprotocol/sdk and viem. @dynamoprotocol/sdk is not on npm yet, so install it from a local build (SDK).

StarterWhat it shows
capped-agentone budget, one hard cap; ticks past the cap refuse with cap
research-crewa lead agent delegating to narrower child allowances
paid-mcpa tool call that is admitted, metered and signed
pay-per-usean end user tops up by credit card and the app earns per call (needs the credit card rail)

Each starter's README.md beside its run.mjs says what it prints.

cd examples/starters/capped-agent
pwd
node run.mjs

Keys

The dashboard's Keys view lists, creates and revokes keys. From scripts:

RouteBodyNotes
GET /tenant/v1/keys-paginated: {data, next_cursor}
POST /tenant/v1/keys{scope, env?, serviceNode?}answers the secret once
POST /tenant/v1/keys/:id/revoke{}takes effect at once

Scopes:

ScopeCan call
owner/owner/…, /plugin/…, /payee/…, /oracle/…, /tenant/…
read_onlyGET on /owner/… and GET /tenant/v1/settings
wire/plugin/… (gateway plugins and the guard)
merchant/merchant/… for the one serviceNode named at creation

A key used outside its scope is refused with key_scope. Environments: test keys run Control Mode and the test rails. live keys exist so you can wire them in, but run Control Mode only until the release gates open (live_mode_gated).

Versions: Dynamo-Version

Each account has a default API version (the newest at sign-up; see GET /tenant/v1/settings). A request may pin another with the Dynamo-Version header; PUT /tenant/v1/settings {defaultVersion} moves the default. A version the deployment does not know is refused with version_unknown; a route newer than the pinned version answers version_unavailable.

Pagination

List routes added on the hosted tier answer {data, next_cursor}. Pass limit (1 to 100, default 20) and send next_cursor back unchanged as cursor; next_cursor: null is the last page. A cursor from another route is refused with invalid_request. The owner API's older list routes (budgets, approvals, alerts, the revenue log, authority records, fees, tasks) page the same way only when you pass limit or cursor; their list keeps its own key (for example budgets) and next_cursor is added beside it.

Errors

Refusals from the hosted tier's own checks (sign-up, keys, settings, versions, scopes, rate limits and quotas) and from owner routes added in owner-api 1.4.0 or later have this shape; older owner routes add errorDetail only when the request sends Dynamo-Error-Detail: 1:

{
  "error": "key_scope",
  "errorDetail": {
    "type": "authentication_error",
    "code": "key_scope",
    "message": "a read_only key cannot call POST /owner/v1/…",
    "param": null,
    "doc_url": "…/errors/key_scope.md",
    "fix": "this key's scope does not allow this route; create a key with the needed scope in the dashboard"
  }
}

The codes are listed on the error index. A refused request bills nothing.

Limits

Each account has its own request rate, budget, stream and storage quotas. Past the request rate the answer is 429 tenant_rate_limited with Retry-After; past a resource quota it is quota_exceeded. GET /tenant/v1/usage shows the account's usage ledger.

The dashboard

<base>/console/ is the human control console for your account: budgets and spend, the network of each budget, approvals, the request log, revenue, top-ups, people and payments, webhooks, the scheduler, reconciliation, alerts and the main switch, plus Quickstart and Keys. A dashboard session is an HttpOnly, SameSite=Strict cookie; every state-changing call carries the session's CSRF token in X-Dynamo-CSRF (csrf).

The main switch

POST /owner/v1/main-switch/pause {reason?} stops new metered work across every budget of the account; POST /owner/v1/main-switch/resume restarts it. Work already signed stays settleable. The dashboard has the same control.

The CLI

@dynamoprotocol/cli is not published yet. From a clone of the repository, build it once and run it with Node:

cd dynamo-protocol
pwd
pnpm install
pnpm --filter @dynamoprotocol/cli build
pnpm --filter "@dynamo/evidence..." -r build
alias dynamo="node $(pwd)/packages/cli/dist/cli.js"
export DYNAMO_VERIFY="$(pwd)/packages/evidence/dist/cli.js"

dynamo verify runs the full offline verifier (Verify an evidence file offline) named by DYNAMO_VERIFY, or dynamo-verify on your PATH, and exits with its code: 0 PASS, 1 FAIL, 2 usage error. With neither available it exits 2.

Then:

cd ~
pwd
dynamo login --url "$DYNAMO_BASE_URL" --key "$DYNAMO_API_KEY"
dynamo keys list
dynamo main-switch status
dynamo logs tail --limit 20
dynamo verify evidence.json

dynamo --help lists every command.

Building for your own users

Status labels: Live means usable today in Control Mode, Stripe TEST mode or on a local or test chain; Preview means built but behind a switch that is off by default; Release-gated means it needs real money. Live credit card keys and live Circle keys for operator-mode ramps refuse boot in this build. Stablecoin on a public chain is not refused in code: it needs the operator to allow the stablecoin mode and Safe multisig vault roles (threshold 2 or more), and no contract is deployed to a public chain in this release.