Frequently asked questions

Short answers to the questions people ask most. Every feature named here carries one of three labels:

Nothing on this page is a promise about real money.

The basics

What is Dynamo?

Dynamo is a protocol for streaming payments across networks of service nodes. One parent budget is split into capped, revocable, per-second allowances called streams, and every payment is a signed voucher. It works for any metered service, not only AI: the metered quantity is called units and a payee is called a serviceNode.

What are budgets, streams and vouchers?

A budget is a funded ceiling with an owner. A stream is an allowance from a budget to one service node, with its own cap and a per-second rate. A stream can open child streams for other agents, which is how a network of agents shares one budget. A voucher is the signed record of how much a stream has spent; the last signed voucher is the billing truth. Live.

How can a budget be funded?

Three ways:

Is real money live?

No. Real-money settlement is Release-gated. A deployment keeps money modes off unless its operator turns them on, live credit card keys and live Circle keys refuse to start, and live API keys on the hosted tier run Control Mode only. Stablecoin is not refused in code: real funds are held back by the operator's configuration and a check that the vault's owner and fee collector are Safe multisigs.

Is anything published yet?

Not yet. The SDKs, plugins and tools are built and tested in the repository; none is on npm or PyPI, so you run them from a clone.

Caps and control

How do caps work?

Every spend is checked against the stream's own cap, every ancestor's cap and the budget's network cap, and against the rate allowed so far. The first check that fails refuses the request, and nothing is billed for it. Live.

Can a sub-agent spend more than the agent that hired it?

No. A child stream's cap can never exceed its parent's remaining headroom, and a child's mandate can only narrow its parent's. Live.

How do I stop spending?

From the narrowest to the widest:

Each action writes a signed record. Live.

If I revoke a stream, is the work already done lost?

No. A revoke signs and settles the stream's work first; if a settlement fails, the revoke still goes ahead and lists what was not settled. Work covered by a voucher signed before the revocation stays settleable for the payee: on contract version 2 for 7 days, on contract version 1 until the payer closes the budget.

Can I raise the cap on a running stream?

No. A running cap or mandate can only be tightened, never widened. To give more room, open a new stream or budget.

What is a mandate?

The rules a budget's funder sets: which categories of service, how deep delegation may go, which payees are allowed or refused, time windows, per-transaction and per-period limits, approval thresholds, the lowest payee identity level, and the lowest agent verification level. A funder who sets none gets a safe default. Mandates never look at the content of a request. Live.

What is an approval?

When an open or a reservation crosses a mandate's approval threshold, it is held, not refused for good. Spending is held for approval only through a reservation: a direct meter or tick without a reservation is not held, and is bounded by caps, limits and the rate envelope instead. The owner approves or rejects it in the console or through the approvals routes. Live.

What is the main switch?

One signed owner instruction that pauses every budget on a deployment and resumes exactly what it paused. While paused, signed work keeps settling. Live.

Errors and refusals

What does a 402 mean?

A gateway plugin (for example the LiteLLM plugin or the guard) answers 402 when the caller's allowance is absent, cannot be verified, is used up, has been stopped, or its local view is too old to trust. Each plugin adds refusals of its own (the LiteLLM plugin, for example, refuses a model or call it cannot price or bound, and waits while a meter journal left by a crash replays); its page lists them. The plugin decides on its own machine, without a network call in the request path, and fails closed. The fix is usually more headroom: a new stream or budget.

What does a 409 from the owner API mean?

The request was refused for a named reason, and nothing was billed. Every refusal carries one stable code with a page under error codes; send Dynamo-Error-Detail: 1 to get the precise code, a fix line and a link to its page.

Why does my refusal say cap when the budget is not used up?

Older clients see the reasons they already know, so their response shape never changes: mandate limits, policies and held approvals arrive as cap; a freeze, stop or amendment arrives as revoked; the rate, exposure and payer-concurrency limits keep their own reasons. Send Dynamo-Error-Detail: 1 to see the precise reason.

