Merchant API - 1.0.0

Not in the preview yet. This feature is built in the repository but is off in the v2.2.6 preview (test mode). Do not treat this page as available on a preview core. See ../preview.md and the release notes.

The serviceNode-facing HTTP surface (R5): verify an allowance aimed at you, read remaining headroom and rate, read the finality state of a settlement, and manage webhook subscriptions. The OpenAPI document (openapi.json) is a versioned artifact at 1.0.0 - regenerated on every build, changed only under the versioning policy (R8). Status: Live in every funding mode the core runs.

Where it is served

bearer token → serviceNode address, and EVENTS_DB to the events database the webhook routes use. The merchant API then listens on its own port, MERCHANT_API_PORT (default 8501), at the paths below. Without both settings it is not served.

a merchant-scoped key created for one serviceNode (keys). Any other key is refused with key_scope.

Surface

EndpointWhat it answers
POST /v1/allowances/verify"Is this credential real, live, and aimed at ME?" - offline JWS check, fail closed
GET /v1/streams/{id}/verify"Is this stream open and payable to me?"
GET /v1/streams/{id}/headroomRemaining cap and network units, rate, finality, unsettled amount, degradation stage
GET /v1/streams/{id}/finalitySettled-frontier finality + billed truth (the last SIGNED voucher)
POST /v1/webhooks · GET /v1/webhooks · DELETE /v1/webhooks/{id}Subscribe / list / revoke event delivery
GET /openapi.jsonThe versioned contract itself

Credit on final only (R2)

checkpointed settlements are visible but pending; only settlement.final (webhook) or finality: "final" (poll) is a credit signal. Everything before that is information, not money.

Posture

nothing. Escrow needs a wallet holding the asset. Card needs one Stripe TEST/platform onboarding - payees are connected accounts. No mode requires the others' credentials.

the webhooks report is micro units of the funding asset - never integrator-defined units, which price work, not money.

semantics do not depend on the rail behind them: the merchant API answers the same shapes in Control Mode, on a local chain and in Stripe TEST mode. Real money is Release-gated (not released): live credit card keys are refused, and a stablecoin mode off a local chain starts only when the operator allows that mode and the vault's owner and fee collector are Safe multisigs with a threshold of two or more.

Auth

Per-serviceNode bearer tokens (MERCHANT_API_TOKENS on a single-tenant core, a merchant key on the hosted tier), ownership-scoped: a caller can never see or affect another node's streams or subscriptions - unknown-or-not-yours answers 404, never 403, so existence is not leaked.

Example

cd ~
pwd
curl -s -X POST http://127.0.0.1:8501/v1/allowances/verify \
  -H "Authorization: Bearer $SERVICE_NODE_TOKEN" \
  -H "content-type: application/json" \
  -d '{"credential": "<the JWS the caller presented>"}'

A valid, live, aimed-at-you credential answers valid: true with its stream, budget, cap and expiry; anything else answers valid: false with a reason. A missing or unknown bearer token answers 401. The same check is available fully offline via the SDK and every gateway plugin - the HTTP form exists for stacks that prefer a service call over an embedded verifier; keep it off the paid request path, where no blocking network call belongs.