v2.0.0 to v2.0.0

---

name: binance-futures-testnet-to-mainnet-promotion

license: Apache-2.0

---

# Binance Futures Testnet to Mainnet Promotion

## When to Use

Invoke this when a strategy that has been running on the Binance Futures testnet is about

to route orders against a mainnet base URL. The promotion step itself is the hazard: the

same code, pointed at a different host with different credentials, moves from fake balances

to real leveraged capital with liquidation risk. This skill supplies the gate that must pass

before an order router is handed a mainnet `ExchangeConfig`, plus the account-level

reconciliation steps that testnet cannot exercise.

Use it for both USDⓈ-M (`fapi`) and COIN-M (`dapi`) futures.

## When NOT to Use

- **Spot or Margin promotion**: Binance spot uses different hosts (`api.binance.com`) and a

different testnet; the host allowlist and the leverage/position-mode checks here do not apply.

- **Brokers with a single endpoint for both environments**: If environments are distinguished

only by credentials, the host-binding logic is inapplicable — see `alpaca-paper-live-key-separation`

for the credential-prefix variant of this pattern.

- **Backtesting or offline simulation**: No live endpoint is involved, so environment

segregation is irrelevant. Use `demo-account-realism-gap-assessment` to judge whether the

testnet record is meaningful at all.

- **As a substitute for a general go-live decision**: This gate checks environment wiring and

configured risk limits. It does not judge whether the strategy's *performance* justifies live

capital — that is `paper-to-live-promotion-checklist`.

- **As a runtime risk control**: This runs once at promotion. Continuous drawdown and exposure

enforcement belongs to `kill-switch-and-drawdown-circuit-breakers`.

## Prerequisites

- Python 3.10+ (standard library only; this module performs no network I/O).

- Separate Binance Futures testnet and mainnet API keys, held in distinctly named

environment variables. Testnet keys are issued from a separate registration flow and are

not valid on mainnet — if the same value appears in both configs, one leg is wrong.

- Mainnet key with Futures trading permission enabled and, where the account allows it, an

IP allowlist. Binance's API-key permission and expiry rules have changed more than once;

confirm the current rules in Binance's API management docs rather than assuming.

- A testnet track record produced against a *testnet* host (verify this — it is the first

thing the gate checks).

## Workflow

1. **Build both configurations**: Construct `ExchangeConfig` for testnet and mainnet.

`MainnetPromotionManager.__init__` rejects, as `ValueError`, any config whose

`environment` enum is wrong, any pair that shares an `api_key` or `api_secret`, and any

nonsensical risk ceiling (e.g. `max_capital_risk_pct=2`, the percent-vs-fraction slip).

2. **Bind each URL to its environment**: `verify_api_connectivity` requires HTTPS and an

*exact* hostname match against the allowlist for the declared environment. Both legs are

checked — a TESTNET-labelled config pointing at `fapi.binance.com` means the "paper"

track record was produced with real orders, so it invalidates the promotion rather than

merely warning. Exact matching is deliberate: a `startswith`/`endswith` comparison accepts

`https://fapi.binance.com.attacker.example`.

3. **Validate risk parameters, failing closed**: `validate_risk_parameters` rejects a missing

key rather than defaulting it, rejects NaN/Inf, rejects non-integer leverage (Binance

accepts integer leverage only), and requires `hard_stop_loss_enabled` to be the boolean

`True` — not any truthy value, because a config loader yielding the string `"false"` is truthy.

4. **Require explicit authorization**: `allow_live_promotion` defaults to `False`. Wire it

from an operator-controlled deployment flag at the call site

(`allow_live_promotion=os.environ.get("BINANCE_ALLOW_MAINNET_PROMOTION") == "true"`).

The module deliberately does not read the environment itself, so the decision stays

explicit and the gate stays deterministic under test.

5. **Reconcile mainnet account state before the first order** — this is the part testnet

cannot cover, because these are per-account, per-environment settings that do not travel

with your code:

- Position mode: `GET /fapi/v1/positionSide/dual`. If it disagrees with testnet, change it

*before* opening anything — `POST /fapi/v1/positionSide/dual` is rejected with `-4067`

when open orders exist and `-4068` when a position exists.

- Multi-assets margin mode (`/fapi/v1/multiAssetsMargin`) and per-symbol margin type

(`/fapi/v1/marginType`, which returns `-4046` when already set to the requested value).

- Leverage: set it with `POST /fapi/v1/leverage` and **read the response back**. Check the

permitted brackets via `GET /fapi/v1/leverageBracket`; the leverage your testnet config

