API & MCP docs

Every public surface of BoltProof: REST, MCP (agents), and A2A (agent-to-agent). Base URL: https://api.boltproof.dev. Auth: X-API-Key header.

Getting started

1. Sign up (email + password) — creates your account and returns a session and your first API key.
2. Call a check:

curl -X POST https://api.boltproof.dev/v1/check \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"rule":"refund_cap","inputs":{"charge_amount":100,"already_refunded":0,"is_duplicate":0,"refund_request":150}}'

REST endpoints

Endpoint	What it does
POST /v1/check	Run one rule. Body {rule, inputs, computation?}. Returns holds | violation | unknown with an explanation and counterexample.
POST /v1/scan	Run every approved rule against a flat {bundle}. Returns all violations + which rules held.
GET /v1/rules	Catalog of approved rules with typed inputs, guarantee, and incident source.
GET /v1/plans	Machine-readable plans: checks/month, overage, seats, features, price.
GET /v1/usage	Current usage vs plan cap for the caller's key.
GET /v1/account	Plan, key hint, usage, billing-portal URL.
POST /v1/check	Run one rule. Body {rule, inputs} → holds | violation | unknown with a counterexample.
POST /v1/scan	Run every approved rule against a flat {bundle}.
GET /v1/rules	Catalog of rules (id, invariant, status, inputs) — same source as MCP.
GET /v1/plans	Machine-readable plans: checks/month, overage, seats, price.
GET /v1/usage	Usage vs plan cap for the caller's key.
GET /v1/account	Plan and usage for the caller's key.
GET /health	Liveness and rule count.
GET /v1/status	Status and deprecation data.

Errors are explicit, never silent: 401 bad key, 402 plan limit reached, 404 unknown rule, 400 bad inputs.

MCP (connect your agent)

Give your agent the solver. Five tools; the rule set is also exposed as rules://<id> resources so agents can read definitions without spending a check. Auth is Authorization: Bearer <API key> (remote) or BOLTPROOF_API_KEY (local).

Remote (Streamable HTTP)

Claude Code / Cursor / any MCP client that supports HTTP:

{
  "mcpServers": {
    "boltproof": {
      "type": "http",
      "url": "https://api.boltproof.dev/mcp",
      "headers": { "Authorization": "Bearer $KEY" }
    }
  }
}

Claude Desktop (local stdio)

{
  "mcpServers": {
    "boltproof": {
      "command": "python3",
      "args": ["-m", "server.mcp_server"],
      "env": { "BOLTPROOF_API_KEY": "$KEY" }
    }
  }
}

Claude Code / CLI

claude mcp add boltproof --transport http https://api.boltproof.dev/mcp \
  --header "Authorization: Bearer $KEY"

MCP tool	Purpose
list_rules	Rule ids, guarantees, status. Free (no quota).
get_rule	One rule's invariant, parameters, sample counterexample. Free.
check_rule	Run one rule on inputs → proof or counterexample. Consumes a check.
explain_counterexample	Why inputs violate a rule (failing clause). Consumes a check.
get_account_status	Plan, used, cap, remaining. Free.

All tools are read-only and closed-world; they only run the deterministic solver. Results describe the encoded rule model — replay counterexamples against your real code.

A2A (agent-to-agent)

BoltProof is a discoverable A2A agent (protocol v1.0).

• Agent card: GET /.well-known/agent-card.json
• JSON-RPC endpoint: POST /a2a — methods SendMessage, SendStreamingMessage, GetTask, ListTasks, CancelTask, GetExtendedAgentCard.

curl -X POST https://api.boltproof.dev/a2a \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"SendMessage","params":{"message":{
    "messageId":"m1","role":"ROLE_USER",
    "parts":[{"data":{"rule":"refund_cap","inputs":{"charge_amount":100,"refund_request":150}}}]}}}'

Status, changelog, deprecation

• Status & deprecation — nothing deprecated at launch.
• Changelog — rules added, API changes.
• Deprecation policy: ≥ 90 days notice, Sunset header on affected endpoints, status on each rule in /v1/rules.

Feedback

Issues and requests: github.com/stevemegr/BoltProof/issues.