SignalDesk

Track A entry for the Binance Agent OS Mini Hackathon: a confirm-before-trade Spot briefing agent on the official Binance MCP Server / Agentic sub-account.

Pitch: Live (or dry-run) MCP market context → short Spot briefing → human-confirmed order draft inside an Agentic virtual sub-account.

Architecture

┌─────────────────────────────────────────────────────────────┐
│  AI client (Claude Code / Codex / ChatGPT / VS Code / …)    │
│  + skills/signaldesk/SKILL.md                               │
│  OR local CLI: node src/cli.js [--dry-run | --live]         │
└───────────────────────────┬─────────────────────────────────┘
                            │ MCP over Streamable HTTP
                            │ Auth: OAuth Bearer (browser consent)
                            │ URL: https://agent.binance.com/mcp/agentic
┌───────────────────────────▼─────────────────────────────────┐
│                 Binance MCP Server (Agent OS)               │
│  Scopes: Market data │ Account │ Trade │ Transfer           │
│  Withdrawal: NEVER available                                │
│  Writes: confirm-before-execute (orders/cancels/transfers)  │
└───────────────────────────┬─────────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────────┐
│         Agentic virtual sub-account (isolated)              │
│  Manual fund from main via Binance UI (agent cannot pull)   │
│  Spot (+ optional Margin/Convert/Futures if granted)        │
└─────────────────────────────────────────────────────────────┘

DRY-RUN path (no OAuth / no keys):
  CLI → DryRunMcp simulator → briefing + confirm → simulated fill

Runtime contract (summary)

See full capture in docs/RUNTIME-CONTRACT.md.

Item	Official
Endpoint	`https://agent.binance.com/mcp/agentic`
Auth	Browser OAuth (not local API keys)
Sub-account	Agentic virtual sub
Trade (if granted)	Spot, Margin, Convert, USDⓈ-M / COIN-M Futures
Withdrawals	Not available
Safety	Confirm before orders / cancels / transfers

Exact MCP tool names / schemas and MCP-specific rate limits are not published on the agentic docs page → marked TODO-VERIFY.

Quick start (DRY-RUN — works without Binance access)

cd repo
node src/cli.js --dry-run --symbol BTCUSDT --quote 10 --yes
# or
npm run dry-run -- --symbol BTCUSDT --quote 10 --yes

Unauthenticated live probe (expects HTTP 401 + Bearer challenge):

node src/cli.js --probe

Live connect (preferred: AI client)

Per Binance MCP Server docs:

claude mcp add binance-mcp-server --transport http https://agent.binance.com/mcp/agentic

Then authenticate in-browser, create/fund the Agentic sub-account, grant Account + Trade (Spot). Load skills/signaldesk/SKILL.md and run the briefing → confirm → verify flow.

Optional CLI live discovery (Bearer from your local OAuth session only — never commit):

cp config.example.json config.json
# set oauth.accessToken locally, OR export BINANCE_MCP_BEARER=...
npm run live

Live CLI lists tools only until schemas are verified (TODO-VERIFY). Do not auto-place live orders from unverified shapes.

Config

config.example.json / config.example.env — placeholders only
Copy to config.json / .env locally; both are gitignored

Repo layout

repo/
  README.md
  package.json
  config.example.json
  config.example.env
  docs/RUNTIME-CONTRACT.md
  skills/signaldesk/SKILL.md
  src/
    cli.js          # entry
    contract.js     # documented constants
    dry-run.js      # simulator
    mcp-live.js     # OAuth Bearer MCP HTTP client + tools/list
    briefing.js     # briefing formatter

Safety

No secrets in git
Confirm-before-trade always
Fund Agentic sub with dust only
No withdrawal path on MCP