Self-host bitcoiners-dca

What you'll have at the end

By the end of this guide your machine will be running a long-lived Python process that automatically buys BTC on schedule using your exchange API key, logs every trade to a local SQLite database, and provides trade-history exports. Dashboard withdrawals are unavailable. Use your exchange's own interface to move funds.

Everything is included — there are no paid tiers:

• DCA on BitOasis, OKX and Binance UAE — one exchange, or all of them with smart routing to the cheapest after-fee price each cycle
• Multi-hop routing (AED → USDT → BTC) where the direct pair is wide
• Buy-the-dip overlay (multiply buys when BTC drops)
• Maker-mode execution (limit orders to save on fees)
• Trade-history CSV export with AED values
• Risk circuit breakers (daily cap, single-buy cap, auto-pause on N failures)
• Backtest engine to dry-run strategies against 365 days of history
• Advanced overlays: volatility-weighted, time-of-day, drawdown-aware
• On-chain smart triggers (MVRV-Z multiplier)
• Funding-rate monitor and cross-exchange arbitrage alerts via Telegram

Withdrawals: use the exchange's own interface. Dashboard withdrawals are unavailable. Keep withdrawal permission disabled on the bot's API key and review the exchange's current fees, limits and destination requirements.

Prerequisites

You need:

• A machine that stays online. A Raspberry Pi 4, a Mac mini, an Umbrel node, an old laptop with the lid taped down, or a small VPS (Hetzner CX11 at ~AED 18/month is plenty). The bot is light — a few hundred MB of RAM, near-zero CPU between cycles.
• Docker (recommended) or Python 3.11+. Most of this guide uses Docker because it's the same on every platform. If you're on a Pi running DietPi or Umbrel, Docker is already there.
• An exchange account. BitOasis, OKX UAE, or Binance UAE. All three are VARA-licensed.
• A Bitcoin hardware wallet if you plan to sweep accumulated BTC off the exchange — BitBox02, Trezor Safe 5, or Ledger. See our hardware wallet guide for UAE residents if you don't have one yet.
• ~45 minutes the first time. Subsequent updates are two commands.

1. Get the source

The bot is open source under the MIT license and the full source is public on GitHub — clone it, audit it, run it yourself. No access request, no waiting.

git clone https://github.com/jiashanlu/bitcoiners-dca.git
cd bitcoiners-dca

Create your config and data directories:

cp config.example.yaml config.yaml
mkdir -p data reports

We'll edit config.yaml in step 3. First the API key.

2. Create your exchange API key (TRADE-only)

Pick the exchange you want to start with. You can add more later by editing the config — with two or more, the bot routes each buy to the cheapest one.

2a. OKX UAE

1. Log into okx.com from your UAE-verified account.
2. Top-right avatar → API → Create V5 API Key.
3. Name: dca-bot (or anything).
4. Permissions: tick Read and Trade only. Do NOT tick Withdraw.
5. IP whitelist: optional but recommended. If your machine has a static IP, paste it. If it's on a home connection, skip this and rely on the key's passphrase.
6. Set a passphrase you'll remember (OKX calls it the API passphrase — required on every request).
7. Save the API key, secret, and passphrase. You'll only see the secret once.

You now have three secrets: OKX_API_KEY, OKX_API_SECRET, OKX_API_PASSPHRASE. Keep them somewhere safe.

2b. BitOasis

1. Log into bitoasis.net.
2. Top-right → Settings → API Token Management.
3. Click Generate New Token.
4. Scopes: Read and Trade only.
5. Copy the Bearer token — BitOasis shows it once.

You now have one secret: BITOASIS_API_TOKEN. BitOasis uses Bearer-token auth, so there's no separate secret/passphrase.

2c. Binance UAE

UAE residents access binance.com via the ADGM-licensed entity. The bot uses the standard Binance API.

1. Log into binance.com (account verified through Binance UAE).
2. Top-right avatar → API Management.
3. Create a System-Generated key (HMAC). Name: dca-bot.
4. Permissions: Enable Reading + Enable Spot & Margin Trading. Do NOT enable Withdrawals.
5. Restrict IP if you can.

3. Configure your strategy

Open config.yaml in your editor. The starter file is heavily commented — every key has a one-line explanation. Here's a minimal setup for OKX, weekly AED 500 with a buy-the-dip overlay:

strategy:
  amount_aed: 500           # AED per buy
  frequency: weekly
  day_of_week: monday
  time: "09:00"
  timezone: "Asia/Dubai"

overlays:
  buy_the_dip:
    enabled: true
    threshold_pct: -10      # if BTC -10% over lookback
    lookback_days: 7
    multiplier: 2.0         # 2× the base AED amount

execution:
  mode: taker               # taker = market order; "maker_only" saves fees but may not fill

routing:
  mode: best_price
  preferred_exchange: null

exchanges:
  okx:
    enabled: true
    api_key_env: OKX_API_KEY
    api_secret_env: OKX_API_SECRET
    passphrase_env: OKX_API_PASSPHRASE
  binance:
    enabled: false
  bitoasis:
    enabled: false

