# Binance Configuration Guide

中文版：[Binance 配置教程](binance.md)

## Scope

The ritmex-bot Binance adapter supports Spot and USDⓈ-M perpetual markets. `BINANCE_MARKET_TYPE` selects the market class, and symbol suffixes can force Spot or perpetual resolution.

## 1. Create an API key

1. Create a dedicated key in [Binance API Management](https://www.binance.com/en/my/settings/api-management).
2. Enable read access.
3. Enable Futures permission for perpetual strategies or Spot Trading permission for Spot strategies.
4. Keep withdrawal permission disabled and add a fixed IP whitelist.
5. Use one-way position mode for USDⓈ-M Futures and configure leverage in the Binance interface.

Mainnet and testnet keys are separate. Follow the [official Spot Testnet guide](https://developers.binance.com/docs/binance-spot-api-docs/testnet) to create Spot credentials. Use Binance Futures Testnet credentials for USDⓈ-M testnet trading.

## 2. Minimal perpetual configuration

```dotenv
EXCHANGE=binance
BINANCE_API_KEY=<your_binance_api_key>
BINANCE_API_SECRET=<your_binance_api_secret>
BINANCE_MARKET_TYPE=perp
BINANCE_SYMBOL=BTCUSDT_PERP
```

`BTCUSDT_PERP` forces perpetual resolution. `BTCUSDT` with `BINANCE_MARKET_TYPE=perp` also selects the perpetual market.

## 3. Minimal Spot configuration

```dotenv
EXCHANGE=binance
BINANCE_API_KEY=<your_binance_api_key>
BINANCE_API_SECRET=<your_binance_api_secret>
BINANCE_MARKET_TYPE=spot
BINANCE_SYMBOL=BTCUSDT_SPOT
```

Spot mode also accepts `BINANCE_SYMBOL=BTCUSDT`. Spot markets have no perpetual positions, funding rates, or derivatives-only protective-order features.

## 4. Market modes and symbols

| Setting | Meaning |
| --- | --- |
| `BINANCE_MARKET_TYPE=perp` | Default mode; prefers USDⓈ-M perpetuals |
| `BINANCE_MARKET_TYPE=spot` | Spot mode |
| `BINANCE_MARKET_TYPE=auto` | Resolves by symbol and applies default selection to duplicate names |
| `BTCUSDT_PERP` | Forces the perpetual market |
| `BTCUSDT_SPOT` | Forces the Spot market |

Use explicit legs for basis arbitrage:

```dotenv
BASIS_FUTURES_SYMBOL=BTCUSDT_PERP
BASIS_SPOT_SYMBOL=BTCUSDT_SPOT
```

## 5. Testnet configuration

`BINANCE_SANDBOX=true` switches the CCXT REST clients. The adapter manages native WebSocket URLs separately, so a complete testnet setup defines both REST and WebSocket endpoints:

```dotenv
BINANCE_SANDBOX=true
BINANCE_SPOT_REST_URL=https://testnet.binance.vision
BINANCE_SPOT_WS_URL=wss://stream.testnet.binance.vision/ws
BINANCE_FUTURES_REST_URL=https://testnet.binancefuture.com
BINANCE_FUTURES_WS_URL=wss://fstream.binancefuture.com
```

Use API keys generated by the matching testnet.

## 6. Optional settings

| Variable | Default | Purpose |
| --- | --- | --- |
| `BINANCE_ACCOUNT_POLL_MS` | `5000` | Account REST reconciliation interval; minimum 1000 ms |
| `BINANCE_ORDERS_POLL_MS` | `3000` | Order REST reconciliation interval; minimum 1000 ms |
| `BINANCE_SPOT_REST_URL` | `https://api.binance.com` | Spot REST base URL |
| `BINANCE_FUTURES_REST_URL` | `https://fapi.binance.com` | Perpetual REST base URL |
| `BINANCE_SPOT_WS_URL` | `wss://stream.binance.com:9443/ws` | Spot WebSocket base URL |
| `BINANCE_FUTURES_WS_URL` | `wss://fstream.binance.com/ws` | Perpetual WebSocket base URL |

## 7. Verify the configuration

```bash
bun run index.ts doctor --exchange binance --symbol BTCUSDT_PERP --json
bun run index.ts market ticker --exchange binance --symbol BTCUSDT_PERP --json
```

These commands create no orders. Run an order command with `--dry-run` before starting a live strategy.

## Troubleshooting

- `Invalid API-key, IP, or permissions`: verify market permissions, IP restrictions, and the mainnet/testnet key source.
- `Binance symbol not found`: use `BTCUSDT_PERP` or `BTCUSDT_SPOT` to select the market explicitly.
- `Position side does not match`: switch the USDⓈ-M Futures account to one-way mode.
- Timestamp errors: synchronize the host clock.

## References

- [Binance Spot API](https://developers.binance.com/docs/binance-spot-api-docs)
- [Binance USDⓈ-M Futures API](https://developers.binance.com/docs/derivatives/usds-margined-futures)
- [Repository Binance API reference](../binance/binance-spot/README.md)