Installation

Prerequisites

Before installing NeuraTrade, ensure you have the following dependencies installed:

Required Dependencies

Go 1.26+

NeuraTrade’s backend is written in Go and requires version 1.26 or higher.Install on macOS:

brew install [email protected]

Install on Linux:

wget https://go.dev/dl/go1.26.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.26.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin

Verify installation:

go version
# go version go1.26 linux/amd64

Bun 1.3+

Required for TypeScript sidecar services (CCXT and Telegram).Install on macOS/Linux:

curl -fsSL https://bun.sh/install | bash

Verify installation:

bun --version
# 1.3.0

Bun is a fast JavaScript runtime compatible with Node.js. It’s significantly faster than Node.js for our use case.

SQLite (default)

SQLite is the default database for development and testing.Install on macOS:

brew install sqlite

Install on Linux:

sudo apt update && sudo apt install sqlite3 libsqlite3-dev

Verify installation:

sqlite3 --version

SQLite has a known startup issue with collector workers (issue neura-v7e6). Consider using PostgreSQL for production deployments.

Redis (recommended)

Redis is used for caching, distributed locks, and quest coordination.Install on macOS:

brew install redis
brew services start redis

Install on Linux:

sudo apt install redis-server
sudo systemctl start redis-server
sudo systemctl enable redis-server

Verify installation:

redis-cli ping
# PONG

Redis is optional for basic functionality but strongly recommended for production use and autonomous trading features.

Optional Dependencies

PostgreSQL

Recommended for production deployments. Provides better concurrency and performance than SQLite.

# macOS
brew install postgresql@15
brew services start postgresql@15

# Linux
sudo apt install postgresql-15

jq

JSON processor for pretty-printing API responses in the terminal.

# macOS
brew install jq

# Linux
sudo apt install jq

Native Installation

Clone Repository

Clone the NeuraTrade repository:

git clone https://github.com/irfndi/neuratrade.git
cd neuratrade

Configure Environment

Create your environment configuration from the template:

cp .env.example .env

Edit .env and update the following minimum required settings:

# Required settings
NEURATRADE_HOME=/home/youruser/.neuratrade
BACKEND_HOST_PORT=58080

# Database (SQLite for development)
DATABASE_DRIVER=sqlite
SQLITE_PATH=/home/youruser/.neuratrade/neuratrade.db

# Server configuration
SERVER_PORT=8080
SERVER_HOST=0.0.0.0
ENVIRONMENT=development

# Redis (optional but recommended)
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0

Replace /home/youruser with your actual home directory path. Never use ~ in the .env file as it may not expand correctly.

Install Dependencies

Download Go modules and install service dependencies:

make mod-download
make services-setup

This will:

Download Go dependencies to local cache (.cache/go-mod)
Install Telegram service Bun dependencies
Set up build cache directories

Build Binaries

Build all NeuraTrade binaries:

make build

This creates the following binaries in ./bin/:

Binary	Description
`neuratrade-server`	Go backend API server
`neuratrade`	CLI gateway for orchestration
`ccxt-service`	Exchange bridge service launcher
`telegram-service`	Telegram bot service launcher

Build output is cached in .cache/go-build for faster incremental builds.

Run Database Migrations

Initialize the database schema:

cd services/backend-api
./database/migrate.sh run

Check migration status:

./database/migrate.sh status

Start Services

Start all services using the gateway:

./bin/neuratrade gateway start

Verify services are running:

./bin/neuratrade gateway status

Or check the health endpoint:

curl -s http://localhost:8080/health | jq

Using the Installation Script

NeuraTrade provides an installation script for automated setup:

./install.sh

This script will:

Build all binaries
Install them to ~/.local/bin (or custom $INSTALL_DIR)
Create configuration directory at ~/.neuratrade
Generate environment template from .env.example
Create CLI shortcuts and compatibility wrappers

Installation Script Options

./install.sh

The --enable-autostart flag configures a macOS LaunchAgent to start NeuraTrade automatically on login.

Directory Structure

NeuraTrade uses the following directory layout:

neuratrade/
├── services/
│   ├── backend-api/          # Go backend (main service)
│   │   ├── cmd/server/       # Server entrypoint
│   │   ├── internal/
│   │   │   ├── api/          # HTTP routes and handlers
│   │   │   ├── services/     # Business logic
│   │   │   ├── database/     # Repository layer
│   │   │   └── ccxt/         # Exchange client
│   │   ├── database/         # SQL migrations
│   │   └── scripts/          # Operational scripts
│   ├── ccxt-service/         # Bun + CCXT exchange bridge
│   └── telegram-service/     # Bun + grammY Telegram bot
├── cmd/neuratrade-cli/       # Gateway CLI
├── protos/                   # Protobuf definitions
├── bin/                      # Built binaries (gitignored)
├── .cache/                   # Build cache (gitignored)
├── Makefile                  # Build orchestration
└── install.sh                # Installation script

Never commit the ~/.neuratrade/ directory. It contains sensitive credentials and should be added to .gitignore.

Runtime State Location

All runtime state is stored in the directory specified by NEURATRADE_HOME (default: ~/.neuratrade):

Configuration Files

config.json

Runtime configuration including:

Exchange API keys and credentials
Telegram chat IDs
AI provider settings
Operational mode preferences

