Setting up Credentials¶

NexusTrader supports three ways to provide exchange API credentials, in priority order:

Direct pass — pass credentials explicitly in code
Settings file — store in .keys/.secrets.toml (and/or NEXUS_ prefixed environment variables)
Environment variables — read from plain environment variables

You can use any combination. Directly passed values always take precedence.

Note

The .keys/.secrets.toml file is optional. If it does not exist, NexusTrader emits a warning but continues to run. Public-only, mock, and backtest workflows do not require any credentials.

Method 1: Settings File (TOML)¶

Create a .keys directory and a .secrets.toml file:

mkdir .keys
touch .keys/.secrets.toml

Add your exchange credentials:

[BYBIT.TESTNET]
api_key = "your_api_key"
secret = "your_secret_key"

[OKX.DEMO_1]
api_key = "your_api_key"
secret = "your_secret_key"
passphrase = "your_passphrase"

Use the settings_key parameter in BasicConfig to auto-resolve:

from nexustrader.config import BasicConfig

# Auto-resolves api_key, secret, passphrase from [BYBIT.TESTNET]
config = BasicConfig(settings_key="BYBIT.TESTNET", testnet=True)

Or access settings manually (legacy approach):

from nexustrader.constants import settings

print(settings.BYBIT.TESTNET.api_key)
print(settings.BYBIT.TESTNET.secret)

Method 2: Environment Variables (NEXUS_ prefix)¶

Dynaconf automatically merges NEXUS_ prefixed environment variables with the TOML file. Use double underscores for nested keys:

export NEXUS_BINANCE__DEMO__API_KEY="your_api_key"
export NEXUS_BINANCE__DEMO__SECRET="your_secret_key"

These are resolved by the same settings_key parameter:

# Reads from NEXUS_BINANCE__DEMO__API_KEY / NEXUS_BINANCE__DEMO__SECRET
config = BasicConfig(settings_key="BINANCE.DEMO", testnet=True)

Method 3: Plain Environment Variables¶

Use BasicConfig.from_env() to read credentials from plain environment variables without the NEXUS_ prefix:

export BINANCE_API_KEY="your_api_key"
export BINANCE_SECRET="your_secret_key"

from nexustrader.config import BasicConfig

# Reads BINANCE_API_KEY, BINANCE_SECRET, BINANCE_PASSPHRASE
config = BasicConfig.from_env("BINANCE", testnet=True)

# Custom variable names
config = BasicConfig.from_env(
    "X",
    api_key_var="MY_KEY",
    secret_var="MY_SECRET",
)

Method 4: Direct Pass¶

Pass credentials directly in code (highest priority, always overrides other sources):

from nexustrader.config import BasicConfig

config = BasicConfig(
    api_key="your_api_key",
    secret="your_secret_key",
    testnet=True,
)

Combining Sources¶

You can combine sources. Directly passed values override settings_key resolution:

# api_key is the direct value; secret is resolved from settings
config = BasicConfig(
    api_key="override_key",
    settings_key="BINANCE.DEMO",
    testnet=True,
)