# 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`](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)

```bash
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):

```bash
node src/cli.js --probe
```

## Live connect (preferred: AI client)

Per [Binance MCP Server docs](https://developers.binance.com/en/docs/agent-native/mcp-server/agentic):

```bash
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):

```bash
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.json) / [`config.example.env`](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

## Links

- Docs: https://developers.binance.com/en/docs/agent-native/mcp-server/agentic  
- Agent OS: https://www.binance.com/en/agent-os  
- Challenge parent notes: `../README.md`, `../SUBMISSION-CHECKLIST.md`