How to Set Up Your First Trading Agent

Setting up an automated trading Agent doesn't have to be complicated. With Quantilan, you can go from zero to live trading in under 15 minutes — using a browser-based setup interface and one-command Docker deployment.

What You'll Need

• A computer or VPS running Linux, macOS, or Windows
• Docker + Docker Compose (or Python 3.11+ for direct setup)
• Exchange account — Binance, Bybit, Hyperliquid, or OKX
• About 15 minutes

Download & Install

Clone the repository and prepare the environment. Docker is the recommended approach for VPS and 24/7 deployments.

Option A — VPS / Linux (one command)

Fresh Ubuntu/Debian server? One command installs Docker, clones the repo, and builds the image:

curl -fsSL https://raw.githubusercontent.com/Quantilan/trading-agent/main/install.sh | bash

After it completes, run make setup once to create your config files:

cd trading-agent
make setup

Where to Run

• VPS (recommended) — $5–6/month on DigitalOcean or Hetzner, runs 24/7 unattended
• Mac Mini / Home Server — any machine that stays on
• Windows — download the ZIP and double-click start.bat

Option B — Mac / Linux with make

git clone https://github.com/Quantilan/trading-agent.git
cd trading-agent
make setup   # create .env and state files
make gui     # open Setup GUI at http://localhost:8080

Option C — Windows

No terminal required. Download and double-click to start.

Python required

Python 3.11 or newer must be installed before running start.bat.
Download it from python.org/downloads — during installation check "Add Python to PATH".

Download trading-agent.zip
Unzip the folder
Double-click start.bat

Dependencies install automatically on the first run. The browser opens at http://localhost:8080.

Option D — Python directly

Good for local development and testing, no Docker needed.

git clone https://github.com/Quantilan/trading-agent.git
cd trading-agent
pip install -r requirements.txt
python setup_gui.py   # opens http://localhost:8080

Create Your Personal Telegram Bot

Your agent uses a personal Telegram bot for control and notifications. It's your own bot — private, free, and directly connected to your agent.

Create Telegram bot via @BotFather

Open Telegram, search @BotFather
Send /newbot
Choose a name and username for your Telegram personal bot
BotFather gives you a token:

1234567890:ABCdefGHIjklMNOpqrsTUVwxyz

Save this token — you'll enter it in the Setup GUI.

Activate your bot — press Start

After creating the bot, you must open it and send /start before it can receive any messages. BotFather shows a link like t.me/YourBotName — tap it, or search the bot by username in Telegram.

Don't skip this step

Without pressing Start, Telegram blocks all messages to your bot and the agent cannot reach you. The "Test Telegram" button in the Setup GUI will fail with "chat not found" until Start is sent.

Get your Chat ID

Message @userinfobot in Telegram
It replies with your numeric ID, e.g. 123456789
That number is your Chat ID — save it too

Security model

Only your Chat ID can control the agent. Even with the Telegram Personal bot token, no one else can issue commands.

Get Your Exchange API Keys

Generate API keys on your exchange. The agent needs trading permission only — never enable withdrawals.

Security

API keys are needed only for TRADE MODE (real orders on exchange). In PAPER MODE (simulated trading) no real orders will be placed and API keys are not required.

You can configure the agent to run in TRADE MODE after testing it in PAPER MODE at any time.

Binance Example:

Log in and go to Account → API Management
Click Create API, give it a name (e.g., "Quantilan")
Enable Futures Trading only
Never enable Withdrawal permissions
Copy your API Key and Secret Key

Recommendation: Use a Sub-Account

Create a dedicated sub-account on the exchange specifically for the agent. This keeps the agent's activity completely separate from your personal trading and other bots — clean P&L, isolated risk, no interference.

Security

API keys are stored only in your local .env file — on your device, on your infrastructure. Quantilan never has access to them.

Hyperliquid — 3 credentials:

Wallet Address — your main wallet (0x...)
Private Key — wallet private key
Agent Address — optional, for a dedicated API sub-account

Configure with Setup GUI

Quantilan ships with a browser-based setup interface. Open it, fill in your credentials, run the connection tests — no manual file editing required.

Launch the GUI:

# Docker
make gui
# → open http://localhost:8080

# Python direct
python setup_gui.py
# → open http://localhost:8080

Local machine: Open http://localhost:8080 in any browser.

