Developers

Payout safety you can call from code.

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.

  • Real Lightning verified on regtest
  • Regtest only · mainnet disabled
  • SDK not on npm
  • v0.x · may change

What is here.

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.

TypeScript SDK

@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.

Signed webhooks

HMAC-SHA256 signatures with a timestamp, at-least-once delivery, and a verification helper that rejects bad signatures and replays.

Verifier CLI

Checks a receipt offline and exits with a code your scripts can act on. It sends no telemetry and needs no account.

Idempotency

Execute and retry require an Idempotency-Key. Reusing a key with a different request is rejected.

Roles and keys

API keys carry the role operator, developer or viewer. None of them can approve a payout.

Quickstart: one payout, end to end.

Against a local API on regtest. The wallet connection and approver setup happen in the web app first.

1 · create and submit (TypeScript)
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
2 · approve (TypeScript, run as the approver)
// 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);
3 · execute once, handle uncertainty (TypeScript)
// 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;
}
4 · fetch the receipt (TypeScript)
// 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.

Verify a receipt, offline.

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.

shell
# 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.

Webhooks.

Verify every delivery with the raw body. Deliveries are at-least-once, so de-duplicate on the event id.

TypeScript
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 types

Webhook event types
EventWhen
obligation.submittedA revision was frozen and approval requested.
obligation.approvedEnough valid signed approvals.
obligation.rejectedAn approver declined.
obligation.cancelledCancelled before any send.
payment.dispatchingThe wallet is being asked to pay.
payment.pendingThe wallet reports the payment in flight.
payment.unknownNo reliable answer yet. Do not resend.
payment.settledSettled, with provider-sourced evidence.
payment.failedThe wallet’s record proves the payment failed.
incident.openedA case needs a person’s attention.
incident.resolvedThat case was resolved.

Endpoints.

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.

Payouts and payments

Payouts and payments: API endpoints
MethodPathWhat it does
POST/v1/obligationsCreate a payout obligation (draft). Optional Idempotency-Key.
POST/v1/lnurl/resolveResolve a Lightning Address into a verified invoice for an exact amount (address, amount_msat).
GET/v1/obligationsList obligations, filter by state.
GET/v1/obligations/:idOne obligation with approvals, payment and next safe actions.
PUT/v1/obligations/:idNew immutable revision; voids earlier approvals.
POST/v1/obligations/:id/submitFreeze the revision, bind the policy, request approval.
POST/v1/obligations/:id/approveApprove with a signature over the intent digest (people only).
POST/v1/obligations/:id/executeSend exactly once. Idempotency-Key required. 202 means not yet certain.
GET/v1/payments/:idPayment attempts and settlement evidence.
POST/v1/payments/:id/reconcileAsk the wallet for its authoritative record.
GET/v1/payments/:id/receiptIssue (once) and download the signed receipt for a settled payment.
GET/v1/audit/verifyRe-verify every audit hash chain in the workspace.
POST/v1/webhooksRegister an endpoint; the signing secret is shown once.
GET/v1/public/issuer-keysReceipt-issuer public keys (informational; get your trust root out-of-band).
GET/v1/openapi.jsonThe OpenAPI document, generated from the same contract the server uses.

Batches

Batches: API endpoints
MethodPathWhat it does
POST/v1/batches/previewValidate a payout CSV. Creates nothing.
POST/v1/batchesCreate draft payouts from CSV. label, csv, optional wallet_connection_id. 201.
GET/v1/batches/:idBatch status with per-item states.
POST/v1/batches/:id/submitSubmit every draft item for approval.
POST/v1/batches/:id/executeExecute every approved item; each is single-use and guarded on its own.

Recurring schedules

Recurring schedules: API endpoints
MethodPathWhat it does
GET/v1/schedulesList schedules.
POST/v1/schedulesCreate a schedule. Opens an invoice-needed task each cycle; never pays by itself. 201.
POST/v1/schedules/:id/:actionaction is pause, resume or cancel.
POST/v1/schedules/run-dueOpen invoice-needed tasks for schedules that are due now.
GET/v1/schedule-cyclesCycles (the invoice-needed tasks).
POST/v1/schedule-cycles/:id/invoiceProvide the invoice for a cycle; creates a normal draft payout. 201.

Reports

Reports: API endpoints
MethodPathWhat it does
GET/v1/reports/payoutsPayout report as JSON or CSV. Real settlements only are summed; no fiat values.
GET/v1/reports/recipients/:idStatement for one recipient.

Plans and billing

Plans and billing: API endpoints
MethodPathWhat it does
GET/v1/plansPublic plan catalogue. Prices are hypotheses.
GET/v1/billingCurrent plan, status, entitlements and usage.
POST/v1/billing/checkoutStart a checkout for a plan (plan_id). Sandbox provider by default.
POST/v1/billing/sandbox/completeSandbox only: complete a checkout through the real webhook path.
POST/v1/billing/cancelCancel at the end of the paid period.
POST/v1/billing/webhook/:providerBilling-provider webhook. Signature-verified and idempotent. provider is stripe, paystack or sandbox.

Support and account

Support and account: API endpoints
MethodPathWhat it does
POST/v1/supportOpen a support request; safe diagnostics are attached. 201.
POST/v1/public/supportSupport request without an account. 201.
GET/v1/exportExport all organisation data (no secrets).
plain HTTP
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.

Batches: payouts from a CSV.

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.

TypeScript
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;
}
  • Batches are verified with the practice wallet and automated tests, not against real nodes.
  • Creating a batch needs a plan that includes batches, and counts every valid row against the monthly payout limit. If the rows would exceed it, the whole batch is refused with entitlement_exceeded.
  • Each item is an ordinary payout. It needs its own signed approval, and execution goes through the normal single-use path.
  • Batch status is completed only when every item has settled; partial when some did and some did not.

Recurring schedules never pay by themselves.

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.

TypeScript
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 | cancel

Cadence 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.

Reports and CSV export.

Totals count real settled payouts only. Simulated settlements are listed but never summed, and no fiat values are produced.

plain HTTP
# 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.

Plan limits: 402 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.

TypeScript
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;
}
Current plan limits (from the plan catalogue)
LimitDeveloperStartupGrowthBusinessEnterprise
members351550Unlimited
wallets12515Unlimited
payouts_per_month25250200010000Unlimited
webhooks131050Unlimited
api_keys2520100Unlimited
batchNot includedIncludedIncludedIncludedIncluded
recurringNot includedNot includedIncludedIncludedIncluded
history_days30 days365 daysFull historyFull historyFull history

Read from the plan catalogue the server runs; prices are hypotheses under test. Your live usage: GET /v1/billing or the billing page.

Billing webhooks: the signature scheme.

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.

TypeScript (Node)
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.
  • A missing, wrong or stale signature is 401 unauthenticated. The secret is a server setting, ORYNT_BILLING_WEBHOOK_SECRET.
  • Events are de-duplicated on (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.
  • The sandbox provider uses the Stripe scheme, grants real entitlements to the workspace, and is refused when the server runs in production mode.
  • The Stripe and Paystack mappings follow each provider's documentation but have never been run against a live provider. No real charge has ever happened.

Errors you should handle on purpose.

  • 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.

Building payouts into a product?

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.