SDK Installation#

How to install and configure the Seesaw SDKs.

Seesaw ships two SDK families per language — see the SDK family matrix for how to choose.

TypeScript Packages#

Install#

# Trust-based (API client + instruction builders + PDA helpers + codecs)
npm install @seesaw/core

# Trustless (account resolution from any Solana RPC; depends on @seesaw/core)
npm install @seesaw/trustless @seesaw/core

yarn add / pnpm add work identically.

Publishing status: public registry publication (npm, crates.io, PyPI) is planned as part of Plan D phase 2. Until that lands, install from the monorepo using the workspace paths (packages/core, packages/trustless, packages/sdk-rust, packages/sdk-python, packages/trustless-rust, packages/trustless-python).

Dependencies#

@seesaw/core ships its Solana Kit v6 dependencies as regular dependencies — there are no peer dependencies to install:

@seesaw/trustless depends only on @seesaw/core, @solana/addresses, and @solana/instructions. It performs RPC calls with plain fetch — no RPC SDK required.

What you bring: a signing/sending stack. The SDKs build Kit Instruction values; compiling, signing, and submitting transactions is your side of the boundary. Use the Kit v6 packages directly (@solana/transaction-messages, @solana/transactions, @solana/keys, @solana/rpc) or any Kit-compatible wallet adapter. Do not mix in legacy @solana/web3.js objects (PublicKey, Transaction) — the types are not compatible.

# Typical signing/sending companions for a Node.js script
npm install @solana/rpc @solana/keys @solana/transactions @solana/transaction-messages @solana/functional

Module format and TypeScript configuration#

Both packages are ESM-first with a CJS fallback ("type": "module", dual exports map with import and require conditions, bundled .d.ts types). They work from both import and require(), but a modern resolution mode is required for the exports map:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "node16",
    "moduleResolution": "node16",
    "strict": true,
    "skipLibCheck": true
  }
}

Notes:

• target must be ES2020 or newer — the SDKs use native bigint for all quantities.
• moduleResolution: "bundler" (with module: "esnext") also works for bundled apps (Vite, Next.js, etc.).
• The packages are developed against TypeScript ~5.7.

Program ID#

The program address is exported directly — prefer this over hardcoding:

import { PROGRAM_ADDRESS } from '@seesaw/core';

// Mainnet program ID: SEEsawgSrxRsgtKRbaThZFEKrVqX3Y64hDipTWyi8F8
// (no separate devnet deployment at this time)
console.log(PROGRAM_ADDRESS);

Every PDA helper, instruction builder, and the TrustlessResolver accept an optional trailing programAddress parameter that defaults to PROGRAM_ADDRESS — you only pass it when targeting a test deployment.

For the full constants reference (PDA seeds, fee curve, time constants, CU estimates), see Constants.

Environment Setup#

# .env
SOLANA_RPC_URL=https://your-rpc-provider.example     # any standard Solana RPC
SEESAW_API_URL=https://api.seesaw.markets            # trust-based reads only

• The trustless family needs only SOLANA_RPC_URL.
• The trust-based API client defaults to the production API; pass apiUrl to createSeesawClient to override (staging: https://api.staging.seesaw.markets).
• WebSocket streams default to wss://api.seesaw.markets/ws; override with the wsUrl option.

Wallet Setup (Node.js)#

Kit v6 represents signers as CryptoKeyPair (WebCrypto). Loading a standard Solana CLI keypair file:

import { readFileSync } from 'node:fs';
import { createKeyPairFromBytes } from '@solana/keys';
import { getAddressFromPublicKey } from '@solana/addresses';

const bytes = new Uint8Array(JSON.parse(readFileSync('/path/to/wallet.json', 'utf-8')));
const keyPair = await createKeyPairFromBytes(bytes); // expects 64 bytes
const walletAddress = await getAddressFromPublicKey(keyPair.publicKey);

In browsers, use a wallet-standard adapter; the SDK never needs your key — it only needs your wallet address to build instructions, and your wallet signs the assembled transaction.

Verify the Installation#

This script needs nothing but an RPC endpoint — it enumerates live markets directly from chain state:

import { TrustlessRpc, listMarkets } from '@seesaw/trustless';

const rpc = new TrustlessRpc({ url: process.env.SOLANA_RPC_URL! });
const markets = await listMarkets(rpc);

console.log(`Found ${markets.length} Seesaw markets`);
for (const { address, market } of markets.slice(0, 5)) {
  console.log(address, 'marketId:', market.marketId.toString());
}
console.log('SDK installed successfully!');

Trust-based equivalent (hosted API):

import { createSeesawClient } from '@seesaw/core';

const client = createSeesawClient({ apiUrl: 'https://api.seesaw.markets' });
console.log(await client.api.markets.current());

Common Issues#

BigInt serialization#

JSON.stringify throws on bigint. If you log SDK values as JSON:

JSON.stringify(value, (_k, v) => (typeof v === 'bigint' ? v.toString() : v));

ERR_REQUIRE_ESM / resolution errors#

The packages use an exports map. If imports fail to resolve, set moduleResolution to node16 (or bundler) in tsconfig.json — the legacy "node" (node10) mode does not read exports conditions.

RPC rate limits#

Public RPC endpoints rate-limit getProgramAccounts aggressively; market discovery (listMarkets) is the heaviest call. Use a dedicated provider, and note that TrustlessRpc automatically uses Helius's paginated getProgramAccountsV2 when available (configurable via the gpaV2 option) and supports per-provider auth headers:

const rpc = new TrustlessRpc({
  url: 'https://your-node.example',
  headers: { Authorization: `Bearer ${process.env.RPC_API_KEY}` },
  commitment: 'confirmed', // default
  timeoutMs: 30_000, // default
});

Other Languages#

Rust#

[dependencies]
# Trust-based: instruction builders, PDA derivation, codecs.
# Optional features: "http" (REST client), "rpc" (solana-client integration).
seesaw-sdk = { path = "packages/sdk-rust" }

# Trustless: validated account resolution from any RPC node.
seesaw-trustless = { path = "packages/trustless-rust" }

See the Rust SDK Guide and the Trustless guide.

Python#

# Trust-based (solders-based)
cd packages/sdk-python && pip install -e ".[dev]"

# Trustless
cd packages/trustless-python && pip install -e .

See the Python SDK Guide and the Trustless guide.

Next Steps#

• Learn Reading Data
• See Building Transactions
• Review Examples
• Go deeper with the Trustless SDK