@lightconexyz/lightcone-sdk 0.6.1 → 0.8.1-rc.2

package/README.md

@@ -177,6 +177,12 @@ ws.subscribe({
 });
 ```
 
+Book streams are snapshot-only: every `book_update` frame carries the full top-20 levels per side (~50ms conflation) and replaces the previous book wholesale (`OrderbookState` handles this; never gate on `seq` — the initial snapshot after every (re)subscribe is `seq: 0`). Subscriptions accept an optional Hyperliquid-style aggregation (`nSigFigs` 2–5, `mantissa` 1/2/5 only with `nSigFigs: 5`; validate with `validateAggregation`). Each `(orderbook, aggregation)` pair is a distinct subscription, so one connection can hold the full-precision and a grouped view of the same book simultaneously — incoming frames are tagged with snake_case `n_sig_figs`/`mantissa` (absent = full precision); key state by `aggregationFromFrame(frame.n_sig_figs, frame.mantissa)`. See [`examples/ws_book_and_trades.ts`](examples/ws_book_and_trades.ts).
+
+```typescript
+ws.subscribe({ type: "book_update", orderbook_ids: [orderbook.orderbookId], nSigFigs: 5, mantissa: 2 });
+```
+
 ### Step 5: Cancel an Order
 
 ```typescript
@@ -218,7 +224,7 @@ Authentication is only required for user-specific endpoints. Authentication is s
 
 ### Cookie handling
 
-After login succeeds, the SDK stores the session token internally and attaches it as `Cookie: auth_token=…` on every authenticated request. Behaviour depends on the runtime:
+After login succeeds, the SDK stores the session token internally and attaches it as `Cookie: lightcone-token=…` on every authenticated request. Behaviour depends on the runtime:
 
 - **Node / non-browser**: token is stored on the `LightconeHttp` instance and added as a `Cookie` header per request.
 - **Browser**: requests use `credentials: "include"` and the runtime supplies the cookie automatically — the SDK's internal store is unused.
@@ -271,6 +277,8 @@ const localClient = LightconeClient.builder()
 
 Each environment configures the API URL, WebSocket URL, Solana RPC URL, and on-chain program ID automatically. Individual URL overrides (`.baseUrl()`, `.wsUrl()`, `.rpcUrl()`) take precedence when called after `.env()`.
 
+The Solana RPC URL can also be overridden via the `SDK_RPC_URL` environment variable, which takes precedence over the environment default. This is useful for pointing all examples at a private RPC to avoid public devnet rate limits.
+
 ## Examples
 
 All examples are runnable with `npx tsx examples/<name>.ts`. Examples default to the production environment and read the wallet keypair from `~/.config/solana/id.json`.
@@ -288,9 +296,10 @@ All examples are runnable with `npx tsx examples/<name>.ts`. Examples default to
 |---------|-------------|
 | [`markets`](examples/markets.ts) | Featured markets, paginated listing, fetch by pubkey, search, platform deposit assets via `globalDepositAssets()` |
 | [`orderbook`](examples/orderbook.ts) | Fetch orderbook depth (bids/asks) and decimal precision metadata |
-| [`trades`](examples/trades.ts) | Recent trade history with cursor-based pagination |
+| [`trades`](examples/trades.ts) | Recent trade history with cursor-based pagination (per-orderbook and market-wide) |
 | [`price_history`](examples/price_history.ts) | Historical candlestick data (OHLCV) at various resolutions |
 | [`positions`](examples/positions.ts) | User positions across all markets and per-market |
+| [`metrics_all`](examples/metrics_all.ts) | Exercise every endpoint on `client.metrics()` - platform, markets, categories, orderbook, leaderboard, history |
 
 ### Placing Orders
 
@@ -371,6 +380,17 @@ Machine-readable rejection codes expose a human-readable `.label()` method. Unre
 | `NOT_ORDER_MAKER` | "Not Order Maker" | Caller is not the order maker |
 | `ORDER_ALREADY_FILLED` | "Order Already Filled" | Order has already been fully filled |
 | `ORDER_ALREADY_CANCELLED` | "Order Already Cancelled" | Order was already cancelled |
