Your First Barfinex Setup: Running Provider in Under 30 Minutes

Before You Start

This guide assumes you have the following installed:

Docker and Docker Compose
Node.js 20 or later
Git

If you're on Windows, WSL2 is strongly recommended for a smooth experience with Docker networking.

Step 1: Clone the Repository

git clone https://github.com/barfinex/monorepo.git
cd monorepo/trading.apps

The monorepo contains all five Barfinex services. For this guide, we only need to start Provider.

Step 2: Environment Configuration

Copy the example environment file:

cp apps/provider/.env.example apps/provider/.env

Open apps/provider/.env and set the values you care about for local development:

PROVIDER_PORT=8081
PROVIDER_BEARER_TOKEN=your-dev-token-here
DATABASE_URL=postgresql://barfinex:barfinex@localhost:5432/barfinex_provider
REDIS_URL=redis://localhost:6379

The bearer token can be any string for local development — just keep it consistent across services.

Step 3: Start the Infrastructure Services

Provider depends on PostgreSQL and Redis. Start them with Docker Compose:

docker-compose -f docker-compose.infra.yml up -d

This starts:

PostgreSQL on port 5432 — stores candle history and subscription registry
Redis on port 6379 — the event bus for inter-service communication

Wait about 10 seconds for both services to be healthy before proceeding.

Step 4: Run Database Migrations

cd apps/provider
npm install
npx prisma migrate deploy

This applies the Prisma schema to your local PostgreSQL instance, creating the tables Provider needs.

Step 5: Start Provider

npm run start:dev

You should see output like:

[Provider] Bootstrap complete
[Provider] REST API listening on :8081
[Provider] WebSocket gateway ready
[Provider] Connector registry loaded: 0 connectors

Step 6: Verify the Health Endpoint

Open a new terminal and run:

curl -H "Authorization: Bearer your-dev-token-here" http://localhost:8081/api/health

You should receive a JSON response indicating the service is healthy and the database connection is active.

Step 7: Add Your First Subscription

Provider needs to know which symbols to watch. Add a subscription via the REST API:

curl -X POST \
  -H "Authorization: Bearer your-dev-token-here" \
  -H "Content-Type: application/json" \
  -d '{"exchange": "binance", "symbol": "BTCUSDT", "timeframes": ["1m", "5m", "1h"]}' \
  http://localhost:8081/api/subscriptions

Provider will immediately begin ingesting candle data for BTCUSDT across the specified timeframes and backfilling available history.

Step 8: Verify Data Is Flowing

Query the candles endpoint to confirm data is arriving:

curl -H "Authorization: Bearer your-dev-token-here" \
  "http://localhost:8081/api/candles?symbol=BTCUSDT&timeframe=1m&limit=5"

If you see five recent candles in the response, your data pipeline is healthy.

What Happens Next

With Provider running, you have a foundation to build on:

Add more subscriptions — any symbol your exchange supports
Install Detector — point it at your running Provider instance and start evaluating strategies
Connect Studio — register your Provider instance in the Studio UI for visual monitoring

The full Installation Guide covers advanced configuration, production deployment, and connecting the remaining services.

Common Issues

Provider fails to connect to PostgreSQL: Ensure Docker Compose infrastructure is running and the DATABASE_URL in your .env matches the Docker Compose service credentials.

Candles endpoint returns empty: Wait 30-60 seconds after adding a subscription for the first candles to be ingested. Provider backtracks and fills recent history on first subscription.

Authentication errors: Make sure the Authorization: Bearer header value exactly matches PROVIDER_BEARER_TOKEN in your .env.