Grid Bot Extended

A Perpetual Futures Trading Bot for X10 Exchange (Extended) - Showcase for ask-starknet

⚠️ CRITICAL WARNINGS ⚠️

🚨 USE AT YOUR OWN RISK 🚨

This software is provided as-is, without any guarantees or warranty. By using this software, you accept all risks associated with automated trading.

NO PROFIT GUARANTEE: This bot does NOT guarantee profits. You can and likely will lose money.
EDUCATIONAL PURPOSE: This is a showcase/demonstration project, not production-ready trading software.
NOT A REAL GRID BOT: This is NOT a traditional grid bot because perpetual futures platforms like Extended don't allow you to own actual tokens - you only have positions. This is better described as a perpetual futures trading bot with grid-like behavior.
HIGH RISK: Trading perpetual futures with leverage involves substantial risk of loss.
NO FINANCIAL ADVICE: This software does not provide financial advice. Do your own research.
TEST FIRST: Always test with small amounts you can afford to lose.

⚠️ Important Limitations

Works with perpetual positions, not spot trading
You don't own the underlying assets
Leverage amplifies both gains and losses
Market volatility can lead to rapid losses
The bot may not perform as expected in all market conditions

📖 About

Grid Bot Extended is a perpetual futures trading bot built for the X10 Exchange (Extended) on Starknet. It implements a grid-like trading strategy on perpetual futures markets.

This project is a showcase of what can be built using ask-starknet, an AI-powered toolkit for Starknet development.

What is a "Grid Bot" on Perpetuals?

Traditional grid bots work by:

Buying assets at lower prices
Selling assets at higher prices
Profiting from market oscillations

However, on perpetual futures platforms like Extended:

You don't own actual tokens
You only hold leveraged positions (long/short)
The bot creates a grid of orders to open/close positions

How It Works

The bot creates a neutral grid strategy designed to profit from small market variations:

Grid Setup: Divides a price range into multiple levels (grid)
Order Placement: Places buy and sell orders at each grid level
Position Management: Opens long positions when price falls, short positions when price rises
Profit Target: Aims to capture small profits from price oscillations within the grid

Strategy Modes:

Neutral: Mixed long/short positions to profit from volatility in both directions
Long: Bias towards long positions (bullish)
Short: Bias towards short positions (bearish)

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                    Grid Bot Extended                     │
│                                                          │
│  ┌────────────┐      ┌──────────────┐      ┌─────────┐ │
│  │   API      │─────▶│  Grid Bot    │─────▶│ X10     │ │
│  │  Server    │      │   Manager    │      │Exchange │ │
│  │  (Express) │      │              │      │  API    │ │
│  └────────────┘      └──────────────┘      └─────────┘ │
│        │                     │                          │
│        │              ┌──────▼──────┐                  │
│        │              │ Starknet    │                  │
│        │              │ Integration │                  │
│        │              └─────────────┘                  │
│        │                                                │
│  ┌─────▼──────┐      ┌──────────────┐                 │
│  │Auth &      │      │  AI Provider │                 │
│  │Rate Limit  │      │  (Optional)  │                 │
│  └────────────┘      └──────────────┘                 │
└─────────────────────────────────────────────────────────┘

🚀 Getting Started

Prerequisites

Node.js 18+
npm or pnpm
X10 Exchange account with API access
Starknet wallet with private key
API secret for server authentication

Installation

Clone the repository

git clone https://github.com/KasarLabs/grid-bot-extended.git
cd grid-bot-extended

Install dependencies
```
npm install
# or
pnpm install
```
Configure environment variables
```
cp .env.example .env
```

Edit .env file with your configuration:

# Required
PORT=5050
API_SECRET=your_secure_random_secret_here
EXTENDED_API_URL=https://api.x10.exchange
EXTENDED_API_KEY=your_x10_api_key
EXTENDED_PRIVATE_KEY=your_starknet_private_key
STARKNET_RPC_URL=https://starknet-mainnet.public.blastapi.io