+| `DUPLICATE_ORDER` | "Duplicate Order" | Order already exists on this orderbook |
+| `POST_ONLY_WOULD_CROSS` | "Post Only Would Cross" | Post-only order would cross resting liquidity |
+| `FOK_NO_FILL` | "FOK No Fill" | Fill-or-kill order could not be fully filled |
+| `IOC_NO_FILL` | "IOC No Fill" | Immediate-or-cancel order got no fill |
+| `WOULD_CROSS_UNAVAILABLE_LIQUIDITY` | "Would Cross Unavailable Liquidity" | Would cross liquidity unavailable for matching |
+| `WOULD_CROSS_BOOK` | "Would Cross Book" | Order remainder would leave orderbook crossed |
+| `MARKET_NOT_FOUND` | "Market Not Found" | Market does not exist |
+| `ORDERBOOK_NOT_FOUND` | "Orderbook Not Found" | Orderbook does not exist |
+| `TOKEN_PAIR_MISMATCH` | "Token Pair Mismatch" | Token pair doesn't match orderbook |
+| `INSUFFICIENT_MARKET_FEE_BUFFER` | "Insufficient Market Fee Buffer" | Not enough market fee buffer |
+| `SIGNATURE_EXPIRED` | "Signature Expired" | Order signature has expired |
 
 ```typescript
 import { SdkError } from "@lightconexyz/lightcone-sdk";
@@ -417,3 +437,7 @@ The SDK generates a UUID v4 `x-request-id` header on every HTTP request. On reje
 - **GET requests**: `RetryPolicy.Idempotent` - retries on transport failures and 502/503/504, backs off on 429 with exponential backoff + jitter.
 - **POST requests** (order submit, cancel, auth): `RetryPolicy.None` - no automatic retry. Non-idempotent actions are never retried to prevent duplicate side effects.
 - Customizable per-call with `RetryPolicy.custom(config)`.
+
+## Trigger Orders
+
+Trigger orders (stop-limit, take-profit-limit) are under development and not yet available. Internal types exist in the source for internal use only.

package/dist/auth/client.d.ts

@@ -1,5 +1,5 @@
 import { type LightconeHttp } from "../http";
-import type { AuthCredentials, User } from "./index";
+import type { AuthCredentials, SessionResponse } from "./index";
 interface AuthState {
     getCredentials(): AuthCredentials | undefined;
     setCredentials(credentials: AuthCredentials | undefined): void;
@@ -13,8 +13,8 @@ export declare class Auth {
     private readonly client;
     constructor(client: ClientContext);
     getNonce(): Promise<string>;
-    loginWithMessage(message: string, signatureBs58: string, pubkeyBytes: Uint8Array, useEmbeddedWallet?: boolean): Promise<User>;
-    checkSession(): Promise<User>;
+    loginWithMessage(message: string, signatureBs58: string, pubkeyBytes: Uint8Array, useEmbeddedWallet?: boolean): Promise<SessionResponse>;
+    checkSession(): Promise<SessionResponse>;
     logout(): Promise<void>;
     disconnectX(): Promise<void>;
     connectXUrl(): string;

package/dist/auth/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/auth/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAe,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AAE1D,OAAO,KAAK,EAAE,eAAe,EAA0D,IAAI,EAAE,MAAM,SAAS,CAAC;AAE7G,UAAU,SAAS;IACjB,cAAc,IAAI,eAAe,GAAG,SAAS,CAAC;IAC9C,cAAc,CAAC,WAAW,EAAE,eAAe,GAAG,SAAS,GAAG,IAAI,CAAC;IAC/D,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED,UAAU,aAAa;IACrB,IAAI,EAAE,aAAa,CAAC;IACpB,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,qBAAa,IAAI;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,aAAa;IAE5C,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;IAM3B,gBAAgB,CACpB,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,UAAU,EACvB,iBAAiB,CAAC,EAAE,OAAO,GAC1B,OAAO,CAAC,IAAI,CAAC;IAmCV,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IA8B7B,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAavB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAKlC,WAAW,IAAI,MAAM;IAIrB,WAAW,IAAI,eAAe,GAAG,SAAS;IAI1C,eAAe,IAAI,OAAO;CAO3B"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/auth/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAe,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AAG1D,OAAO,KAAK,EAAE,eAAe,EAA+B,eAAe,EAAE,MAAM,SAAS,CAAC;AAE7F,UAAU,SAAS;IACjB,cAAc,IAAI,eAAe,GAAG,SAAS,CAAC;IAC9C,cAAc,CAAC,WAAW,EAAE,eAAe,GAAG,SAAS,GAAG,IAAI,CAAC;IAC/D,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED,UAAU,aAAa;IACrB,IAAI,EAAE,aAAa,CAAC;IACpB,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,qBAAa,IAAI;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,aAAa;IAE5C,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;IAM3B,gBAAgB,CACpB,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,UAAU,EACvB,iBAAiB,CAAC,EAAE,OAAO,GAC1B,OAAO,CAAC,eAAe,CAAC;IAoBrB,YAAY,IAAI,OAAO,CAAC,eAAe,CAAC;IAgBxC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAavB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAKlC,WAAW,IAAI,MAAM;IAIrB,WAAW,IAAI,eAAe,GAAG,SAAS;IAI1C,eAAe,IAAI,OAAO;CAO3B"}

package/dist/auth/client.js

@@ -4,6 +4,7 @@ exports.Auth = void 0;
 const error_1 = require("../error");
 const http_1 = require("../http");
 const shared_1 = require("../shared");
+const index_1 = require("./index");
 class Auth {
     client;
     constructor(client) {
@@ -22,51 +23,22 @@ class Auth {
             pubkey_bytes: Array.from(pubkeyBytes),
             use_embedded_wallet: useEmbeddedWallet,
         };
-        const response = await this.client.http.post(url, body, http_1.RetryPolicy.None);
-        const credentials = {
-            user_id: response.user_id,
-            wallet_address: (0, shared_1.asPubkeyStr)(response.wallet_address),
-            expires_at: parseExpiry(response.expires_at),
-        };
-        this.client.authState.setCredentials(credentials);
-        return {
-            id: response.user_id,
-            wallet_address: response.wallet_address,
-            linked_account: response.linked_account,
-            privy_id: response.privy_id,
-            embedded_wallet: response.embedded_wallet,
-            x_username: response.x_username,
-            x_user_id: response.x_user_id,
-            x_display_name: response.x_display_name,
-            google_email: response.google_email,
-        };
+        const session = await this.client.http.post(url, body, http_1.RetryPolicy.None);
+        this.client.authState.setCredentials(credentialsFromSession(session));
+        return session;
     }
     async checkSession() {
         const url = `${this.client.http.baseUrl()}/api/auth/me`;
-        let response;
+        let session;
         try {
-            response = await this.client.http.get(url, http_1.RetryPolicy.Idempotent);
+            session = await this.client.http.get(url, http_1.RetryPolicy.Idempotent);
         }
         catch (error) {
             this.client.authState.setCredentials(undefined);
             throw error_1.SdkError.from(error);
         }
-        this.client.authState.setCredentials({
-            user_id: response.user_id,
-            wallet_address: (0, shared_1.asPubkeyStr)(response.wallet_address),
-            expires_at: parseExpiry(response.expires_at),
-        });
-        return {
-            id: response.user_id,
-            wallet_address: response.wallet_address,
-            linked_account: response.linked_account,
-            privy_id: response.privy_id,
-            embedded_wallet: response.embedded_wallet,
-            x_username: response.x_username,
-            x_user_id: response.x_user_id,
-            x_display_name: response.x_display_name,
-            google_email: response.google_email,
-        };
+        this.client.authState.setCredentials(credentialsFromSession(session));
+        return session;
     }
     async logout() {
         const url = `${this.client.http.baseUrl()}/api/auth/logout`;
@@ -99,6 +71,17 @@ class Auth {
     }
 }
 exports.Auth = Auth;
+/**
+ * Derive session credentials from the envelope. The trading wallet comes from
+ * the identity + auth method.
+ */
+function credentialsFromSession(session) {
+    return {
+        user_id: session.user.user_id,
+        wallet_address: (0, shared_1.asPubkeyStr)((0, index_1.tradingWallet)(session.user, session.auth_method)),
+        expires_at: parseExpiry(session.expires_at),
+    };
+}
 function parseExpiry(timestamp) {
     if (timestamp > 1_000_000_000_000) {
         return new Date(timestamp);

package/dist/auth/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/auth/client.ts"],"names":[],"mappings":"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","sourcesContent":["import { SdkError } from \"../error\";\nimport { RetryPolicy, type LightconeHttp } from \"../http\";\nimport { asPubkeyStr } from \"../shared\";\nimport type { AuthCredentials, LoginRequest, LoginResponse, MeResponse, NonceResponse, User } from \"./index\";\n\ninterface AuthState {\n  getCredentials(): AuthCredentials | undefined;\n  setCredentials(credentials: AuthCredentials | undefined): void;\n  clearCaches(): Promise<void>;\n}\n\ninterface ClientContext {\n  http: LightconeHttp;\n  authState: AuthState;\n}\n\nexport class Auth {\n  constructor(private readonly client: ClientContext) {}\n\n  async getNonce(): Promise<string> {\n    const url = `${this.client.http.baseUrl()}/api/auth/nonce`;\n    const response = await this.client.http.get<NonceResponse>(url, RetryPolicy.None);\n    return response.nonce;\n  }\n\n  async loginWithMessage(\n    message: string,\n    signatureBs58: string,\n    pubkeyBytes: Uint8Array,\n    useEmbeddedWallet?: boolean\n  ): Promise<User> {\n    const url = `${this.client.http.baseUrl()}/api/auth/login_or_register_with_message`;\n    const body: LoginRequest = {\n      message,\n      signature_bs58: signatureBs58,\n      pubkey_bytes: Array.from(pubkeyBytes),\n      use_embedded_wallet: useEmbeddedWallet,\n    };\n\n    const response = await this.client.http.post<LoginResponse, LoginRequest>(\n      url,\n      body,\n      RetryPolicy.None\n    );\n\n    const credentials: AuthCredentials = {\n      user_id: response.user_id,\n      wallet_address: asPubkeyStr(response.wallet_address),\n      expires_at: parseExpiry(response.expires_at),\n    };\n    this.client.authState.setCredentials(credentials);\n\n    return {\n      id: response.user_id,\n      wallet_address: response.wallet_address,\n      linked_account: response.linked_account,\n      privy_id: response.privy_id,\n      embedded_wallet: response.embedded_wallet,\n      x_username: response.x_username,\n      x_user_id: response.x_user_id,\n      x_display_name: response.x_display_name,\n      google_email: response.google_email,\n    };\n  }\n\n  async checkSession(): Promise<User> {\n    const url = `${this.client.http.baseUrl()}/api/auth/me`;\n\n    let response: MeResponse;\n    try {\n      response = await this.client.http.get<MeResponse>(url, RetryPolicy.Idempotent);\n    } catch (error) {\n      this.client.authState.setCredentials(undefined);\n      throw SdkError.from(error);\n    }\n\n    this.client.authState.setCredentials({\n      user_id: response.user_id,\n      wallet_address: asPubkeyStr(response.wallet_address),\n      expires_at: parseExpiry(response.expires_at),\n    });\n\n    return {\n      id: response.user_id,\n      wallet_address: response.wallet_address,\n      linked_account: response.linked_account,\n      privy_id: response.privy_id,\n      embedded_wallet: response.embedded_wallet,\n      x_username: response.x_username,\n      x_user_id: response.x_user_id,\n      x_display_name: response.x_display_name,\n      google_email: response.google_email,\n    };\n  }\n\n  async logout(): Promise<void> {\n    const url = `${this.client.http.baseUrl()}/api/auth/logout`;\n    try {\n      await this.client.http.post<{ success: boolean }, Record<string, never>>(url, {}, RetryPolicy.None);\n    } catch {\n      // Backend cookie clear can fail in local/dev setups; still clear local state.\n    }\n\n    await this.client.http.clearAuthToken();\n    this.client.authState.setCredentials(undefined);\n    await this.client.authState.clearCaches();\n  }\n\n  async disconnectX(): Promise<void> {\n    const url = `${this.client.http.baseUrl()}/api/auth/disconnect_x`;\n    await this.client.http.post<{ success: boolean }, Record<string, never>>(url, {}, RetryPolicy.None);\n  }\n\n  connectXUrl(): string {\n    return `${this.client.http.baseUrl()}/api/auth/oauth/link/x`;\n  }\n\n  credentials(): AuthCredentials | undefined {\n    return this.client.authState.getCredentials();\n  }\n\n  isAuthenticated(): boolean {\n    const credentials = this.credentials();\n    if (!credentials) {\n      return false;\n    }\n    return Date.now() < credentials.expires_at.getTime();\n  }\n}\n\nfunction parseExpiry(timestamp: number): Date {\n  if (timestamp > 1_000_000_000_000) {\n    return new Date(timestamp);\n  }\n  return new Date(timestamp * 1000);\n}\n"]}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/auth/client.ts"],"names":[],"mappings":"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","sourcesContent":["import { SdkError } from \"../error\";\nimport { RetryPolicy, type LightconeHttp } from \"../http\";\nimport { asPubkeyStr } from \"../shared\";\nimport { tradingWallet } from \"./index\";\nimport type { AuthCredentials, LoginRequest, NonceResponse, SessionResponse } from \"./index\";\n\ninterface AuthState {\n  getCredentials(): AuthCredentials | undefined;\n  setCredentials(credentials: AuthCredentials | undefined): void;\n  clearCaches(): Promise<void>;\n}\n\ninterface ClientContext {\n  http: LightconeHttp;\n  authState: AuthState;\n}\n\nexport class Auth {\n  constructor(private readonly client: ClientContext) {}\n\n  async getNonce(): Promise<string> {\n    const url = `${this.client.http.baseUrl()}/api/auth/nonce`;\n    const response = await this.client.http.get<NonceResponse>(url, RetryPolicy.None);\n    return response.nonce;\n  }\n\n  async loginWithMessage(\n    message: string,\n    signatureBs58: string,\n    pubkeyBytes: Uint8Array,\n    useEmbeddedWallet?: boolean\n  ): Promise<SessionResponse> {\n    const url = `${this.client.http.baseUrl()}/api/auth/login_or_register_with_message`;\n    const body: LoginRequest = {\n      message,\n      signature_bs58: signatureBs58,\n      pubkey_bytes: Array.from(pubkeyBytes),\n      use_embedded_wallet: useEmbeddedWallet,\n    };\n\n    const session = await this.client.http.post<SessionResponse, LoginRequest>(\n      url,\n      body,\n      RetryPolicy.None\n    );\n\n    this.client.authState.setCredentials(credentialsFromSession(session));\n\n    return session;\n  }\n\n  async checkSession(): Promise<SessionResponse> {\n    const url = `${this.client.http.baseUrl()}/api/auth/me`;\n\n    let session: SessionResponse;\n    try {\n      session = await this.client.http.get<SessionResponse>(url, RetryPolicy.Idempotent);\n    } catch (error) {\n      this.client.authState.setCredentials(undefined);\n      throw SdkError.from(error);\n    }\n\n    this.client.authState.setCredentials(credentialsFromSession(session));\n\n    return session;\n  }\n\n  async logout(): Promise<void> {\n    const url = `${this.client.http.baseUrl()}/api/auth/logout`;\n    try {\n      await this.client.http.post<{ success: boolean }, Record<string, never>>(url, {}, RetryPolicy.None);\n    } catch {\n      // Backend cookie clear can fail in local/dev setups; still clear local state.\n    }\n\n    await this.client.http.clearAuthToken();\n    this.client.authState.setCredentials(undefined);\n    await this.client.authState.clearCaches();\n  }\n\n  async disconnectX(): Promise<void> {\n    const url = `${this.client.http.baseUrl()}/api/auth/disconnect_x`;\n    await this.client.http.post<{ success: boolean }, Record<string, never>>(url, {}, RetryPolicy.None);\n  }\n\n  connectXUrl(): string {\n    return `${this.client.http.baseUrl()}/api/auth/oauth/link/x`;\n  }\n\n  credentials(): AuthCredentials | undefined {\n    return this.client.authState.getCredentials();\n  }\n\n  isAuthenticated(): boolean {\n    const credentials = this.credentials();\n    if (!credentials) {\n      return false;\n    }\n    return Date.now() < credentials.expires_at.getTime();\n  }\n}\n\n/**\n * Derive session credentials from the envelope. The trading wallet comes from\n * the identity + auth method.\n */\nfunction credentialsFromSession(session: SessionResponse): AuthCredentials {\n  return {\n    user_id: session.user.user_id,\n    wallet_address: asPubkeyStr(tradingWallet(session.user, session.auth_method)),\n    expires_at: parseExpiry(session.expires_at),\n  };\n}\n\nfunction parseExpiry(timestamp: number): Date {\n  if (timestamp > 1_000_000_000_000) {\n    return new Date(timestamp);\n  }\n  return new Date(timestamp * 1000);\n}\n"]}

package/dist/auth/index.d.ts

@@ -1,37 +1,117 @@
 import type { PubkeyStr } from "../shared";
 export * from "./client";
 export * from "./native";
-export interface User {
-    id: string;
-    wallet_address: string;
-    linked_account: LinkedAccount;
-    privy_id?: string;
-    embedded_wallet?: EmbeddedWallet;
-    x_username?: string;
-    x_user_id?: string;
-    x_display_name?: string;
-    google_email?: string;
-}
-export interface LinkedAccount {
-    id: string;
-    type: LinkedAccountType;
-    chain?: ChainType;
-    address: string;
-}
-export declare enum LinkedAccountType {
-    Wallet = "wallet",
-    TwitterOauth = "twitter_oauth",
-    GoogleOauth = "google_oauth"
+/**
+ * How a session authenticated, as reported by the backend (derived from which
+ * token verified the request).
+ */
+export declare enum AuthMethod {
+    Privy = "privy",
+    Lightcone = "lightcone"
 }
 export declare enum ChainType {
     Solana = "solana",
     Ethereum = "ethereum"
 }
-export interface EmbeddedWallet {
+/** A Privy-managed embedded wallet. */
+export interface PrivyEmbeddedWallet {
     privy_id: string;
     chain: ChainType;
     address: string;
 }
+/** Privy account data attached to an identity. */
+export interface UserPrivyData {
+    /** The Privy DID (`did:privy:...`). */
+    id: string;
+    /**
+     * Always present: Privy registration provisions the embedded wallet in the
+     * same transaction that creates the user.
+     */
+    wallet: PrivyEmbeddedWallet;
+}
+/**
+ * X account data — the same shape whether X is the login identity or a
+ * connected account on a Google/wallet identity.
+ */
+export interface XAccountData {
+    /** X numeric user id (Privy `subject`); absent on legacy rows. */
+    user_id?: string;
+    username: string;
+    display_name?: string;
+    avatar_url?: string;
+}
+/** Google account data for a Google login identity. */
+export interface GoogleAccountData {
+    email: string;
+    name?: string;
+    given_name?: string;
+    family_name?: string;
+    avatar_url?: string;
+}
+/**
+ * The login identity — how the user authenticates. `type` narrows the variant.
+ *
+ * Privy data lives on the variant because its presence is determined by the
+ * identity type: Google/X login only exists via Privy OAuth (guaranteed DID +
+ * embedded wallet), while wallet users opt into Privy (SIWS) or stay
+ * self-custody.
+ */
+export type UserIdentity = {
+    type: "google";
+    account: GoogleAccountData;
+    privy: UserPrivyData;
+} | {
+    type: "x";
+    account: XAccountData;
+    privy: UserPrivyData;
+} | {
+    type: "wallet";
+    address: string;
+    chain: ChainType;
+    privy?: UserPrivyData;
+};
+/** Full user profile — the `user` object of {@link SessionResponse}. */
+export interface User {
+    user_id: string;
+    identity: UserIdentity;
+    /** X account connected by a non-X-identity user; absent when identity is X. */
+    connected_x?: XAccountData;
+}
+/**
+ * Session envelope returned by `loginWithMessage`, `register-privy`, and
+ * `GET /api/auth/me`. There is no `wallet_address` field — derive the
+ * session's trading wallet with {@link tradingWallet}.
+ */
+export interface SessionResponse {
+    user: User;
+    expires_at: number;
+    auth_method: AuthMethod;
+    is_beta: boolean;
+}
+/** Human-readable login-method label ("Google" / "X" / "Solana"). */
+export declare function identityText(identity: UserIdentity): "Google" | "X" | "Solana";
+/** Privy account data, regardless of identity type. */
+export declare function userPrivy(user: User): UserPrivyData | undefined;
+/** The X account, whether it is the login identity or a connected account. */
+export declare function userXAccount(user: User): XAccountData | undefined;
+/**
+ * The wallet a session operates as.
+ *
+ * Google/X identities only exist via Privy registration, which always
+ * provisions an embedded wallet — that wallet is the answer regardless of
+ * auth method. Wallet identities depend on the session: a Privy (SIWS)
+ * session trades via the embedded wallet, a Lightcone session trades via the
+ * wallet that signed in.
+ */
+export declare function tradingWallet(user: User, authMethod: AuthMethod): string;
+/**
+ * Best display name for the user. Google: `name`, falling back to the email;
+ * X: `display_name`, falling back to the username; wallet identities show the
+ * shortened address (`FRGk...WcPR`).
+ */
+export declare function displayName(user: User): string;
+/** Avatar URL from the login identity's OAuth provider, if any. */
+export declare function avatarUrl(user: User): string | undefined;
 export interface AuthCredentials {
     user_id: string;
     wallet_address: PubkeyStr;
@@ -45,30 +125,6 @@ export interface LoginRequest {
     pubkey_bytes: number[];
     use_embedded_wallet?: boolean;
 }
-export interface LoginResponse {
-    user_id: string;
-    wallet_address: string;
-    expires_at: number;
-    linked_account: LinkedAccount;
-    privy_id?: string;
-    embedded_wallet?: EmbeddedWallet;
-    x_username?: string;
-    x_user_id?: string;
-    x_display_name?: string;
-    google_email?: string;
-}
-export interface MeResponse {
-    user_id: string;
-    wallet_address: string;
-    linked_account: LinkedAccount;
-    privy_id?: string;
-    embedded_wallet?: EmbeddedWallet;
-    x_username?: string;
-    x_user_id?: string;
-    x_display_name?: string;
-    google_email?: string;
-    expires_at: number;
-}
 export interface NonceResponse {
     nonce: string;
 }

package/dist/auth/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AAEzB,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,cAAc,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,iBAAiB,CAAC;IACxB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,oBAAY,iBAAiB;IAC3B,MAAM,WAAW;IACjB,YAAY,kBAAkB;IAC9B,WAAW,iBAAiB;CAC7B;AAED,oBAAY,SAAS;IACnB,MAAM,WAAW;IACjB,QAAQ,aAAa;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,SAAS,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,SAAS,CAAC;IAC1B,UAAU,EAAE,IAAI,CAAC;CAClB;AAED,wBAAgB,eAAe,CAAC,WAAW,CAAC,EAAE,eAAe,GAAG,OAAO,CAKtE;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAE/D;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,cAAc,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,cAAc,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;CACf"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"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"}

package/dist/auth/index.js

@@ -14,22 +14,106 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ChainType = exports.LinkedAccountType = void 0;
+exports.ChainType = exports.AuthMethod = void 0;
+exports.identityText = identityText;
+exports.userPrivy = userPrivy;
+exports.userXAccount = userXAccount;
+exports.tradingWallet = tradingWallet;
+exports.displayName = displayName;
+exports.avatarUrl = avatarUrl;
 exports.isAuthenticated = isAuthenticated;
 exports.generateSigninMessage = generateSigninMessage;
+const str_1 = require("../shared/fmt/str");
 __exportStar(require("./client"), exports);
 __exportStar(require("./native"), exports);
-var LinkedAccountType;
-(function (LinkedAccountType) {
-    LinkedAccountType["Wallet"] = "wallet";
-    LinkedAccountType["TwitterOauth"] = "twitter_oauth";
-    LinkedAccountType["GoogleOauth"] = "google_oauth";
-})(LinkedAccountType || (exports.LinkedAccountType = LinkedAccountType = {}));
+/**
+ * How a session authenticated, as reported by the backend (derived from which
+ * token verified the request).
+ */
+var AuthMethod;
+(function (AuthMethod) {
+    AuthMethod["Privy"] = "privy";
+    AuthMethod["Lightcone"] = "lightcone";
+})(AuthMethod || (exports.AuthMethod = AuthMethod = {}));
 var ChainType;
 (function (ChainType) {
     ChainType["Solana"] = "solana";
     ChainType["Ethereum"] = "ethereum";
 })(ChainType || (exports.ChainType = ChainType = {}));
+/** Human-readable login-method label ("Google" / "X" / "Solana"). */
+function identityText(identity) {
+    switch (identity.type) {
+        case "google":
+            return "Google";
+        case "x":
+            return "X";
+        case "wallet":
+            return "Solana";
+        default: {
+            const exhaustive = identity;
+            throw new Error(`Unknown identity: ${JSON.stringify(exhaustive)}`);
+        }
+    }
+}
+/** Privy account data, regardless of identity type. */
+function userPrivy(user) {
+    switch (user.identity.type) {
+        case "google":
+        case "x":
+            return user.identity.privy;
+        case "wallet":
+            return user.identity.privy;
+    }
+}
+/** The X account, whether it is the login identity or a connected account. */
+function userXAccount(user) {
+    return user.identity.type === "x" ? user.identity.account : user.connected_x;
+}
+/**
+ * The wallet a session operates as.
+ *
+ * Google/X identities only exist via Privy registration, which always
+ * provisions an embedded wallet — that wallet is the answer regardless of
+ * auth method. Wallet identities depend on the session: a Privy (SIWS)
+ * session trades via the embedded wallet, a Lightcone session trades via the
+ * wallet that signed in.
+ */
+function tradingWallet(user, authMethod) {
+    switch (user.identity.type) {
+        case "google":
+        case "x":
+            return user.identity.privy.wallet.address;
+        case "wallet":
+            return authMethod === AuthMethod.Privy
+                ? (user.identity.privy?.wallet.address ?? user.identity.address)
+                : user.identity.address;
+    }
+}
+/**
+ * Best display name for the user. Google: `name`, falling back to the email;
+ * X: `display_name`, falling back to the username; wallet identities show the
+ * shortened address (`FRGk...WcPR`).
+ */
+function displayName(user) {
+    switch (user.identity.type) {
+        case "google":
+            return user.identity.account.name ?? user.identity.account.email;
+        case "x":
+            return user.identity.account.display_name ?? user.identity.account.username;
+        case "wallet":
+            return (0, str_1.shorten)(user.identity.address, 8);
+    }
+}
+/** Avatar URL from the login identity's OAuth provider, if any. */
+function avatarUrl(user) {
+    switch (user.identity.type) {
+        case "google":
+        case "x":
+            return user.identity.account.avatar_url;
+        case "wallet":
+            return undefined;
+    }
+}
 function isAuthenticated(credentials) {
     if (!credentials) {
         return false;

package/dist/auth/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AA+CA,0CAKC;AAED,sDAEC;AAtDD,2CAAyB;AACzB,2CAAyB;AAqBzB,IAAY,iBAIX;AAJD,WAAY,iBAAiB;IAC3B,sCAAiB,CAAA;IACjB,mDAA8B,CAAA;IAC9B,iDAA4B,CAAA;AAC9B,CAAC,EAJW,iBAAiB,iCAAjB,iBAAiB,QAI5B;AAED,IAAY,SAGX;AAHD,WAAY,SAAS;IACnB,8BAAiB,CAAA;IACjB,kCAAqB,CAAA;AACvB,CAAC,EAHW,SAAS,yBAAT,SAAS,QAGpB;AAcD,SAAgB,eAAe,CAAC,WAA6B;IAC3D,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,WAAW,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;AACvD,CAAC;AAED,SAAgB,qBAAqB,CAAC,KAAa;IACjD,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,gCAAgC,KAAK,EAAE,CAAC,CAAC;AAC3E,CAAC","sourcesContent":["import type { PubkeyStr } from \"../shared\";\n\nexport * from \"./client\";\nexport * from \"./native\";\n\nexport interface User {\n  id: string;\n  wallet_address: string;\n  linked_account: LinkedAccount;\n  privy_id?: string;\n  embedded_wallet?: EmbeddedWallet;\n  x_username?: string;\n  x_user_id?: string;\n  x_display_name?: string;\n  google_email?: string;\n}\n\nexport interface LinkedAccount {\n  id: string;\n  type: LinkedAccountType;\n  chain?: ChainType;\n  address: string;\n}\n\nexport enum LinkedAccountType {\n  Wallet = \"wallet\",\n  TwitterOauth = \"twitter_oauth\",\n  GoogleOauth = \"google_oauth\",\n}\n\nexport enum ChainType {\n  Solana = \"solana\",\n  Ethereum = \"ethereum\",\n}\n\nexport interface EmbeddedWallet {\n  privy_id: string;\n  chain: ChainType;\n  address: string;\n}\n\nexport interface AuthCredentials {\n  user_id: string;\n  wallet_address: PubkeyStr;\n  expires_at: Date;\n}\n\nexport function isAuthenticated(credentials?: AuthCredentials): boolean {\n  if (!credentials) {\n    return false;\n  }\n  return Date.now() < credentials.expires_at.getTime();\n}\n\nexport function generateSigninMessage(nonce: string): Uint8Array {\n  return new TextEncoder().encode(`Sign in to Lightcone\\nNonce: ${nonce}`);\n}\n\nexport interface LoginRequest {\n  message: string;\n  signature_bs58: string;\n  pubkey_bytes: number[];\n  use_embedded_wallet?: boolean;\n}\n\nexport interface LoginResponse {\n  user_id: string;\n  wallet_address: string;\n  expires_at: number;\n  linked_account: LinkedAccount;\n  privy_id?: string;\n  embedded_wallet?: EmbeddedWallet;\n  x_username?: string;\n  x_user_id?: string;\n  x_display_name?: string;\n  google_email?: string;\n}\n\nexport interface MeResponse {\n  user_id: string;\n  wallet_address: string;\n  linked_account: LinkedAccount;\n  privy_id?: string;\n  embedded_wallet?: EmbeddedWallet;\n  x_username?: string;\n  x_user_id?: string;\n  x_display_name?: string;\n  google_email?: string;\n  expires_at: number;\n}\n\nexport interface NonceResponse {\n  nonce: string;\n}\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"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","sourcesContent":["import type { PubkeyStr } from \"../shared\";\nimport { shorten } from \"../shared/fmt/str\";\n\nexport * from \"./client\";\nexport * from \"./native\";\n\n/**\n * How a session authenticated, as reported by the backend (derived from which\n * token verified the request).\n */\nexport enum AuthMethod {\n  Privy = \"privy\",\n  Lightcone = \"lightcone\",\n}\n\nexport enum ChainType {\n  Solana = \"solana\",\n  Ethereum = \"ethereum\",\n}\n\n/** A Privy-managed embedded wallet. */\nexport interface PrivyEmbeddedWallet {\n  privy_id: string;\n  chain: ChainType;\n  address: string;\n}\n\n/** Privy account data attached to an identity. */\nexport interface UserPrivyData {\n  /** The Privy DID (`did:privy:...`). */\n  id: string;\n  /**\n   * Always present: Privy registration provisions the embedded wallet in the\n   * same transaction that creates the user.\n   */\n  wallet: PrivyEmbeddedWallet;\n}\n\n/**\n * X account data — the same shape whether X is the login identity or a\n * connected account on a Google/wallet identity.\n */\nexport interface XAccountData {\n  /** X numeric user id (Privy `subject`); absent on legacy rows. */\n  user_id?: string;\n  username: string;\n  display_name?: string;\n  avatar_url?: string;\n}\n\n/** Google account data for a Google login identity. */\nexport interface GoogleAccountData {\n  email: string;\n  name?: string;\n  given_name?: string;\n  family_name?: string;\n  avatar_url?: string;\n}\n\n/**\n * The login identity — how the user authenticates. `type` narrows the variant.\n *\n * Privy data lives on the variant because its presence is determined by the\n * identity type: Google/X login only exists via Privy OAuth (guaranteed DID +\n * embedded wallet), while wallet users opt into Privy (SIWS) or stay\n * self-custody.\n */\nexport type UserIdentity =\n  | { type: \"google\"; account: GoogleAccountData; privy: UserPrivyData }\n  | { type: \"x\"; account: XAccountData; privy: UserPrivyData }\n  | { type: \"wallet\"; address: string; chain: ChainType; privy?: UserPrivyData };\n\n/** Full user profile — the `user` object of {@link SessionResponse}. */\nexport interface User {\n  user_id: string;\n  identity: UserIdentity;\n  /** X account connected by a non-X-identity user; absent when identity is X. */\n  connected_x?: XAccountData;\n}\n\n/**\n * Session envelope returned by `loginWithMessage`, `register-privy`, and\n * `GET /api/auth/me`. There is no `wallet_address` field — derive the\n * session's trading wallet with {@link tradingWallet}.\n */\nexport interface SessionResponse {\n  user: User;\n  expires_at: number;\n  auth_method: AuthMethod;\n  is_beta: boolean;\n}\n\n/** Human-readable login-method label (\"Google\" / \"X\" / \"Solana\"). */\nexport function identityText(identity: UserIdentity): \"Google\" | \"X\" | \"Solana\" {\n  switch (identity.type) {\n    case \"google\":\n      return \"Google\";\n    case \"x\":\n      return \"X\";\n    case \"wallet\":\n      return \"Solana\";\n    default: {\n      const exhaustive: never = identity;\n      throw new Error(`Unknown identity: ${JSON.stringify(exhaustive)}`);\n    }\n  }\n}\n\n/** Privy account data, regardless of identity type. */\nexport function userPrivy(user: User): UserPrivyData | undefined {\n  switch (user.identity.type) {\n    case \"google\":\n    case \"x\":\n      return user.identity.privy;\n    case \"wallet\":\n      return user.identity.privy;\n  }\n}\n\n/** The X account, whether it is the login identity or a connected account. */\nexport function userXAccount(user: User): XAccountData | undefined {\n  return user.identity.type === \"x\" ? user.identity.account : user.connected_x;\n}\n\n/**\n * The wallet a session operates as.\n *\n * Google/X identities only exist via Privy registration, which always\n * provisions an embedded wallet — that wallet is the answer regardless of\n * auth method. Wallet identities depend on the session: a Privy (SIWS)\n * session trades via the embedded wallet, a Lightcone session trades via the\n * wallet that signed in.\n */\nexport function tradingWallet(user: User, authMethod: AuthMethod): string {\n  switch (user.identity.type) {\n    case \"google\":\n    case \"x\":\n      return user.identity.privy.wallet.address;\n    case \"wallet\":\n      return authMethod === AuthMethod.Privy\n        ? (user.identity.privy?.wallet.address ?? user.identity.address)\n        : user.identity.address;\n  }\n}\n\n/**\n * Best display name for the user. Google: `name`, falling back to the email;\n * X: `display_name`, falling back to the username; wallet identities show the\n * shortened address (`FRGk...WcPR`).\n */\nexport function displayName(user: User): string {\n  switch (user.identity.type) {\n    case \"google\":\n      return user.identity.account.name ?? user.identity.account.email;\n    case \"x\":\n      return user.identity.account.display_name ?? user.identity.account.username;\n    case \"wallet\":\n      return shorten(user.identity.address, 8);\n  }\n}\n\n/** Avatar URL from the login identity's OAuth provider, if any. */\nexport function avatarUrl(user: User): string | undefined {\n  switch (user.identity.type) {\n    case \"google\":\n    case \"x\":\n      return user.identity.account.avatar_url;\n    case \"wallet\":\n      return undefined;\n  }\n}\n\nexport interface AuthCredentials {\n  user_id: string;\n  wallet_address: PubkeyStr;\n  expires_at: Date;\n}\n\nexport function isAuthenticated(credentials?: AuthCredentials): boolean {\n  if (!credentials) {\n    return false;\n  }\n  return Date.now() < credentials.expires_at.getTime();\n}\n\nexport function generateSigninMessage(nonce: string): Uint8Array {\n  return new TextEncoder().encode(`Sign in to Lightcone\\nNonce: ${nonce}`);\n}\n\nexport interface LoginRequest {\n  message: string;\n  signature_bs58: string;\n  pubkey_bytes: number[];\n  use_embedded_wallet?: boolean;\n}\n\nexport interface NonceResponse {\n  nonce: string;\n}\n"]}

package/dist/client.d.ts

@@ -1,7 +1,6 @@
 import { Connection, Keypair, PublicKey, Transaction } from "@solana/web3.js";
 import { Auth, type AuthCredentials } from "./auth";
 import type { ClientContext } from "./context";
-import { Admin } from "./domain/admin";
 import type { FaucetResponse } from "./domain/faucet";
 import { Markets } from "./domain/market";
 import { Metrics } from "./domain/metrics";
@@ -16,6 +15,7 @@ import { LightconeHttp } from "./http";
 import { LightconeEnv } from "./env";
 import { Privy } from "./privy";
 import { Rpc } from "./rpc";
+import { RpcFailoverState } from "./rpcFailover";
 import { DepositSource, type PubkeyStr } from "./shared";
 import { type ExternalSigner, type SigningStrategy } from "./shared/signing";
 import { WsClient, type WsConfig } from "./ws";
@@ -29,17 +29,23 @@ declare class AuthState {
 export declare class LightconeClient implements ClientContext {
     readonly http: LightconeHttp;
     readonly programId: PublicKey;
-    readonly connection?: Connection;
+    readonly primaryConnection?: Connection;
+    readonly backupConnection?: Connection;
+    readonly rpcFailoverState: RpcFailoverState;
     private depositSourceValue;
     private signingStrategyValue?;
     private orderNonceValue;
     private readonly wsConfigValue;
     private readonly authStateStore;
+    /** @deprecated Use primaryConnection — kept for ClientContext compat. */
+    get connection(): Connection | undefined;
     constructor(params: {
         http: LightconeHttp;
         wsConfig: WsConfig;
         programId?: PublicKey;
-        connection?: Connection;
+        primaryConnection?: Connection;
+        backupConnection?: Connection;
+        rpcFailoverState?: RpcFailoverState;
         depositSource?: DepositSource;
         signingStrategy?: SigningStrategy;
         orderNonce?: number;
@@ -55,16 +61,16 @@ export declare class LightconeClient implements ClientContext {
     setOrderNonce(nonce: number): void;
     clearOrderNonce(): void;
     /**
-     * Get the current `auth_token` cookie value, if any. Populated by the SDK
+     * Get the current `lightcone-token` cookie value, if any. Populated by the SDK
      * after a successful login, then attached on every authed request. Useful
-     * for forwarding the token through the `*WithAuth` methods, or
+     * for forwarding the token through the `*WithCookies` methods, or
      * persisting the session across processes.
      */
     authToken(): Promise<string | undefined>;
     /**
-     * Clear the cached `auth_token`. Subsequent authed calls will go out
+     * Clear the cached `lightcone-token`. Subsequent authed calls will go out
      * without a `Cookie` header (and 401) unless they use a
-     * `*WithAuth` variant.
+     * `*WithCookies` variant.
      */
     clearAuthToken(): Promise<void>;
     signAndSubmitTx(tx: Transaction): Promise<string>;
@@ -90,7 +96,6 @@ export declare class LightconeClient implements ClientContext {
      * `POST /api/claim`
      */
     claim(walletAddress: PubkeyStr): Promise<FaucetResponse>;
-    admin(): Admin;
     auth(): Auth;
     privy(): Privy;
     referrals(): Referrals;
@@ -106,7 +111,8 @@ export declare class LightconeClientBuilder {
     private programIdValue;
     private depositSourceValue;
     private signingStrategyValue?;
-    private rpcUrlValue?;
+    private primaryRpcUrlValue?;
+    private backupRpcUrlValue?;
     /**
      * Set the deployment environment. Configures the API URL, WebSocket URL,
      * RPC URL, and program ID for the given environment.
@@ -127,6 +133,8 @@ export declare class LightconeClientBuilder {
     externalSigner(signer: ExternalSigner): LightconeClientBuilder;
     privyWalletId(walletId: string): LightconeClientBuilder;
     rpcUrl(url: string): LightconeClientBuilder;
+    /** Set a backup Solana RPC URL for automatic failover. */
+    backupRpcUrl(url: string): LightconeClientBuilder;
     build(): LightconeClient;
 }
 export {};