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

# Session keys

> A scoped, revocable key that signs trades with no wallet prompt: who signs a trade, how to authorise, fund, use, renew and revoke a session key, how to gate before you send, and what a leaked key costs.

An `open`, an `add_collateral` and a `request_close` carry no quote, so a person can approve each one
in a wallet. A **session key** removes the prompt on every trade: the trader authorises a
short-lived, scoped, revocable key once, and that key then signs locally. This page says who can
sign a trade, and documents the session key the program provides.

The instructions that carry a quote are `set_take_profit`, and any `settle`, `stamp_book` or
`prove_price` a client sends itself. A quote ages out in slots, so a person reading a wallet dialog
cannot land one of those: sign it locally. Read [quotes](https://docs.rekt.money/sdk/quotes.md) for the age rule.

## Who can sign a trade

Who signs is an integration decision, and there is more than one reasonable answer. Weigh them for
your own product.

> [card] Your service signs
>
> Your own backend holds, or is delegated, the authority to sign and signs each trade
> programmatically with no per-trade prompt. You choose the custody model and where the key lives.
> Whatever signs holds that authority for as long as it holds the key.

> [card] A scoped delegate
>
> The program provides a **session-key delegate**: the trader authorises a short-lived, scoped,
> revocable key once, and that key then signs locally with no dialog. The rest of this page is its
> reference.

> [card] The trader signs each
>
> The trader approves every open, add and close request in their wallet. None of them carries a
> quote, so each is a single attempt and no clock runs against the prompt. The cost is a prompt on
> every trade.

> [!NOTE]
>
> Whichever you choose, the program checks the signer. The pages on [opening](https://docs.rekt.money/sdk/opening.md),
> [orders and closes](https://docs.rekt.money/sdk/orders.md) and [reading gates](https://docs.rekt.money/sdk/gates.md) do not assume a particular signing
> model. Gas is a separate decision: see [who pays the fee](#who-pays-the-fee).

### Who pays the fee

A Solana transaction has a **fee payer**, and the fee payer signs. That gives you a second axis,
independent of who signs the trade:

* **The user pays their own fee.** Simplest, but the user needs lamports on the key that pays. In the
  delegate model below that is the delegate key, not the wallet.
* **You sponsor the fee.** A fee payer you control is added to the transaction so the user needs no
  SOL. How you fund it is your choice.

The fee payer does not have to be the key that signs the trade. Placing it on a human wallet puts the
prompt back on every trade.

## The program's option: a session-key delegate

The program provides a `TradeDelegate`: a short-lived, scoped, rate-limited key that the trader
authorises once and that then signs locally with no dialog. If you take this route, the human is out
of the trading path.

> [card] It never holds funds
>
> The money stays in the trader's own token account. The session spends against an SPL allowance
> the trader grants. That allowance is the ceiling on what a leaked key can **take**. It is not the
> ceiling on what a leak can **cost**: see
> [what a leak costs](#what-a-session-key-costs-you-if-it-leaks).

> [card] Its trading has a hard deadline
>
> An absolute expiry on the `TradeDelegate`, 24 hours by default, after which the key can neither
> open nor close here. **The SPL allowance has no clock and does not expire with it.** Revoke; do
> not wait.

> [card] Its trading has a spend rate
>
> A decaying budget per window on what the key may OPEN here, metered on the open's `budget`: the
> fee-inclusive total, the money actually at risk. It does not meter the SPL allowance, and by
> default it equals the allowance, so it is not what bounds a leak.

> [card] It is revocable, with one exception
>
> One instruction, effective in the same slot, and it returns the account's rent.
>
> **The exception:** if the USDC account the allowance was granted over is frozen, closed, or has
> been handed to somebody else, the program cannot clear the approval. It ends the session, and the
> allowance survives and comes back the moment the account works again. Clearing it then takes its
> own signature against that account.
>
> The token account is a **required** account on the revoke: pass `TradeDelegate.tokenAccount`,
> read off the chain.

> [!WARNING]
>
> **A session key is an SPL delegate over the trader's own USDC.** Authorising a session approves the
> session key for the allowance on the trader's token account, under the trader's own signature. **A
> token approval names an amount and a key. It does not name a program, and it carries no clock.** A
> holder of the key can therefore sign one SPL `Transfer` of up to the remaining allowance to any
> account it chooses. This venue is not in that path, and neither the spend window, the expiry nor
> `restrictions` applies to it. Expiry ends the trading rights; the approval stands until it is
> revoked. Size the allowance for one session, and revoke on logout rather than letting it expire.

## Using the delegate, step by step

It is five moves. The funding step is the one most often skipped: a session that authorises correctly
and then cannot send anything.

**1. Generate a session key in the client**

An ordinary keypair, created where the trades will be signed. It is not the trader's wallet and
must never be derived from it.

```ts session.ts theme={"dark"}
import { Keypair } from '@solana/web3.js';

/**
 * Generate it here. **WRITE THE SECRET BEFORE YOU SEND THE AUTHORISATION** — step 2 — and
 * remove it only on a decoded REFUSAL, never on an unknown.
 *
 * Scope the storage to the session and clear it on logout, at which point you also call
 * `endSession` (step 5). A session key in durable storage outlives the trader's intent.
 */
export const sessionKey = Keypair.generate();
```

> [!WARNING]
>
> **Persist the secret BEFORE the authorisation is sent, not after it is confirmed.** A key stored
> for an authorisation that never landed costs 64 unused bytes. A key discarded for an
> authorisation that did land leaves the chain holding a `TradeDelegate` naming a public key whose
> secret exists nowhere, with the session's fuel SOL on it and a standing SPL approval on the
> trader's USDC. A confirmation poll that times out on a transaction that landed produces exactly
> that.
>
> **Remove the stored key only on a decoded refusal.** A blockhash expiring does not tell you
> whether a transaction was accepted, so a send you could not confirm must keep the key. See
> [the failures that are not the program's](https://docs.rekt.money/sdk/errors.md#errors-that-are-not-the-programs).

**2. Authorise it — one transaction, one wallet prompt, ever**

`authorizeSession` builds the authorisation. **One instruction sets all three limits**: the
expiry, the spend window, and the SPL token allowance. The program performs the SPL `approve`
itself, so the half the token program enforces cannot go missing.

```ts authorise.ts theme={"dark"}
import { Connection, Keypair, PublicKey, Transaction } from '@solana/web3.js';
import {
  DEFAULT_SESSION_TERMS,
  authorizeSession,
  configPda,
  delegatePda,
  ourInstruction,
  toHex,
} from '@rekt-trading/1000x';

export async function authorise(args: {
  connection: Connection;
  owner: PublicKey;
  /** The trader's own USDC account. The allowance is written against THIS account. */
  traderToken: PublicKey;
  sessionKey: Keypair;
  /** How much this session may spend in total before it must be renewed. */
  allowance: bigint;
  sign: (tx: Transaction) => Promise<Transaction>;
}): Promise<string> {
  const built = authorizeSession({
    owner: toHex(args.owner),
    delegateKey: toHex(args.sessionKey.publicKey),
    delegate: toHex(delegatePda(args.owner).address),
    traderToken: toHex(args.traderToken),
    // Required: the program reads the governed maximum stake off the config account.
    config: toHex(configPda().address),
    // 24 hours, a 24-hour spend window, and the window's ceiling. Override deliberately.
    terms: DEFAULT_SESSION_TERMS,
    // Required, with no default. `0` grants Close and Retarget; `DELEGATE_NO_CLOSE` withholds both.
    restrictions: 0,
    // The SPL allowance is a TOTAL that draws down and never refills. Size it for how long
    // the trader means to be at the desk; the window limit only bounds the rate.
    allowance: args.allowance,
  });

  const tx = new Transaction().add(...built.map(ourInstruction));
  tx.feePayer = args.owner;
  tx.recentBlockhash = (await args.connection.getLatestBlockhash('confirmed')).blockhash;

  // The ONE wallet prompt in the whole arrangement. The trader may take as long as they like
  // reading it.
  const signed = await args.sign(tx);

  // STORE THE SECRET HERE, before the send — not after a confirmation. See step 1.
  persistSessionSecret(args.owner, args.sessionKey.secretKey);

  return args.connection.sendRawTransaction(signed.serialize());
}
```

> [!WARNING]
>
> **The chain holds a delegate and this device does not hold its key — what now?** It is the
> state a confirmation timeout produces. The recovery is **`endSession`** (step 5): it closes the
> delegate account, drops the SPL allowance, is signed by the *trader* rather than by the lost
> key, and returns the rent. Then start a new session. The lost key's SOL cannot be recovered.

> [!NOTE]
>
> Show the trader what they are signing: the expiry, the per-window ceiling and the allowance, in
> dollars. This transaction is the whole of the authority they are handing over, and it is the
> only moment they get to look at it.

**3. Fund it — the session pays its own fee**

If the *owner* pays the fee, the owner signs, and the wallet prompt is back on every trade. So on
this route the fee is paid by a key that is not the human: the session key itself (shown here),
or a separate sponsoring fee payer you add to the transaction (see
[who pays the fee](#who-pays-the-fee)). Either way it needs lamports. The simplest shape funds the
session key in the same moment you authorise it.

```ts fund.ts theme={"dark"}
import { LAMPORTS_PER_SOL, PublicKey, SystemProgram, Transaction } from '@solana/web3.js';

/**
 * Enough SOL for the session's own transaction fees. Send it alongside the authorisation so a
 * trader signs once for both.
 *
 * Return the remainder to the owner when you revoke — a session key that keeps a dust balance
 * after logout is a wallet nobody is watching.
 */
export function fundSession(owner: PublicKey, sessionKey: PublicKey, sol = 0.01): Transaction {
  return new Transaction().add(
    SystemProgram.transfer({
      fromPubkey: owner,
      toPubkey: sessionKey,
      lamports: BigInt(Math.round(sol * LAMPORTS_PER_SOL)),
    }),
  );
}
```

> [!WARNING]
>
> A session that is authorised but unfunded fails at the network layer, before any of this
> protocol's refusals are reached, so none of the gate reports on these pages will explain it.
> Check the session key's lamport balance at start-up and top it up before it reaches zero.

**4. Sign every trade with the session key**

The session **signs and pays**. The book, the token account and the money all stay the owner's:
`authority` is whoever signs, and `delegate` names the session's account so the program can
check it.

```ts trade-with-session.ts theme={"dark"}
import {
  ComputeBudgetProgram,
  Connection,
  Keypair,
  PublicKey,
  TransactionMessage,
  VersionedTransaction,
} from '@solana/web3.js';
import {
  assetId,
  computeUnitLimit,
  configPda,
  delegatePda,
  ix,
  marketPda,
  ourInstruction,
  priceAccountsFor,
  toHex,
  traderPda,
  vaultPda,
  type ConfigView,
  type MarketView,
} from '@rekt-trading/1000x';

export async function openWithSession(args: {
  connection: Connection;
  config: ConfigView;
  symbol: string;
  market: MarketView;
  /** The trader. Signs NOTHING here. */
  owner: PublicKey;
  /** The session. Signs and pays. */
  sessionKey: Keypair;
  traderToken: PublicKey;
  vaultToken: PublicKey;
  protocolToken: PublicKey;
  /** The fee-inclusive TOTAL to spend. The debit is at most this. */
  budget: bigint;
  direction: 'long' | 'short';
  rungBps: number;
  userTimerS: number;
  /** The mandatory floor on the position SIZE — `sizeForTotal(budget, config.params).collateral`.
   *  `0n` is refused (`MinCollateralOutRequired`). */
  minCollateralOut: bigint;
  /** A durable key you choose, or `0n`. Read by nothing on chain. */
  openerTag: bigint;
}): Promise<string> {
  const built = ix.open(
    {
      // Whoever signs. With a session that is the session key, not the owner.
      authority: toHex(args.sessionKey.publicKey),
      trader_token: toHex(args.traderToken),
      config: toHex(configPda().address),
      market: toHex(marketPda(assetId(args.symbol)).address),
      vault: toHex(vaultPda().address),
      vault_token: toHex(args.vaultToken),
      protocol_token: toHex(args.protocolToken),
      // The OWNER's book, always. The session never gets one of its own.
      positions: toHex(traderPda(args.owner).address),
      // `null` here with a signer who is not the owner is refused by the program, so this
      // cannot be used to open against somebody else's book.
      delegate: toHex(delegatePda(args.owner).address),
    },
    {
      // Fee-inclusive TOTAL; the venue takes its fee from inside it.
      budget: args.budget,
      direction: args.direction === 'long' ? 0 : 1,
      rung_bps: args.rungBps,
      user_timer_s: args.userTimerS,
      // Mandatory floor on the position SIZE. Set it to `sizeForTotal`'s predicted collateral,
      // never a token value; `0n` is refused.
      min_collateral_out: args.minCollateralOut,
      referrer: null,
      // `0` is the market's own tier, 1000x: see `/sdk/opening`. The tier is a property of the
      // trade, so a session key and the owner pass the same value.
      tier: 0,
      // A durable key you choose, read by nothing on chain. `0n` is the absence.
      opener_tag: args.openerTag,
    },
    // The market's fee-terms account when it has terms. An order carries no quote.
    priceAccountsFor(args.market, args.config, 'open'),
  );

  const { blockhash } = await args.connection.getLatestBlockhash('confirmed');
  const message = new TransactionMessage({
    // The session pays. An owner fee payer means an owner signature means a wallet prompt.
    payerKey: args.sessionKey.publicKey,
    recentBlockhash: blockhash,
    instructions: [
      ComputeBudgetProgram.setComputeUnitLimit({ units: computeUnitLimit('open') }),
      ComputeBudgetProgram.setComputeUnitPrice({ microLamports: 1_000 }),
      ourInstruction(built),
    ],
  }).compileToV0Message();
  const tx = new VersionedTransaction(message);
  tx.sign([args.sessionKey]);
  // Simulate first, as on /sdk/opening: a refusal costs nothing and arrives as a name.
  const sim = await args.connection.simulateTransaction(tx, { commitment: 'confirmed' });
  if (sim.value.err !== null) throw new Error(JSON.stringify(sim.value.err));
  return args.connection.sendTransaction(tx);
}
```

**5. Revoke on logout**

`endSession` closes the delegate account **and** drops the SPL allowance, in one instruction
signed by the trader. It takes effect in the same slot and returns the account's rent, so
revoking costs less than nothing.

```ts revoke.ts theme={"dark"}
import { Connection, PublicKey, Transaction } from '@solana/web3.js';
import { decodeTradeDelegate, delegatePda, endSession, ourInstruction, toHex } from '@rekt-trading/1000x';

export async function revoke(args: {
  connection: Connection;
  owner: PublicKey;
  sign: (tx: Transaction) => Promise<Transaction>;
}): Promise<string | null> {
  const address = delegatePda(args.owner).address;
  const info = await args.connection.getAccountInfo(address, 'confirmed');
  // No account is not an error — it is a trader with no session, which is the goal state.
  if (!info) return null;

  const delegate = decodeTradeDelegate(new Uint8Array(info.data));

  const built = endSession({
    owner: toHex(args.owner),
    delegate: toHex(address),
    // MUST be the account the allowance was granted over. `TradeDelegate.tokenAccount` is
    // pinned by the chain — read it rather than re-deriving the trader's associated token
    // account and hoping the two agree.
    traderToken: delegate.tokenAccount,
  });

  const tx = new Transaction().add(...built.map(ourInstruction));
  tx.feePayer = args.owner;
  tx.recentBlockhash = (await args.connection.getLatestBlockhash('confirmed')).blockhash;
  const signed = await args.sign(tx);
  return args.connection.sendRawTransaction(signed.serialize());
}
```

> [!NOTE]
>
> Revoke on logout, on wallet disconnect, and on tab close if you can reach it. Also revoke
> when the trader asks: put the control somewhere they can find it, showing the expiry and the
> remaining allowance.

## Gate before you send

Three separate clocks can stop a session, and only two of them belong to this program. Check all
three before you build a transaction. A refusal predicted costs nothing; a refusal discovered costs a
fee and a confusing failure.

```ts session-gates.ts theme={"dark"}
import {
  decodeTradeDelegate,
  delegateGates,
  delegatePda,
  sessionAllowanceGates,
  sessionState,
  toHex,
  type GateReport,
} from '@rekt-trading/1000x';
import { Connection, PublicKey } from '@solana/web3.js';

export async function sessionReports(args: {
  connection: Connection;
  owner: PublicKey;
  sessionKey: PublicKey;
  traderToken: PublicKey;
  collateral: bigint;
  nowUnix: bigint;
}): Promise<{ authority: GateReport; allowance: GateReport; expiresInS: number }> {
  const info = await args.connection.getAccountInfo(delegatePda(args.owner).address, 'confirmed');
  const delegate = info ? decodeTradeDelegate(new Uint8Array(info.data)) : null;

  // The SPL allowance is the clock NO account of this program can see. Read it from the token
  // account itself. Pass `null` if you could not: `sessionAllowanceGates` then refuses to report
  // green, because an unread limit reported as green is how this arrangement fails quietly.
  const parsed = await args.connection.getParsedAccountInfo(args.traderToken, 'confirmed');
  const data = parsed.value?.data;
  const allowance =
    data && 'parsed' in data ? BigInt(data.parsed.info.delegatedAmount?.amount ?? '0') : null;

  const ctx = {
    delegate,
    owner: toHex(args.owner),
    signer: toHex(args.sessionKey),
    nowUnix: args.nowUnix,
    allowance,
  };

  return {
    authority: delegateGates(ctx, args.collateral),
    allowance: sessionAllowanceGates(ctx, args.collateral),
    expiresInS: delegate ? sessionState(delegate, args.nowUnix).expiresInS : 0,
  };
}
```

### The three clocks

| Clock | Who enforces it | How it ends | How you restore it |
| - | - | - | - |
| **Expiry** | this program | an absolute deadline, 24 hours by default | `renewSession` — one trader signature |
| **Spend window** | this program | a decaying budget per window, so it refills continuously rather than resetting on a boundary | wait, or `renewSession` with a higher limit |
| **SPL allowance** | the SPL Token program | a **total** that draws down and never refills | `renewSession`, which carries the `approve` with it |

> [!WARNING]
>
> **The allowance is the one that will surprise you.** A long-running session usually stops not
> because it expired and not because it hit its per-window ceiling, but because the SPL allowance
> reached zero. That refusal arrives from the *token program* as `InsufficientFunds`, carrying none
> of this program's error shape. It reads to a trader as the venue being broken.
>
> The rule that removes the edge: **renew the session and the allowance together, always.**
> `renewSession` does exactly that in one instruction.

```ts renew.ts theme={"dark"}
import { DEFAULT_SESSION_TERMS, configPda, delegatePda, renewSession, toHex } from '@rekt-trading/1000x';
import { PublicKey } from '@solana/web3.js';

/** Renew well before the deadline — a session that expires mid-trade fails the trade, not the tick. */
export function buildRenewal(
  owner: PublicKey,
  sessionKey: PublicKey,
  traderToken: PublicKey,
  /** Read off `TradeDelegate.restrictions` — a renewal re-states the byte rather than keeping it. */
  restrictions: number,
) {
  return renewSession({
    owner: toHex(owner),
    delegateKey: toHex(sessionKey),
    delegate: toHex(delegatePda(owner).address),
    traderToken: toHex(traderToken),
    config: toHex(configPda().address),
    terms: DEFAULT_SESSION_TERMS,
    restrictions,
  });
}
```

> [!WARNING]
>
> **`restrictions` is an argument, not a default.** A renewal re-states the byte: `renewSession`
> writes what it is given, so a hardcoded `0` returns a Close button to a session that had it
> withheld. Read it off `TradeDelegate.restrictions` and pass it back.

## The byte wall

A session open costs about **128 bytes** more than an owner-signed one: the `TradeDelegate` account
(32 B), the session's own signature (64 B) and its pubkey in the account list (32 B). An order carries
no quote, so it still fits Solana's 1,232-byte packet with room to spare. A wrapped open names
Minute's accounts as well as the venue's, and an instruction that carries a quote (a keeper's `settle`)
carries the quote too: those compose a v0 message with the market's address lookup table. Measure your
real byte count with a signed transaction before you send it.

> [!WARNING]
>
> **1,232 bytes is a hard limit for a client built on `@solana/web3.js` v1.** The library serialises a
> message into a buffer of exactly that size. A larger transaction throws `ERR_OUT_OF_RANGE` locally
> and **never reaches the network**, so there is nothing to observe on chain and no error code to
> catch. Keep every transaction within 1,232 bytes; the lookup table is the way.

Choose the lookup table with `chooseMarketTable`. It
tries the market's own table when the SDK names one, then the shared table `SHARED_KIND2_TABLE`, and
returns the first one that passes the SDK's check. It never skips a market for want of a table.

Every table is frozen: nobody can change what it resolves. A new table address reaches you in an SDK
release, and `chooseMarketTable` picks it up. Read a table's contents once and cache them by address
for the life of your process.

Pass as `required` the protocol accounts your transaction names: `config` and `vault` (from the SDK's
`configPda()` and `vaultPda()`) and, if you read it, `vault_token`. Pass `protocol_token`
(`config.treasury`) as `rotatable`, never in `required`: the treasury can change after a table is
frozen, and a table that lacks it costs 31 bytes and a warning, never the table. Never pass a trader's
or a position's account.

```ts lookup-table.ts theme={"dark"}
import { Connection, PublicKey } from '@solana/web3.js';
import type { AddressLookupTableAccount } from '@solana/web3.js';
import { chooseMarketTable, configPda, vaultPda } from '@rekt-trading/1000x';

/** Contents by table address. A frozen table never changes, so this cache never goes stale. */
const cache = new Map<string, AddressLookupTableAccount>();

export async function marketTable(
  connection: Connection,
  marketAddress: PublicKey,
  treasury: PublicKey, // config.treasury, from your own config read
): Promise<AddressLookupTableAccount[]> {
  const chosen = await chooseMarketTable({
    market: marketAddress,
    // The protocol accounts this transaction names. Never a trader's or a position's account.
    required: [
      { name: 'config', address: configPda().address },
      { name: 'vault', address: vaultPda().address },
    ],
    // Can change after a table is frozen: a warning when a table lacks it, never a refusal.
    rotatable: [{ name: 'protocol_token', address: treasury }],
    fetchTable: async (address) => {
      const hit = cache.get(address.toBase58());
      if (hit !== undefined) return hit;
      const got = (await connection.getAddressLookupTable(address, { commitment: 'confirmed' })).value;
      if (got !== null) cache.set(address.toBase58(), got);
      return got;
    },
  });
  // Bytes, never a refusal: an account composed as a static key, or the shared table in for a market's own.
  for (const note of [chosen.standIn, ...chosen.warnings]) if (note !== null) console.warn(note);
  return chosen.table === null ? [] : [chosen.table]; // []: compose legacy, and measure it with dryRun: true
}
```

> [!NOTE]
>
> A market's own table must contain that market and every `required` account. The shared table does
> not contain the markets it serves: a `required` account it lacks composes as a static key (+31 B).
> If you check a table yourself instead of calling `chooseMarketTable`, call
> `marketTableCheckSized({ market, address, table, required, shared })` on each of
> `marketTableCandidates(market)`, and hold each
> table to its own size. One minimum for every table refuses a good table.

> [!NOTE]
>
> `submitBenchmarkQuoted`, the sender for instructions that carry a quote, refuses a lookup table on a
> legacy message rather than dropping it silently. Measure your real byte count with `dryRun: true`:
> it builds and signs exactly what would be sent, and sends nothing.

## Closing: a session key can do it

> [!WARNING]
>
> **A session key CAN request a close, and it can move a take-profit target**, unless its grant
> carries `DELEGATE_NO_CLOSE`.
>
> `request_close` and `set_take_profit` share one authoriser, so a session key authorised for the
> position reaches both. The settle that completes a requested close is sent by anyone, and every
> other close reason (knockout, take-profit, the two expiries, `lastResort` and `borrowSpent`) is
> permissionless and needs no signature from the trader at all.
>
> A grant with `DELEGATE_NO_CLOSE` cannot request a close and cannot move a target.

## What a session key costs you if it leaks

The arrangement is deliberately **weaker** than signing each trade with the wallet. State this to
yourself plainly before you ship:

* **The exposure is the SPL allowance, and the allowance is spendable to any destination.** A leaked
  key can open positions until the allowance, the window budget or the expiry stops it. It can also
  move up to the remaining allowance wherever the holder likes with one SPL `Transfer`, without
  touching this program, so the window and the expiry do not bind that. **It cannot exceed the
  allowance.** Revoking an approval is a separate act from letting a session expire.
* **It CAN close a position and CAN move a take-profit target, unless you withhold that.** A leaked
  key can close a trader out at a moment the attacker chooses, or move a position's target. Size the
  session for it.

  Pass `restrictions: DELEGATE_NO_CLOSE` to `authorizeSession` and the session can neither close nor
  retarget (`DelegateMayNotClose`, 6156). **Passing `0` grants close and retarget.** `restrictions` is
  required on `authorizeSession` and on `renewSession`; omitting it is a build error, and with the types
  erased it throws. **A renewal re-states the byte rather than keeping it**: renew a session with `0`
  and you have granted it a Close button. Read the current value off `TradeDelegate.restrictions`
  (`sessionStanding` returns it as `restrictions`) and pass it in. The raw instructions
  `authorize_delegate` and `renew_delegate` take
  `(duration_s, window_seconds, window_limit, allowance, restrictions)`.

  Bit 1 of `restrictions` is accepted and does nothing. Any other bit is refused
  (`DelegateRestrictionUnknown`, 6157), so check `DELEGATE_RESTRICTIONS_KNOWN` before you send.

  The owner is never restricted by this: a trader signing with their own wallet can close, unless a
  guardian stop is set (`config.settlesDisabled`, or `config.oracleFrozen`, which leaves a priced
  close no price).
* **Revoking clears both halves.** `endSession` ends the session and withdraws the SPL approval in the
  same instruction, so revoke rather than waiting for expiry. **Expiry ends the trading rights and
  does not withdraw the approval.** If the trader's token account was frozen or closed when you
  revoked, send a bare SPL `revoke` against it once it is usable again.
* **Settlement proceeds cannot be redirected.** A settle pays the destination recorded on the book,
  and no session key can change that record.
* **A session key cannot authorise another delegate.** That still needs the owner.
* **Size the allowance for the session, not for the year.** The SDK's default is
  `DEFAULT_DELEGATE_WINDOW_LIMIT`, **\$1,000** (`allowance ?? terms.windowLimit`). A large allowance to
  save a renewal prompt trades the trader's money for your convenience. A small one has a cost too:
  a trader who exhausts it meets a wallet prompt at exactly the moment the session existed to remove
  one. **Pass `allowance` explicitly.** The window limit is a per-window rate ceiling and the
  allowance is a lifetime total: they are two different numbers.
* **Revoke on logout.** It is one instruction, it is instant, and it refunds rent.

## Tell what state a session is in, from the chain

Two accounts, and one call.

**1. Read the delegate PDA**

`delegatePda(owner)` — seeds `[b"delegate", owner]`, one per trader. `decodeTradeDelegate`
gives you `expiresAt`, `delegate`, `windowLimit`, `windowSpent`, `windowSince`, `restrictions`
and `tokenAccount`.

**2. Read TradeDelegate.tokenAccount, and never a guess**

`revokeDelegate` pins its `trader_token` to that exact address and refuses any other with
`WrongDelegateTokenAccount` (6122). `decodeTokenDelegate` reads the SPL side of it: the
account's state, its delegate slot, and the allowance still standing.

**3. Ask for the standing**

`sessionStanding` names the combination, because the combination is what decides what to do.

```ts sessions-state.ts theme={"dark"}
import { chainNowSeconds, decodeTradeDelegate, delegatePda, sessionStanding, unhex } from '@rekt-trading/1000x';
import { PublicKey } from '@solana/web3.js';

const [pda] = await connection.getMultipleAccountsInfo([delegatePda(owner).address]);
const view = pda ? decodeTradeDelegate(new Uint8Array(pda.data)) : null;
const [tok] = view
  ? await connection.getMultipleAccountsInfo([new PublicKey(unhex(view.tokenAccount))])
  : [null];

const standing = sessionStanding({
  delegate: view,
  tokenAccount: tok ? new Uint8Array(tok.data) : null,
  // The chain's clock: the program judges a session's expiry against `Clock.unix_timestamp`.
  nowUnix: BigInt(await chainNowSeconds(connection)),
});
```

| `kind` | the delegate | the SPL approval | `action` |
| - | - | - | - |
| `none` | no account | none | nothing to do |
| `active` | live | live, to this key | `resume` |
| `allowance-exhausted` | live | spent or cleared | `renew` |
| `displaced` | live | live, to **another program's key** | `renew` |
| `expired-approval-live` | **expired** | **live** | `revoke` |
| `expired` | expired | gone | `revoke` |
| `orphaned-approval` | **no account** | live | `revoke-spl-only` |
| `frozen` | either | unreachable | `revoke`, then a bare SPL `revoke` after the thaw |
| `unknown` | — | **not read** | read it |

> [!WARNING]
>
> **`expired-approval-live` is the state to alert on, and no error code will tell you about it.**
> The venue side has a clock; the SPL approval does not, and an expiry does not close the account.
> A trade attempted by an expired key is refused with `DelegateExpired` (6108), which reads as
> *renew and carry on* and says nothing about a standing authority over the trader's USDC.
>
> Pass `tokenAccount: null` for an account you read and found closed. Leave it `undefined` only
> when you have genuinely not looked: `sessionStanding` then answers `unknown` rather than
> calling the session active.

> [!NOTE]
>
> **A token account holds one delegate slot.** SPL Token's `approve` writes it unconditionally, so
> any other program the trader approves takes it from this session, with nothing emitted. The
> session keeps passing every gate this program can check and fails inside the token program on the
> next open. `sessionStanding` reports it as `displaced`; a renewal takes the slot back.

### The four pathways

| pathway | send | who signs | cost | when |
| - | - | - | - | - |
| **resume** | nothing | — | nothing | `kind: 'active'` |
| **renew** | `renewSession` | the **trader**, never the key | one signature, rent unchanged | expired, budget bound, allowance spent, approval displaced, or the key must be rotated |
| **close and reopen** | `endSession`, then `authorizeSession` | the trader, twice | two signatures; rent returned then re-paid | you are changing the token account — a renewal may not move it (`DelegateTokenAccountMayNotChange`, 6137) |
| **revoke** | `endSession` | the trader | **less than nothing** — the account closes to the trader and returns its rent | logout, a leaked key, or any expired session |

* **A renewal resets the spend meter and re-states `restrictions`.** Read the current byte off
  `TradeDelegate.restrictions` and pass it back; `0` is not *unchanged*, it is *this session may
  close positions*.
* **A renewal re-approves the SPL allowance in the same instruction**, so it is the fix for an
  exhausted or displaced approval as well as for an expiry.
* **Rotating a leaked key is a renewal, not a reopen.** `renewSession` takes a different
  `delegateKey`, and the approval moves to it in the same instruction.
* **`endSession` is safe on a session that already expired, and safe to send twice.**

## The refusals a session meets

None of these appear in `openGates`: the program checks them very early, before the other gates in
that report. `delegateGates` predicts the first four; read it.

| Error | Code | Retry | What it means, and the fix |
| - | - | - | - |
| `DelegateExpired` | 6108 | never | The absolute deadline passed. Do not retry with this key. The trader sends `renewSession`, or signs the request directly. |
| `DelegateWindowLimitReached` | 6109 | after-state-changes | This window's ceiling is used up. The budget decays continuously, so waiting works, or renew with a higher limit. |
| `NotTheDelegate` | 6110 | never | The signer is not this trader's authorised key. Re-authorise. |
| `DelegateMayNotSign` | 6115 | never | The owner signed **and** passed the delegate account. Pass `delegate: null` when the owner signs for themselves. |
| `DelegateMayNotClose` | 6156 | never | The session's grant carries `DELEGATE_NO_CLOSE`, and this was a close or a retarget. The owner may close with their own signature, unless a guardian stop is set (`config.settlesDisabled`, or `config.oracleFrozen`, which leaves a priced close no price). |

And one that is not this program's at all: `InsufficientFunds` from the SPL Token program, when the
allowance is exhausted. `sessionAllowanceGates` is the only thing that predicts it.

## Where to go next

> [card] [Quotes and freshness](https://docs.rekt.money/sdk/quotes.md)
>
> What a quote is, why a settle can be refused with `6007`, and what to do about it.

> [card] [Opening a position](https://docs.rekt.money/sdk/opening.md)
>
> The transaction shape, the two hard walls, and building the instruction.

> [card] [Reading gates](https://docs.rekt.money/sdk/gates.md)
>
> Every protocol refusal, before you send, with its measured value.

> [card] [Error handling](https://docs.rekt.money/sdk/errors.md)
>
> The full catalogue, and whether retrying can ever help.


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