BFUSD Arbitrage Bot

A Go-based Binance BFUSD/USDT arbitrage bot with a BoltDB-backed persistent state machine, post-only maker orders, basis-point entry signals, BFUSD redemption-quota tracking, Telegram controls, and Docker deployment.

Warning

This software can place real orders and is intended for educational and research use. Review the strategy, API permissions, and risk controls before trading with real funds.

Overview

The bot monitors the Binance Spot BFUSD/USDT market for deviations from the 1.0000 reference price. The documented entry signal is:

bp = round((1.0 - price) * 10,000)

Orders are allowed when bp > 0, which means BFUSD is trading below 1.0000.

Examples:

• Price 0.9999 → bp = 1
• Price 0.9998 → bp = 2
• Price 1.0002 → bp = -2 and no entry

The bot tracks filled notional by round. When a round reaches its target, it notifies the configured Telegram chat and enters WAIT_REDEEM. After BFUSD has been redeemed, use /redeemed to continue to the next round.

Features

• Monitors the Binance Spot BFUSD/USDT market at a configurable interval
• Calculates entry signals in basis points
• Supports post-only maker orders and optional taker execution
• Persists the trading state and round progress in BoltDB
• Restores state after a process or container restart
• Tracks the daily BFUSD fast-redemption quota
• Selects or previews FAST versus STANDARD redemption
• Exposes operational controls through Telegram
• Supports dry-run mode
• Includes Docker and Docker Compose deployment

Persistent State Machine

The current state is stored in BoltDB and uses the following modes:

• IDLE: monitoring and trading are disabled
• ARMED: the strategy is active
• WAIT_REDEEM: the current target has been reached and redemption confirmation is required
• DONE: all configured rounds have completed

State includes the current round, accumulated notional, last observed price, last basis-point value, and update time.

Redemption-Quota Tracking

The quota manager tracks the daily free fast-redemption allowance and estimates the remaining quota from Binance redemption history.

• /quota displays the current quota status
• /preview <amount> previews whether an amount should use FAST or STANDARD redemption
• Fast-redemption usage is recorded against the configured daily allowance
• The quota window resets at the configured daily reset boundary

Quota information is an operational aid. Always verify current Binance product terms, limits, fees, and API behavior before relying on it.

Quick Start with Docker

1. Clone and configure

git clone <your-repository-url> bn-bfusd-arb
cd bn-bfusd-arb
cp .env.example .env

Edit .env and add your credentials:

TELEGRAM_BOT_TOKEN=your_telegram_bot_token
CHAT_ID=your_telegram_chat_id

BINANCE_API_KEY=your_binance_api_key
BINANCE_API_SECRET=your_binance_api_secret

You can obtain a Telegram bot token from @BotFather and determine your chat ID with a Telegram user-information bot.

2. Deploy

./deploy.sh

The deployment script validates the environment, builds the Docker image, starts the container, and displays its status.

3. Start the strategy

In the configured Telegram chat:

1. Send /start to display the command summary.
2. Send /status to inspect the current state.
3. Send /arm to enable monitoring and trading.

Local Installation

Requirements

• Go 1.22 or newer
• A Telegram bot token and chat ID
• A Binance API key with Spot trading access

Build and run

go mod download
go build -o bfusd-arb
./bfusd-arb

The application loads .env automatically when the file is present. Environment variables provided by the runtime can also be used.

Configuration

Copy .env.example to .env and adjust the following values:

# Required Telegram settings
TELEGRAM_BOT_TOKEN=
CHAT_ID=

# Required Binance settings
BINANCE_API_KEY=
BINANCE_API_SECRET=

# Market and round settings
PAIR=BFUSDUSDT
TARGET_NOTIONAL_USDT=1250
MAX_ROUNDS=4
POLL_INTERVAL_MS=800

# Strategy settings
MODE=SPEED
ALLOW_TAKER=true
MAKER_POST_ONLY=true

# Risk controls
ORDER_SIZE_USDT=50
MAX_OPEN_ORDERS=4
SLIPPAGE_BPS_FOR_TAKER=0
CANCEL_RESTING_ON_HIT=true

# Runtime settings
DRY_RUN=false
LOG_LEVEL=info
DB_PATH=./bot.db

Configuration reference

