SDK & API

TypeScript SDK

The @rustag/sdk package exposes a single client class, RustagClient, that wraps a running stagenet's REST API (default base http://localhost:9000). It targets the REST surface, not the Solana JSON-RPC port — for transactions you point a @solana/web3.js Connection at the stagenet's RPC URL instead.

Construction

import { RustagClient } from "@rustag/sdk"; const client = new RustagClient({ baseUrl: "http://localhost:9000" });

RustagClientOptions has two optional fields: baseUrl (default http://localhost:9000; trailing slashes are stripped) and fetch (a custom fetch implementation, e.g. for Node runtimes without a global fetch). The default global fetch is bound to globalThis to avoid the browser's “Illegal invocation” error; if no fetch is available, the constructor throws. getStagenet() returns the stagenet's rpcUrl, which you can hand straight to @solana/web3.js:

const stagenet = await client.getStagenet();await client.airdrop(wallet, 1000); import { Connection } from "@solana/web3.js";const connection = new Connection(stagenet.rpcUrl); // http://127.0.0.1:8899

Client methods

Phase 1 — available in the local MVP:

• health() → { status } — liveness check.
• getStagenet() → StagenetInfo — id, name, network, slot, rpcUrl, wsUrl, mirrorEnabled, mainnetRpc, and account/transaction/dirty counts.
• listAccounts({ limit?, offset? }) → AccountInfo[] — newest-touched first.
• getAccount(pubkey) → AccountInfo — lazily mirrored from mainnet if not local.
• listTransactions({ limit? }) → TransactionInfo[].
• airdrop(pubkey, sol) → { signature, lamports } — unlimited, instant, free.
• overrideAccount(params) → { ok } — set lamports and/or raw SPL tokenBalance.
• preload(programs) → { loaded, unknown }.

Phase 2 Phase 2 · Preview — depends on the corresponding background workers being enabled on the server:

• listSchedules(), createSchedule(params), deleteSchedule(id), toggleSchedule(id, enabled).
• getMetrics({ series?, limit? }) → analytics time-series, each point { t, v }.
• simulate(transactions, { label?, encoding? }) → ScenarioReport — replay signed transactions against an isolated fork (the base is never mutated).

await client.getStagenet();await client.listAccounts({ limit: 100 });await client.getAccount("<PUBKEY>");await client.airdrop("<PUBKEY>", 1000);await client.overrideAccount({ pubkey: "<PUBKEY>", lamports: 5_000_000_000 });await client.preload(["jupiter", "pyth", "raydium"]); const report = await client.simulate([signedTxBase64], { label: "swap-scenario" });console.log(report.succeeded, "/", report.total, "ok in", report.durationMs, "ms");

REST API

The REST API is an axum router mounted under /api, served on http://127.0.0.1:9000 by default. It is the surface consumed by the dashboard and the SDK; CORS is permissive.

Phase 2 Phase 2 · Preview endpoints — require the scheduler / metrics / simulation workers to be enabled:

curl -s http://127.0.0.1:9000/api/airdrop \  -H 'content-type: application/json' \  -d '{"pubkey":"<PUBKEY>","sol":1000}'# => { "signature": "...", "lamports": 1000000000000 }

JSON-RPC compatibility

A stagenet speaks a Solana-compatible JSON-RPC dialect, so a wallet or a @solana/web3.js Connection can point at it and just work. The RPC server listens on http://127.0.0.1:8899 and accepts a JSON-RPC 2.0 body at POST /; both single requests and batch arrays are supported. The advertised version is { solana-core: 2.1.0, feature-set: 0 }.

Any method outside this list returns JSON-RPC error -32601 (“method not found”). Encoded transactions are decoded as base58 first, falling back to base64, unless an explicit encoding is supplied.

import { Connection } from "@solana/web3.js"; const connection = new Connection("http://127.0.0.1:8899");const balance = await connection.getBalance(pubkey);await connection.requestAirdrop(pubkey, 2_000_000_000);

WebSocket subscriptions

The WebSocket server listens on ws://127.0.0.1:8900. In Phase 1 subscriptions are poll-based (≈1s interval):

• accountSubscribe → returns a subscription id, then pushes an accountNotification whenever the account's (lamports, data length) fingerprint changes.
• signatureSubscribe → one-shot; fires once the transaction is found, then auto-cancels. This is what @solana/web3.js uses, so sendAndConfirmTransaction / confirmTransaction work out of the box.
• slotSubscribe → accepted for compatibility, but no slot stream is emitted.
• accountUnsubscribe / signatureUnsubscribe / slotUnsubscribe → cancel a subscription.