ProofRun

Every action, accounted for.

A reusable skill and MCP for budget-bound Binance trading workflows. ProofRun records the preview and human approval before execution, then reconciles an interrupted attempt against its original order identity.

Hackathon release: live Binance public market data + simulated execution. No real funds move. The dashboard clearly labels this distinction. The demo exchange persists an accepted order before deliberately losing the response; restarting ProofRun and reconciling retrieves that same order without submitting twice.

Try it now

Live demo
Remote MCP: https://proofrun-agent.up.railway.app/mcp
Reusable skill

The public endpoint is a shared, simulated sandbox. Do not submit account information or secrets. Each prepared mission returns an approval URL for its exact preview.

For clients supporting Streamable HTTP MCP:

{
  "mcpServers": {
    "proofrun": { "url": "https://proofrun-agent.up.railway.app/mcp" }
  }
}

Run

Requires Node.js 24 or newer.

npm ci
npm start

Open http://127.0.0.1:4317. Prepare a 20 USDT BTCUSDT mission, type the exact displayed approval phrase, leave “Simulate a lost response” checked, execute, then recover the original order. Download the receipt.

npm test
npm run mcp

MCP configuration (replace the absolute paths):

{
  "mcpServers": {
    "proofrun": {
      "command": "node",
      "args": ["/absolute/path/to/ProofRun/src/mcp.js"],
      "env": {
        "PROOFRUN_DB": "/absolute/path/to/ProofRun/data/proofrun.sqlite"
      }
    }
  }
}

Use the same database path for the dashboard and MCP. Install or load skills/proofrun/SKILL.md in your agent runtime. The skill guides the agent; deterministic checks live in the server.

Four tools

Tool	Purpose
`prepare_mission`	Read evidence, apply limits and save a preview
`get_mission`	Inspect state, approval and receipt
`execute_mission`	Claim one already human-approved simulated submission
`reconcile_mission`	Query the original order; never resubmit

Human approval is a separate dashboard action and is intentionally absent from the MCP tool list.

Recovery contract

SQLite WAL stores an atomic submission claim before contacting the exchange. Concurrent calls cannot claim the same mission twice. A timeout becomes UNKNOWN, not FAILED. Reconciliation matches the client order ID, market, side, type, quantity and limit price to the approved plan. Unavailable or missing status does not unlock resubmission. This release permits one submission attempt per mission; it does not promise universal exactly-once execution or prevent a human from creating another mission.

Binance client order IDs alone are not permanent idempotency keys: Binance may accept reuse once a previous order is filled. ProofRun therefore also keeps a durable local submission lock.

Scope and provenance

New standalone hackathon project by the PolyDesk builder. Reuses architectural lessons from PolyDesk's bounded decisions, explicit authorization and receipt recovery. Existing PolyDesk services and deployments are untouched. Hash PayLink payment integration is future work and is not claimed in this demo.

Binance integration uses public /api/v3/ticker/bookTicker, /api/v3/ticker/24hr and /api/v3/exchangeInfo at Binance's documented market-data-only host. This is API integration; official hosted Binance MCP authentication is not claimed. The reusable skill is intended for use in an Agent OS workflow.

A reference HMAC testnet transport is included but deliberately not enabled: testnet-specific market filters, account permissions and acceptance remain to be verified. There is no production order transport. The 1% reserve is an allocation buffer, not a guarantee of fees. Receipts do not claim verified commissions.

Verification

npm test covers restart recovery, 20 concurrent submissions, missing approval, expiry, changed order parameters, unavailable status, mismatched receipts and budget bounds. These are deterministic local tests, not live exchange execution evidence.

Sources: Binance REST API, Binance Skills Hub, Agent OS hackathon.

Deployment

The default server binds to localhost. Set HOST=0.0.0.0 for an isolated public demo only deployment. The public demo must never receive real account credentials. SQLite data needs a persistent volume for durability across deployment replacements; process restart persistence alone is not disk durability across hosts.

License

MIT. Independent project; no Binance affiliation or endorsement.