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
- Single-tenant core: set
MERCHANT_API_TOKENSto a JSON object of
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.
- Multi-tenant hosted tier: the same routes under
/merchant/v1/…, with
a merchant-scoped key created for one serviceNode (keys). Any other key is refused with key_scope.
Surface
| Endpoint | What 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}/headroom | Remaining cap and network units, rate, finality, unsettled amount, degradation stage |
GET /v1/streams/{id}/finality | Settled-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.json | The 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
- Onboarding is self-contained per funding mode (R6). Control Mode needs
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.
- Settled amounts are asset-denominated (R7). Every amount this API and
the webhooks report is micro units of the funding asset - never integrator-defined units, which price work, not money.
- Sandbox/testnet parity (R9). The endpoints, schemas and finality
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.