@naulix/sdk

Official NAULIX SDK for Node.js. Talks to the NAULIX API the same way the Python SDK does — same resource names, same shapes, same retry + idempotency semantics.

NAULIX is an XRPL-native staged-escrow trade settlement platform. Voyages, generic escrows, P2P RLUSD, webhook endpoints — all surfaced here.

Install

npm install @naulix/sdk

Requires Node 18 or later (uses the built-in fetch + crypto modules — no axios, no node-fetch, zero runtime dependencies).

Quick start

import { NaulixClient } from "@naulix/sdk";

const naulix = new NaulixClient({ apiKey: process.env.NAULIX_API_KEY! });

// Create a voyage — four staged XRPL escrows minted in the background.
const voyage = await naulix.voyages.create({
  originPortLocode:      "IEDUB",
  destinationPortLocode: "DEHAM",
  mmsi:                  "636019825",
  amountRlusd:           10_000,
  sellerXrplAddress:     "rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe",
  buyerXrplAddress:      "rUgw8e2x8wMFeB8N3W2mJj6935wB5wimsm",
});

// Poll until escrow_locked
console.log(voyage["frid"], voyage["status"]);

The key prefix decides which environment you target:

| Prefix | Environment | | ------------ | ----------- | | sk_test_* | sandbox | | sk_live_* | production |

Resources

| Property | Purpose | | ------------------------------ | ----------------------------------------------------------------- | | naulix.voyages | Create + track AIS-tracked voyages with four staged escrows. | | naulix.escrows | Generic XRPL escrow primitive (vesting, marketplace, web3 svc). | | naulix.payments | Generic P2P RLUSD send (remittance). | | naulix.apiKeys | Create / rotate / revoke API keys. | | naulix.webhookEndpoints | Create webhook destinations + manage delivery. |

Errors

Every API failure becomes a NaulixError. Branch on err.code, never on err.message:

import { NaulixError } from "@naulix/sdk";

try {
  await naulix.voyages.create({ /* ... */ });
} catch (err) {
  if (err instanceof NaulixError) {
    if (err.code === "voyage_invalid_port_locode") {
      // surface field-specific UI error
    } else if (err.statusCode === 429) {
      // back off
    } else {
      throw err;
    }
  }
}

Webhooks

The webhook signature helper is standalone — use it whether or not you also use the SDK for outbound calls.

import { verifyWebhookSignature } from "@naulix/sdk";
import express from "express";

const app = express();
app.use(express.raw({ type: "application/json" }));

app.post("/webhooks/naulix", (req, res) => {
  const raw = (req.body as Buffer).toString("utf8");
  const sig = req.header("naulix-signature") ?? "";
  if (!verifyWebhookSignature(process.env.WEBHOOK_SECRET!, sig, raw)) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(raw);
  // event.type, event.data, …
  res.sendStatus(200);
});

Verification uses HMAC-SHA-256 with a constant-time compare. The helper rejects timestamps older than 5 minutes by default — pass { toleranceSec: N } to widen.

Retry + idempotency

Every write call ships with a fresh Idempotency-Key header (UUID v4). Override per-call via the idempotencyKey field if you have your own customer-driven identity.

The transport retries on 5xx and network errors with a fixed exponential schedule (500ms → 1.5s → 4s). 4xx responses are permanent — they throw immediately.

License

Apache-2.0