This file is created by the CLI bootstrap command or Telegram bot integration.

This file contains sensitive credentials. Set permissions to 600: chmod 600 ~/.neuratrade/config.json

neuratrade.db (SQLite only)

SQLite database file containing:

Market data and price history
Arbitrage opportunities
Trading signals and indicators
User accounts and API keys
Quest and agent state

Location configured via SQLITE_PATH in .env.

logs/

Service log files:

backend.log - Backend API server logs
gateway.log - Gateway orchestration logs
telegram.log - Telegram bot logs
ccxt.log - Exchange service logs

Logs rotate automatically and are formatted as JSON when LOG_FORMAT=json.

pids/

Process ID files for running services:

backend.pid - Backend server PID
telegram.pid - Telegram service PID
ccxt.pid - CCXT service PID

Used by the gateway for process management.

Environment Variables

Key environment variables for NeuraTrade configuration:

Core Settings

Variable	Required	Default	Description
`NEURATRADE_HOME`	Yes	`~/.neuratrade`	Runtime state directory
`SERVER_PORT`	No	`8080`	Backend API port
`BACKEND_HOST_PORT`	No	`58080`	External host port mapping
`ENVIRONMENT`	No	`development`	Runtime environment
`LOG_LEVEL`	No	`info`	Logging level (debug/info/warn/error)
`LOG_FORMAT`	No	`json`	Log format (json/text)

Database Settings

Variable	Required	Default	Description
`DATABASE_DRIVER`	Yes	`sqlite`	Database driver (sqlite/postgres)
`SQLITE_PATH`	If SQLite	-	Path to SQLite database file
`DATABASE_URL`	If PostgreSQL	-	PostgreSQL connection URL
`DATABASE_HOST`	If PostgreSQL	`localhost`	PostgreSQL host
`DATABASE_PORT`	If PostgreSQL	`5432`	PostgreSQL port
`DATABASE_USER`	If PostgreSQL	`postgres`	PostgreSQL username
`DATABASE_PASSWORD`	If PostgreSQL	-	PostgreSQL password
`DATABASE_DBNAME`	If PostgreSQL	`neuratrade`	PostgreSQL database name

Service Settings

Variable	Required	Default	Description
`REDIS_HOST`	No	`localhost`	Redis host
`REDIS_PORT`	No	`6379`	Redis port
`REDIS_PASSWORD`	No	-	Redis password
`CCXT_SERVICE_URL`	No	`http://localhost:3001`	CCXT service URL
`TELEGRAM_PORT`	No	`3002`	Telegram service port
`TELEGRAM_BOT_TOKEN`	If using Telegram	-	Telegram bot token from @BotFather

Security Settings

Variable	Required	Default	Description
`ADMIN_API_KEY`	Recommended	-	Admin API key for protected endpoints
`JWT_SECRET`	Yes	-	JWT signing secret (min 32 chars)
`BCRYPT_COST`	No	`12`	Bcrypt hashing cost

Always set strong, unique values for ADMIN_API_KEY and JWT_SECRET in production. Use openssl rand -base64 32 to generate secure random values.

Verification

After installation, verify your setup:

Check Binary Versions

./bin/neuratrade --version
./bin/neuratrade-server --version
go version
bun --version

Verify Services

./bin/neuratrade gateway status
curl -s http://localhost:8080/health | jq

Test Database Connection

# SQLite
sqlite3 ~/.neuratrade/neuratrade.db "SELECT COUNT(*) FROM schema_migrations;"

# PostgreSQL
psql -d neuratrade -c "SELECT COUNT(*) FROM schema_migrations;"

Test Redis Connection

redis-cli ping
# PONG

Check API Endpoints

curl -s http://localhost:8080/api/v1/exchanges/supported | jq
curl -s http://localhost:8080/api/v1/market/prices | jq

Next Steps

Configure Exchanges

Add exchange API keys and credentials

Setup Telegram

Configure the Telegram bot for notifications

Enable AI Agents

Set up autonomous trading with AI agents

API Reference

Explore the complete API documentation

Get Started

Core Features

Configuration

Guides

Prerequisites

Required Dependencies

Optional Dependencies

PostgreSQL

jq

Native Installation

Using the Installation Script

Installation Script Options

Directory Structure

Runtime State Location

Configuration Files

Environment Variables

Core Settings

Database Settings

Service Settings

Security Settings

Verification

Next Steps

Configure Exchanges

Setup Telegram

Enable AI Agents

API Reference

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Guides

​Prerequisites

​Required Dependencies

​Optional Dependencies

PostgreSQL

jq

​Native Installation

​Using the Installation Script

​Installation Script Options

​Directory Structure

​Runtime State Location

​Configuration Files

​Environment Variables

​Core Settings

​Database Settings

​Service Settings

​Security Settings

​Verification

​Next Steps

Configure Exchanges

Setup Telegram

Enable AI Agents

API Reference

Build docs developers (and LLMs) love

Prerequisites

Required Dependencies

Optional Dependencies

Native Installation

Using the Installation Script

Installation Script Options

Directory Structure

Runtime State Location

Configuration Files

Environment Variables

Core Settings

Database Settings

Service Settings

Security Settings

Verification

Next Steps