# Automated Trading Bot

## ZO Trading Bot

Example bot that trades on [ZO Finance](https://zofai.io) using the **zo-sdk**. Supports market orders with take-profit/stop-loss (TPSL), and a grid bot.

{% embed url="<https://github.com/zofinance/zo-integration-examples/tree/main/trading-bot>" %}

### Prerequisites

* **Node.js** (v18+)
* **pnpm** (or npm)
* A **Sui wallet** with a private key you can export (for automated signing)
* **SUI** on the target network (mainnet/testnet) for gas and trading

### Quick start

#### 1. Install dependencies

```bash
pnpm install
```

#### 2. Configure environment

Copy the example env file and set your secrets (never commit `.env`):

```bash
cp .env.example .env
```

Edit `.env`:

| Variable              | Required | Description                                                                              |
| --------------------- | -------- | ---------------------------------------------------------------------------------------- |
| `NETWORK`             | No       | `mainnet` or `testnet`. Default: `mainnet`.                                              |
| `SUI_MAINNET_RPC_URL` | No       | Sui mainnet RPC. Default: public fullnode.                                               |
| `SUI_TESTNET_RPC_URL` | No       | Sui testnet RPC. Default: public fullnode.                                               |
| `PRIVATE_KEY`         | **Yes**  | Sui private key in **Bech32** format (e.g. `suiprivkey1...`). Used to sign transactions. |

**Getting your Bech32 private key**

* From **Sui CLI**: export the key for your key identity (Bech32 is one of the supported formats).
* From **Sui wallet**: use the wallet’s export feature if it supports Bech32; otherwise you may need to convert.

The app uses `decodeSuiPrivateKey(privateKeyBech32)` from `@mysten/sui/cryptography`, so the key must be in a format that function accepts (e.g. Bech32 `suiprivkey1...`).

#### 3. Run the bot

**Market / TPSL bot** (entry point: `index.ts`):

```bash
pnpm start
```

**Grid bot** (entry point: `grid-bot-run.ts`):

```bash
pnpm run grid
```

Before running, edit the config in the corresponding file (see below).

***

### Integration overview

#### How the bot connects to ZO

1. **Connection** (`connection.ts`)
   * Builds a `SuiClient` from `SUI_MAINNET_RPC_URL` or `SUI_TESTNET_RPC_URL` and `NETWORK`.
   * Uses **zo-sdk** `SDKFactory` to create API and DataAPI instances for ZLP, SLP, and USDZ pools.
   * ZO API endpoint: `https://api.zofinance.io`. Pyth price connection: `https://hermes.pyth.network`.
2. **Keypair** (`keypair.ts`)
   * Loads `PRIVATE_KEY` from env and creates an `Ed25519Keypair` via `decodeSuiPrivateKey` + `Ed25519Keypair.fromSecretKey`.
   * Used for signing all Sui transactions (opens/closes positions, places/cancels orders).
3. **Trade config**
   * You choose pool (`LPToken.ZLP`, `LPToken.SLP`, or `LPToken.USDZ`), index token (e.g. `btc`), collateral (e.g. `nusdc`), sizes, and (for TPSL) take-profit/stop-loss percentages.

#### Config for market / TPSL bot

Edit `index.ts` and set `TradeConfig` (and optionally switch between `tradeWithMarketOrder` and `tradeWithTPSL`):

* `indexToken`, `collateralToken`, `pool`, `long`
* `minSize` / `maxSize` (in index token base units, e.g. 1e8 for BTC) or fixed `size`
* `collateralAmount` (in collateral base units, e.g. 6 decimals for USDC)
* `takeProfitPercentage`, `stopLossPercentage`
* `tradeInterval` (ms), `tradeMode`: `'Market'` or `'TPSL'`
* `createOpposite`: whether to open the opposite position after closing.

#### Config for grid bot

Edit `grid-bot-run.ts` and set the grid config object:

* `indexToken`, `collateralToken`, `pool`
* `gridLowerPrice`, `gridUpperPrice`, `gridLevels`
* `orderSize` (index token base units), `collateralAmount` (collateral base units)
* `pollIntervalMs`, optional `maxVolumeUSD`

Then run:

```bash
pnpm run grid
```

#### Project layout

| File              | Purpose                                                                                             |
| ----------------- | --------------------------------------------------------------------------------------------------- |
| `index.ts`        | Market / TPSL bot entry; defines `TradeConfig` and calls `tradeWithMarketOrder` or `tradeWithTPSL`. |
| `grid-bot-run.ts` | Grid bot entry; defines grid config and calls `runGridBot`.                                         |
| `grid-bot.ts`     | Grid bot logic (place/cancel orders, rebalance grid).                                               |
| `trade.ts`        | Core trading: open/close positions, TPSL and market flows.                                          |
| `connection.ts`   | Sui client and ZO SDK API/DataAPI instances (ZLP/SLP/USDZ).                                         |
| `keypair.ts`      | Loads `PRIVATE_KEY` from env and returns Ed25519 keypair.                                           |
| `network.ts`      | Reads `NETWORK` from env (mainnet/testnet).                                                         |
| `order.ts`        | Order caps and order key parsing.                                                                   |
| `position.ts`     | Position helpers.                                                                                   |
| `utils.ts`        | Relayer fee, reserve amount, coin helpers.                                                          |
| `constants.ts`    | Slippage, relayer fee, trade-level constants.                                                       |
| `deployments.ts`  | Uses `zo-sdk` `getConsts(NETWORK)` for contract addresses.                                          |

#### Dependencies

* **zo-sdk** – ZO protocol API and types (pools, positions, orders).
* **@mysten/sui** – Sui client, keypair, transactions.
* **dotenv** – Loads `.env` into `process.env`.
* **bignumber.js** – Numeric handling for sizes and fees.


---

# Agent Instructions: 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:

```
GET https://docs.zofinance.io/building-on-zo/automated-trading-bot.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.