assumed may exceed what this account and notional tier allow, and Binance has applied

lower caps to newly opened futures accounts.

- Symbol filters: re-read `GET /fapi/v1/exchangeInfo` on mainnet. `LOT_SIZE` (`stepSize`,

`minQty`), `MIN_NOTIONAL`, `PRICE_FILTER` (`tickSize`) and symbol availability are not

guaranteed to match testnet, so quantities that were accepted on testnet can be

rejected live.

6. **Promote**: Call `promote_to_mainnet(strategy_params)`. Every call re-runs the full

pre-flight sequence; a prior success never short-circuits a later parameter set.

7. **Pilot, then scale**: Run minimum-notional size first and compare realized slippage,

funding, and fees against the testnet assumptions before increasing allocation. See

`incremental-capital-deployment-for-new-strategies`.

> Full step-by-step procedure with endpoint-level detail: see `references/workflows.md`.

> Cited Binance API surface for this skill: see `references/standards.md`.

> Printable sign-off checklist: see `assets/checklist.md`.

## Common Pitfalls

- **Treating any `https://` URL as safe**: HTTPS says nothing about *which* venue you reached.

Bind the host to the declared environment and compare hostnames exactly.

- **Reusing one credential pair across both configs**: If the shared value is the mainnet key,

the "testnet" phase was live trading. If it is the testnet key, mainnet auth simply fails —

the harmless direction, which is why the dangerous direction goes unnoticed.

- **Defaulting a missing risk limit**: `params.get("leverage", 0)` turns a typo'd key into a

pass. On a promotion gate, absent means reject.

- **Comparing against NaN**: `float("nan") > max_leverage` is `False`, so a NaN risk parameter

passes a naive bounds check. Test finiteness explicitly.

- **Truthiness checks on safety flags**: the string `"false"` from an env var or YAML loader is

truthy and will silently disable a stop-loss requirement.

- **Treating "already promoted" as idempotent**: returning the mainnet config on a repeat call

without re-validating lets a later, over-leveraged parameter set inherit an earlier approval.

- **Assuming account settings carry over**: position mode, multi-assets mode, margin type and

leverage are per-account and per-environment. Changing position mode after you already hold

a position or open order fails (`-4067`/`-4068`), so reconcile before the first order.

- **Assuming testnet symbol filters match mainnet**: differing `stepSize`/`minNotional` produce

live `-2010` rejections for sizes that worked on testnet.

- **Logging config objects**: a plain dataclass `repr` prints `api_secret` verbatim into logs

and tracebacks. `ExchangeConfig` here redacts it; do the same for any config you add.

- **Trusting the testnet fill model**: Binance testnet order books are thin and synthetic.

Slippage, partial fills, and funding observed there are not evidence about mainnet.

- **Retrying an ambiguous order on the first live orders**: a timed-out `POST /fapi/v1/order`

may already have been accepted. Send a client-supplied `newClientOrderId`

(`^[\.A-Z\:/a-z0-9_-]{1,36}$`) and reconcile before resubmitting — see

`order-placement-idempotency`.

## Verification

- Run the unit suite: `python -m unittest discover -s skills/binance-futures-testnet-to-mainnet-promotion/scripts`.

- Point a TESTNET-labelled config at `https://fapi.binance.com` and confirm

`run_pre_flight_checks` returns `False`.

- Set `base_url` to `https://fapi.binance.com.attacker.example` and confirm rejection.

- Construct a manager with the same `api_key` in both configs and confirm `ValueError`.

- Omit `leverage` from `strategy_params` and confirm rejection; repeat with

`capital_risk_pct=float("nan")` and with `hard_stop_loss_enabled="false"`.

- Leave `allow_live_promotion` at its default and confirm `promote_to_mainnet` raises

`PromotionError`.

- Promote successfully, then call again with `leverage=50` and confirm `PromotionError`.

- Confirm `repr(config)` and `str(config)` contain no secret material.

- Against the live account: confirm `POST /fapi/v1/leverage` echoes back the leverage you

requested, and that `GET /fapi/v1/exchangeInfo` filters for every traded symbol match the

quantities your sizing logic emits.

## Related Skills

- `paper-to-live-promotion-checklist`

- `alpaca-paper-live-key-separation`

- `demo-account-realism-gap-assessment`

- `sandbox-vs-production-endpoint-drift`

- `perpetual-futures-funding-rate-handling`

- `kill-switch-and-drawdown-circuit-breakers`

- `order-placement-idempotency`

- `incremental-capital-deployment-for-new-strategies`