Getting paid as a payee

This guide is for a service that is paid through Dynamo: its address is the serviceNode of the streams that pay it. You keep your own key. The core signs vouchers for the work you deliver and hands them to you; you settle them yourself, or (on contract version 2) a relayer submits them for you and the contract still pays your address. The core never holds your key: a core configured with a payee key refuses to boot, in every mode (Control Mode too).

Status: Live on a local chain and in Stripe TEST mode. Settling real money is Release-gated.

Everything below is on the payee surface, payee-api/0.1.0. It is pre-1.0 and may change with a note in the core-host CHANGELOG.

Vouchers are handed to payees only in the stablecoin mode. On a Control-only core /payee/v1/vouchers is not registered and answers a plain 404; /payee/v1/destinations and /payee/v1/terms/* exist on every core.

Run a payee-kit core locally

This section needs a single-tenant local core (the operator guide), Foundry (anvil, forge, cast) and a clone at DYNAMO_REPO.

  1. Start a local chain with contract version 2. Keep it running; it

prints the environment block for the core and the Anvil dev keys of two payees (PAYEE_1, PAYEE_1_KEY, …); prefix that line with export in each terminal you use as the payee or the owner.

cd "$DYNAMO_REPO"
pwd
pnpm install --frozen-lockfile
pnpm --filter @dynamo/core-host... -r build
make dev-chain
  1. In a second terminal, boot the core in the stablecoin mode with payee-kit

custody. Paste the addresses make dev-chain printed; the owner key is Anvil dev account 1 and the gas-only relayer key Anvil dev account 7, public test keys.

cd "$DYNAMO_REPO"
pwd
export DYNAMO_OWNER_TOKEN="dp-local-owner-$(openssl rand -hex 16)"
export CORE_KEY_ENCRYPTION_KEY="$(openssl rand -hex 32)"
OWNER_API_TOKEN="$DYNAMO_OWNER_TOKEN" PLUGIN_WIRE_TOKEN="dp-local-wire-$(openssl rand -hex 16)" \
  OWNER_API_PORT=8790 CORE_DB="$PWD/.dynamo-local/payee-$(date +%s)" \
  CORE_ALLOWED_MODES=none,usdc CORE_ESCROW_SETTLEMENT=payee-kit \
  CORE_ESCROW_RPC_URL=http://127.0.0.1:8545 \
  CORE_ESCROW_V2_VAULT=0xV2_VAULT CORE_ESCROW_V2_ASSET=0xV2_ASSET CORE_ESCROW_V2_ASSET_REGISTRY=0xV2_REGISTRY \
  CORE_ESCROW_OWNER_KEY=0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d \
  CORE_ESCROW_V2_RELAYER_KEY=0x4bbbf85ce3377467afe5d46f804f221813b2bb87f24d81f60f1fcdbf7cbf4356 \
  node deploy/image/entry.mjs
  1. Open a stablecoin budget and a stream that pays PAYEE_1, and meter

some work. The full request and response shapes are in the core's OpenAPI document, GET /owner/v1/openapi.json (no token needed).

cd "$DYNAMO_REPO"
pwd
export DYNAMO_BASE_URL=http://127.0.0.1:8790
AUTH="Authorization: Bearer $DYNAMO_OWNER_TOKEN"
BUDGET=$(curl -s -X POST "$DYNAMO_BASE_URL/owner/v1/budgets" -H "$AUTH" -H "content-type: application/json" \
  -d '{"funding": "usdc", "capTotal": "5000000"}' | node -pe 'JSON.parse(require("fs").readFileSync(0)).budgetId')
STREAM=$(curl -s -X POST "$DYNAMO_BASE_URL/owner/v1/budgets/$BUDGET/streams" -H "$AUTH" -H "content-type: application/json" \
  -d "{\"serviceNode\": \"$PAYEE_1\", \"ratePerSecondUnits\": \"1000000\", \"capUnits\": \"2000000\"}" \
  | node -pe 'JSON.parse(require("fs").readFileSync(0)).streamId')
sleep 2
curl -s -X POST "$DYNAMO_BASE_URL/owner/v1/streams/$STREAM/ticks" -H "$AUTH" -H "content-type: application/json" \
  -d '{"units": "700000"}'
  1. As the payee, prove your address and collect and settle your vouchers

(the sections below).

Anvil must run with a block time (make dev-chain uses one second). On Anvil's default, where a block is mined only when a transaction arrives, the latest block can be older than the voucher's signing time and a settle reverts with SignedInFuture (shown as custom error 0xd663ef37 by tools without the vault ABI). Mine a block (cast rpc evm_mine) or pass --block-time 1.

Prove your address

Every /payee/v1/* request carries one of two credentials.

A Dynamo-Payee v2 proof (owner-api 1.9.0). A proof is made for one request and works once. It signs, each on its own line: dynamo-payee-auth-v2, the deployment's audience (GET /payee/v1/audience), your address in checksummed (EIP-55) form, the HTTP method, the exact path with the query string in canonical form (pairs sorted by key then value, each percent-encoded per RFC 3986), the SHA-256 (hex) of the exact body bytes you send (an empty body hashes the empty string), a fresh 16-byte nonce (32 lowercase hex) and the current Unix time in seconds. Sign with your serviceNode key (an EIP-191 personal signature; a contract account is checked through ERC-1271 where the deployment has a chain) and send

Authorization: Dynamo-Payee v2;payee=<address>;aud=<audience>;ts=<unixSeconds>;nonce=<nonce>;body=<sha256>;sig=<signature>.

It is valid for 300 seconds, at this deployment (or tenant) only, for this method, path and body only, once. @dynamoprotocol/payee-kit 1.0.0 (PayeeClient.authorize, signPayeeRequest) and the Python dynamoprotocol 1.0.0 (PayeeClient.authorize, sign_payee_request) build it for you.

cd ~
pwd
AUD=$(curl -s "$DYNAMO_BASE_URL/payee/v1/audience" | jq -r .audience)
ADDR=0xYourServiceNodeAddress
AT=$(date +%s)
NONCE=$(openssl rand -hex 16)
BODY_SHA=$(printf '' | shasum -a 256 | cut -d' ' -f1)
MSG=$(printf 'dynamo-payee-auth-v2\n%s\n%s\nGET\n/payee/v1/vouchers\n%s\n%s\n%s' "$AUD" "$ADDR" "$BODY_SHA" "$NONCE" "$AT")
SIG=$(cast wallet sign --private-key "$PAYEE_KEY" "$MSG")
curl -s "$DYNAMO_BASE_URL/payee/v1/vouchers" -H "Authorization: Dynamo-Payee v2;payee=$ADDR;aud=$AUD;ts=$AT;nonce=$NONCE;body=$BODY_SHA;sig=$SIG"

A payee credential. The budget owner can mint a credential for one serviceNode with POST /owner/v1/scoped-credentials {"kind": "payee", "serviceNode": "0x…", "payeeConsent": {…}}. The consent is yours: a dynamo-payee-consent-v1 signature over the audience, your address, the grantee (GET /payee/v1/audience answers it: owner, or the tenant), the scope payee-credential, the credential's expiry, a fresh nonce and the time (PayeeClient.consent(expiresAt) in either kit). It mints one credential, once, and the credential stops working at the expiry you chose. The secret (dsc1.payee.…) is shown once; it reaches the /payee/v1/* reads and deliveries, the payment records of streams paying you, and (owner-api 1.8.0) POST /plugin/v1/meter for those streams; nothing else (credential_scope). It never sets where you are paid: POST /payee/v1/destinations and POST /payee/v1/offramps take only your own v2 proof. It is revoked with POST /owner/v1/scoped-credentials/:id/revoke.

A missing or refused proof answers 401 payee_credential, with a reason naming the check (for example payee_proof_replayed or payee_proof_audience); a refused consent answers 400 payee_consent.

Migrating to payee-kit 1.0

The address-and-time proof (Dynamo-Payee <address>.<unixSeconds>.<signature> over dynamo-payee-auth-v1) is refused on every route at every Dynamo-Version (payee_proof_v1): whoever held one could use it on any payee route for five minutes, including setting where you are paid. There is no switch to accept it.

authorize(method, pathAndQuery, body) for each request and send exactly the body you signed (Python: content=, not json=).

(PayeeClient.consent(expiresAt)) instead of payeeProof; a payeeProof answers 400 payee_proof_v1.

credential there answers 403 credential_scope. A credential minted before the change keeps working for everything else.

Register where you are paid

GET /payee/v1/destinations lists your destinations; POST /payee/v1/destinations adds one.

where proof is an EIP-191 signature by the destination address over dynamo-payout-destination-v2, newline, the deployment's audience (GET /payee/v1/audience, the same one your proofs name), newline, your serviceNode, newline, the destination address. The earlier text without the audience (dynamo-payout-destination-v1) is refused at every version. A destination equal to your serviceNode is verified. A different address is recorded as pending_v2: neither contract version in this release pays a separate payout address, so the contract pays your serviceNode.

a Stripe Connect account (TEST mode) and answers an onboardingUrl until the account is verified. Status is verified, pending or restricted; the core re-reads the account on each Connect webhook before applying it. This needs the credit card rail configured on the core, which on the hosted entry means a real Stripe TEST secret key (STRIPE_SECRET_KEY, sk_test_…) and CORE_CARD_PAYEES; there is no keyless simulator setting (the Stripe TEST simulator is injected by tests only). Without them the card destination answers 409 card_rail_not_configured.

{"rail": "wire", "bankAccountId": "…"}, the off-ramp's only payout destination; see Ramps. With ramps off a wire destination is refused as an unknown rail (400).

Collect and settle your vouchers

GET /payee/v1/vouchers answers the latest signed voucher per stream that pays you. A voucher is cumulative: settling the latest one pays everything up to it.

The payee kit (@dynamoprotocol/payee-kit for TypeScript, dynamoprotocol.payee for Python, both unpublished in this release) verifies each voucher offline against the signers you expect, settles it with your own key, and claims before every deadline. Its README is packages/payee-kit/README.md in the repository. Both kits verify version 1 and version 2 vouchers offline. Settling with your own key through the kit is tested on contract version 1; on version 2 the operator's relayer submits your vouchers (see Contract version 2).

On the local setup above (contract version 2) the core's relayer submits your vouchers and the contract pays PAYEE_1; read them with GET /payee/v1/vouchers and check them with the kit's verifyVoucher. The kit's own-key settle example below is for a contract version 1 vault, which make dev-chain does not deploy; run it from the repository root with your key against a version 1 deployment:

cd "$DYNAMO_REPO"
pwd
pnpm --filter @dynamoprotocol/payee-kit... -r build
DYNAMO_BASE_URL=http://127.0.0.1:8790 RPC_URL=http://127.0.0.1:8545 \
  PAYEE_KEY="$PAYEE_1_KEY" BUDGET_OWNER=0x70997970C51812dc3A010C7d01b50e0d17dc79C8 \
  node packages/payee-kit/examples/settle.mjs

It prints the settle transaction for each stream, then your earnings: the voucher total, what is settled on chain, and what is unsettled. While your settle is pending, the owner's checkpoint on the stream answers 409 state_conflict ("handed to the payee; awaiting its settle").

Claim before the deadline. A voucher signed before a stream's cut-off (at or before it on version 2) stays settleable for a window that depends on the contract version; on version 2 it is 7 days after the cut-off. When a stream is revoked, the core hands its last voucher over at once. Each voucher item then carries cutoffAt (the cut-off, unix seconds) and, on version 2, deadline (the last second it can settle); domainVersion names the contract version the voucher is signed for. Both kits verify a version 2 voucher against that version and refuse one signed after cutoffAt before any transaction; claimBeforeDeadlines (Python: claim_before_deadlines) uses deadline unless you pass your own deadlineOf (Python: deadline_of). The two kits answer the same shared vectors (packages/payee-kit/vectors/).

Offer terms

A deployment with a terms catalogue lets you offer objective service terms (machine-measurable metrics only) that a payer accepts when opening a stream to you. On contract version 2, value delivered after an attested breach of those terms can be refunded to the payer from held value inside the holdback window; matured value is never refunded.

Pending claims (contract v2, R-313)

If a USDC-style blocklist (or a token that returns false from transfer) rejects the payee or fee collector on releaseHeld, the vault still finishes the release: it credits pendingClaims and emits PaymentDeferred. Everyone else in that call is still paid. The recipient later calls claim(asset) on BudgetVaultV2 (only msg.sender can claim its own credit). In payee-kit:

const owed = await payee.pendingClaim({ chainId, vault, asset });
if (owed > 0n) await payee.claimPending({ chainId, vault, asset });

The core raises a settlement.failed alert with code payment_deferred to the budget operator; the owner console budget page lists any pending claims and the claim step.

(1 to 16 terms, from 60 seconds to 30 days): answers 201 with the offer, its id (tof_…) and its termsFingerprint.

answers 404.

Without a catalogue these answer 409 terms_unavailable. A payer accepts your offer by id at stream open (terms on POST /owner/v1/budgets/:id/streams).

On version 2 a breach report counts on chain only from a breach signer you accepted for that stream (acceptBreachSigner). Accept only signers you trust to report objective facts.

Errors you may see

credential_scope, terms_unavailable, terms_not_in_catalogue, terms_offer_expired, hop_parent_signer.