> For the complete documentation index, see [llms.txt](https://docs.lighter.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lighter.xyz/evm/interop/accounts.md). # Accounts Lighter EVM and Lighter Core use separate account models. This page explains both models and how an EVM address can control a Core account. ## Lighter EVM accounts Lighter EVM uses the same account model and address format as Ethereum L1: accounts are either externally owned accounts (EOAs) or smart contracts, identified by a 20-byte address. Account state is independent between L1 and Lighter EVM. ## Core accounts Core has master accounts and subaccounts. Each subaccount belongs to, and is controlled by, exactly one master account. Every Core account maintains its own state, including balances, orders, positions, and API keys. Every Core account is uniquely identified by a `uint48 accountIndex` assigned when the account is created. Master account indices are in `[0, 2^47 - 1]`, while subaccount indices are in `[2^47, 2^48 - 2]`. A master account is created when the protocol processes the first deposit for a previously unregistered address. Once the master account exists, subaccounts can be created under it. Master accounts are also well-indexed by the tuple `(domain, address)`, where `domain` is either Ethereum L1 or Lighter EVM. Each tuple identifies at most one Core master account, and each master account has exactly one controlling tuple. Core therefore treats the same 20-byte address on Ethereum L1 and Lighter EVM as two distinct controllers. ### EVM-controlled accounts An EVM-controlled master account is indexed by `(Lighter EVM, address)`, where `address` may identify an EOA or a smart contract. Core creates the master account when it processes the first [deposit from Lighter EVM](/evm/interop/tokens/token-transfers/evm-and-core.md#evm-to-core) to the controlling EVM address. Once the account is created, you can retrieve its `accountIndex` from Lighter EVM using the [EVM account index](/evm/interop/reading-core-from-evm.md#evm-account-index) read. The controlling address operates the master account and its subaccounts through the [`EvmToCoreEntrypoint`](https://github.com/elliottech/lighter-contracts/blob/lighter-evm-devnet/contracts/messaging/EvmToCoreEntrypoint.sol) and [`EvmInteropManager`](https://github.com/elliottech/lighter-contracts/blob/lighter-evm-devnet/contracts/interop/EvmInteropManager.sol) predeploys; see [EVM and Core](/evm/interop/message-passing/evm-and-core.md). ### L1-controlled accounts An L1-controlled master account is indexed by `(Ethereum L1, address)`. Core creates the master account when it processes the first deposit from Ethereum L1 to the controlling L1 address. The controlling address operates the master account and its subaccounts from L1 and cannot operate them from Lighter EVM. These accounts can only be created by deposits from L1. ### Account authorization Core recognizes two forms of authorization: **API-key authorization** and **master authorization**. #### API-key authorization An API key authorizes its holder to submit routine Core transactions, such as placing and cancelling orders, without obtaining separate approval from the master account’s controller for each transaction. The key holder signs these transactions and submits them directly to Core, without sending an Ethereum L1 or Lighter EVM transaction. The controller may hold the API key itself or allow a separate operator to hold it. For example, a smart contract can register a key held by an off-chain operator, allowing that operator to trade on the contract’s behalf. Accounts created through deposits initially have no API keys. The master account’s controller must authorize registering the first key and can later update or revoke it. For what an API key can do, including on subaccounts, see Lighter's [API keys guide](https://docs.lighter.xyz/developers/integration-guides/api-keys#permissions). `GET /api/v1/accountsByEvmAddress?evm_address=...` lists an EVM-controlled account's subaccounts. To generate an API-key pair locally, see [generate an API-key pair](/evm/signing-core-transactions.md#generate-an-api-key-pair) in the Signing Core transactions guide. An API key can be registered in three ways. * **From Core.** An EOA controller of an L1-controlled or EVM-controlled account can submit a signed `ChangePubKey` transaction (`txType = 8`). It requires a signature from the new API key and the controller's ECDSA signature, so no previously registered key is needed. See [Lighter's API-key registration guide](https://docs.lighter.xyz/developers/integration-guides/create-accounts-programmatically#id-2.-register-an-api-key). * **From EVM.** The controller of an EVM-controlled account calls [`EvmToCoreEntrypoint.changePubKey(...)`](/evm/interop/message-passing/evm-and-core.md#change-public-key). * **From L1.** The controller of an L1-controlled account calls [`L1CoreMessaging.changePubKey(...)`](/evm/interop/message-passing/l1-and-core.md#supported-requests). See [Signing Core transactions](/evm/signing-core-transactions.md) for setting up the WASM signer and submitting transactions directly to Core. #### Master authorization Master authorization is explicit approval from the master account’s controller. It is required to manage API keys and to perform certain sensitive operations, such as withdrawals to L1. A directly submitted Core transaction may require API-key authorization, master authorization, or both, depending on the operation. The controller can provide master authorization in either of two ways: * **By signature.** If the controlling address is an EOA, it can provide an ECDSA signature [authorizing the operation](/evm/signing-core-transactions.md#add-controller-authorization). * **From its controlling domain.** The controller can call the corresponding method on Ethereum L1 or Lighter EVM. The authenticated caller provides master authorization, so a separate ECDSA signature is unnecessary. A smart contract cannot produce an ECDSA signature. A contract-controlled account must therefore use the appropriate L1-initiated or EVM-initiated method when master authorization is required. It can still register an API key that an off-chain operator uses for routine transactions requiring only API-key authorization. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.lighter.xyz/evm/interop/accounts.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.