Overview

Lighter provider instances, SDK-owned signing, setup, and configuration

This section covers behavior shared by the Lighter deployments exposed through the perps SDK. For general concepts, see Action Pattern.

Lighter signs actions with a per-account native keypair registered on-chain through REGISTER_API_KEY. Public provider metadata calls this an SDK signer: the Lighter plugin owns key generation, persistence, WASM loading, signing, and read-only token lifecycle (see Authentication). Applications do not instantiate a signer or pass a key store separately.

​

Provider instances

Provider key	Deployment	Deposit chain	Collateral	REST / WebSocket
lighter	Lighter mainnet	Ethereum (first deposit); Lighter chain (existing accounts)	USDC	Mainnet Lighter endpoints
lighter-rh	Lighter on Robinhood Chain	Robinhood Chain	USDG	Robinhood Lighter endpoints

The Lighter chain is LI.FI chain id ChainId.LTR, the routing destination for existing accounts (LIGHTER_USDC). Ethereum is where the account-opening bridge deposit runs (ETHEREUM_USDC). lighter-rh uses Robinhood Chain for both (ROBINHOOD_USDG).

Both providers expose the same normalized SDK contract but keep endpoints, caches, credentials, signing configuration, and asset registries isolated.

import { createPerpsClient, PerpsWsClient } from '@lifi/perps-sdk';
import {
  lighterProvider,
  lighterRhProvider,
  LIGHTER_RH_REST_URL,
  lighterWsProvider,
} from '@lifi/perps-sdk-provider-lighter';

const client = createPerpsClient({
  apiKey: 'your-api-key',
  providers: [lighterProvider(), lighterRhProvider()],
});

const ws = new PerpsWsClient(client, {
  wsProviders: {
    lighter: lighterWsProvider(),
    'lighter-rh': lighterWsProvider({ restUrl: LIGHTER_RH_REST_URL }),
  },
});

Each provider defaults to encrypted browser localStorage for its signing key and read-only token. Pass storage to a provider factory only for SSR, tests, or a different persistence backend. Authenticated WebSocket channels automatically reuse resolveAuthToken from the co-registered REST provider; a custom resolver is only needed for a standalone WebSocket client. A PerpsClient user passes perps.client to PerpsWsClient.

​

WASM signer

The Lighter signer is a 12.9 MB WASM binary downloaded on first use. Call loadLighterWasm() early to warm it up before the first trade. It needs no bundler configuration and runs client-side only (in Next.js, load it with a dynamic import and ssr: false). Under a Content Security Policy, script-src must include 'wasm-unsafe-eval'; 'unsafe-eval' is not required.

import { loadLighterWasm } from '@lifi/perps-sdk-provider-lighter';

await loadLighterWasm();

​

Authentication and rate limits

Authenticated reads (getOrders, getOrder, getFills, getActivity, getPortfolioHistory) resolve a bearer token in this order: the persisted long-lived read-only token, then a read-only token created on first use with the registered API key and persisted, then a standard token (read and write, at most 8 hours) while read-only token creation fails.

The authenticated data reads throw SetupRequired when no token resolves, and the SDK sends no request to Lighter. They throw Unauthorized when Lighter rejects the token, and AccountNotFound when the wallet has no Lighter account. getPositions and getWithdrawableBalances need no token, so their only access code is AccountNotFound. getAccount is a status read: when the wallet has no locally stored API key that matches the registered key, it returns a zero fee tier and apiKeyRegistered: false. When the keys match, getAccount reads the fee tier with the resolved token and throws Unauthorized if Lighter rejects the token. getAccount throws AccountNotFound for a wallet with no Lighter account. getAvailableToTrade reads through getAccount, so it throws the same two codes. See Account access.

lighterProvider() option	Description
storage	Persistence backend for the API key and read-only token. Defaults to encrypted browser localStorage
restUrl	Lighter REST base URL. Defaults to the deployment’s endpoint
tokenLifetimeSeconds	Standard token lifetime. Default 1 hour; Lighter caps it at 8 hours
tokenRenewBufferSeconds	A cached standard token is re-created when its remaining life falls below this. Default 60

​

Topics

• Signing Model — WASM signing, the native key versus the L1 wallet, and dual-authorized setup
• Deposits — provider-owned deposit discovery for Lighter mainnet and Robinhood Chain
• Setup — the steps in sequence order with their signer and relay, the required Plus or Premium account tier, and the account mode choice
• Trading — trading and account actions
• Withdrawals — per-asset/per-category balance discovery and settlement paths
• WebSocket Protocol — channel mapping and provider-owned authentication

​

Defaults and constraints

• Default margin mode: CROSS when marginMode is omitted from placeOrder or updateLeverage. Isolated-only markets reject CROSS; see Margin modes.
• Trade signing: trading actions are authorized by the plugin’s SDK signer with no per-trade wallet popup. A fast withdrawal also needs one wallet signature; see Withdrawals.
• Order fields: price is required.
• Withdrawal destination: the account owner address only.
• Mainnet deposit: Ethereum mainnet USDC plus ETH for gas.
• Robinhood deposit: Robinhood Chain USDG plus native gas.
• Key slot: the backend selects the slot and sends it in wasmSignParams.api_key_index; re-registering that slot replaces the prior key.
• Account tier: Plus or Premium is required on both Lighter Core and Robinhood Chain: Lighter accepts orders routed through an integrator only from those tiers. The accountType setup step is a choice, and Plus is the recommended option.

​

Account figures

PerpsClient.getAccountSummary() builds the AccountSummary totals for Lighter from these venue fields:

AccountSummary field	Venue source
portfolioValue	total_asset_value plus the settlement asset’s spot balance, plus the USD value of every non-settlement holding
availableMargin	cross_asset_value minus cross_initial_margin_requirement, floored at 0
marginUsed	Sum of marginUsed across open positions
unrealizedPnl	Sum of unrealizedPnl across open positions

See Withdrawals for the per-asset and per-category figures getWithdrawableBalances() reads.

​

Candle intervals

The provider supports these OHLCV intervals: 1m, 5m, 15m, 30m, 1h, 4h, 12h, 1d. Requesting any other interval, including 1w, raises a validation error.

​

Related pages

• SDK / Providers — provider discovery and deposit-flow descriptors
• SDK / Withdrawal — withdrawable-balance discovery and submission
• SDK / Streaming — normalized WebSocket subscriptions
• SDK / Actions — authorization-step variants