ETS-backed credential registry for integration testing.
Supports multiple credential sets per exchange for multi-API exchanges (e.g., Binance spot vs futures testnets require separate credentials).
Credentials are registered once at test startup (in test_helper.exs),
then retrieved by generated tests at runtime. ETS with read_concurrency: true
allows lock-free reads from any process.
Usage
# In test_helper.exs - register credentials for each sandbox
CCXT.Testnet.register_all_from_env([
{:bybit, testnet: true},
{:binance, testnet: true},
{:binance, :futures, testnet: true},
{:okx, testnet: true, passphrase: true}
])
# In tests - retrieve credentials for specific sandbox
creds = CCXT.Testnet.creds(:bybit) # default sandbox
creds = CCXT.Testnet.creds(:binance, :futures) # futures sandboxSandbox Keys
Multi-API exchanges have different testnets per API section:
| Sandbox Key | Env Var Infix | Example Hostname |
|---|---|---|
:default | (none) | testnet.binance.vision |
:futures | _FUTURES | testnet.binancefuture.com |
:coinm | _COINM | testnet.binancefuture.com/dapi |
Env Var Convention
{EXCHANGE}[_{SANDBOX}]_TESTNET_API_KEY{EXCHANGE}[_{SANDBOX}]_TESTNET_API_SECRET{EXCHANGE}_PASSPHRASE(ifpassphrase: true)
When :testnet is true, the _TEST_ infix is accepted as a silent fallback
(e.g. BINANCE_FUTURES_TEST_API_KEY is treated as an alias for
BINANCE_FUTURES_TESTNET_API_KEY). The canonical _TESTNET_ name remains
preferred and is the one surfaced in creds!/2 error messages.
Summary
Functions
Returns a specification to start this module under a supervisor.
Clears all registered credentials (for test isolation).
Get credentials for an exchange/sandbox. Returns nil if unregistered.
Get credentials or raise ArgumentError with a helpful message.
Env var prefix for a given exchange + sandbox combination.
List unique exchange atoms with any registered credentials.
Register credentials directly.
Register credentials for multiple exchanges from environment variables.
Register credentials from environment variables.
Returns true when credentials are registered for the given exchange/sandbox.
List all registered {exchange, sandbox_key} tuples.
Derive sandbox_key from a sandbox URL's hostname/path.
Starts the Testnet registry GenServer (owns the ETS table).
Types
@type config_entry() :: {atom(), register_opts()} | {atom(), atom(), register_opts()}
Config entry for register_all_from_env/1
@type register_opts() :: [ testnet: boolean(), passphrase: boolean(), sandbox: boolean(), secret_suffix: String.t() ]
Options for register_from_env/2,3
Functions
Returns a specification to start this module under a supervisor.
See Supervisor.
@spec clear() :: :ok
Clears all registered credentials (for test isolation).
@spec creds(atom(), atom()) :: CCXT.Credentials.t() | nil
Get credentials for an exchange/sandbox. Returns nil if unregistered.
@spec creds!(atom(), atom()) :: CCXT.Credentials.t()
Get credentials or raise ArgumentError with a helpful message.
Env var prefix for a given exchange + sandbox combination.
Examples
iex> CCXT.Testnet.env_var_prefix(:binance, :default)
"BINANCE_TESTNET"
iex> CCXT.Testnet.env_var_prefix(:binance, :futures)
"BINANCE_FUTURES_TESTNET"@spec exchanges_with_creds() :: [atom()]
List unique exchange atoms with any registered credentials.
Register credentials directly.
Returns :ok if credentials validate, :skipped if required fields are missing.
@spec register_all_from_env([config_entry()]) :: [{atom(), atom()}]
Register credentials for multiple exchanges from environment variables.
Returns the list of successfully registered {exchange, sandbox_key} tuples.
@spec register_from_env(atom(), atom() | register_opts(), register_opts()) :: :ok | :skipped
Register credentials from environment variables.
Env var pattern: {EXCHANGE}[_{SANDBOX}][_TESTNET]_API_KEY|_API_SECRET.
Options
:testnet- Include_TESTNETin env var names (default:false):passphrase- Also load passphrase from{EXCHANGE}_PASSPHRASE(default:false):sandbox- Value forcredentials.sandbox(default: value of:testnet):secret_suffix- Override secret env var suffix (default:"API_SECRET")
Returns :ok on success, :skipped when required env vars are absent.
Returns true when credentials are registered for the given exchange/sandbox.
List all registered {exchange, sandbox_key} tuples.
Derive sandbox_key from a sandbox URL's hostname/path.
Examples
iex> CCXT.Testnet.sandbox_key_from_url("https://testnet.binance.vision/api/v3")
:default
iex> CCXT.Testnet.sandbox_key_from_url("https://testnet.binancefuture.com/fapi/v1")
:futures
iex> CCXT.Testnet.sandbox_key_from_url("https://testnet.binancefuture.com/dapi/v1")
:coinm@spec start_link(keyword()) :: GenServer.on_start()
Starts the Testnet registry GenServer (owns the ETS table).