TypeScript client

npm install @sotirea/sdk

It runs on Node 20 or later and other server runtimes with fetch and Web Crypto. It is an ES module with its own types. Its types and methods are generated from the same Go types as the API itself, so they always match what the API serves. MIT licence.

A client

import { Sotirea } from '@sotirea/sdk'

const sotirea = new Sotirea({
  baseUrl: process.env.SOTIREA_API!,
  apiKey: process.env.SOTIREA_API_KEY!,
})

Options also take your own fetch, for timeouts, proxies or tracing, and a userAgent naming your application. Make one client and reuse it.

Server-side only

The client holds your API key, so it belongs on your server. Never use it in a browser or a mobile app, where anyone could read the key. See authentication.

Calling the API

There is one method per operation, named for what it does:

Operation	Method
Who this key is	getMe()
Open a vault	createVault({ reference })
Balances	listBalances({ vault })
Quote a payment	quotePayment(body)
Pay out	sendPayment(idempotencyKey, body)
One payment	getPayment(id)

and so on for every operation in the API reference. Request and answer fields keep the API’s own names, such as vault_id and gas_pool_covers. A list answers a Page with items, page, pageSize, total, totalPages, hasNext and its requestId.

Amounts are strings of the asset’s smallest unit, never numbers: see deposits and finality.

Refusals

A refusal throws a SotireaError with status, code, message, rule, requestId and, when the API says how long to wait, retryAfter:

try {
  await sotirea.sendPayment('payout-42', pay)
} catch (err) {
  if (err instanceof SotireaError && err.rule === 'new_destination') {
    // approve the address first
  }
}

Handle refusals has a fuller example, and errors and refusals lists every rule.

Webhooks

verifyWebhook(secret, headers, rawBody) checks a delivery and answers its event, and paymentEvent, depositEvent and gasPoolEvent read its data by type. See verify webhooks.

Versions

The client follows the API’s version 1: a new minor version adds fields, operations and values, and never removes or changes one. See the changelog.