qualto-mcp
Provides tools for placing, canceling, and verifying spot orders on Binance via the Agent OS gateway, including account balance and price checks, with claim-based attestation against Binance order history.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@qualto-mcp Verify my last BNB order claim against Binance."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Qualto
Qualto is a bounded, verification-first AI trading agent built on Binance Agent OS.
It can reason about a trading mandate and execute on Binance — but it isn't allowed to claim an order succeeded until Binance itself proves it.
The LLM decides what claim to propose. Qualto's deterministic boundary decides whether it may execute. Binance decides whether the resulting claim is true.
If Binance can't prove it, the agent can't claim it.
Binance Agent OS Mini Hackathon · Track A
Demo video: https://x.com/MystiqueMide/status/2097474244095451324?s=20
Live site: qualto.vercel.app
Repository: github.com/mystiquemide/qualto
The Problem
An AI agent can say "I bought BNB" whether the trade happened or not. Those reports are self-reported — the user has to independently open the exchange and check. Until then, a hallucinated fill and a real one look identical.
Qualto makes Binance verify the agent's claim automatically.
Related MCP server: binance-mcp-chainvector
How Qualto Solves It
user → AI agent → claim → Qualto boundary → Agent OS → Binance → verification → agent responseThe agent reasons. Given a mandate plus live Binance price and balance, the LLM drafts a strict trading claim — symbol, side, quantity, price, status — as validated JSON.
The claim gets an identity. Before execution, the claim receives a unique ID, and Qualto stamps that ID into the Binance order itself using
newClientOrderId.Execution through Agent OS. Qualto executes the order through the Binance Agent OS MCP endpoint — the agent never places raw orders.
Binance becomes the judge. Qualto reads the order back from Binance through two lookup paths (by
orderIdand by the claim ID) and requires both readbacks to agree. Claim fields are checked against the exchange record: symbol, side, quantity, price, status.The verdict is enforced, not advisory. Match →
PROVED. No match, unreadable, or unprovable →UNPROVEDand the trading session locks — the agent cannot trade again until an operator intervenes.
When the agent claims a fill, Qualto additionally verifies the executed quantity before returning PROVED. Resting orders, cancellations, and partial fills are each attested against their actual exchange state.
Why Binance Agent OS Is Essential
Qualto is load-bearing on Agent OS — remove it and nothing above survives:
Execution: all orders go through the official Agent OS MCP endpoint (
agent.binance.com/mcp/agentic).Authentication: OAuth 2.1 via the registered Agent OS host connector.
Market data: live prices and balances from
spot.tickerPriceandspot.getAccount.The proof itself: Binance's order record — with the claim ID inside it — is the source of truth for every verdict. The proof lives on Binance's ledger, not in Qualto's log.
Of the 366 tools Agent OS exposes, Qualto admits exactly 6 (spot account, ticker, place, get, trades, cancel). Everything else is rejected before a request exists.
What We Built
An AI trading agent whose execution claims must be proven by Binance, plus the verification layer that enforces it.
Capability | Status |
LLM agent loop: mandate → live context → reasoned claim (tools disabled, stdin prompt, 120 s budget) | Shipped, proven live |
Claim-bound placement + dual readback + field diff via Agent OS | Shipped, proven live |
Verdicts PROVED / UNPROVED / PARTIAL / PENDING with session lock | Shipped, proven live |
Session states ACTIVE / BLOCKED / ERROR / CLOSED, replay protection, write gates | Shipped |
Standalone MCP server ( | Shipped |
Agent skill ( | Shipped |
| Shipped |
Web console (landing + docs) — qualto.vercel.app | Shipped |
CI (pytest / ruff / mypy), GitHub Pages, Vercel auto-deploy | Shipped |
Planned but not built: native attestation in the Agent OS console, x402 payment gating, multi-venue attestation, remote-HTTP MCP, multi-session persistence.
Architecture
┌───────────────────────── operator ─────────────────────────┐
│ CLI (qualto propose / claim / agent / verify / cleanup) │
│ Web console (Next.js — qualto.vercel.app) │
└──────────┬────────────────────────────────────────────────┘
│ mandates, claims (strict JSON)
┌──────────▼────────────────────────────────────────────────┐
│ AI agent layer │
│ LLM (Hermes): mandate + live context → one claim. │
│ Zero tools. Prompt over stdin. 120 s wall clock. │
├───────────────────────────────────────────────────────────┤
│ Qualto boundary (Python 3.11+, zero core deps) │
│ claim schema strict, decimal-exact, replay-proof │
│ attestation bind → dual readback → field diff │
│ session ACTIVE / BLOCKED / ERROR / CLOSED │
│ receipts append-only JSONL, fsync, 0600 │
│ MCP server 5 tools, double write gate │
├───────────────────────────────────────────────────────────┤
│ Agent OS client │
│ JSON-RPC over streamable HTTP · request-ID matching · │
│ two-layer tool allowlist (366 → 6) │
└──────────┬────────────────────────────────────────────────┘
│ OAuth 2.1 (registered host connector)
┌──────────▼────────────────────────────────────────────────┐
│ Binance Agent OS MCP → Binance spot sub-account │
│ The order record IS the proof │
└───────────────────────────────────────────────────────────┘Live Proof
Real orders, placed by the agent, still visible in Binance order history — each carrying its claim ID as the client order ID:
Binance order | Claim ID | Verdict |
|
| PROVED, then CANCELED at zero execution |
|
| PROVED, then CANCELED at zero execution |
| string-transport proof | PROVED, then CANCELED at zero execution |
Every live proof used the zero-cost pattern: below-market dust limit → PROVED → immediate cancel → post-cancel readback confirming zero execution. The negative path was also proven live, twice: gateway severed before placement → UNPROVED → session BLOCKED → writes refused → operator recovery.
Re-verify any receipts file against live Binance at any time:
qualto verify --receipts-file receipts.jsonl # read-onlyBenchmarks (measured, not marketed): PROVED verdict → confirmed cancellation 353 ms · full Agent OS gateway cycle 1.2–1.4 s · mandate → PROVED ~28 s (LLM-bound) — verification is never the bottleneck; the thinking is.
Reliability: the behavior above is backed by 11,433 passing tests (~19 s, no network) — 10,665 parameterized claim-contract cases (sides × order types × statuses × quantities × price tolerances × envelope shapes), 12 MCP server tool/gate tests, and 756 focused behavioral tests (dual readback, replay rejection, session locking, orphan cleanup, CLI). Reproduce with pytest -q.
Run It Yourself
Requirements: Python 3.11+ · a Binance account with a funded Agentic sub-account · a registered Agent OS host credential (Codex CLI authenticated with the Binance connector) as QUALTO_CODEX_CREDENTIALS_FILE. No database, no personal API keys, no main-account access — ever.
Quickstart
git clone https://github.com/mystiquemide/qualto && cd qualto
python3 -m venv .venv && .venv/bin/pip install -e ".[test]"
export QUALTO_CODEX_CREDENTIALS_FILE=/path/to/host-credentials.json
.venv/bin/qualto smoke # read-only gateway check
.venv/bin/qualto propose --mandate "buy 5 USDT of BNB" # agent drafts, nothing placed
# first zero-cost proof cycle on your own sub-account
cat > my-claim.json <<'EOF'
{
"claimId": "qualto-claim-yourownid001",
"mandate": "buy a small below-market BNB limit order, then cancel",
"symbol": "BNBUSDT", "side": "BUY", "orderType": "LIMIT",
"quantity": "0.009", "price": "600", "status": "NEW",
"reason": "Dust proof order bound to this claim ID."
}
EOF
.venv/bin/qualto claim --claim-file my-claim.json \
--receipts-file runtime/my-receipts.jsonl \
--confirm-live-write --cancel-after-attestationWeb console: cd web && npm install && npm run dev.
Security
Permission model: only Qualto's boundary places orders; the LLM has zero tools; the MCP surface is five fixed tools; the underlying Binance operations are a 6-entry allowlist enforced before any request is built.
Secret handling: the host credential is loaded per request, in memory, never logged, never in receipts; a dedicated test asserts no leakage. Missing or expired ⇒ fail closed, no order.
Input validation: closed claim schema at the boundary — unknown fields, float quantities, reused claim IDs, out-of-range prices rejected before placement.
Access control: every live write requires
--confirm-live-write(CLI) or the env flag plus per-call confirmation (MCP); exit code 2 and nothing is sent without it.Transport: JSON-RPC responses matched to request IDs; mismatches rejected.
Safety
The agent may: read live context, draft claims, and — through the Qualto boundary — place claim-bound orders and cancel the exact order bound to a claim.
The agent may not: reach withdrawal, transfer, futures, or margin paths; place any order that isn't claim-bound; unblock a session it got blocked.
Requires explicit human approval: every live write, every session recovery, every cleanup.
Unknown outcomes fail closed: an order whose placement result is unknown produces an intent receipt and a
qualto cleanuppath that resolves it by claim ID. The safe state is always "no order."
Agent Integrations
Agent | How it interacts | Status |
OpenAI Codex | The OAuth credential rides Codex's registered Binance Agent OS connector. All live proofs in this repo ran on this path. | Tested, live-proven |
Claude Code / Claude Desktop | Install the agent skill ( | Supported |
Qwen Code | Same skill installs to | Supported |
Any MCP-compatible client |
| Supported |
Binance Integration
Endpoint: Binance Agent OS MCP (
agent.binance.com/mcp/agentic), JSON-RPC over streamable HTTP, protocol2025-03-26, OAuth 2.1 via the registered host connector.Tools: 366 exposed → 6 allowlisted:
spot.getAccount,spot.tickerPrice,spot.newOrder,spot.getOrder,spot.myTrades,spot.deleteOrder.Order identity: every order placed with
newClientOrderId = claimId— the attestation is visible in Binance's own order history UI.Envelope: all activity confined to a funded Agentic sub-account; main-account funds are structurally out of reach.
Skill Integrations
qualto-claim-bound-trading(skills/) — teaches SKILL.md-compatible agents the policy: never call Binance order endpoints directly, report verdicts verbatim, never soften an UNPROVED, stop when the session locks.MCP tools (
qualto-mcp):qualto_session_status,qualto_read_context,qualto_attest_claim,qualto_cleanup_claim,qualto_verify_receipts. Live writes requireQUALTO_ENABLE_LIVE_WRITE=1and a per-callconfirm_live_writeflag.
Other Integrations
Web console — Next.js 15 (
web/), deployed to qualto.vercel.app and GitHub Pages.Hermes — LLM provider for the drafting loop.
CI/CD — GitHub Actions on every push; Pages and Vercel deploy from
main.
Authentication
Users never hand Qualto a Binance API key. Authentication rides a registered Agent OS host connector's OAuth credential (QUALTO_CODEX_CREDENTIALS_FILE), loaded per request, expiry-checked every call, never persisted. Sessions are local and explicit; MCP sessions add the double write gate.
Limitations
Single session, spot only, one symbol per claim; attestation is per-order, not per-strategy.
The claim file — not the mandate — is the binding contract.
Third-party agent OAuth identities are not yet admitted by Binance; Qualto runs on the registered host-credential path and fails closed when unavailable.
The MCP server is stdio-only; remote-HTTP clients (ChatGPT, Devin) cannot connect today.
Qualto proves a trade happened exactly as claimed — it does not judge whether the trade was a good idea.
Human supervision required for: every live write, every session recovery, any state after an UNPROVED verdict.
Vision
Everyone is building agents that decide what to trade. Qualto tackles whether you can trust what the agent says it did. That wedge generalizes: claim-bound orders as an Agent OS convention (reserved client-order-ID namespace, native console attestation), "no proof, no payment" settlement gating for agentic commerce (x402), multi-venue attestation, and remote MCP so any hosted agent can connect.
Contributing
git clone https://github.com/mystiquemide/qualto && cd qualto
python3 -m venv .venv && .venv/bin/pip install -e ".[test,quality]"
.venv/bin/pytest -q && .venv/bin/ruff check . && .venv/bin/mypyPR expectations: tests for every behavioral change, all quality gates green, no credentials or receipt data committed. New Binance operations go into the allowlist in qualto/mcp/client.py with negative tests; new agent surfaces belong in skills/ and qualto/mcp/server.py with the same fail-closed gates. MIT license. Keep the invariant intact — if Binance can't prove it, the agent can't claim it.
Available Tools
5 toolsqualto_attest_claimC
Validate and place one claim-bound order, read it back by both IDs, and return PROVED, UNPROVED, PARTIAL, or PENDING.
Inputs: claim (required), confirm_live_write, cancel_after_attestation. Returns: object
qualto_cleanup_claimC
Resolve an orphan order by claim ID and cancel that exact order.
Inputs: claim (required), confirm_live_write. Returns: object
qualto_read_contextA
Read live price and quote balance context without placing an order.
Inputs: symbol. Returns: object
qualto_session_statusB
Read the current Qualto session state and write policy.
Inputs: no named parameters. Returns: object
qualto_verify_receiptsA
Re-read persisted claim attestations using read-only Binance calls.
Inputs: no named parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clear role: session state, market context, claim attestation, cleanup, and verification. There is slight overlap between the informational tools (session_status, read_context, verify_receipts), but descriptions make the boundaries clear.
Most tools follow a consistent qualto_<verb>_<noun> pattern with a uniform prefix. The exception is qualto_session_status, which uses a noun phrase rather than a verb, creating a minor inconsistency.
Five tools is well-scoped for a specialized attestation workflow. Each tool earns its place and the set is neither bloated nor too thin.
The tool set covers the core claim lifecycle: check session, read context, place/validate a claim, clean up orphans, and verify persisted receipts. A minor gap is the absence of a general order listing or detailed status history tool, but the core workflow is complete.
Related MCP Connectors
Trading MCP server for AI agents, with live market data, account reads and controlled execution.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server for Gainium — manage trading bots, deals, and balances via AI assistants
Pre-trade risk gating and verifiable decision evidence for AI trading agents. Oracle-backed price/safety checks across Base, Solana, Hyperliquid and BNB, plus signed receipts and portable evidence bundles for any agent action.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAgent-native, self-hosted MCP server for crypto trading and DeFi management. Enables agents to query balances, execute trades, and manage positions with a policy engine and secure key storage.8Apache 2.0
- AlicenseCqualityDmaintenanceOne MCP server that pairs Binance execution with ChainVector market intelligence. Connect it to any MCP client and the agent can read live signals, regime classification, probabilities and risk gauges from ChainVector, pick a strategy template, and execute the resulting decision on Binance.100MIT
- AlicenseBqualityCmaintenanceA Binance price-action and liquidity-focused MCP server for AI agents, offering 39 tools for market data, analysis, screening, alerts, and order execution with paper-first safety and optional real trading.39MIT

attestify-mcpofficial
AlicenseAqualityDmaintenanceMCP server exposing Attestify OS agents as callable tools, enabling governed AI agent runs for financial, compliance, and regulated workflows with immutable receipts and on-chain settlement.158 npmMIT