Availability
It needs Node 20 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.Reads that survive a provider outage
If you setNEXT_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.
Four things that bite, first because they bite first
1. Money is bigint, in USDC base units
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:2. Do not cache Params
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 exists as a fallback for first paint before your first fetch resolves. It is not a
source of truth and you should not settle anything against it.3. A slot index is not a position
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
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.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: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.
