# ProofGate

![ProofGate — Proof Before Every Trade](./public/og.png)

**Proof before every trade. / 每一次交易前，先让证据过关。**

[Watch the 27-second bilingual product demo](./public/proofgate-demo.mp4)

ProofGate is a read-only AI market-analysis agent and Trade Readiness Passport
for Binance Spot markets. It converts live evidence into one of three
inspectable outcomes:

- `WATCH`: no configured material gate failed; keep monitoring.
- `RESEARCH_MORE`: one material gate failed; gather fresh evidence.
- `NO_TRADE`: multiple independent gates failed.

Every outcome includes the raw signal, configured threshold, rule status, and
recheck condition. The result is a risk-control artifact, not investment advice
or an order instruction.

## Current safety boundary

- Public Binance Spot market data only.
- No Binance account, balance, position, order, transfer, or withdrawal access.
- No private key, API key, or token is required.
- Futures data is intentionally excluded because it is unavailable from the
  current development region.
- Official Binance Agent OS MCP authorization is a separate, owner-controlled
  step and has not been enabled in this repository.

## Architecture

```text
Binance Spot public market data
       │
       ├── 24h ticker + bid/ask
       ├── order book (±1% depth)
       └── 1h klines (realised volatility)
       │
       ▼
Deterministic ProofGate risk engine
       │
       ├── Web passport UI
       └── Local read-only MCP tool
```

The web interface and MCP server call the same market-data service and the same
risk engine, preventing rule drift between the demo and agent workflow.

## Run the web demo

Requirements: Node.js 22.13 or newer.

```bash
npm install
npm run dev
```

Open `http://localhost:3000`, enter a Binance Spot pair such as `BTCUSDT`,
then select **Run gate**.

## Run the MCP server

```bash
npm run mcp:build
npm run mcp:start
```

The stdio server exposes one focused tool:

| Tool | Purpose | Permissions |
| --- | --- | --- |
| `proofgate_analyze_spot_market` | Fetch live public Spot evidence and create a Trade Readiness Passport | Read-only, open-world market request |

For a complete protocol-level check:

```bash
npm run mcp:smoke
```

The smoke test launches the compiled stdio server, completes an MCP handshake,
lists tools, runs a live `SOLUSDT` call, and verifies the invalid-symbol error
path.

## Reproduce the agent in Codex

Codex supports local STDIO MCP servers. Clone and build ProofGate:

```bash
git clone https://github.com/sergepoliakov/proofgate-agent-os.git
cd proofgate-agent-os
npm ci
npm run mcp:build
```

Register the compiled server with Codex from the repository root:

```bash
codex mcp add proofgate -- node "$(pwd)/dist-mcp/mcp/server.js"
codex mcp list
```

Restart the Codex client, then ask:

> Use `proofgate_analyze_spot_market` to create a Trade Readiness Passport
> for SOLUSDT. Explain every failed or warning threshold. Do not access an
> account or execute a trade.

Expected workflow:

1. Codex discovers `proofgate_analyze_spot_market`.
2. The MCP tool validates the Spot symbol.
3. It reads public Binance ticker, order-book and 1h kline data.
4. The deterministic engine checks momentum, spread, ±1% depth, realised
   volatility and freshness.
5. Codex receives structured evidence plus WATCH, RESEARCH_MORE or NO_TRADE.

Remove the local server when finished:

```bash
codex mcp remove proofgate
```

### Optional official Binance Agent OS connection

The official Binance MCP endpoint can be added separately:

```bash
codex mcp add binance-agent-os --url https://agent.binance.com/mcp/agentic
codex mcp login binance-agent-os
```

The account owner must complete Binance browser authorization. For the
ProofGate workflow, enable market-data permission only and leave account,
trading, transfer and withdrawal permissions disabled. Availability and
eligibility depend on Binance account and jurisdiction rules. This optional
OAuth path remains pending owner verification in the current release.

## Verification

```bash
npm run lint
npm test
npm run mcp:smoke
npm run build
```

## Agent OS integration status

The local ProofGate MCP server is working. The official Binance Agent OS MCP
endpoint requires Binance browser authorization before its tool list can be
used. That authorization remains pending so the account owner can review and
grant market-data-only permissions. No execution permission is needed for this
project.