Variable	Description	Default
TELEGRAM_BOT_TOKEN	Telegram bot token	Required
CHAT_ID	Telegram chat that controls the bot	Required
BINANCE_API_KEY	Binance API key	Required
BINANCE_API_SECRET	Binance API secret	Required
PAIR	Binance Spot symbol	BFUSDUSDT
TARGET_NOTIONAL_USDT	Filled notional required per round	1250
MAX_ROUNDS	Total number of rounds	4
POLL_INTERVAL_MS	Market polling interval in milliseconds	800
MODE	Execution preference: SPEED or PRICE	SPEED
ALLOW_TAKER	Enables taker execution when strategy conditions permit	true
MAKER_POST_ONLY	Uses post-only maker orders	true
ORDER_SIZE_USDT	Requested order notional	50
MAX_OPEN_ORDERS	Maximum number of resting orders	4
SLIPPAGE_BPS_FOR_TAKER	Minimum basis-point advantage for taker execution	0
CANCEL_RESTING_ON_HIT	Cancels resting orders after the round target is reached	true
DRY_RUN	Simulates order actions without submitting live orders	false
LOG_LEVEL	Application log level	info
DB_PATH	BoltDB state-file path	./bot.db

Telegram Commands

Operations

• /start — Show the welcome message and command summary
• /status — Show the current state and strategy status
• /arm — Enable monitoring and trading
• /disarm — Stop trading and return to IDLE

Round management

• /redeemed — Confirm redemption and advance to the next round
• /reset confirm — Reset all persisted progress

Quota tools

• /quota — Display the current BFUSD redemption quota
• /preview <amount> — Preview the redemption method for an amount

Runtime parameters

• /settarget 1250 — Change the per-round target
• /rounds 4 — Change the total number of rounds
• /dry — Toggle dry-run mode

Strategy Flow

1. In ARMED, poll the market every POLL_INTERVAL_MS.
2. Calculate bp = round((1 - price) * 10,000).
3. Evaluate the configured entry and risk conditions.
4. Submit a post-only maker order, or an optional taker order when enabled and allowed by the slippage threshold.
5. Update accumulated notional from execution reports.
6. When TARGET_NOTIONAL_USDT is reached, notify Telegram and enter WAIT_REDEEM.
7. After redemption, send /redeemed to start the next round.
8. Enter DONE after MAX_ROUNDS rounds.

Docker Operations

# Show container status
docker compose ps

# Follow logs
docker compose logs -f bfusd-arb

# Restart the service
docker compose restart

# Stop the service
docker compose down

# Rebuild and restart
docker compose up --build -d

The Compose configuration stores BoltDB data in a named volume so state survives container replacement.

Testing Safely

Start in dry-run mode:

DRY_RUN=true

Then deploy normally:

./deploy.sh

For an initial live test, use small values:

TARGET_NOTIONAL_USDT=10
ORDER_SIZE_USDT=5

Confirm observed orders, fills, quota calculations, state transitions, and Telegram notifications before increasing exposure.

Architecture

• Language: Go 1.22+
• Persistence: BoltDB through bbolt
• Exchange integration: Binance REST API
• Control and notifications: Telegram Bot API
• Deployment: Docker and Docker Compose

Monitoring and Troubleshooting

View recent logs:

docker compose logs --tail=100 bfusd-arb

Common checks:

1. If the bot does not respond, verify TELEGRAM_BOT_TOKEN and CHAT_ID.
2. If order submission fails, verify Binance API permissions, balances, symbol filters, and account restrictions.
3. If prices do not update, check network connectivity and Binance API rate limits.
4. If state cannot be opened, verify that DB_PATH is writable and that only one process is using the BoltDB file.

Security

• Store credentials only in .env or the deployment platform's secret manager.
• Never commit .env, API keys, private keys, or production credentials.
• Grant the Binance API key only the permissions required for Spot trading.
• Do not enable withdrawals for this bot.
• Restrict access to the host, Telegram chat, logs, and state database.
• Rotate credentials immediately if they are exposed.

Risk Notice

• BFUSD may trade above or below its reference value.
• Redemption availability, timing, quotas, and fees can change.
• Post-only orders may remain unfilled or be rejected when they would cross the book.
• Taker orders can incur fees and slippage.
• API latency, rate limits, partial fills, and exchange outages can affect execution.
• Dry-run behavior cannot reproduce every live-market condition.
• You are responsible for all trading and operational risk.

License

MIT License.