TypeScript API reference

Package: stoka (ESM + CJS; Node ≥ 20, modern browsers).

Top-level

createClient(options)

Factory that builds a StokaClient from a Stellar secret. The recommended entry point for server-side usage.

createClient({
  env?: "prod" | "test",       // default "prod"
  baseUrl?: string,             // override env URL
  secret: string,               // Stellar S… seed
  rpcUrl?: string,              // required for pubnet
}): StokaClient

BASE_URL, STELLAR_NETWORK

export const BASE_URL = {
  prod: "https://api.stoka.space",
  test: "https://test.api.stoka.space",
};
export const STELLAR_NETWORK = {
  prod: "stellar:pubnet",
  test: "stellar:testnet",
};

Classes

StokaClient

Low-level constructor. Use when bringing a wallet signer (browser or remote) instead of a local secret.

Method	Purpose
manifest()	GET /.well-known/stoka.json — pricing + x402 config. Free.
store(key, body, ttl?)	POST /v1/store — create a new blob. Paid.
update(key, body, ttl?)	PUT /v1/object/{key} — overwrite a blob. Paid.
retrieve(key)	GET /v1/retrieve/{key} — fetch a blob. Paid.
delete(key)	DELETE /v1/object/{key} — free, wallet-signed.
usage(days?)	GET /v1/me/usage — per-day USDC counters. Free.

Constructor:

new StokaClient({
  baseUrl: string,
  signer: WalletSigner,
  signMessage?: (message: string) => Promise<string>, // hex-encoded sig
  rpcUrl?: string,
})

StokaError

Thrown for any non-2xx server response. Fields:

• status: number — HTTP status.
• body: unknown — decoded JSON or raw text.

Signer interface

WalletSigner

interface WalletSigner {
  readonly address: string;           // G…
  readonly networkPassphrase: string;
  signAuthEntry(preimageXdr: string): Promise<string>; // base64 signature
}

fromSecret(secret, network?)

In-process keypair implementation. Network defaults to testnet.

fromSecret(secret: string, network?: "stellar:testnet" | "stellar:pubnet"): WalletSigner

fromWalletsKit(kit, address, networkPassphrase)

Adapter for @creit.tech/stellar-wallets-kit. Imported structurally — the SDK is not a hard dependency.

Subpath export

stoka/x402

Standalone x402 "exact" scheme signer. Use outside stoka to integrate x402 payments into your own service:

import { buildExactPayment, fromSecret } from "stoka/x402";

const built = await buildExactPayment(
  { scheme: "exact", network: "stellar:testnet", asset: "CBIE…",
    payTo: "GAA…", maxAmountRequired: "1170",
    extra: { areFeesSponsored: true } },
  fromSecret(process.env.STELLAR_SECRET!),
);

fetch(url, { headers: { "X-PAYMENT": built.xPayment }, /* … */ });

Error helpers

explainSimulateError(raw), SimulateError

Parses a Soroban RPC HostError: Error(Contract, #N) string into a structured SimulateErrorInfo (kind, code, symbol, hint, events, raw). The paid-flow code wraps simulate failures as SimulateError so consumers can branch on funding issues vs. unknown host failures.