> For the complete documentation index, see [llms.txt](https://botlyz.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://botlyz.gitbook.io/docs/english/installation-pas-a-pas/connecter-un-compte-lighter.md). # Connect your account to Botlyz (API key) ## Before you start To trade with Botlyz, you must connect a Lighter account (an account on the Lighter perpetual DEX). This page explains how to add an exchange account and generate a secure API key. Before following this page, make sure your Lighter account is ready: * [Create a Lighter account](/docs/english/installation-pas-a-pas/creer-un-compte-lighter.md): open an account on Lighter and connect your wallet. * [Deposit funds on Lighter](/docs/english/installation-pas-a-pas/deposer-des-fonds.md): fund your account with collateral (USDC). * [Understanding L1 and L2](/docs/english/comprendre-l1-l2.md): the difference between your wallet (L1) and your Lighter trading account (L2). If you are just getting started, follow the [step-by-step installation guide](/docs/english/installation-pas-a-pas.md) instead, which covers all these steps in order. > **Important**: Botlyz is an automation **software editor**, not a fund manager. The tool is **non-custodial**: you keep **full control** of your capital and your keys. Strategies run under your responsibility, based on a configuration that you sign yourself (EIP-712). Trading carries a risk of loss, and past performance does not guarantee future results. ## Lighter API key: what is it? A **Lighter API key** is a technical identifier that allows the software to place and cancel orders on your Lighter account, strictly applying the rules you have configured and signed. It is made up of two parts: 1. **Key index** (4 to 254): a number you choose to identify this key. 2. **Private key**: a long hexadecimal character string that signs orders. ### Security: a "trade-only" key Botlyz **can only place and cancel orders** with this key. It **cannot**: * Withdraw funds from your account. * Transfer your collateral. * Change your account settings. * View your other API keys. This is what is called a **"trade-only"** key, or "limited to orders". No withdrawal is therefore possible with the key entrusted to Botlyz. ## Prerequisites ### Have a Lighter account 1. Create your Lighter account via our referral link: [app.lighter.xyz/?referral=BOTLYZ](https://app.lighter.xyz/?referral=BOTLYZ). 2. Connect with your wallet (the same one used for Botlyz). See [Connecting your wallet](/docs/english/installation-pas-a-pas/connecter-votre-wallet.md). 3. Deposit collateral into your Lighter account. To deposit funds, see [Deposit funds on Lighter](/docs/english/installation-pas-a-pas/deposer-des-fonds.md). ### Minimum capital The minimum capital depends on **the pair you trade**: * Each pair has a **minimum order size** (in USD), defined by Lighter. For example, some pairs require a minimum of 20 to 50 USD per order. * Botlyz recomputes this minimum based on your leverage and your allocation. * Before deploying a strategy, Botlyz displays the **minimum tradable capital required** and your current capital. Example: * HYPE pair, minimum 50 USD, 5x leverage, 50% allocation: minimum tradable capital 500 USD, i.e. a required capital of about 100 USD. Botlyz prevents you from deploying a strategy if your capital is insufficient. ## Generating a Lighter API key This key is created **at Lighter**, not in Botlyz. Plan to write down **three pieces of information** that you will then enter into Botlyz: your **Ethereum address**, the **key index** and the **private key**. > 👉 Create your key directly at [app.lighter.xyz/apikeys](https://app.lighter.xyz/apikeys) (at Lighter: **Settings** then **API Keys**). The key index must be between **4 and 254** (indices 0 to 3 are reserved by Lighter for its own apps). 1. Open [app.lighter.xyz/apikeys](https://app.lighter.xyz/apikeys) and connect to Lighter with your wallet (the one you already use for Botlyz). 2. Click the **"Generate API Key"** button. 3. Choose a free **key index**, between **4 and 254** (for example, 4). Indices **0 to 3 are reserved** by Lighter for its own applications: do not use them. This is the **only setting to make**: there is **no permission to choose**. A Lighter API key can only **trade, never withdraw** your funds anyway. Write down the index you chose, it will be asked again. 4. If Lighter asks, **sign** with your wallet to confirm (a free, off-chain operation). 5. Lighter then displays the **private key** (it may appear only **once**). **Copy it immediately** and keep it in a safe place (for example a password manager). 6. Also note your **Ethereum address** (it starts with `0x`): it is the public address of your wallet, visible in Lighter and in your wallet. At the end, you must have **three items** on hand: your **Ethereum address** (`0x...`), the **key index** (between 4 and 254) and the **private key** (a long hexadecimal string). They will be requested in the next step. > **Warning**: do not close this page without having copied your private key. Lighter displays it only once: if you lose it, you will not be able to retrieve it and will have to create a new key. ## Connecting the key to Botlyz ### Through the Botlyz interface 1. Go to **Settings** then **Exchange accounts** (or the equivalent). 2. Click **"Add a Lighter account"**. 3. Fill in: * **Label**: a name for this account (e.g. "My main account"). * **Ethereum address**: the public address of the Lighter wallet (e.g. `0x1234...`). * **Key index**: the number you chose at Lighter (e.g. 4). * **Private key**: paste the private key copied from Lighter. 4. Botlyz **immediately verifies** the key with Lighter. * If the key is valid, it is accepted and **encrypted at rest** (never stored in plain text). * If it is invalid or expired, Botlyz rejects the connection with an error message. 5. Once connected, the account appears in your list of accounts. ### Lighter sub-accounts Lighter supports **sub-accounts** (isolated sub-accounts attached to the same Ethereum address). For example: * Main account: your default Lighter account. * Sub-account 1: isolated collateral for one strategy. * Sub-account 2: isolated collateral for another strategy. Botlyz automatically detects the sub-account associated with your API key during connection. If you have several sub-accounts, you can connect a key for each of them (with different labels). ## Security of your API key ### At Botlyz * Your private key is **encrypted immediately** after verification (strong encryption at rest). * It is **never stored in plain text** and **never logged**. * Only the Botlyz server that runs your strategies can decrypt it. * If you delete the Lighter account, the key is deleted from the database. ### At Lighter * The key exists on the Lighter registry. If you revoke it at Lighter, Botlyz can no longer use it. * You can revoke a key at any time, without prior notice to Botlyz (the strategies will then stop working). ### Best practices 1. **Use a key dedicated to Botlyz.** Do not share the same key with other services. 2. **Keep a modest amount of collateral** on this sub-account. The lower the collateral, the more limited the risk if the key is compromised. 3. **Revoke the key if**: * You no longer use Botlyz. * You suspect a leak. * You change strategy or venue. 4. **Never share your private key** with anyone, including Botlyz support. ## After connecting ### Approving the protocol fee Before deploying your first strategy on this account, you must **approve the protocol fee**: **10 bps (0.10%)** charged automatically on each order via Lighter's "partner attribution" program, capped at 10 bps. This is a **protocol fee, charged and remitted by the platform; it is NOT a Botlyz invoice or commission**. This process: 1. Generates a message to sign (off-chain, free). 2. You sign it with your wallet. 3. Botlyz records your approval. You only need to approve it once per account or sub-account. For details of the fee model, see [Fees](/docs/english/frais.md). ### Viewing your balance In Botlyz, go to **Accounts** and click on the Lighter account. You will see: * The available collateral (USD). * The open positions. * The trade history. The balance is fetched in real time via the authenticated Lighter API. ## Managing several Lighter accounts You can connect several Lighter accounts or sub-accounts to Botlyz: * Each receives a distinct label. * Each strategy runs on **a single account** (no multi-account per strategy). * Allocations are **independent per account** (one strategy at 80% on account A, another at 80% on account B: this is possible). ## Editing or deleting an account ### Renaming an account 1. Go to **Settings** then **Accounts**. 2. Click the edit icon (pencil). 3. Change the label and confirm. ### Updating the API key 1. If your API key is expired or compromised, create a new one at Lighter. 2. In Botlyz, click the account, then **"Update the key"**. 3. Enter the new private key and the new index. 4. Botlyz verifies and updates. ### Deleting an account 1. Go to **Settings** then **Accounts**. 2. Click the account, then **"Delete"**. 3. If strategies are active, Botlyz stops them (all positions are closed). 4. Once all positions are closed, the account is deleted. ## Troubleshooting ### "Invalid API key" * Check that you copied the private key **in full** (without extra spaces). * Check that the **key index** is correct (the one you chose at Lighter). * If the key was revoked at Lighter, create a new one and try again. ### "Sub-account not found" * You entered a sub-account index that does not exist for your Ethereum address. * Check the exact index at Lighter (Settings then Sub-accounts). ### "No Lighter account for this address" * The Ethereum address does not correspond to a valid Lighter account. * Check that you have created a Lighter account and deposited collateral. * Use the same address as the one you are connected with on Lighter. ### "Balance momentarily unavailable" * The Lighter API is temporarily unavailable. * Wait a few seconds and try again. * If the problem persists, check Lighter's status on its official channels. ## Frequently asked questions **Q. Can the same Lighter account be connected to several Botlyz users?** No. Each Lighter account can only be connected to **a single Botlyz wallet**. If you need separation, create sub-accounts at Lighter. **Q. Can this API key withdraw my funds?** No. A Lighter API key can only **trade**: it allows **no withdrawal** to an external address. There is in fact no permission to set when creating it, this is how it works by design. Your funds can only come back to your own wallet, and you are the one who triggers the withdrawal on Lighter. **Q. How many keys can I connect?** As many as you like. You can have one key per strategy, one key per sub-account, etc. Botlyz handles this transparently. **Q. What happens if I revoke the API key at Lighter?** Your Botlyz strategies will stop working (orders will no longer be placed). Botlyz has no way of knowing that the key is revoked until the Lighter API rejects the request. **Q. Does Botlyz charge fees on top of Lighter's?** The only Botlyz fee is the **protocol fee of 10 bps (0.10%)**, charged automatically on each order via Lighter's "partner attribution" program and capped at 10 bps. It is a **protocol fee, charged and remitted by the platform; it is NOT a Botlyz invoice or commission**. Botlyz charges **no commission on your gains**. In addition, the Lighter platform's own fees (trading, funding) apply independently of Botlyz. See [Fees](/docs/english/frais.md). **Q. Is my API key used for anything other than orders?** No. It is only used to: * Place orders (limit or market). * Cancel orders. * Read your balance and your positions (for PnL calculation). It cannot withdraw funds. --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://botlyz.gitbook.io/docs/english/installation-pas-a-pas/connecter-un-compte-lighter.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.