What is checkpoint_pending?

A short, bounded wait near the end of a budget: the stream's unsettled work is checkpointed first, then the same request is admitted. The SDKs wait and retry for you; other clients retry after the Retry-After header.

Why is a payment refused with rate right after a stream opens?

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.

Am I charged for a call that failed?

No, if it failed before delivering anything. A refused call, or one that failed before any output reached you, bills nothing, and no fee is earned on units that never billed. A call that streamed output to you and then failed bills its reserved bound, because the delivered output is final.

Will a retry bill me twice?

No. A retried request with the same requestRef is billed exactly once, and a success is returned only after a voucher covering it is signed.

Refunds and disputes

Who decides a refund?

AI inference (text, image, video or raw compute time) carries no refunds, as is the industry norm: a delivered result is final. Refunds exist only on services that developers build on Dynamo, and only where the developer chooses to offer them: the developer writes objective terms into the budget (what counts as a failure, how much is returned, by when), and the user sees and accepts them before using the service. Dynamo enforces exactly those terms and never judges or decides a refund itself; terms and verified-value settlement are Preview and off by default. Unspent budget that returns to the payer when a budget closes or a branch stops is not a refund: that money was never spent.

How do refunds work?

A payee can offer objective terms, such as a latency or error-rate threshold, that the payer accepts when the stream opens. A signed breach report from a signer the payer accepted stops the stream, and the value after the breach is returned to the buyer first, from held funds, inside the holdback window. A terms stream holds settlements back for at least its longest term window; if the payer names no holdback, for that window plus 900 seconds. Preview: terms need a terms catalogue, which is off by default; where it is on, they run in Control Mode, on the credit card rail in TEST mode and on contract version 2 on a local chain. Outside terms, the default holdback is 300 seconds, and by default a stream may declare 0 to 86,400.

What happens after the holdback window?

The units are final and a refund is refused at the protocol level. From then on it is a matter of the payee's own terms, and the evidence export gives both sides the record.

How do disputes work?

Recourse cases cover objective facts only: a breach of accepted terms, a task milestone that was not delivered, or a payment that does not match its record. The payee answers with its own signature; any money moves only through the existing refund paths and never above the disputed amount. Live; cases about a breach of terms are Preview, because terms need a terms catalogue.

Does Dynamo judge whether work was good?

No. Dynamo accepts objective facts only, such as latency, error rate, availability, unit counts, delivery and explicit acceptance. It never stores or acts on a quality rating.

Keys and security

Who holds the keys?

Each party holds its own, with one exception for a single self-hosted stablecoin deployment: there the budget owner's key (CORE_ESCROW_OWNER_KEY) is configured into the core, and a multi-tenant deployment refuses to start with it. Payers otherwise sign with their own keys, payees settle with their own keys, and an oracle signs in its own process. The core holds its own engine signer, a gas-only relayer key that can move no value, the session keys of Control Mode streams, and a per-stream voucher key the core generates for a stream it opens for a payer (credit card top-ups, human payments, stablecoin adoptions), bounded to that stream's cap and payee, sealed at rest per stream. Where a payer supplies its own session signer (as on the adopted rails), the core uses it instead. A deployment configured with a payee's or an oracle's private key refuses to start.

Will Dynamo support ever ask for my key or token?

Never. Support never asks for private keys, owner tokens, API keys, card numbers or request bodies. If you have pasted one into a ticket, treat it as exposed and rotate it.

How are keys stored?

Session keys, the engine signer and webhook secrets are encrypted at rest with AES-256-GCM under a key-encryption key that the operator keeps outside the data volume. A production deployment refuses to start without it.

Has Dynamo been audited?

An audit package covering contract version 2, the engine and its cryptography, and the hosted service has been prepared. See security and trust for the current status.

How do I report a vulnerability?

