NodeBlink SDK

Official TypeScript client for the NodeBlink Settlement API. Zero dependencies, Node 18+.

Install

npm install nodeblink-sdk

Quickstart

import { NodeBlink } from "nodeblink-sdk";

const nb = new NodeBlink({ apiKey: process.env.NODEBLINK_SECRET_KEY! });

// 1. Create a settlement for 10 USDC.
const settlement = await nb.settlements.create({
  amount: "10.00",
  recipient: "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
  reference: "order_1234",
  idempotencyKey: "order_1234", // safe to retry
});

// 2. The payer sends USDC including settlement.payment.reference as a key.
//    Then verify with the resulting transaction signature:
const result = await nb.settlements.verify(settlement.id, { signature });

if (result.result === "confirmed") {
  console.log("Paid:", result.amount, "USDC");
}

Webhooks

import { verifyWebhook } from "nodeblink-sdk";

app.post("/webhooks", express.raw({ type: "application/json" }), (req, res) => {
  const event = verifyWebhook(
    req.body.toString("utf8"),          // RAW body, not parsed JSON
    req.header("NodeBlink-Signature"),
    process.env.NODEBLINK_WEBHOOK_SECRET!,
  );
  if (event.type === "settlement.confirmed") fulfill(event.data.object);
  res.sendStatus(200);
});

verifyWebhook throws on a bad/stale signature, so a thrown error = reject.

Test mode

Use an nb_test_… key. verify confirms instantly without an on-chain payment, so you can exercise the whole create → verify → webhook flow for free.

API surface

| Method | Endpoint | | ----------------------------------- | ------------------------------------- | | settlements.create(params) | POST /api/v2/settlements | | settlements.retrieve(id) | GET /api/v2/settlements/{id} | | settlements.verify(id, { signature }) | POST /api/v2/settlements/{id}/verify | | settlements.list({ limit, status }) | GET /api/v2/settlements | | subscriptions.create(params) | POST /api/v2/subscriptions | | subscriptions.retrieve(id) | GET /api/v2/subscriptions/{id} | | subscriptions.list({ status }) | GET /api/v2/subscriptions | | subscriptions.cancel(id, { at_period_end }) | POST /api/v2/subscriptions/{id}/cancel | | subscriptions.charges(id) | GET /api/v2/subscriptions/{id}/charges | | subscriptions.testAdvance(id) | POST /api/v2/subscriptions/{id}/test_advance (TEST) | | webhookEndpoints.create({ url }) | POST /api/v2/webhook_endpoints | | webhookEndpoints.list() | GET /api/v2/webhook_endpoints | | webhookEndpoints.del(id) | DELETE /api/v2/webhook_endpoints/{id} |

See docs/settlement-api.md for the full reference.

Subscriptions (recurring USDC, non-custodial)

const sub = await nb.subscriptions.create({
  amount: "9.99",
  interval: "month",
  periods_approved: 12, // payer approves exactly 12 × 9.99 USDC upfront
});
// Send the payer to sub.approval.url — one wallet signature approves the
// subscription AND pays the first period. Then fulfill on
// `subscription.charged` webhooks (each carries the verified settlement).