risk:
  max_daily_aed: 1000       # hard daily cap — clamps even big dip-triggered buys
  max_single_buy_aed: 2000  # per-buy cap
  max_consecutive_failures: 5

dry_run: true               # KEEP THIS ON FOR NOW

Now write your API key into an environment file (Docker reads this):

cat > .env <<'EOF'
OKX_API_KEY=your_key_here
OKX_API_SECRET=your_secret_here
OKX_API_PASSPHRASE=your_passphrase_here
EOF
chmod 600 .env

4. Validate + dry-run

Build the Docker image and validate the config:

docker build -t bitcoiners-dca .
docker run --rm --env-file .env \
  -v $PWD/config.yaml:/app/config.yaml \
  bitcoiners-dca validate

validate parses the YAML, confirms your API credentials work, and prints a summary of what the bot will do. If anything is wrong, fix it here before you go any further.

Now run one dry-run buy cycle:

docker run --rm --env-file .env \
  -v $PWD/config.yaml:/app/config.yaml \
  -v $PWD/data:/app/data \
  bitcoiners-dca buy-once

With dry_run: true this prints what it would have bought (exchange, AED amount, BTC estimate, fee, effective price) without placing an order. Read it carefully. If the math looks right, you're ready to go live.

5. Go live

Edit config.yaml and set:

dry_run: false

Then start the bot as a long-running container:

docker compose up -d

The bundled docker-compose.yml runs the bot daemon-mode (cron + interval scheduler) with restart-on-failure policy. Logs go to stdout, which Docker captures. View them with:

docker compose logs -f

Your first real buy will hit at the next scheduled cycle (Monday 09:00 Asia/Dubai in our example). Watch the first one closely.

6. Withdraw through your exchange

Dashboard withdrawals are unavailable. Open your exchange's own withdrawal interface when you choose to move funds to your wallet. Keep withdrawal permission disabled on the bot's API key.

Verify the destination address on your hardware device, choose the appropriate network, and follow the exchange's current address verification and recipient-information requirements. Review the withdrawal charge, minimum amount and any waiting period before submitting. Fees and requirements vary by provider and account.

7. Monitoring + logs

The bundled docker-compose.yml starts a self-service web dashboard alongside the daemon. Open http://localhost:8000 on the machine running the bot — you'll see balances, recent cycles, scheduled strategy, exchange status, and the backtest engine.

The bot also exposes three things you should watch from the CLI:

Logs:

docker compose logs -f       # live tail
docker compose logs --tail 100  # last 100 lines

Status snapshot:

docker compose exec dca bitcoiners-dca status

Status shows: last cycle outcome, lifetime AED spent, lifetime BTC bought, current exchange balances, whether circuit breakers have tripped.

Telegram alerts (recommended):

Create a Telegram bot via @BotFather, get the token, and note your Telegram chat ID (DM @userinfobot). Then:

# in .env
TG_BOT_TOKEN=123456:abcdef...

# in config.yaml
notifications:
  telegram:
    enabled: true
    bot_token_env: TG_BOT_TOKEN
    chat_id: 123456789   # YOUR chat ID — get it from @userinfobot on Telegram

You'll get a Telegram message after every cycle (buy succeeded, buy failed, circuit breaker tripped).

Trade-history CSV export:

docker compose exec dca bitcoiners-dca export-tax-csv --year 2026

Writes a trade-history CSV to ./reports/ with AED values and cost-basis calculations for activity recorded by the bot. Trades and transfers outside the bot are not included. This is a recordkeeping export, not a complete tax calculation or filing.

Troubleshooting

"OKX request signature invalid"

Almost always a wrong passphrase. The passphrase is case-sensitive and is the one you set when creating the API key on OKX, not your account password. Recreate the key if you've lost it.

BitOasis "401 Unauthorized"

Bearer token issues: confirm the token is in .env as BITOASIS_API_TOKEN, no quotes, no trailing whitespace, no newline at the end. The token format is a long alphanumeric string with hyphens — not a UUID.

Bot says "dry-run mode — no order placed" and I want it to be live

Edit config.yaml: dry_run: false at the bottom of the file. Then docker compose restart.

Circuit breaker tripped — bot won't buy

After 5 consecutive cycle failures the bot auto-pauses (a safety measure against blowing through your daily cap while an exchange is having an outage). Inspect logs to find the root cause, then resume:

docker compose exec dca bitcoiners-dca risk resume

How do I update to a newer version?

cd bitcoiners-dca
git pull
docker compose build --no-cache
docker compose up -d

Your config.yaml, .env, SQLite DB in data/, and trade-history reports in reports/ are all volume-mounted — they survive image rebuilds.

Where to get help

Email support@bitcoiners.ae with the output of docker compose logs --tail 100 and a short description of what you tried. Issues are also welcome on the public GitHub issue tracker.

The full Bitcoin community is on @bitcoinersae on Telegram — drop questions there too. UAE Bitcoiners help each other.