TypeScript quickstart

Write and read a blob against testnet in under a minute.

1. Install

npm install stoka

2. Fund a testnet wallet

1. Generate a Stellar wallet — any SEP-43 wallet or a one-liner with the SDK:

   import { Keypair } from "@stellar/stellar-sdk";
   console.log(Keypair.random().secret());

2. Open https://faucet.circle.com/ and pick Stellar Testnet.

3. Paste the wallet's G… public address. You'll receive testnet USDC plus the trustline, both of which the client needs.

Set the seed in your environment:

export STELLAR_SECRET=SXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

3. Store and retrieve

import { createClient } from "stoka";

const client = createClient({
  env: "test",
  secret: process.env.STELLAR_SECRET!,
});

await client.store("greeting", new TextEncoder().encode("hello from ts"));

const buf = await client.retrieve("greeting");
console.log(new TextDecoder().decode(buf.bytes));

The first call triggers a 402 challenge; the client signs it and retries. You'll see ~2–3s of wall time the first time (Soroban RPC simulate).

4. Handle insufficient funds

import { StokaError } from "stoka";

try {
  await client.store("greeting", new TextEncoder().encode("hi"));
} catch (e) {
  if (e instanceof StokaError) {
    console.error("HTTP", e.status, e.body);
  } else {
    // Soroban / network-layer issue — see `e.message`.
    console.error(e);
  }
}

5. Browser flow

import { StokaClient, fromWalletsKit } from "stoka";
import { StellarWalletsKit, WalletNetwork, allowAllModules } from "@creit.tech/stellar-wallets-kit";

const kit = new StellarWalletsKit({
  network: WalletNetwork.TESTNET,
  modules: allowAllModules(),
});
await kit.openModal({ onWalletSelected: w => kit.setWallet(w.id) });
const { address } = await kit.getAddress();

const signer = fromWalletsKit(kit, address, "Test SDF Network ; September 2015");
const client = new StokaClient({
  baseUrl: "https://test.api.stoka.space",
  signer,
});

await client.retrieve("greeting");