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

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.

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.

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.

Whichever you choose, the program checks the signer. The pages on opening, orders and closes and reading gates do not assume a particular signing model. Gas is a separate decision: see 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.

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.

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.

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.

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.

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.

   session.ts

   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();
   

   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.

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.

   authorise.ts

   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());
   }
   

   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.

   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). Either way it needs lamports. The simplest shape funds the session key in the same moment you authorise it.

   fund.ts

   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)),
       }),
     );
   }
   

   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.

   trade-with-session.ts

   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.

   revoke.ts

   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());
   }
   

   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.

session-gates.ts

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

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.

renew.ts

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,
  });
}

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.

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.

lookup-table.ts

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
}

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.

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

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.

sessions-state.ts

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

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.

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

Quotes and freshness

What a quote is, why a settle can be refused with 6007, and what to do about it.

Opening a position

The transaction shape, the two hard walls, and building the instruction.

Reading gates

Every protocol refusal, before you send, with its measured value.

Error handling

The full catalogue, and whether retrying can ever help.