Email security@dynamo.zone and please do not open a public issue. Any reproducible path where a missing, malformed, expired, revoked or stale credential still gets service is treated as the most severe class of report.

Evidence

What is an evidence bundle?

A file the budget owner exports for one budget, holding its signed records, vouchers and authority chain. Anyone can check it offline with no network, using dynamo-verify or dynamoprotocol verify. The check proves what was signed; on its own it does not prove billing, which needs the on-chain settlement or the engine-signed payment records beside it. Live.

What if someone edits an evidence bundle?

Verification fails, and the result names the element that was tampered with or is missing.

The hosted tier

What is a tenant?

On a multi-tenant deployment each account is a tenant with its own stores, signer, encryption key, quotas and events. A request with one tenant's credentials cannot see another tenant's data: another tenant's id answers exactly like an id that does not exist. Live.

What is the difference between test keys and live keys?

Test keys (dk_test_…) reach the money modes the operator has turned on, against test rails. Live keys (dk_live_…) run Control Mode only; asking for a money mode answers 409 live_mode_gated.

What are the default quotas?

Per tenant, by default: 1000 budgets, 10000 streams, 600 requests per minute and 512 MiB of storage. Over a quota the answer is 409 quota_exceeded; over the request rate it is 429 tenant_rate_limited with a Retry-After header. The operator can set other quotas.

Integrations

Which agent frameworks are supported?

Plugins exist for the OpenAI Agents SDK (Python and JavaScript), LangChain and LangGraph (Python), LangGraph.js, CrewAI, Google ADK, Claude Agent SDK (Python and TypeScript), the AI SDK, Mastra, Microsoft Agent Framework, Pydantic AI, Strands, NVIDIA NeMo Agent Toolkit, LlamaIndex, n8n and Dify. Each runs Live in Control Mode; none is published yet. See frameworks.

Which gateways are supported?

The LiteLLM plugin and the one-command guard, Kong (also on Kong AI Gateway 2.2), APISIX, Envoy and agentgateway, Bifrost, and a one-api operator recipe. The Kong, APISIX, Envoy and Bifrost plugins pass the same shared conformance vectors, so their refusals look the same; the LiteLLM plugin is checked against the shared credential vectors. Live in Control Mode.

Does Dynamo work with MCP, A2A and x402?

Yes. There is a paid-tool MCP adapter, agents can hire each other over A2A with a draft Bounded Delegation extension, and there is an x402 conformance suite and buyer. Live on local mocks and in Control Mode.

Payees and end users

I am a payee. How do I get paid?

You fetch the vouchers that pay you, verify them offline and settle with your own key, using the payee kit. On the credit card rail, payouts go to your connected account in Stripe TEST mode. Live on a local chain and in TEST mode.

What is the Task Allowance?

A way to pay for delivered work: the payee quotes milestones, delivers, and is paid once the work is accepted, explicitly or by silence when the acceptance window ends. Live in Control Mode, the credit card rail in TEST mode and contract version 2.

What are ramps, KYA and card agent programs?

Ramps move money between a bank account and a stablecoin budget; KYA checks an agent's verification level; card agent programs let a card network's agent token fund a budget. All three are Preview: off by default and run only against sandboxes or mocks. Operator-mode ramps with live keys are Release-gated.

Fees

What does Dynamo charge?

Control Mode has no fee, because no money moves. On the money rails every fee is its own ledger row, tied to the settlement that produced it. No fee is earned before its units are final, the fee on refunded units is reversed, and failed actions carry no fee. On the credit card rail the application fee seeds at 50 bps on the operator's revenue switchboard; contract version 2 caps its protocol fee at 150 bps in the contract itself. See fees.

Running a deployment

Is there an uptime promise?

No. The deployment is built and load-tested to stated objectives, but no figure is promised to customers. Operators can publish a status page built from the core's own monitoring.

Where do I look up an error?

Every code has a page under error codes with the cause, what to do and the response on the wire.