VPS: The GUI is bound to 127.0.0.1 only (not public). Access it securely via SSH tunnel — run this on your local machine:

ssh -L 8080:localhost:8080 user@your-vps-ip
# Then open http://localhost:8080 in your browser

Not sure of the exact command? Run make tunnel on the server — it prints the right command for your IP.

Configuration

Exchange & Credentials Exchange, API Key / Secret, paper or live mode

Risk Management Margin %, leverage, max positions, default SL %, default TP %, trailing stop

Telegram Bot Telegram Bot token from @BotFather, your Chat ID

Signal & Notifications Signal source, license key, parser mode (regex / LLM)

Tests & Status

Connection Test Exchange connectivity, balance, position mode

Order Test Full cycle: open → set SL/TP → modify SL → close

Telegram Test Telegram Bot name, connection, chat ID verification

Signal & Quantilan License License validity, plan name, expiry date

Agent Logs Live streaming log output from the running agent

Readiness Checklist

At the bottom of the left column you'll see a checklist of completed tests. Clicking Start Agent with any item unchecked shows a specific warning and recommendation — but you can start anyway if you know what you're doing.

Choose Your Signal Source

The agent supports two signal modes. Pick one in the Signal & Notifications section of the GUI.

Quantilan Server (recommended)

Receive HMAC-signed trading signals via WebSocket from Quantilan strategies. Requires a license key from @quantilan_bot.

SIGNAL_SOURCE=server
SIGNAL_SERVER=wss://signals.quantilan.com
LICENSE_KEY=XXXX-XXXX-XXXX-XXXX

Telegram Channel Parsing

Forward any signal channel to your personal Telegram bot, or type commands in plain language. Two parser modes available:

regex Rule-based. Supports top 30 coins, RU/EN/UA. Fast and free — no API key needed.

llm AI-powered. Understands any language and format. Supports Claude (Anthropic) and Groq — free tier, no credit card required (console.groq.com).

SIGNAL_SOURCE=telegram
PARSER_MODE=regex        # regex | llm
CONFIRM_TRADE=true       # ask before executing

# LLM mode — choose provider:
LLM_PROVIDER=groq        # groq (free) | claude
LLM_API_KEY=gsk_...      # Groq key from console.groq.com

You can write or forward signal messages in any format. The agent confirms before executing:

buy eth long
sol short sl 2% tp 5%
close btc
стоп на 1800
тейк на 3500

Smart Command Feedback

If the agent doesn't recognise a command, it explains why — instead of staying silent.
For example: "Understood: LONG, but coin PEPE is not in the supported list."
To add a coin, edit coins.json and restart. Type /help in the bot to see the full list of supported coins.

Start the Agent

Once all tests pass in the GUI, start the agent. It runs in the background and restarts automatically on crash.

Via GUI — click "Start Agent"

The Agent Logs panel expands automatically and streams live output.

Via terminal (Docker):

make start    # start agent in background
make logs     # tail live logs
make stop     # stop agent
make restart  # restart (reloads .env)
make status   # show container status

Python direct:

python main.py

What happens at startup

Agent connects to your exchange and verifies balance
License is validated and bound to your device
WebSocket or Telegram signal listener starts
Telegram bot goes online — send /start to verify

Monitor & Control via Telegram

Once running, control your agent entirely from Telegram.

/start

Status, balance, open positions count

/positions

Open positions with unrealized P&L

/pnl

P&L stats: wins, losses, win rate

/equity

Equity curve chart

/stop

Pause trading (keeps positions)

/resume

Resume trading

/close_all

Close all positions (with confirmation)

/mode

Switch paper ↔ live trading

Pro Tips

• Start in paper mode — simulated trading with virtual balance, no real orders
• Monitor the first 20 trades before switching to live
• Keep margin per trade at 3–5% of your balance
• Check logs regularly with make logs

Troubleshooting

API connection error — double-check API key, secret, and permissions (Futures Trading must be enabled)
Telegram bot not responding — verify the token has no extra spaces; make sure you pressed Start in the telegram bot chat
License check fails — ensure your server has outbound HTTPS access to license.quantilan.com
No signals received — check your WebSocket connection in the Signal & License test panel
Insufficient balance — reduce margin % or add funds to your futures wallet

Need Help?

Telegram support: @quantilan_support_bot

Ready to Start Trading?

Deploy Quantilan on your infrastructure and start algorithmic trading today.

View Pricing Plans Download Agent