API keys

You can use API keys to trade and manage your lighter account programmatically. Each API key will be assigned an index, ranging from 0 to 254 - indexes 0, and 1 are reserved for desktop and mobile interfaces.

Each internal account, whether that's a master account or a sub-account, will have its own separate API key index - and each comes with a public & private key, and its own nonce.

Permissions

API keys enable both write and read permissions, allowing you to query auth-gated REST endpoints and Websocket channel, but also send transactions and process withdrawals.

While it allows to process withdrawals, you should consider that only secure withdrawals can be executed without also providing the account's Ethereum private key - as they can only be sent to the same L1 address that created the account. On the other hand, Fast Withdrawals and Transfers can be sent to other L1 addresses and will require the wallet's private key.

Authentication

To interact with certain endpoints, you will need to generate an auth token using your API private key. You can do so using our GO SDK, or use the create_auth_token_with_expiry() function in our Python SDK. Each auth code can have a maximum expiry of 8 hours, and it uses the following structure: {expiry_unix}:{account_index}:{api_key_index}:{random_hex}.

Read-only Authentication

Using a canonical auth code, you can generate read-only auth tokens - those won't allow placing trades nor request withdrawals (essentially, you won't be able to sign transactions hence initialize a signer client), but you will be able to access auth-gated data via API. Each read-only auth code can have a maximum expiry of 10 years, and a minimum of 1 day. They will use the following structure: ro:{account_index}:{single|all}:{expiry_unix}:{random_hex}. You can generate one using the createToken endpoint, or via front-end.

How to create API keys programmatically

You can create new keys programmatically using either the Python SDK, or the GO SDK. While generating the API keys does not require your L1 private key, associating them with your Lighter account does. You can either do this via the SDKs, or interact with Lighter's smart contract directly using the ChangePubKey function (this is particularly helpful if you're running a multi-sig).

Nonce management

Each API key will have its own nonce, and the API servers require it to be increased by 1 for each transaction you submit. While the Python SDK handles nonce management on its own, you might want to manage it locally to handle more complex systems. Since some types of transactions may be subject to speed bumps based on your account type, and they are processed sequentially, you may want to use multiple API keys for the same account e.g. one for each type of order to always guarantee the fastest execution.