# Optional
NODE_ENV=development
CORS_ORIGIN=*

Security Tip: Generate a strong API_SECRET using:
openssl rand -hex 32

Build the project
```
npm run build
```
Start the server
```
npm start
```
The server will start on http://localhost:5050

📡 API Documentation

Authentication

All /api/* endpoints require authentication using the X-API-Secret header:

X-API-Secret: your_api_secret_from_env

Rate Limiting:

General endpoints: 100 requests per 15 minutes
Authentication attempts: 5 failed attempts per 15 minutes (brute force protection)
Trade history: 20 requests per minute

Endpoints

1. Health Check

No authentication required

GET /health

Response:

{
  "success": true,
  "message": "Service is healthy",
  "data": {
    "status": "ok",
    "uptime": 123.456,
    "timestamp": "2025-11-17T12:00:00.000Z"
  }
}

2. Start Grid Bot

Requires authentication

POST /api/start-grid-bot
Content-Type: application/json
X-API-Secret: your_api_secret

Request Body:

{
  "gridBotTokens": [
    {
      "symbol": "EUR-USD",
      "priceRange": {
        "upperPrice": 1.163,
        "lowerPrice": 1.161
      },
      "gridSpacing": {
        "levelsMax": 4
      },
      "investment": 1.5,
      "leverage": 10,
      "strategy": "neutral"
    }
  ]
}

Configuration Fields:

Field	Type	Required	Description
`symbol`	string	✅	Trading pair (e.g., "EUR-USD", "BTC-USD", "ETH-USD")
`priceRange.upperPrice`	number	✅	Upper bound of the grid (must be > lowerPrice)
`priceRange.lowerPrice`	number	✅	Lower bound of the grid (must be > 0)
`gridSpacing.levelsMax`	number	✅	Number of grid levels (1-1000)
`investment`	number	✅	Investment amount per grid level in USD
`leverage`	number	✅	Leverage multiplier (e.g., 10 = 10x leverage)
`strategy`	string	✅	Trading strategy: `"neutral"`

Strategy Types:

neutral: Balanced approach - profits from price oscillations in both directions
long: Bullish bias - more long positions, expects price to rise overall (not implemented for now)
short: Bearish bias - more short positions, expects price to fall overall (not implemented for now)

Response (Success):

{
  "success": true,
  "message": "Grid bot manager started successfully with 1 bot(s)"
}

Response (Error):

{
  "success": false,
  "message": "Invalid grid bot configuration",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Upper price must be greater than lower price",
    "details": {}
  }
}

3. Stop Grid Bot

Requires authentication

POST /api/stop-grid-bot
Content-Type: application/json
X-API-Secret: your_api_secret

Request Body:

{}

Response:

{
  "success": true,
  "message": "Grid bot stopped successfully"
}

4. Get Trade History

Requires authentication

GET /api/trade-history
X-API-Secret: your_api_secret

Response:

{
  "success": true,
  "message": "Trade history retrieved successfully",
  "data": {
    "trades": [],
    "totalTrades": 0,
    "totalProfit": 0
  }
}

Notes:

Results are cached for 60 seconds for performance
Rate limited to 20 requests per minute

🧪 Testing with Postman

A Postman collection is included: postman_collection.json

Import Steps:

Open Postman
Click Import
Select postman_collection.json
Update the API_SECRET variable to match your .env file

Collection Variables:

BASE_URL: http://localhost:5050
API_SECRET: Your API secret from .env

📊 Example Use Cases

Example 1: Single Token Grid Bot (EUR-USD)

{
  "gridBotTokens": [
    {
      "symbol": "EUR-USD",
      "priceRange": {
        "upperPrice": 1.163,
        "lowerPrice": 1.161
      },
      "gridSpacing": {
        "levelsMax": 4
      },
      "investment": 1.5,
      "leverage": 10,
      "strategy": "neutral"
    }
  ]
}

What this does:

Creates 4 grid levels between $1.161 and $1.163
Invests $1.50 per level with 10x leverage
Uses neutral strategy for balanced trading

Example 2: Multiple Token Grid Bots

{
  "gridBotTokens": [
    {
      "symbol": "BTC-USD",
      "priceRange": {
        "upperPrice": 50000,
        "lowerPrice": 45000
      },
      "gridSpacing": {
        "levelsMax": 10
      },
      "investment": 100,
      "leverage": 5,
      "strategy": "long"
    },
    {
      "symbol": "ETH-USD",
      "priceRange": {
        "upperPrice": 3000,
        "lowerPrice": 2500
      },
      "gridSpacing": {
        "levelsMax": 8
      },
      "investment": 50,
      "leverage": 3,
      "strategy": "neutral"
    }
  ]
}

What this does:

Runs 2 bots simultaneously
BTC bot: 10 levels, $100/level, 5x leverage, long bias
ETH bot: 8 levels, $50/level, 3x leverage, neutral

🔒 Security Features

API Authentication: Required for all trading endpoints
Rate Limiting: Prevents brute force and DDoS attacks
Brute Force Protection: Progressive lockout after failed auth attempts
CORS: Configurable origin restrictions
Helmet: Security headers enabled
Input Validation: Zod schema validation for all requests

🛠️ Development

Project Structure

grid-bot-extended/
├── src/
│   ├── config/          # Configuration loaders
│   ├── manager/         # Grid bot manager logic
│   ├── middleware/      # Auth & rate limiting
│   ├── server/          # Express server
│   ├── types/           # TypeScript types
│   └── index.ts         # Entry point
├── postman_collection.json
├── .env.example
├── package.json
└── README.md

Available Scripts

npm run build       # Build TypeScript to JavaScript
npm start           # Start production server
npm run dev         # Development mode with watch
npm run format      # Format code with Prettier

🤝 Contributing

This is a showcase project. Contributions are welcome but please understand:

This is NOT production-ready
Use at your own risk
No warranty or guarantees

📜 License

ISC

🔗 Links

ask-starknet: https://github.com/KasarLabs/ask-starknet
X10 Exchange: https://x10.exchange
Starknet: https://starknet.io

⚖️ Disclaimer

THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

THE AUTHORS AND KASAR LABS ARE NOT RESPONSIBLE FOR ANY LOSSES, DAMAGES, OR OTHER LIABILITIES THAT MAY RESULT FROM USING THIS SOFTWARE.

TRADING CRYPTOCURRENCIES AND PERPETUAL FUTURES INVOLVES SIGNIFICANT RISK. ONLY TRADE WITH MONEY YOU CAN AFFORD TO LOSE.

Made with ❤️ by KasarLabs

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
docs		docs
src		src
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.npmrc		.npmrc
.prettierignore		.prettierignore
.prettierrc		.prettierrc
Dockerfile		Dockerfile
Dockerfile.dev		Dockerfile.dev
LICENSE		LICENSE
README.md		README.md
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
postman_collection.json		postman_collection.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Grid Bot Extended

⚠️ CRITICAL WARNINGS ⚠️

🚨 USE AT YOUR OWN RISK 🚨

⚠️ Important Limitations

📖 About

What is a "Grid Bot" on Perpetuals?

How It Works

🏗️ Architecture

🚀 Getting Started

Prerequisites

Installation

📡 API Documentation

Authentication

Endpoints

1. Health Check

2. Start Grid Bot

3. Stop Grid Bot

4. Get Trade History

🧪 Testing with Postman

Import Steps:

Collection Variables:

📊 Example Use Cases

Example 1: Single Token Grid Bot (EUR-USD)

Example 2: Multiple Token Grid Bots

🔒 Security Features

🛠️ Development

Project Structure

Available Scripts

🤝 Contributing

📜 License

🔗 Links

⚖️ Disclaimer

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages