Binance MCP Trader Agent

English | 简体中文

Risk-gated AI trading agent for the Binance Agent OS mini hackathon (Track 2: Connect MCP and trade — see docs/submission.md).

It connects to the official Binance Agent OS MCP endpoint and turns natural trading intent into policy-checked, user-confirmed MCP tool calls. The local trader-agent server researches, enforces risk gates, and builds executable Binance MCP requests; it never places orders itself. Everything is dry-run by default, and live execution additionally requires five explicit gates (see Live Trading Gates).

Docs map:

• AGENTS.md — first-read rules for coding agents.

• docs/operator-manual.md — complete commands, config keys, safety gates, demos, troubleshooting.

• docs/mcp-server-development.md — build notes and security rules for the local trader-agent MCP server.

• docs/submission.md — hackathon submission notes.

• docs/TODO.md — code-review findings backlog.

Official Binance MCP endpoint (the only one; no local Binance package, no API keys in this repo):

https://agent.binance.com/mcp/agentic

Architecture

Two MCP servers in the same AI client:

AI client (Claude Code / Codex / ...)
  |-- binance-mcp-server  official Binance MCP: OAuth, market/account data, confirmed execution
  |-- trader-agent        local stdio server (this repo): research, policy, order planning, ledgers

The local server is a planner/auditor/researcher and the source of the approved execution request. It stores no Binance credentials, never calls Binance, and never places orders itself. After research and explicit user approval, the AI client calls the official Binance MCP order tool, then calls trader-agent.record_mcp_execution to archive the result. Live CLI execution also exists behind five gates.

Typical loop:

fetch klines via binance-mcp-server -> save CSV under data/ ->
trader-agent research (backtest / gridsim / significance) -> policy_check ->
propose_order_plan (returns the executable request) -> user confirms the exact request ->
binance-mcp-server order/strategy tool -> record_mcp_execution (append-only archive)

Related MCP server: trading-platform-mcp-server

Highlights

Research engine (local, offline candle files)

• MA, RSI, MACD, Bollinger indicators and buy/sell/hold signals.

• MA/RSI strategy backtests with fees, slippage, and gap-aware fills (a stop filled through a gap takes the worse open price); entry semantics are identical to the live signal (fresh golden cross + RSI band), so backtests measure exactly the strategy that propose-from-signal follows.

• Triple-barrier exits: fixed stop-loss/take-profit, optional time limit, optional trailing stop, and an optional time-decaying ROI table (roiTable, freqtrade minimal_roi style).

• Parameter grid optimization with six selectable scoring losses: default (composite), sharpe, sortino, calmar, maxdrawdown, onlyprofit; constraints on return/drawdown/trades/win-rate/Sharpe are always enforced.

• Walk-forward train/test validation; randomized return-path significance tests (seeded, p-value with +1 correction).

• Grid planning: budget-driven level count (investment vs exchange min-notional vs min spacing), prices/amounts quantized to exchange rules, per-level take-profit coerced to the grid step (coerce_tp_to_step), and a state-machine fill simulation over candles (research gridsim) with cycle counts, realized PnL, and per-level state histogram.

• HTML reports with candlesticks, trade markers, and equity curves.

Risk and policy gates (single entry: evaluatePolicy)

• Allowlists for venues and symbols; market orders disabled by default; single-order quote cap; futures leverage cap; opening shorts require reduceOnly; position cap via maxOpenPositions; futures positionMode (one-way/hedge) derived into positionSide.

• Order throttle: per-symbol open-order cap (maxOpenOrdersPerSymbol) and minimum seconds between live orders (minSecondsBetweenLiveOrders).

• Fail-closed budget pre-check: executable=true requires accountFreeQuote (free balance reported by the AI client from the official Binance MCP account tool) covering the quote amount, and respect of the exchange minNotional when exchangeRules are provided. Missing balance data keeps executable=false. Grid plans check balance against the total investment and minNotional per level; reduce-only exits skip the balance cap (they release margin instead of spending it).

• Performance circuit breakers (freqtrade-Protections style), evaluated from the local execution ledger: per-symbol cooldown after a recorded exit (cooldownMinutesAfterExit), StoplossGuard stop-loss counting per pair and globally within a lookback window, and a realized-PnL drawdown breaker (maxDrawdownQuoteUsdt). Breakers gate opening orders only — reduceOnly exits always pass.

• Every proposal returns an executableRequest object (executable, server: "binance-mcp-server", toolName, arguments, confirmationText, reason) — the exact request the AI client may submit after the user confirms it. confirmationText never contains the confirmation phrase itself.

• Demo-friendly multi-agent decision chain: Signal -> Bull -> Bear -> Risk Judge -> Distribution.

Execution and records

• Dynamic tools/list discovery; schema-aware mapping of trading intent (or grid bounds) to the best matching order tool; grid level tables are attached to tool arguments when the selected tool exposes a levels-like property.

• Every proposal/execution is a task with id, status, decision chain, and classified error details; authentication/insufficient-funds failures can pause the trader until trader resume.

• Stop-loss/take-profit protection is planned as a linked group (native OCO when the MCP server exposes one); quantities are hydrated from the actual entry fill. With submitProtectiveOrders=false (default) the group is archived as skipped and live fills are marked completed_unprotected.

• Exit-role records (role: "exit") accept realizedPnlQuote and feed the cooldown/StoplossGuard/drawdown breakers.

• All CLI JSON output and ledgers are redacted for secret-like fields before printing or writing; smoke tests run on fully isolated ledgers (runs-smoke/) and pin the real Binance MCP tool surface (tool names and argument keys captured from production) as regression fixtures.

Quick Start

npm install
copy config\agent.example.json config\agent.local.json
copy .env.example .env
npm run typecheck
npm run build
npm run smoke

npm start and npm run smoke import compiled files from dist/, so always build first. Node >= 20.

Offline policy check and dry-run proposal:

npm start -- policy --config config/agent.local.json --symbol BTCUSDT --side buy --type limit --quote 20 --price 65000
npm start -- propose --config config/agent.local.json --symbol BTCUSDT --side buy --type limit --quote 20 --price 65000

policy is offline and never connects to MCP. propose connects to Binance MCP, discovers order tools, and builds the candidate MCP call without trading. propose fails the budget pre-check until you pass --accountFree <free-quote-usdt> (and optionally --tickSize/--stepSize/--minNotional):

npm start -- propose --symbol BTCUSDT --side buy --type limit --quote 20 --price 65000 --accountFree 100 --minNotional 5

Offline research on a CSV/JSON OHLCV file:

npm start -- research backtest --file data/BTCUSDT-15m.csv --symbol BTCUSDT --timeframe 15m
npm start -- research gridsim --file data/BTCUSDT-15m.csv --symbol BTCUSDT --timeframe 15m --priceLow 76500 --priceHigh 79500 --quote 1000
npm start -- research optimize --file data/BTCUSDT-15m.csv --symbol BTCUSDT --timeframe 15m --loss calmar

CLI Command Reference

Notable flags:

• Trade intent (policy/propose/execute): --symbol/-s, --side, --venue, --type, --quote, --price, --amount, --leverage, --reduceOnly, --openPositions, --strategyType spot|futures|grid.

• Pre-check inputs: --accountFree (free quote balance), --openOrders, --lastOrderAt, --tickSize, --stepSize, --minNotional (the latter three also quantize grid levels).

• Grid proposals: --priceLow, --priceHigh, --gridLevels, --coerceTp.

• Research parameters: --fast, --slow, --rsi, --rsiMin, --rsiMax, --takeProfit, --stopLoss, --timeLimitBars, --trailingStopActivation, --trailingStopDelta, --roiTable '<json>', --quote, --initialCash, --feeRate, --slippageRate; optimization constraints --minReturn/--maxDrawdown/--minTrades/--minWinRate/--minSharpe; research optimize --loss <name>; research significance --simulations/--seed; research report --out.

Full command and config reference: docs/operator-manual.md.

Using with an AI Client

1. Add the official Binance MCP server

Claude Code (verified working):

claude mcp add -s user -t http binance-mcp-server https://agent.binance.com/mcp/agentic

Codex CLI:

codex mcp add binance-mcp-server --url https://agent.binance.com/mcp/agentic
codex mcp login binance-mcp-server

Generic JSON MCP clients:

{
  "mcpServers": {
    "binance-mcp-server": {
      "url": "https://agent.binance.com/mcp/agentic"
    }
  }
}

Do not paste the endpoint into a normal AI chat and ask the model to install it. Add it through the client's MCP/server settings. -s user registers the server globally; without it the server only loads in sessions started from that project directory. Restart the client after adding — the MCP server list loads at client startup.

2. Authenticate and pick scopes

Open the MCP menu in the AI client, select binance-mcp-server, run the OAuth flow, and grant the least scope needed:

• Market data — tickers, order books, candles, funding rates. Start here.

• Account — Agentic sub-account balances, positions, bills. Needed for accountFreeQuote.

• Trade — spot, margin, convert, USD-M / COIN-M futures; only when ready to test live trading.

• Transfer — wallet-to-wallet inside the same Agentic sub-account only.

Binance Agent OS MCP does not expose withdrawal permission. It cannot withdraw funds to an external address.

3. Add the local trader-agent MCP server

Claude Code (verified working; --prefix makes the script run with the repo as cwd so config/data/runs resolve correctly from anywhere):

claude mcp add -s user trader-agent -- npm --prefix D:/GOPATH/src/github.com/sereneFIREGroup/trading/binance-mcp-trader-agent run mcp-server

Codex CLI (run from the repo root):

codex mcp add trader-agent -- npm run mcp-server

The server is a stdio MCP server built on the official TypeScript MCP SDK (@modelcontextprotocol/sdk), started via npm run mcp-server. Tool surface (15 tools) — research tools accept offline candle files only (file under data/, reports/, or runs/) and never fetch from Binance:

• research_signal, research_backtest, research_optimize, research_walkforward, research_significance, research_report, research_gridsim

• policy_check (gates + ledger-derived breakers), propose_order_plan (task/order plan + executableRequest + grid level table; never calls Binance itself)

• record_mcp_execution (archives the result after the AI client calls the official Binance MCP; role: "exit" + realizedPnlQuote feed the breakers)

• list_tasks, list_research_sessions, list_executions

• trader_status, trader_resume

propose_order_plan inputs mirror the CLI pre-check inputs (accountFreeQuote, exchangeRules, openOrders, lastOrderAt, strategyType, grid bounds) plus binanceTools metadata from the official server's tools/list, so tool selection and argument mapping run locally. Full input schemas: docs/mcp-server-development.md.

4. Agent runtime prompt

Paste into the AI client:

You have two MCP servers:

1. binance-mcp-server: official Binance MCP. Use it for market data, account reads, and order execution only after explicit user confirmation.
2. trader-agent: local risk/research agent. Use it first for research, backtests, policy checks, order plans, task ledgers, and execution records.

Required order for any trade:
trader-agent.research_backtest / research_significance / research_gridsim
-> trader-agent.propose_order_plan (returns the executable request)
-> show the executableRequest.confirmationText to the user and wait for explicit approval
-> binance-mcp-server order tool
-> trader-agent.record_mcp_execution (role "exit" with realizedPnlQuote after a position closes)

Never call Binance order tools before trader-agent returns a passing policy, an order plan, and the exact executable request, and the user confirms that request.

5. Fund the Agentic sub-account (live testing only)

Trading happens inside a dedicated Agentic sub-account isolated from the main account; the agent cannot pull funds from the main account. For live tests, manually transfer a small test amount:

Profile -> Dashboard -> Sub-account -> Asset Management -> Transfer

Skip this for read-only market-data tests and dry-run demos.

6. Verify connectivity

npm run build
npm start -- tools --config config/agent.local.json

A healthy connection prints Binance MCP tools. HTTP 401 → re-authenticate the MCP server in the AI client or refresh BINANCE_MCP_AUTH_TOKEN. Then test read-only market data (quote, research signal) before any account or trading tests. If market data works but account/order commands fail, grant the missing Account or Trade scope and confirm the sub-account is eligible for the venue.

Standalone CLI Direct-HTTP Mode

The standalone npm start -- ... CLI can also talk to Binance MCP directly. It cannot read OAuth tokens from Codex CLI's encrypted MCP auth store; set a short-lived bearer token only in your shell or ignored .env:

$env:BINANCE_MCP_AUTH_TOKEN="your_short_lived_mcp_token_here"

• npm start -- policy ... — fully offline; no MCP auth needed.

• npm start -- research ... --file data/BTCUSDT-15m.csv — offline research/backtest/report; no MCP auth needed.

• npm start -- tools|quote|account|propose|execute ... — direct MCP HTTP mode; needs BINANCE_MCP_AUTH_TOKEN until a dedicated OAuth bridge exists.

Live Trading Gates

Live execution is intentionally hard to trigger. All five must agree:

1. config/agent.local.json: "mode": "live"

2. CLI flag: --live

3. Environment variable: BINANCE_AGENT_LIVE=1

4. Confirmation phrase: --confirm I_ACCEPT_BINANCE_LIVE_TRADING_RISK

5. Finished research proof: --researchSession <id> from research backtest | optimize | walkforward | significance | report | gridsim | propose-from-signal (a plain research signal id is not accepted)

set BINANCE_AGENT_LIVE=1
npm start -- execute --config config/agent.local.json --live --researchSession research_backtest_... --confirm I_ACCEPT_BINANCE_LIVE_TRADING_RISK --symbol BTCUSDT --side buy --type limit --quote 20 --price 65000

Safety Model

• Default mode is dry-run; market orders disabled; single order capped at 25 USDT by default (grid: the cap applies per level, the balance pre-check to the total investment).

• Futures short opening disabled unless reduce-only; performance breakers never block reduce-only exits.

• executable=true is fail-closed: without reported balance the request stays non-executable with an explicit reason.

• Live execution records stop-loss/take-profit protection as a linked order group but does not submit those extra orders. Add --submitProtection only when the discovered Binance MCP tools clearly support OCO / stop-loss / take-profit placement. Native OCO tools delegate sibling cancellation to the exchange; linked non-OCO orders are archived with an explicit operator cancellation policy.

• Monitoring-level barriers (time limit, trailing stop, ROI table) are surfaced in order plans as warnings — they are not exchange-native orders and require the operator/AI client to watch and act.

• No private key, mnemonic, Binance API key, or long-lived token is required by the repo; real .env and local config are git-ignored. Never store secrets in tracked files.

• The local MCP server never stores Binance OAuth tokens or API keys, never adds Binance REST API-key support, and never calls Binance directly; all exchange actions go through the official binance-mcp-server connection owned by the AI client after explicit user confirmation, or stay CLI-only.

• All CLI JSON output and runtime ledgers redact secret-like fields before printing or writing; the confirmation phrase is never embedded in tool output.

• Research MCP tools accept offline files only, confined to data/, reports/, and runs/ (path traversal and absolute paths rejected), and must never call order/account/transfer tools.

• Authentication and insufficient-funds failures are classified and can pause the trader.

• Smoke tests run on isolated runs-smoke/ ledgers and never touch the production runs/ audit trail.

Demo Script

1. npm start -- tools — dynamic Binance MCP tool discovery.

2. Dry-run propose (with --accountFree) — show the policy decision and the executableRequest with its confirmation text.

3. Oversized quote or missing --accountFree — show the fail-closed blocker.

4. research backtest — strategy validated before trading (fees, slippage, gap-aware stops).

5. research gridsim — grid level table + state-machine replay over candles.

6. research optimize --loss maxdrawdown — parameter search under a chosen scoring loss.

7. research significance + research report — statistical validation and the HTML chart.

8. Record exits via record_mcp_execution (role: "exit", realizedPnlQuote), then show policy_check firing cooldown / StoplossGuard / drawdown breakers.

9. tasks --limit 5 and executions --limit 5 — every proposal has a task id, decision chain, and order plan; every submitted call is archived.

10. Switch config to live — execution still fails until env + confirmation + research session are present.

11. Tiny live limit order — only if the contest sub-account is authorized and funded.

Project Structure

binance-mcp-trader-agent/
  LICENSE              MIT
  AGENTS.md            first-read rules for coding agents
  src/
    cli.ts             command-line agent
    mcp-server.ts      local stdio trader-agent MCP server entrypoint (15 tools)
    mcp-tools/         MCP input validation (zod), path confinement, tool registrations
    mcp-client.ts      Streamable HTTP MCP JSON-RPC client (SSE-aware)
    tool-router.ts     dynamic Binance MCP tool selection and argument mapping (order/OCO/protection/grid)
    payload.ts         helpers for reading unknown MCP payloads
    policy.ts          the single safety-policy entry: allowlists, caps, throttle, breakers, live gates
    safety.ts          output and ledger redaction helpers
    research/          indicators, market data parsing, backtest (triple barrier + ROI table),
                       grid-plan (level tables), grid-simulator, optimization losses,
                       significance tests, sessions, HTML reports
    trading/           trading workflow, executable-request builder, order plan (OCO/protection),
                       decision chain, task/execution ledgers, recent-exit lookups, failure handling
  config/
    agent.example.json safe template config (includes breaker + roiTable defaults)
  scripts/smoke.mjs    end-to-end smoke tests on isolated runs-smoke/ ledgers
  docs/
    operator-manual.md full operator manual (commands, config keys, troubleshooting)
    mcp-server-development.md  local MCP server tool schemas and security rules
    submission.md      hackathon submission notes
    TODO.md            code-review findings backlog