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).
| Starter | What it shows |
|---|---|
capped-agent | one budget, one hard cap; ticks past the cap refuse with cap |
research-crew | a lead agent delegating to narrower child allowances |
paid-mcp | a tool call that is admitted, metered and signed |
pay-per-use | an 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:
| Route | Body | Notes |
|---|---|---|
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:
| Scope | Can call |
|---|---|
owner | /owner/…, /plugin/…, /payee/…, /oracle/…, /tenant/… |
read_only | GET 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.
- Top-up page (Live in Stripe TEST mode; live card keys Release-gated): an end user funds their own budget by credit card.
- Widgets, budget links and the portal (Live): show an end user what their money funds and let them freeze or revoke it.
- Human payments (Live): fund a budget, pay a person or an agent, see what you receive, and the network of people and agents.
- Ramps (Preview, Circle sandbox; operator mode with live keys Release-gated): the on-ramp into a stablecoin budget and the off-ramp to a bank account.
- KYA (Preview, test mock provider only): require an attested agent verification level in a mandate.
- Card agent programs (Preview, offline mocks and Stripe TEST only): fund a root credit card budget with a Mastercard Agent Pay or Visa Intelligent Commerce token whose controls only narrow the mandate.
- Test agents and payees (Live): reserved service nodes that approve, refuse, run slow, dispute or fail settlement, in Control Mode.
- Fees (Live): the stated credit card pricing, the fee ledger and the revenue summary.
- Credit card rail: TEST mode and the live-ready switch (live mode Release-gated): payees verified while the core runs, and the live safeguards.
- Getting paid as a payee (Live on a local chain): prove your address, register where you are paid, collect and settle vouchers with your own key, offer terms.
- Contract version 2 (Live on a local chain; not on a public chain): what changes for a budget on the second stablecoin contract, how an operator turns it on, and user-owned budgets.
- Adopted payment rails (library preview, not selectable by core configuration): the x402, MPP, Circle and Solana rails.
- Webhooks (Live): signed webhook endpoints and the event catalogue.