treasuryprime-sdk

An unofficial, production-grade TypeScript client for the Treasury Prime Ledger API — bank accounts, ACH, wires, book transfers, FedNow, cards, KYC/KYB account opening, check deposit, webhooks, sandbox simulations, and more.

Zero runtime dependencies. Dual ESM/CJS with bundled type declarations. Node.js 18.17+.

Install

npm install treasuryprime-sdk

Quick start

import { Client, TreasuryPrimeError } from "treasuryprime-sdk";

const client = new Client(
  process.env.TREASURY_PRIME_KEY_ID!,
  process.env.TREASURY_PRIME_KEY_VALUE!,
  { environment: "sandbox" }, // default; use "production" when you're ready
);

try {
  const account = await client.accounts.get("acct_0112233445566");
  console.log(`${account.name}: ${account.available_balance} available`);
} catch (err) {
  if (err instanceof TreasuryPrimeError) {
    console.error(`treasury prime error (${err.type}, HTTP ${err.statusCode}): ${err.message}`);
  }
  throw err;
}

Architecture

A lightweight ports-and-adapters (hexagonal) layout, scaled to what an API client actually needs — there's no business logic to isolate, so the boundary that matters is the network:

• Port — Fetch (the shape of the global fetch function) is the one seam between this library and the network. Swap in an instrumented, rate-limited, or test-double implementation via ClientOptions.fetch.
• Adapter — the internal Transport class is the one concrete adapter: it turns method calls into authenticated, retried, JSON HTTP requests and turns responses into typed values or TreasuryPrimeError.
• Domain — every resource (Account, Ach, Wire, Card, ...) is a plain TypeScript interface mirroring the wire format. Each resource's *Service class (AccountService, AchService, ...) is a thin, explicit adapter mapping list/get/create/update/delete onto Transport calls — a repository pattern, with the repetitive plumbing shared via a BaseService<T> and each resource's own file keeping its documented, typed public methods.

Resource coverage

Domain	Client property	Notes
Accounts	accounts	+ lock/unlock, setInterestRate, averageBalances, dailyBalances, transactions, pendingTransactions, generateStatement/fetchStatement, tax documents
Account applications	accountApplications
Account locks	accountLocks	read-only history
Account number reservations	accountNumberReservations
Account products	accountProducts	read-only
ACH	ach	+ cancel
Additional person applications	additionalPersonApplications
Book transfers	books
Businesses	businesses
Business applications	businessApplications
Cards	cards	+ activate/suspend/terminate/reissue; get supports show_pan/show_cvv via options.query
Card auth loop endpoints	cardAuthLoopEndpoints
Card events	cardEvents	read-only
Card products	cardProducts
Checks	checks	+ cancel, stopPayment
Check deposits	checkDeposits
Counterparties	counterparties
Deposits (account funding)	deposits
Deposit sweeps	depositSweeps
Digital wallet tokens	digitalWalletTokens	+ provisionWithApplePay, provisionWithGooglePay
Documents	documents
FedNow	fednow	+ routingNumberStatus
Files	files	raw upload/download/get
Green Dot	greendot	+ locations
Incoming ACH	incomingAch	+ returnTransfer
Incoming wires	incomingWires	read-only
Invoice account numbers	invoiceAccountNumbers
KYC	kyc
KYC products	kycProducts	read-only
Manual holds	manualHolds	+ release
Network transfers	networkTransfers
People	people
Person applications	personApplications
Reserve accounts	reserveAccounts
Routing numbers	routingNumbers	read-only lookup
Statement configs	statementConfigs
Transactions	transactions
Webhooks	webhooks	+ enable/disable
Wires	wires	+ cancel
Marqeta	marqeta	jsAccessToken, uxToolkitAccessToken (for Marqeta-processor programs)
Sandbox simulations	simulation	create (general) + achStatus, wireStatus, checkDepositStatus, fedNowReceive, greendotComplete, cardAuthRequest

Idempotency

Every create accepts an idempotencyKey option:

import { generateIdempotencyKey } from "treasuryprime-sdk";

const key = generateIdempotencyKey();
const ach = await client.ach.create(
  {
    account_id: "acct_1",
    counterparty_id: "cp_1",
    amount: "104.20",
    direction: "debit",
  },
  { idempotencyKey: key },
);

Generate one key per business operation and persist it alongside that operation — reuse it across retries of the same operation rather than minting a fresh one per HTTP call.

Pagination

list() returns a Page<T>, which implements AsyncIterable<T> — the idiomatic way to consume it is for await...of, which fetches pages lazily and stops as soon as you break:

const page = await client.ach.list({ query: { status: "pending" } });

for await (const transfer of page) {
  if (transfer.amount === "0.00") break; // no further pages are fetched
  console.log(transfer.id, transfer.status);
}

// or, eagerly collect everything:
const all = await page.all();

// or iterate page-by-page instead of item-by-item:
for await (const p of page.pages()) {
  console.log(`got a page of ${p.data.length} items`);
}

Webhooks

import { validateWebhookSignature, WebhookEvent } from "treasuryprime-sdk";

app.post("/webhooks/treasury-prime", async (req, res) => {
  if (!validateWebhookSignature(req.headers["authorization"], whUser, whSecret)) {
    return res.sendStatus(401);
  }

  const event = WebhookEvent.parse(req.rawBody);

  if (event.event.startsWith("ach.")) {
    const ach = await event.fetch<Ach>(client);
    // handle ach
  }

  res.sendStatus(200);
});

Treasury Prime intentionally sends a thin payload and doesn't guarantee delivery order — always re-fetch via WebhookEvent#fetch rather than trusting embedded state.

Sandbox simulations

await client.simulation.achStatus(achId, "settled");

Fails against a "production" client — Treasury Prime enforces this itself.

Errors

Every network-touching call rejects with a TreasuryPrimeError — always instanceof TreasuryPrimeError, with a type ("api_error", "network_error", "timeout", "validation_error", "decode_error"), and for API errors, statusCode and the decoded response body.

Escape hatch

Endpoints not covered by a typed resource method (or a brand-new one Treasury Prime just shipped) are reachable via the same authenticated, retried transport everything else uses:

const result = await client.request<Record<string, unknown>>("GET", "/some/new/endpoint");

Configuration

const client = new Client(keyId, keyValue, {
  environment: "production",
  maxRetries: 3,
  retryBaseDelayMs: 500,
  maxRetryDelayMs: 10_000,
  receiveTimeoutMs: 30_000,
  fetch: myInstrumentedFetch, // matches the global fetch signature
  onRequest: ({ method, url }) => logger.debug(`${method} ${url}`),
});

Every method also accepts a per-call options object (idempotencyKey, headers, query, signal) as its last argument.

A note on field fidelity

Treasury Prime doesn't publish a single machine-readable schema. The field set here was extracted from a companion, hand-maintained Elixir client and cross-checked against Treasury Prime's docs where available. Entity and params interfaces mirror the wire format directly (snake_case, matching Treasury Prime's JSON) rather than being translated to camelCase, so what you see in a debugger or curl response matches what you see in your editor. Deeply nested, bank-specific, or rarely-documented sub-objects (physical_address, bankdata, card_controls, fx_quote, and similar) are intentionally typed as Record<string, unknown> rather than guessed-at nested interfaces, so this client never silently drops a field Treasury Prime adds or a particular bank partner requires. Verify field-level behavior against Treasury Prime's docs before relying on it for anything money-moving.

Development

npm run check   # typecheck, lint, format check, test
npm run build   # dual ESM/CJS + .d.ts via tsup

License

MIT — see LICENSE.