Binance Spot / Work your inventory
Binance Spot grid bot.
Build starting Spot inventory, then maintain a buy and a sell around the latest execution price. Track real fills and realised FIFO results.
How the Spot grid works
Binance Spot grid trades inventory that the account actually holds. It begins with a market purchase of SIZE × WIDTH to establish inventory, records its real fills, and places one buy below and one sell above the centre. STEP is an absolute quote-asset price distance, not a percentage.
When an order fills, the bot cancels and reconciles its sibling before rebuilding both orders around the observed execution price. It accounts for partial sibling fills during cancellation rather than treating them as unexecuted. Order status is polled through REST, subject to Binance request-weight and order-rate limits.
A configuration example
With a size of 0.001 BTC, width of 2 and step of 100 USDT, the initial market order buys 0.002 BTC. Each subsequent grid order uses 0.001 BTC, with buy and sell prices 100 USDT either side of the centre. The market must satisfy Binance's size, tick, notional and balance filters. This example is not a price forecast or a return estimate.
What to monitor
A rising market can consume available base inventory; a falling market can consume available quote balance. The grid cannot follow an unlimited move. There is no perpetual funding or derivatives liquidation in this Spot implementation, but inventory can still lose substantial value.
Realised results use FIFO fills and account for commissions in base or quote assets. Third-asset commissions such as BNB are reported separately. Unrealised inventory value is excluded from that figure. Restart recovery uses saved client IDs so it does not buy the initial inventory again. Use the Open source tab for the exact environment variables and testnet setup.
Configuration
Clone the repository and create your environment file:
git clone https://github.com/akilibots/akili-binance-grid.git
cd akili-binance-grid
cp .env.example .env
Edit .env and set:
| Variable | Meaning |
|---|---|
KEY, SECRET |
API credentials for the selected environment |
SYMBOL |
A listed Spot market, for example BTCUSDT |
BINANCE_BASE_URL |
REST URL; the example selects https://testnet.binance.vision |
WIDTH |
Initial inventory multiplier, a positive integer |
SIZE |
Base-asset quantity for each grid order |
STEP |
Quote-asset price spacing on either side of the centre |
POLL_SECONDS |
Order-status polling interval, default 1 second |
TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID |
Optional status notifications |
Verify the current market's filters and fees. Sizes must satisfy LOT_SIZE; limit prices are rounded down to PRICE_FILTER tick size. Binance applies its remaining notional, balance and other order filters. A rejected order stops the bot; it is not silently retried with changed quantities.
How it works
The bot buys SIZE * WIDTH at market once to establish inventory, using actual
executed quantity and price in its records. It then places one buy at centre - STEP and one sell at centre + STEP, both of SIZE.
When an order fills, the bot cancels and reconciles its sibling before rebuilding both orders around the observed execution price. Partial fills during cancellation are recorded before rebuilding. All recorded purchases are real fills, including the initial inventory. No synthetic entry prices are inserted.
The implementation polls REST order status. It has no expiring listen key to renew and does not promise a particular high-frequency throughput. Polling must respect the exchange's request-weight and order-rate limits.
Realised FIFO profit is reported in the quote asset and includes commissions paid in the base or quote asset. Commissions in other assets, such as BNB, are reported separately rather than converted at an invented rate. The figure excludes unrealised inventory value. Inventory and available balances still limit how far the grid can follow a sustained move.
Get it running and keep it running
docker compose up --build -d
docker compose logs -f
Stop it with docker compose down. This stops the process, not its exchange
orders. Compose uses the runtime Docker target and persists ./data. data/state.json
records strategy progress and data/exchange.json records client order IDs before
submission. Keep these files together. Restarting reconciles the original IDs
instead of buying the starting inventory again. An uncertain submission or failed
cancellation stops execution rather than creating an untracked replacement.
Do not delete state to recover from an error. Check exchange orders, fills and balances first. Existing settings, account, symbol and API environment are bound to the saved state. Use a separate data directory for each bot. A process lock prevents two instances from using the same directory. Stopping the process leaves its orders on the exchange; cancel them explicitly when required.
Legacy versions did not persist their trades. Reconcile their existing inventory and orders before starting this version with a fresh data directory.
Test it yourself
docker build --target test -t binance-grid-test .
docker run --rm --network none binance-grid-test
The offline suite tests inventory initialization, restart recovery, cancellation, FIFO fees and the actual SDK's signing and response-model code against mocked HTTP responses. Live credentials are not needed. Passing the suite does not establish live exchange execution or profitability.
Use Binance Spot grid in your workspace
Manage your Binance Spot grid strategy through the Akilibots app. Keep the bot configuration, exchange connection and execution history together.
Set up your account and exchange
- Create your account and sign in to your workspace.
- Open exchange connections and add a Binance Spot connection with trading permissions and withdrawals disabled.
- Check that the connection uses the intended account and has the funds needed for the strategy. Use testnet to check the configuration first.
- Create a bot and select Binance Spot grid.
Configure the strategy
- Choose a listed Spot symbol and the matching API environment.
- Set the base-asset order size and quote-asset grid step.
- Set WIDTH, the initial inventory multiplier.
- Review the polling interval, market filters and available balances.
Review and run
- Review the market, network, order quantities and maximum exposure. Save the configuration.
- Start the bot, then check the first action against the exchange account.
- Use the bot detail view to monitor orders, executions, logs and errors. A queued request or submitted order is not a confirmed fill.
- Pause the bot before changing its strategy. Check the exchange for open orders and positions; stopping a bot does not itself close a position.
- If execution stops with a reconciliation error, compare the saved bot state with exchange orders and fills before resuming.
Commercial access
For account access and deployment enquiries, contact Akilibots. Never include wallet mnemonics, private keys or API secrets in an email.
Commercial service guide