> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rekt.money/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> What the SDK needs to run, how it points at a cluster, and the four things that bite integrators first.

The SDK is what you build against. It is not a generated IDL client — those are a solved problem —
it is the layer above one: the settlement arithmetic, every refusal the program can raise *before*
you send, and chain access that assumes providers fail.

## Availability

<Warning>
  **The SDK is not public yet.** It is not on npm or on any other registry, and there is no
  install command for it. The pages in this section describe its interface.
</Warning>

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.

<Note>
  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](/sdk/quickstart#set-up).
</Note>

## 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 |

```ts theme={"dark"}
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.

```ts theme={"dark"}
import { readCached, AllProvidersFailed } from '@rekt/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 things that bite, first because they bite first

<AccordionGroup>
  <Accordion title="1. Money is bigint, in USDC base units" icon="hashtag">
    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:

    ```ts theme={"dark"}
    import { parseUsdc } from '@rekt/1000x';

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

  <Accordion title="2. Do not cache Params" icon="rotate">
    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.
  </Accordion>

  <Accordion title="3. A slot index is not a position" icon="key">
    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.
  </Accordion>

  <Accordion title="4. A landed open is an order, not a position" icon="key">
    **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](/sdk/orders).

    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](/sdk/quotes). A short-lived, scoped, revocable
    [session-key delegate](/sdk/sessions) can sign the trades a person does make, with no prompt.
  </Accordion>
</AccordionGroup>

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:

```ts theme={"dark"}
import { PROGRAM_ID, RUNG_FLOOR_BPS, TIERS, catalogue, configPda } from '@rekt/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`,
    `leverage tiers  ${TIERS.join(', ')}`,
    `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

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/sdk/quickstart">
    Read the protocol, price an open, and see what every close would pay.
  </Card>

  <Card title="Session keys" icon="key" href="/sdk/sessions">
    Who signs a trade, and how the program's session-key delegate works: authorise, fund, sign,
    revoke.
  </Card>

  <Card title="Quotes and freshness" icon="satellite-dish" href="/sdk/quotes">
    What a quote is, why `6007` happens, and what to do instead of surfacing a failed trade.
  </Card>

  <Card title="Reading gates" icon="traffic-light" href="/sdk/gates">
    Every refusal, before the action, with its measured value and its threshold.
  </Card>

  <Card title="Opening a position" icon="paper-plane" href="/sdk/opening">
    Build the order, size it, simulate, send, and read its sequence number.
  </Card>

  <Card title="Error handling" icon="bug" href="/sdk/errors">
    What a client must handle, and when retrying helps.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.