kstablepay-rail-sdk

Node.js SDK for K-STable Pay onchain rail APIs.

Install

npm i kstablepay-rail-sdk

Usage

import { createKstChainClient } from "kstablepay-rail-sdk";

const kstchain = createKstChainClient({
  baseUrl: process.env.PAY_API_BASE_URL!,
  walletSecretKey: process.env.WALLET_SECRET_KEY!,
  timeoutMs: 10000,
});

const issued = await kstchain.signPayload({
  orderNo: "ord_20260321_0001",
  merchantKey: "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  payerAddress: "0xC8313324B6C16Cec8F410ebfE1b22Ff4f5d2DDC8",
  amount: "1000000",
});

const latest = await kstchain.getSignPayload(issued.paymentKey);

const authorized = await kstchain.authorize({
  paymentKey: issued.paymentKey,
  signature: "0x...",
  payloadHash: latest.payloadHash,
});

const command = await kstchain.getCommand(authorized.commandId);
console.log(command.status);

import { createKstTreasuryClient } from "kstablepay-rail-sdk";

const treasury = createKstTreasuryClient({
  baseUrl: process.env.TREASURY_API_BASE_URL!,
  timeoutMs: 10000,
});

const charged = await treasury.chargeToken(
  {
    toAddress: "0xC8313324B6C16Cec8F410ebfE1b22Ff4f5d2DDC8",
    amount: "1000000",
    tokenSymbol: "KST",
  },
  { idempotencyKey: "charge_ord_20260321_0001" },
);

console.log(charged.chargeId, charged.txHash);

API

• health()
• ready()
• signPayload(req, opts?)
• getSignPayload(paymentKey, opts?)
• authorize(req, opts?)
• capture(req, opts?)
• void(req, opts?)
• refund(req, opts?)
• settle(req, opts?)
• getCommand(commandId, opts?)
• confirm(req, opts?)
• createKstTreasuryClient(...)
• treasury.chargeToken(req, opts?)
• treasury.chargeNative(req, opts?)
• treasury.mint(req, opts?)
• treasury.burn(req, opts?)
• treasury.createReserveSnapshot(req, opts?)

Error handling

SDK throws KstApiError for non-2xx or error envelope responses.

import { KstApiError } from "kstablepay-rail-sdk";

try {
  await kstchain.authorize({ paymentKey, signature });
} catch (e) {
  if (e instanceof KstApiError) {
    console.error(e.status, e.code, e.message);
  }
}

Notes

• This SDK is intended for server-side (Node >= 18) usage.
• Do not expose walletSecretKey in browser/frontend code.