Environment:Nautechsystems Nautilus trader Binance API Credentials
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Live_Trading, Exchange_Adapters |
| Last Updated | 2026-02-10 08:30 GMT |
Overview
Binance exchange API credentials environment providing API key and secret authentication for spot, margin, futures, and demo trading via environment variables.
Description
The Binance adapter requires API credentials to be set as environment variables. The credential system supports three environments: production (live trading), testnet (paper trading on Binance testnet), and demo (Binance demo environment). Credentials are loaded via the `get_env_key()` utility which raises a `RuntimeError` if the required variable is not set. The system also supports Ed25519 key authentication with automatic detection of key format.
Deprecation note: The `*_ED25519_*` prefixed environment variables (e.g., `BINANCE_ED25519_API_KEY`) are deprecated. Ed25519 keys should now be set in the standard variables (e.g., `BINANCE_API_KEY`).
Usage
This environment is required when configuring the Binance adapter for live or testnet trading. Specifically, it is needed when creating `BinanceDataClientConfig` or `BinanceExecClientConfig` instances without explicitly passing API credentials in code.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| Network | Internet access to Binance API | api.binance.com (production), testnet.binance.vision (testnet) |
| Account | Binance account with API key generated | Separate keys for spot vs futures may be needed |
Dependencies
No additional packages beyond the core NautilusTrader installation.
Credentials
Production environment:
- `BINANCE_API_KEY`: Binance API key for live trading
- `BINANCE_API_SECRET`: Binance API secret (HMAC or Ed25519 PEM)
Testnet environment (Spot/Margin):
- `BINANCE_TESTNET_API_KEY`: Testnet API key for spot/margin
- `BINANCE_TESTNET_API_SECRET`: Testnet API secret for spot/margin
Testnet environment (Futures):
- `BINANCE_FUTURES_TESTNET_API_KEY`: Testnet API key for futures
- `BINANCE_FUTURES_TESTNET_API_SECRET`: Testnet API secret for futures
Demo environment:
- `BINANCE_DEMO_API_KEY`: Demo API key (shared across products)
- `BINANCE_DEMO_API_SECRET`: Demo API secret
Deprecated (do not use for new setups):
- `BINANCE_ED25519_API_KEY` → use `BINANCE_API_KEY` instead
- `BINANCE_ED25519_API_SECRET` → use `BINANCE_API_SECRET` instead
Quick Install
# Set production credentials
export BINANCE_API_KEY="your-api-key-here"
export BINANCE_API_SECRET="your-api-secret-here"
# Or for testnet
export BINANCE_TESTNET_API_KEY="your-testnet-key"
export BINANCE_TESTNET_API_SECRET="your-testnet-secret"
Code Evidence
Credential loading from `adapters/env.py:20-23`:
def get_env_key(key: str) -> str:
if key not in os.environ:
raise RuntimeError(f"Environment variable '{key}' not set")
else:
return os.environ[key]
Ed25519 key auto-detection from `adapters/binance/common/credentials.py:31-47`:
def is_ed25519_private_key(api_secret: str) -> bool:
try:
key_data = "".join(
line for line in api_secret.splitlines()
if not line.startswith("-----")
)
key_bytes = base64.b64decode(key_data, validate=True)
return _ED25519_OID in key_bytes
except Exception:
return False
Deprecated variable fallback from `adapters/binance/common/credentials.py:119-131`:
def _get_credential_with_ed25519_fallback(ed25519_key: str, standard_key: str) -> str:
standard_value = os.environ.get(standard_key)
if standard_value is not None:
return standard_value
ed25519_value = os.environ.get(ed25519_key)
if ed25519_value is not None:
warnings.warn(
f"'{ed25519_key}' is deprecated and will be removed in a future version. "
f"Set your Ed25519 credentials in '{standard_key}' instead.",
DeprecationWarning,
stacklevel=4,
)
return ed25519_value
raise ValueError(f"'{standard_key}' not found in environment")
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `RuntimeError: Environment variable 'BINANCE_API_KEY' not set` | Credential not in environment | Set `export BINANCE_API_KEY=...` or pass key directly to config |
| `ValueError: 'BINANCE_API_KEY' not found in environment` | Neither standard nor deprecated variable set | Set the required environment variable |
| `DeprecationWarning: 'BINANCE_ED25519_API_KEY' is deprecated` | Using old-style variable names | Rename to `BINANCE_API_KEY` (without ED25519 prefix) |
Compatibility Notes
- Ed25519 keys: Supported via automatic detection. Both PEM-formatted and raw base64-encoded keys work. Encrypted PEM files are NOT supported.
- HMAC keys: The default authentication method. No special handling needed.
- Demo environment: Uses a single shared key across all Binance products (spot, futures, etc.).