Installation

What the SDK needs to run, how it points at a cluster, and four rules to know before the first trade.

Build against the SDK, not against a client generated from the IDL. The SDK has the settlement arithmetic, every refusal the program can raise before you send, and chain access that assumes providers fail. For a client in another language, write to [e-mail].

Requirements

The SDK needs Node 20.19 or later, or Node 22.12 or later. It does not load on Node 20.18 or on 22.0 to 22.11. Wheelman, the bot built on it, needs Node 22.18 or later. @solana/web3.js is a peer dependency (^1.98.0): the SDK uses your copy rather than bundling its own. That matters: two copies of web3.js in one bundle means two PublicKey classes and instanceof checks that fail in ways that are painful to debug.

The package is ESM-only; there is no CommonJS build. Your project needs "type": "module" in its package.json, or .mts files. The setup and the install line are on the Quickstart.

Point it at a cluster

Two environment variables, referenced by name only — never paste an endpoint that carries a token into source, into a command line, or into a screenshot.

Variable	Used by	Shape
SOLANA_RPC_URL	your own Connection	a single endpoint
NEXT_PUBLIC_RPC_ENDPOINTS	the SDK’s pooled reader, read() / readCached()	comma-separated endpoints; unset, it reads the public Solana mainnet endpoint

import { Connection } from '@solana/web3.js';

const url = process.env['SOLANA_RPC_URL'];
if (!url) throw new Error('SOLANA_RPC_URL is not set');

export const connection = new Connection(url, 'confirmed');

Provider endpoints usually put the API key in the URL path, so a log line that prints the endpoint prints a live credential. Keep it in an environment file your version control ignores, and redact the path before you print anything.

Reads that survive a provider outage

If you set NEXT_PUBLIC_RPC_ENDPOINTS, the SDK’s own reader races the two healthiest endpoints, demotes whichever fails, retries across different providers, and — with readCached — returns the last good value marked stale rather than throwing.

import { readCached, AllProvidersFailed } from '@rekt-trading/1000x';

export async function currentSlot(): Promise<{ slot: number; stale: boolean }> {
  try {
    const hit = await readCached('slot', (c) => c.getSlot('confirmed'), 5_000);
    // Render the age. A number that is thirty seconds old and says so beats a spinner.
    return { slot: hit.value, stale: hit.stale };
  } catch (e) {
    if (e instanceof AllProvidersFailed) throw new Error(`every RPC provider failed: ${e.message}`);
    throw e;
  }
}

Four rules to know first

1. Money is bigint, in USDC base units

Not number. A u64 above 2^53 loses exactness as a double — silently, and rounding in a direction nobody chose. Every amount in this SDK is a bigint in base units (six decimals), and division truncates toward zero to match the on-chain engine exactly.

Parse user input with parseUsdc, which is exact and never goes through a float:

import { parseUsdc } from '@rekt-trading/1000x';

export const oneDollar = parseUsdc('1.00');   // 1_000_000n
export const twentyCents = parseUsdc('0.20'); // 200_000n

2. Do not cache Params

Every protocol parameter is governed and tunable on chain without a program upgrade. A cached copy quotes stale terms to a user. Read them from the config account, and surface how old your copy is rather than hiding it.

LAUNCH holds the package’s default values, and they are not the venue’s. It is not a source of truth: show nothing from it and settle nothing against it.

3. A slot index is not a position

The one that costs a builder their second trade rather than their first. Positions live in slots inside one trader account, and slots are reused — index 3 today and index 3 tomorrow are different trades.

So the SDK never hands you a bare index. The handle is PositionRef = { trader, slot, seq }, and settle is called with seq, so a stale handle finds nothing instead of closing a neighbour.

4. A landed open is an order, not a position

An open carries no quote. It is an order: the stake is taken when it lands, and the venue’s next price after a short delay fills it or the order is returned. A wallet can sign it. Read the entry when the order is filled, never at the tap: see orders and closes.

A quote matters only for the instructions that carry one, such as a settle a keeper sends. Its age is judged at execution, against market.maxOracleAgeSlots slots of network time: a governed field, so read it rather than assume it. Those are sent from code, not from a wallet dialog; see quotes and freshness. A short-lived, scoped, revocable session-key delegate can sign the trades a person does make, with no prompt.

And one that is not about the SDK at all: at the barrier the trader receives nothing. If your interface tells a user they keep a fraction of their stake on a knockout, it is wrong.

Check the interface

This is the shape of a first call against the SDK. It runs against nothing — no cluster, no keys — and reads only what the SDK derives locally or ships with:

import { PROGRAM_ID, RUNG_FLOOR_BPS, catalogue, configPda } from '@rekt-trading/1000x';

export function selfTest(): string {
  const errors = catalogue(); // every refusal the program can raise, from the client IDL
  const config = configPda().address; // derived locally, never trusted from a web page
  return [
    `program         ${PROGRAM_ID}`,
    `config PDA      ${config.toBase58()}`,
    `rung floor      ${RUNG_FLOOR_BPS} bps`,
    `error catalogue ${errors.length} entries, codes ${errors[0]?.code} and up`,
  ].join('\n');
}

A live market’s four preset rungs are not a constant: they end at the payout cap, which is governed. Read them with presetRungsBps(rungCeilingBps(market, config.params)) once you have the config.

Where to go next

Quickstart

Read the protocol, price an open, and see what every close would pay.

Session keys

Who signs a trade, and how the program’s session-key delegate works: authorise, fund, sign, revoke.

Quotes and freshness

What a quote is, why 6007 happens, and what to do instead of surfacing a failed trade.

Reading gates

Every refusal, before the action, with its measured value and its threshold.

Opening a position

Build the order, size it, simulate, send, and read its sequence number.

Error handling

What a client must handle, and when retrying helps.