> For the complete documentation index, see [llms.txt](https://documentation.kodiak.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.kodiak.finance/user-guide/perp-bots.md).

# Perp Bots

### Deploying your first bot <a href="#deploying-your-first-bot" id="deploying-your-first-bot"></a>

1. **Accept Terms of Service:** Review the Terms of Use and Privacy Policy, check the acknowledgement box, then select `Agree and Continue`.

<figure><img src="/files/erOYYah2I8kp6sQUlSJh" alt=""><figcaption></figcaption></figure>

2. **Connect Wallet:** Select `Connect Wallet` in the top-right corner of the app and choose your desired wallet provider.

<figure><img src="/files/avqozNyOhquqnbCWsnaj" alt="Connect Wallet"><figcaption></figcaption></figure>

3. **Sign in with your wallet:** After connecting, accept Terms of Service, select `Sign in` and confirm the signature request in your wallet.

<figure><img src="/files/nqG5PtzOYWeGKMUVD3Q7" alt=""><figcaption></figcaption></figure>

4. **Set your passphrase:**
   * Go to the Accounts page and select `Set passphrase` in the banner.

<figure><img src="/files/5lP7aG53bbhiNcHCIZON" alt=""><figcaption></figcaption></figure>

* In the modal window that opens, create a passphrase that will be used to encrypt your exchange API keys in your browser before they are stored.

{% hint style="info" %}
Keep this passphrase safe. If you lose it, you will need to reset your linked accounts and add them again.
{% endhint %}

<figure><img src="/files/HXKCwtx7pbbgf56mx92f" alt=""><figcaption></figcaption></figure>

5. **Add an account:** On the Accounts page select `Add Account`.

<figure><img src="/files/Uie7cHRpm179ggIM2PIe" alt=""><figcaption></figcaption></figure>

The app currently supports the following exchanges: Kodiak Perps and Hyperliquid. In this guide, we will use Kodiak Perps.

You will see then two options:

1. Generate new API Key: creates a new API Key for your exchange account through the app.
2. Use Existing: adds API credentials that were already created on the exchange side.

For this guide, we will continue with option 1.

<figure><img src="/files/xvm3lJlndzcS3jJX5Pxp" alt=""><figcaption></figcaption></figure>

Select an exchange account you want to use, enter a name for it, then click `Generate API Key` button and confirm the signature request in your wallet.

<figure><img src="/files/YL8bTdQDxblQimuYk83U" alt=""><figcaption></figcaption></figure>

Once an account is created, it appears in the accounts list with an Active status. Active account can be used to deploy and run bots. You can also deactivate an account from this page if you no longer want to use it.

6. **Deploy a bot:** Go to the Deploy page.&#x20;

At the top of the page, select exchange, account and trading pair for your bot.

The left side of the screen contains a chart for the selected market. After setting lower and upper grid bounds, grid levels will appear on the chart.\
\
Use the configuration panel on the right to define how your grid bot should trade.

* Grid Lower Bound: lowest price where the bot will place orders.
* Grid Upper Bound: highest price where the bot will place orders.
* Order Size per Grid Level:  USD amount used for each grid level.
* Number of levels: number of grid levels created between lower and upper grid bounds.
* Level type: spacing method for grid levels.

&#x20;   a) Arithmetic: equal price spacing between levels (e.g., $100 apart)

&#x20;   b) Geometric: equal percentage spacing between levels (e.g., 1% apart). Better for volatile assets.

* Max orders per side: maximum orders opened at a time per side of grid.
* Orders Frequency: update frequency for refreshing orders.

Below the configuration fields, review calculated summary below the configuration fields. It shows whether selected grid settings fit the free margin available in the account. If settings match your strategy and account has enough margin, click `Deploy Bot`.

<figure><img src="/files/ZFb4lE8CNVIaGAGq3H51" alt=""><figcaption></figcaption></figure>

7. **Monitor your bot:** After deployment, the app opens the bot details page.

At the top of the page, you can see the bot name, current status, exchange, trading pair, version and deployment time. Status badges show the current bot state and help you see whether the bot is active and trading within the configured range.

The chart shows the selected market together with bot data. You can use it to review grid levels, open orders, filled orders and current position.

<figure><img src="/files/HMpKTFdfFfElEyBwWIeC" alt=""><figcaption></figcaption></figure>

Below the chart, you can find detailed sections for margin, grid configuration, position, open orders, analytics, fills, error logs and API usage. These sections help you monitor how the bot is performing and check whether it is trading as expected.

8. **Manage your bot:** Use the action buttons at the top of the bot details page to control the bot.

* Pause: temporarily stops the bot from managing orders.
* Resume: starts a paused bot again.
* Stop: stops the bot completely. When stopping, you can choose whether to keep position open or close them.
* Copy: opens the deploy page with the same configuration so you can create a similar bot.

<figure><img src="/files/3T68mUj89B1WGDW60ZoJ" alt=""><figcaption></figcaption></figure>

9. **Find your bots later:** Go to Dashboard page to view your own bots.

The dashboard shows active and historical bots, along with performance metrics such as total PNL, grid PNL, unrealized PNL, fees and volume. From there you can open any bot details or deploy a new bot.

<figure><img src="/files/MqPxyif9G8tFlTrVFD8s" alt=""><figcaption></figcaption></figure>

### Common issues

<details>

<summary>I cannot deploy a bot</summary>

Make sure your wallet is connected, you are signed in, your passphrase is unclocked, and at least one account exists for selected exchange.

</details>

<details>

<summary>Margin required is too high</summary>

Reduce order size, reduce number of grid levels, narrow grid range, or add more funds to selected account.

</details>

<details>

<summary>Bot is out of range</summary>

Current market price is outside configured grid bounds. Stop the bot and deploy a new one with updated bounds.

</details>

<details>

<summary>I forgot my passphrase</summary>

Go to Settings page and reset your passphrase. After resetting it, you will need to add your accounts again.

</details>