REST + OpenAPI
JSON over HTTPS. Errors are RFC 7807 style application/problem+json with a stable code to switch on and a request_id to quote.
Developers
A REST API with an OpenAPI document, a typed TypeScript SDK, signed webhooks and an offline receipt verifier. The samples below are taken from the SDK and the API contract in the repository, and checked against them.
JSON over HTTPS. Errors are RFC 7807 style application/problem+json with a stable code to switch on and a request_id to quote.
@orynt/sdk: a small fetch-based client with typed responses, idempotency helpers and approval-signing helpers. It lives in the repository (packages/sdk) and is not published to npm yet.
HMAC-SHA256 signatures with a timestamp, at-least-once delivery, and a verification helper that rejects bad signatures and replays.
Checks a receipt offline and exits with a code your scripts can act on. It sends no telemetry and needs no account.
Execute and retry require an Idempotency-Key. Reusing a key with a different request is rejected.
API keys carry the role operator, developer or viewer. None of them can approve a payout.
Against a local API on regtest. The wallet connection and approver setup happen in the web app first.
import { OryntClient, OryntApiError, newIdempotencyKey, generateKeyPair, signApprovalBody } from "@orynt/sdk";
const orynt = new OryntClient({
baseUrl: "http://127.0.0.1:8787", // your own Orynt API (regtest)
apiKey: process.env.ORYNT_API_KEY, // starts with "orynt_"; an API key can never approve
});
// 1. Record the obligation. Amounts are whole millisatoshis, sent as strings.
const draft = await orynt.obligations.create(
{
counterparty_name: "Ada (docs contributor)",
amount_msat: "250000000", // 250,000 sats
invoice: "lnbcrt1…", // the payee's BOLT11 invoice
memo: "October docs work",
external_ref: "grant-2026-014",
},
newIdempotencyKey(), // optional: the same key replays the same result
);
// 2. Freeze this revision and request approval.
const submitted = await orynt.obligations.submit(draft.id);
console.log(submitted.state, submitted.intent_digest); // approvers sign this digest// 3. A person approves, as themselves. `approverClient` is an OryntClient bound to that
// person's own session; API keys cannot approve. The key never leaves their device.
const keys = generateKeyPair(); // illustration: in real use, load the approver's stored key pair.
// Its public key is registered once via POST /v1/me/approval-key
const me = await approverClient.me();
const body = signApprovalBody(keys, submitted, me.user.id, me.workspace.id);
await approverClient.obligations.approve(draft.id, body);// 4. Execute, exactly once.
try {
const { obligation, certain } = await orynt.obligations.execute(draft.id);
if (!certain) {
// HTTP 202: the outcome is not known yet (UNKNOWN or RECONCILING).
// Do NOT call execute again. Wait for the wallet's own record instead:
const paymentId = obligation.payment?.id;
if (paymentId) await orynt.payments.reconcile(paymentId);
const resolved = await orynt.obligations.waitUntilResolved(draft.id, { timeoutMs: 120_000 });
console.log(resolved.state); // SETTLED, DEFINITIVELY_FAILED, or still UNKNOWN / RECONCILING
}
} catch (err) {
// A second send while a payment is unresolved is refused with HTTP 409.
if (err instanceof OryntApiError && err.code === "send_blocked_unresolved") {
console.log("Already in motion or unresolved:", err.requestId);
} else throw err;
}// 5. After settlement, download the signed receipt and keep it.
import { writeFileSync } from "node:fs";
const settled = await orynt.obligations.get(draft.id);
if (settled.payment) {
const receipt = await orynt.payments.receipt(settled.payment.id);
writeFileSync("receipt.json", JSON.stringify(receipt, null, 2));
}The one rule to remember.
If certain is false (HTTP 202), the payout is Unknown, not failed. Do not execute again. Reconcile or wait. The API refuses a second send anyway, with send_blocked_unresolved.
The verifier is a separate program that does not contact Orynt. It rejects tampered, replayed, stale or forged receipts, and tells you what a receipt cannot prove.
# Build the verifier once (it lives in the repository, next to the SDK).
pnpm --filter @orynt/verifier build
# Check the receipt offline. Get the issuer's public key out-of-band; do not trust
# a key only because the receipt carries it.
node packages/verifier/dist/orynt-verify.mjs receipt.json \
--trust-key <issuer-public-key-hex> \
--expect-payment-hash <payment-hash-hex> \
--expect-amount-msat 250000000 \
--expect-network regtest
# Exit codes: 0 verified | 1 rejected | 2 usage or file error
# 3 intact, but issuer not trusted | 4 simulator receipt (not a real payment)The verifier lives in packages/verifier. Build it with the command above; no binary is published.
Verify every delivery with the raw body. Deliveries are at-least-once, so de-duplicate on the event id.
import { verifyWebhook, WebhookSignatureError } from "@orynt/sdk";
// Works with any runtime that gives you the raw request body (here: a fetch-style handler).
export async function POST(request: Request): Promise<Response> {
const raw = await request.text(); // the exact bytes; do not re-serialise parsed JSON
try {
const event = verifyWebhook(
raw,
request.headers.get("orynt-signature") ?? "", // format: t=<unix seconds>,v1=<hex hmac>
process.env.ORYNT_WEBHOOK_SECRET!, // shown once when you create the endpoint
);
// Delivery is at-least-once: de-duplicate on event.id.
if (event.type === "payment.settled") {
// mark your own record as paid
}
return new Response("ok");
} catch (err) {
if (err instanceof WebhookSignatureError) return new Response("bad signature", { status: 400 });
throw err;
}
}| Event | When |
|---|---|
obligation.submitted | A revision was frozen and approval requested. |
obligation.approved | Enough valid signed approvals. |
obligation.rejected | An approver declined. |
obligation.cancelled | Cancelled before any send. |
payment.dispatching | The wallet is being asked to pay. |
payment.pending | The wallet reports the payment in flight. |
payment.unknown | No reliable answer yet. Do not resend. |
payment.settled | Settled, with provider-sourced evidence. |
payment.failed | The wallet’s record proves the payment failed. |
incident.opened | A case needs a person’s attention. |
incident.resolved | That case was resolved. |
Every method and path here is checked against the API contract (packages/contract/src/routes.ts) when this site is built. The OpenAPI document served by the API is the full reference; the SDK covers the payout flow, and the newer endpoints below are called with orynt.request or plain HTTP.
| Method | Path | What it does |
|---|---|---|
POST | /v1/obligations | Create a payout obligation (draft). Optional Idempotency-Key. |
POST | /v1/lnurl/resolve | Resolve a Lightning Address into a verified invoice for an exact amount (address, amount_msat). |
GET | /v1/obligations | List obligations, filter by state. |
GET | /v1/obligations/:id | One obligation with approvals, payment and next safe actions. |
PUT | /v1/obligations/:id | New immutable revision; voids earlier approvals. |
POST | /v1/obligations/:id/submit | Freeze the revision, bind the policy, request approval. |
POST | /v1/obligations/:id/approve | Approve with a signature over the intent digest (people only). |
POST | /v1/obligations/:id/execute | Send exactly once. Idempotency-Key required. 202 means not yet certain. |
GET | /v1/payments/:id | Payment attempts and settlement evidence. |
POST | /v1/payments/:id/reconcile | Ask the wallet for its authoritative record. |
GET | /v1/payments/:id/receipt | Issue (once) and download the signed receipt for a settled payment. |
GET | /v1/audit/verify | Re-verify every audit hash chain in the workspace. |
POST | /v1/webhooks | Register an endpoint; the signing secret is shown once. |
GET | /v1/public/issuer-keys | Receipt-issuer public keys (informational; get your trust root out-of-band). |
GET | /v1/openapi.json | The OpenAPI document, generated from the same contract the server uses. |
| Method | Path | What it does |
|---|---|---|
POST | /v1/batches/preview | Validate a payout CSV. Creates nothing. |
POST | /v1/batches | Create draft payouts from CSV. label, csv, optional wallet_connection_id. 201. |
GET | /v1/batches/:id | Batch status with per-item states. |
POST | /v1/batches/:id/submit | Submit every draft item for approval. |
POST | /v1/batches/:id/execute | Execute every approved item; each is single-use and guarded on its own. |
| Method | Path | What it does |
|---|---|---|
GET | /v1/schedules | List schedules. |
POST | /v1/schedules | Create a schedule. Opens an invoice-needed task each cycle; never pays by itself. 201. |
POST | /v1/schedules/:id/:action | action is pause, resume or cancel. |
POST | /v1/schedules/run-due | Open invoice-needed tasks for schedules that are due now. |
GET | /v1/schedule-cycles | Cycles (the invoice-needed tasks). |
POST | /v1/schedule-cycles/:id/invoice | Provide the invoice for a cycle; creates a normal draft payout. 201. |
| Method | Path | What it does |
|---|---|---|
GET | /v1/reports/payouts | Payout report as JSON or CSV. Real settlements only are summed; no fiat values. |
GET | /v1/reports/recipients/:id | Statement for one recipient. |
| Method | Path | What it does |
|---|---|---|
GET | /v1/plans | Public plan catalogue. Prices are hypotheses. |
GET | /v1/billing | Current plan, status, entitlements and usage. |
POST | /v1/billing/checkout | Start a checkout for a plan (plan_id). Sandbox provider by default. |
POST | /v1/billing/sandbox/complete | Sandbox only: complete a checkout through the real webhook path. |
POST | /v1/billing/cancel | Cancel at the end of the paid period. |
POST | /v1/billing/webhook/:provider | Billing-provider webhook. Signature-verified and idempotent. provider is stripe, paystack or sandbox. |
| Method | Path | What it does |
|---|---|---|
POST | /v1/support | Open a support request; safe diagnostics are attached. 201. |
POST | /v1/public/support | Support request without an account. 201. |
GET | /v1/export | Export all organisation data (no secrets). |
curl -X POST "$ORYNT_URL/v1/obligations/$OBLIGATION_ID/execute" \
-H "authorization: Bearer $ORYNT_API_KEY" \
-H "idempotency-key: idem_$(uuidgen | tr -d '-')"
# 200: the outcome is certain.
# 202: not certain yet (UNKNOWN or RECONCILING). Do not call execute again.
# 409 send_blocked_unresolved: a payment for this payout already exists or is unresolved.Up to 200 rows per batch. Header counterparty,amount_sats,invoice, optionally memo and external_ref. Rows are validated one by one: a bad row is reported and never stops the others, and the same invoice twice in one file is flagged.
import { OryntClient, OryntApiError } from "@orynt/sdk";
const orynt = new OryntClient({ baseUrl: "http://127.0.0.1:8787", apiKey: process.env.ORYNT_API_KEY });
// Header: counterparty,amount_sats,invoice (optional: memo, external_ref). Up to 200 rows.
// If an invoice carries an amount, it must equal amount_sats.
const csv = [
"counterparty,amount_sats,invoice,memo,external_ref",
"Ada (docs),25000,<bolt11 invoice>,Docs round 7,PO-1042",
"Bo (tests),40000,<bolt11 invoice>,Docs round 7,PO-1043",
].join("\n");
// 1. Check the file first. Nothing is created.
const { data: preview } = await orynt.request<{ valid: number; invalid: number; total_msat: string; errors: Array<{ row: number; error: string | null }> }>(
"POST", "/v1/batches/preview", { body: { csv } });
if (preview.invalid > 0) console.log(preview.errors); // row-level reasons; good rows are unaffected
try {
// 2. Create draft payouts. Bad rows are reported, good rows are still created.
const { data: batch } = await orynt.request<{ batch_id: string; created: number; failed: number }>(
"POST", "/v1/batches", { body: { label: "Docs round 7", csv } });
// 3. Ask for approval on every draft item. Approvers then sign each one, as for any payout.
await orynt.request("POST", `/v1/batches/${batch.batch_id}/submit`);
// 4. Later: execute every APPROVED item. Each is single-use and guarded on its own.
const { data: run } = await orynt.request<{ items: Array<{ id: string; http: number }>; status: { status: string } }>(
"POST", `/v1/batches/${batch.batch_id}/execute`);
console.log(run.status.status); // in_progress | completed | partial | closed_unsettled
} catch (err) {
// 402 entitlement_exceeded: the plan has no batches, or the rows would exceed the monthly payout limit.
if (err instanceof OryntApiError && err.code === "entitlement_exceeded") console.log(err.requestId);
else throw err;
}entitlement_exceeded.completed only when every item has settled; partial when some did and some did not.A Lightning invoice is single-use and expires, so a schedule cannot hold one. Each cycle becomes an “invoice needed” task instead, and only one task can exist per schedule per cycle.
import { OryntClient } from "@orynt/sdk";
const orynt = new OryntClient({ baseUrl: "http://127.0.0.1:8787", apiKey: process.env.ORYNT_API_KEY });
// A schedule NEVER pays by itself. A Lightning invoice is single-use, so each cycle opens an
// "invoice needed" task. You supply the invoice; it becomes a normal draft payout.
const { data: schedule } = await orynt.request<{ id: string }>("POST", "/v1/schedules", {
body: {
counterparty_id: "<counterparty uuid>",
amount_sats: "50000",
memo: "Monthly stipend",
cadence: "monthly", // "weekly" | "monthly"
first_due: "2026-12-01", // YYYY-MM-DD
},
});
// Opens a task for every schedule that is due (at most one per schedule per cycle).
await orynt.request("POST", "/v1/schedules/run-due");
const { data: cycles } = await orynt.request<{ data: Array<{ id: string; cycle: string; status: string }> }>("GET", "/v1/schedule-cycles");
const waiting = cycles.data.find((c) => c.status === "awaiting_invoice");
if (waiting) {
// The payee sends a fresh invoice; the result is an ordinary draft that still needs approval.
await orynt.request("POST", `/v1/schedule-cycles/${waiting.id}/invoice`, { body: { invoice: "<bolt11 invoice>" } });
}
await orynt.request("POST", `/v1/schedules/${schedule.id}/pause`); // pause | resume | cancelCadence is weekly or monthly. Recurring schedules need a plan that includes them. Amounts are given in sats as a string here (amount_sats); payouts elsewhere use millisatoshi strings.
Totals count real settled payouts only. Simulated settlements are listed but never summed, and no fiat values are produced.
# JSON report. Only real settlements are summed; simulated ones are listed but never added up. No fiat values.
curl "$ORYNT_URL/v1/reports/payouts?from=2026-11-01&to=2026-11-30" \
-H "authorization: Bearer $ORYNT_API_KEY"
# The same report as CSV, for a spreadsheet or an accountant.
curl "$ORYNT_URL/v1/reports/payouts?from=2026-11-01&to=2026-11-30&format=csv" \
-H "authorization: Bearer $ORYNT_API_KEY" -o payouts.csv
# Filters: from, to (dates), counterparty_id, state, format=json|csv.
# One recipient's statement: GET /v1/reports/recipients/:id
# How far back a report reaches depends on the plan (history_days); older rows are not returned.entitlement_exceeded.Plan limits are enforced on the server, so an API call that would exceed one is refused with HTTP 402 and the code entitlement_exceeded.
import { OryntClient, OryntApiError } from "@orynt/sdk";
const orynt = new OryntClient({ baseUrl: "http://127.0.0.1:8787", apiKey: process.env.ORYNT_API_KEY });
try {
await orynt.webhooks.create({ url: "https://example.com/orynt-hook", events: ["*"] });
} catch (err) {
if (err instanceof OryntApiError && err.code === "entitlement_exceeded") {
// HTTP 402. The problem body says which limit, on which plan, and how much is used.
const p = err.problem as unknown as { entitlement?: string; plan?: string; limit?: number; used?: number };
console.log(err.httpStatus, p.entitlement, p.plan, p.limit, p.used);
// Free a resource or change plan in the app (/app/billing). Retrying the same call will not help.
} else throw err;
}| Limit | Developer | Startup | Growth | Business | Enterprise |
|---|---|---|---|---|---|
members | 3 | 5 | 15 | 50 | Unlimited |
wallets | 1 | 2 | 5 | 15 | Unlimited |
payouts_per_month | 25 | 250 | 2000 | 10000 | Unlimited |
webhooks | 1 | 3 | 10 | 50 | Unlimited |
api_keys | 2 | 5 | 20 | 100 | Unlimited |
batch | Not included | Included | Included | Included | Included |
recurring | Not included | Not included | Included | Included | Included |
history_days | 30 days | 365 days | Full history | Full history | Full history |
Read from the plan catalogue the server runs; prices are hypotheses under test. Your live usage: GET /v1/billing or the billing page.
POST /v1/billing/webhook/:provider is called by a billing provider, not by your code. It is public, so every request is authenticated by its signature, and each event is applied at most once.
import { createHmac } from "node:crypto";
// How the billing webhook at POST /v1/billing/webhook/:provider is authenticated.
// You normally never send this yourself: the billing provider does. This shows the scheme, e.g. for tests.
const secret = process.env.ORYNT_BILLING_WEBHOOK_SECRET!; // server-side secret
const raw = JSON.stringify({ id: "evt_123", type: "checkout.session.completed", created: Math.floor(Date.now() / 1000) /* … */ });
// :provider = "stripe" or "sandbox": header Stripe-Signature: t=<unix seconds>,v1=<hex>
// v1 = HMAC-SHA256(secret, `${t}.${rawBody}`), and the timestamp must be within 5 minutes.
const t = Math.floor(Date.now() / 1000);
const stripeStyle = `t=${t},v1=${createHmac("sha256", secret).update(`${t}.${raw}`).digest("hex")}`;
// :provider = "paystack": header x-paystack-signature: <hex>
// HMAC-SHA512(secret, rawBody)
const paystackStyle = createHmac("sha512", secret).update(raw).digest("hex");
console.log(stripeStyle, paystackStyle);
// A valid, repeated event is acknowledged with 200 {"received":true,"result":"duplicate"}; it can never grant an entitlement twice.401 unauthenticated. The secret is a server setting, ORYNT_BILLING_WEBHOOK_SECRET.(provider, event id). A repeat, an out-of-order older event, or an unknown subscription is acknowledged 200 so the provider stops retrying; the body says applied, duplicate, stale or ignored.sandbox provider uses the Stripe scheme, grants real entitlements to the workspace, and is refused when the server runs in production mode.send_blocked_unresolved (409): a payment already exists or is unresolved. Wait and reconcile.approval_stale (409): the policy changed after approval. Submit again.idempotency_conflict (422): that key was used with a different request.mainnet_disabled (409): mainnet execution is switched off on this server.entitlement_exceeded (402): a plan limit. See plan limits.Stability.
Version 0.x. Routes, fields and event payloads may change without notice. Nothing here is a stable, supported interface yet. It has had an AI-assisted review but no human security audit. Every error code is in the help center.
Create a free account, get an API key and try the flow on regtest. Tell us where the API gets in your way: early feedback from developers shapes it directly.