Setup

Account setup for Lighter deployments: sequence, signer and relay of each step, and the required Plus or Premium tier

Before trading on lighter or lighter-rh, use the provider metadata and checkSetup() flow. The plugin owns the native signing key, encrypted persistence, WASM signer, and read-only token lifecycle; applications supply the user wallet only when a step is signed by USER.

A brand-new address must complete its first-deposit flow before setup. REGISTER_API_KEY needs the venue-assigned account_index, so an unfunded account returns accountExists: false with no setup steps.

const provider = 'lighter'; // or 'lighter-rh'
let required = await perps.checkSetup({ provider, address: userAddress });

if (!required.accountExists) {
  // Complete getDepositFlow() before setup.
}

while (required.accountExists && !required.isReady) {
  // The checklist is in sequence order. Handle its first unsatisfied item.
  const item = required.checklist.find((entry) => !entry.satisfied);
  if (!item) break;

  const { options } = item.descriptor;
  if (options !== null) {
    // Show the options and let the user choose. This example takes the recommended one.
    const option = options.find((o) => o.default === true) ?? options[0];
    await perps.executeProviderOption({
      provider,
      address: userAddress,
      option,
    });
  } else {
    const step = required.setup.find((s) => s.action === item.descriptor.type);
    if (!step) break;
    await perps.executeProviderSetupAction({
      provider,
      address: userAddress,
      step,
      checklist: required.checklist,
    });
  }

  // The checklist is a snapshot. Read it again after each step.
  required = await perps.checkSetup({ provider, address: userAddress });
}

checkSetup() runs SDK-signed steps such as setReferrer itself, without a wallet prompt. It returns the steps that need the user in descriptor sequence order.

The SDK never applies a choice for the user. The snippet above picks the recommended option only to keep the example short. An application shows the options and lets the user choose. A choice can block the steps after it: on a new account, approveIntegrator (sequence 30) waits for the accountType choice (sequence 25). The snippet therefore handles the checklist one item at a time, in sequence order. See How checkSetup() treats each step.

If you call the API without the SDK, see Integrating without the SDK.

​

Steps in sequence order

A step runs only after every step with a lower sequence is satisfied.

Sequence	Step	Type	signer	relay	Shown to the user
10	registerApiKey	Action	USER	API	Yes
20	setReferrer (conditional)	Action	SDK	CLIENT	No. The SDK applies it without a wallet prompt.
22	accountMode	Choice	SDK	API	Yes
25	accountType	Choice	SDK	CLIENT	Yes
30	approveIntegrator	Action	USER	API	Yes

setReferrer is present only when the deployment has a referral code and an X handle configured. lighter-rh currently advertises no setReferrer step.

Every step uses the wasmBlob signing method. relay: API means the signed step goes to POST /executeAction. relay: CLIENT means the SDK sends the step to Lighter itself, and nothing reaches LI.FI.

​

Setup descriptors

​

registerApiKey

Registers a provider-native Lighter keypair at an on-chain key slot. The new key signs the WASM ChangePubKey blob and the user’s L1 wallet countersigns the EIP-191 authorization.

Title	Register trading API key
Signer	USER
Relay	API
Signing method	wasmBlob
Sequence	10
Revoke	none
When needed	First setup, or when the local key no longer matches the registered slot

The backend selects the registration slot and sends it in wasmSignParams.api_key_index. Re-registering that slot replaces its prior key. Each provider instance namespaces its persisted key, so lighter and lighter-rh credentials never collide.

​

setReferrer

Applies LI.FI’s configured referral code. The SDK creates a short-lived auth token and posts the request directly to Lighter (/api/v1/referral/use); no WASM blob is produced and nothing goes to the LI.FI backend, although the descriptor advertises wasmBlob. A referral code already applied to the account (any referrer) satisfies the step. This descriptor is omitted unless both the referral code and referral X handle are configured. checkSetup() applies it inline without a wallet prompt. Tell your users that a referral code is applied.

Title	Apply referral code
Signer	SDK
Relay	CLIENT
Signing method	wasmBlob
Sequence	20
Revoke	none

The SDK sends the referral to Lighter with a form post to /api/v1/referral/use, authenticated with a Lighter auth token made from the API key. The token never reaches LI.FI.

​

accountMode

A choice between a Simple and a Unified trading account. It sets how Lighter margins the positions of the account. The user decides, and the SDK never applies the choice.

Title	Account mode
Signer	SDK
Relay	API
Signing method	wasmBlob
Sequence	22
Revoke	none
Options	Simple Trading Account ({ mode: 'simpleTradingAccount' }), Unified Trading Account ({ mode: 'unifiedTradingAccount' })
Docs	Lighter unified trading accounts

The Unified Trading Account option carries default: true. This marks it as the recommended option for a UI. It is a hint only. Nothing is changed until the user picks an option and the client executes it. Lighter rejects a change while the account has open positions or pending orders, and the SDK surfaces the venue error.

​

accountType

A choice of the Lighter account tier. The step is required on both Lighter deployments, Lighter Core (lighter) and Robinhood Chain (lighter-rh). An unsatisfied tier keeps isReady false. The step is a choice between Plus and Premium.

Title	Account tier
Signer	SDK
Relay	CLIENT
Signing method	wasmBlob
Sequence	25
Revoke	none
Options	Plus ({ tier: 'plus' }, recommended), Premium ({ tier: 'premium' })
Docs	Lighter trading fees

For fees and the full comparison of the tiers, see Lighter account types.

How the user chooses. The user picks Plus or Premium in the tier setting and confirms the choice. Plus is the recommended option, and a UI pre-selects it. The SDK never applies the tier on its own.

Changing the tier. The user can change the tier afterwards. Lighter owns the rules of a tier change. A move up, such as Plus to Premium, has no cooldown. A move down is allowed only when 24 hours have passed since the last change. Lighter refuses a tier change while the account has open positions or open orders.

Why the step is required. Lighter accepts orders routed through an integrator only from Plus or Premium accounts. Without a tier, the SDK and executeAction return SetupRequired. The tier step is sequenced before approveIntegrator for this reason.

The SDK executes the chosen option with a form post to /api/v1/changeAccountTier, authenticated with a Lighter auth token made from the API key. The token never reaches LI.FI.

​

approveIntegrator

Authorizes LI.FI’s integrator account and maximum fee cap. Lighter requires both the native WASM signature and the L1 owner’s EIP-191 signature when the integrator belongs to another address with non-zero fee caps.

Title	Authorise integrator allowance
Signer	USER
Relay	API
Signing method	wasmBlob
Sequence	30
Revoke	revokeIntegrator
Docs	Lighter partner integration
When needed	When the deployment has an integrator configured and the existing approval is insufficient

The step is revocable. Its revoke points at revokeIntegrator, an entry in actions with signer: SDK and relay: API. Lighter treats an approval with every maximum fee and the approval expiry set to 0 as a revocation. It needs no L1 signature. After the revoke, the step is unsatisfied and checkSetup() stages it again. See executeProviderRevoke.