Human payments

A person can fund a budget, pay a person or an agent, and see what they receive as a payee, from the console (/console, People and payments) or the routes below, which are owner-api 1.8.0. On the multi-tenant (hosted) tier a request served at an older version (by its Dynamo-Version header or the account's default) gets version_unavailable; a single-tenant core does not check the pin.

Status: Live in Control Mode, Stripe TEST mode and on local chains. Real-money funding is Release-gated.

Limits in this release

list a ramp with available: false and unavailableReason: "ramps_not_built", and nothing calls a ramp. With CORE_RAMPS=circle the ramp can fund stablecoin budgets (operator mode on Circle's sandbox only); see Ramps.

in-repo simulator). No card data reaches Dynamo.

contract version 2 and is exercised on local chains only in this release. A public chain needs the operator to allow the stablecoin mode with multisig vault roles, and stays Release-gated.

sign in your own browser wallet; on a credit card budget the root hop may instead be your signed-in click (a pay-consent, root position only). Pasting a hop you signed elsewhere stays available under Advanced.

the amount; the amount is at most 16 digits of micro-USD.

The key bound

Dynamo never holds a payer's own signing key. For the stream it opens for the payment, the core holds 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. In a credit card or stablecoin budget the person who pays is the budget's root funder: they sign the hop (signHopIntent, sent as delegation) with their own key, and the payee signs its own offer (payeeOffer). The core checks both signatures and holds neither key. Money modes require these signatures by default: a payment with either signature missing is refused with pay_signature_required and nothing is opened. An operator can relax this with CORE_OWN_HOPS=optional, which applies to every mode. Control Mode moves no money and needs no signature.

The key never leaves the wallet. The console and the /pay pages sign with one script served by this deployment (/pay/assets/wallet.js; the pages load no third-party or inline script) that asks the wallet in the page (EIP-1193) for an account (eth_requestAccounts) and a typed-data signature (eth_signTypedData_v4). Only the signature is sent. The core recovers the signer and refuses a hop whose signer is not the hop's delegator (the budget's funder, or the parent stream's payee) with pay_wrong_signer.

Sign with your wallet

GET /owner/v1/human/payments/intent?budgetId=…&payeeServiceNode=…&amountMicroUsd=… (optional parentStreamId, category) returns delegator, the hop intent (a fresh nonce and the hash of the mandate the hop inherits) and its EIP-712 typedData (domain Dynamo Protocol, version 1). Sign typedData with the delegator's wallet and send the payment with delegation: {address, nonce, mandateHash, signature, scheme: "eip712"}. A wallet-signed hop can be sent once: a replayed signature is refused with hop_replay. A declined wallet request sends nothing.

When the budget lives on a chain (stablecoin escrow), the domain also carries chainId, and on contract v2 the vault as verifyingContract; the intent answer names them in chain, and the delegation carries the same chainId (and verifyingContract). A signature made for one chain or vault is refused on another (hop_signature). Credit card and Control budgets keep the two-field domain and take no chain.

A payee signs its offer the same way on /pay/receive (Offer to be paid, signed with your wallet): the page shows the signed offer to hand to the payer, with scheme: "eip712". For a stablecoin payer, enter the payer's chain id (and the contract v2 vault); the offer then carries them and is accepted only on that chain (offer_signature otherwise).

On a credit card budget the payer may choose Consent in the console instead of a wallet. The root hop is then recorded as a pay-consent: the signed-in owner's click, bound to the page's CSRF token, signed by the engine and marked consented in evidence 1.4.0 (a budget with a pay-consent exports only as 1.4.0). A pay-consent is accepted at the root of a payment only; every hop below it is signed with its delegator's own key, and both offline verifiers refuse a pay-consent anywhere else (hop_consent). The payee's signed offer is still required. Clicking again with the same requestRef returns the recorded payment and opens nothing new. An API key or owner token cannot consent (pay_consent_session), and consent is refused on any other funding mode (pay_consent_card_only).

Fund a budget

GET /owner/v1/human/funding-options lists control, card, stablecoin and ramp (and card_agent when card agent programs are on), each with available. Fund a budget with POST /owner/v1/budgets (Control Mode or credit card) or, for stablecoin, the adopt path described in contract version 2.

Pay a person or an agent

cd ~
pwd
curl -s -X POST "$DYNAMO_BASE_URL/owner/v1/human/payments" \
  -H "Authorization: Bearer $DYNAMO_API_KEY" -H 'Dynamo-Version: 1.8.0' \
  -H 'content-type: application/json' \
  -d '{"budgetId":"bud_…","payeeServiceNode":"0x00000000000000000000000000000000000000a1","amountMicroUsd":"250000","requestRef":"rent-2026-10"}'
FieldRequiredMeaning
budgetIdyesthe budget that pays
payeeServiceNodeyesthe address that is paid, a person or an agent
amountMicroUsdyespositive integer micro-USD as a decimal string, at most 16 digits
requestRefyesyour id for this payment (letters, digits, _ . : -, up to 64); a retry with the same value pays once
parentStreamIdnopay from a stream instead of the budget's root
categorynothe hop's category, inside the budget's mandate
delegationin money modes with own hops requiredyour signed hop (address, nonce, signature, optional mandateHash, scheme: "eip712", chainId, verifyingContract)
payeeOfferin money modes with own hops requiredthe payee's signed offer (categories, issuedAt, expiresAt, signature, optional scheme: "eip712", chainId, verifyingContract)
consentnotrue from the signed-in console on a credit card budget's root, instead of delegation
sessionKeyAddressnoowner-api 1.9.0: a session key the payer signs vouchers with itself; library and self-hosted cores only (see below)

A payer-supplied session key. On a library or self-hosted core configured with the payer's session signers (CoreConfig.sessionSigners, never read from the environment), sessionKeyAddress opens the payment's stream on that key and its vouchers are signed through the resolver; the core stores no key for the stream. A key the resolver does not supply is refused with session_signer_missing and nothing is opened; a signature that is not canonical or not the key's is refused with session_signer_mismatch and nothing is acknowledged. The hosted tier answers session_signer_unavailable. Without the field the core generates the stream's key as before.

The answer is returned only after a voucher covering the amount is signed; it carries the payment and the voucher (seq, cumulativeUnits, cumulativeAmount, signedAt, signature). duplicate: true marks a retry that returned the recorded payment. GET /owner/v1/human/payments?budgetId=… lists payments (paginated with cursor, limit 1 to 100).

From the console, a change needs the page's CSRF token and the console's own origin. A read-only API key can read these routes but cannot pay (key_scope).

See the network

GET /owner/v1/human/budgets/:id/network lists every node with the recorded facts about it: root-funder, receives-payments, signs-hops-with-own-key, consent-recorded, pays-from-console-session. A node is shown as a person when consent or a console-session payment is recorded for it, as an agent when it signs hops or receives payments, and as unattributed otherwise. Nothing else is used: no content is inspected and nobody declares what they are. On the multi-tenant tier a payment from the signed-in dashboard is recorded as a console-session payment; one made with an API key is not.

Receive as a payee

GET /payee/v1/receive shows a payee what it is owed: signed, settled and awaiting-settlement totals, its streams and its registered destinations. It is read-only and needs a payee credential (a Dynamo-Payee v2 proof for that request or a scoped payee credential; see getting paid as a payee). The page /pay/receive shows the same view in a browser: paste the credential, it is sent only to this deployment and never stored.

Error codes

pay_signature_required

This budget is in a money mode and requires own hops. Sign the hop with your own key and send it as delegation, with the payee's signed offer as payeeOffer. Nothing was opened.

pay_wrong_signer

The hop signature recovers to an address that is not this hop's delegator. Sign with the wallet of the budget's funder (or the parent stream's payee). Nothing was opened.

Consent is a click in the console while signed in. An API key or owner token cannot consent. Nothing was opened.

Consent pays from a credit card budget's root only. On a stablecoin budget sign with your wallet. Nothing was opened.

pay_intent_unavailable

The delegator has no mandate to sign against, so this budget cannot take a wallet-signed hop.

A pay-consent was placed where it is not allowed: below the root, on a top-up budget, or without its CSRF binding. Nothing was opened.

hop_replay

This hop signature or consent was already used. Get a fresh intent and sign again.

pay_pending

The payment's stream opened this second and cannot bill yet. Retry with the same requestRef after Retry-After. Nothing was billed.

pay_unsigned

No voucher was signed, so nothing was acknowledged. Retry with the same requestRef; it bills exactly once.

pay_frozen

The budget or its parent stream is frozen or stopped. Thaw it from the console first. A retry of a payment already signed still returns it when only the budget is frozen; when the parent allowance (or one above it) is frozen or stopped, the retry gets this refusal too, and nothing is billed twice.

pay_budget_inactive

The budget is closed. Fund a new budget.

payee_no_destination

On a credit card budget the payee has registered no payout destination. See the credit card rail. Nothing was opened.

payee_unverified

On a credit card budget the payee's payout destination is not verified. Nothing was opened.

session_signer_missing

No session signer is supplied for sessionKeyAddress on this deployment. Supply it, or omit the field. Nothing was opened.

session_signer_mismatch

The session signer answered a signature that is not canonical or not the key's. No voucher was signed and nothing was acknowledged; retry with the same requestRef once the signer is fixed.

session_signer_unavailable

The hosted tier takes no payer-supplied session signer. Omit sessionKeyAddress. Nothing was opened.

request_ref_conflict

The requestRef was used for a different payment (or another session key). Use a new one.

csrf_invalid

The change was not sent from the console page served by this deployment.

not_found

No such budget here. Ids are scoped to this deployment.

invalid_request

The body or parameters failed validation; param names the field. Unknown fields are refused.