{
  "openapi": "3.1.0",
  "info": {
    "title": "Butterfly Delta Pre-trade Integrity API",
    "version": "1.2.0",
    "description": "A $0.01 machine-paid exact-order pre-trade execution-integrity gate for autonomous crypto trading bots. Send the intended venue, side, size, order type, and thresholds immediately before an order. Butterfly Delta returns PASS, BLOCK, or UNKNOWN from live Coinbase and Gemini venue availability, spread, quote freshness, visible order-book depth, estimated slippage, and cross-venue divergence, plus source digests and a signed five-minute expiry. It accepts x402 or MPP on Base and never executes trades.",
    "contact": {
      "name": "Butterfly Delta",
      "email": "butterflydelta.com@gmail.com",
      "url": "https://butterflydelta.com/"
    },
    "x-guidance": "Call cryptoTradingBotExactOrderDepthSlippagePreflight with the exact venue, side, size, order type, limit price when applicable, and thresholds immediately before each order submission. Submit only under the caller's own policy when executionGate.state is PASS; fail closed on BLOCK or UNKNOWN."
  },
  "servers": [
    { "url": "https://butterflydelta.com" }
  ],
  "paths": {
    "/api/agent/order-preflight": {
      "post": {
        "operationId": "cryptoTradingBotExactOrderDepthSlippagePreflight",
        "summary": "Check exact-order depth and slippage before submitting a Coinbase or Gemini crypto order",
        "description": "Call after createOrder and immediately before submitOrder. Each x402- or MPP-protected call costs $0.01 USDC on Base. Send trade.pair, venue, side, baseSize, optional orderType and limitPrice, plus risk thresholds. executionGate returns signed PASS, BLOCK, or UNKNOWN from live Coinbase Exchange and Gemini venue, spread, freshness, order-book depth, estimated slippage, and divergence observations. Re-run before every successive order; missing required measurements return UNKNOWN and fail closed.",
        "tags": ["Trading", "Execution integrity", "x402", "MPP"],
        "x-payment-info": {
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.01" },
          "protocols": [
            { "x402": {} },
            { "mpp": { "method": "evm", "intent": "charge", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } }
          ]
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/PreflightRequest" },
              "examples": {
                "exactMarketOrder": {
                  "value": {
                    "trade": {
                      "pair": "BTC-USD",
                      "venue": "coinbase",
                      "side": "buy",
                      "orderType": "market",
                      "baseSize": 0.25,
                      "maxEstimatedSlippageBps": 25,
                      "minDepthCoveragePct": 100,
                      "maxVenueSpreadBps": 10,
                      "maxCrossVenueDivergenceBps": 20,
                      "maxQuoteAgeSeconds": 10,
                      "minHealthyVenues": 2
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Signed assumption-state preflight",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PreflightResponse" }
              }
            }
          },
          "400": { "description": "Invalid action or assumptions" },
          "402": { "description": "x402 or MPP payment required" },
          "503": { "description": "Payment rail or attestation signer temporarily unavailable" }
        }
      }
    }
  },
  "components": {
    "requestBodies": {
      "PreflightRequest": {
        "required": true,
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/PreflightRequest" },
            "examples": {
              "tradePreflight": {
                "value": {
                  "trade": {
                    "pair": "BTC-USD",
                    "maxVenueSpreadBps": 10,
                    "maxCrossVenueDivergenceBps": 20,
                    "maxQuoteAgeSeconds": 10,
                    "minHealthyVenues": 2,
                    "venue": "coinbase",
                    "side": "buy",
                    "orderType": "market",
                    "baseSize": 0.25,
                    "maxEstimatedSlippageBps": 25,
                    "minDepthCoveragePct": 100
                  }
                }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "PreflightRequest": {
        "type": "object",
        "required": ["trade"],
        "properties": {
          "trade": {
            "type": "object",
            "description": "Bot-native policy input expanded into explicit signed assertions.",
            "required": ["pair", "venue", "side", "baseSize"],
            "properties": {
              "pair": { "type": "string", "pattern": "^[A-Za-z0-9]{2,15}[-/_]USD$", "examples": ["BTC-USD", "ETH-USD", "SOL-USD"] },
              "maxVenueSpreadBps": { "type": "number", "minimum": 0, "maximum": 10000, "default": 10 },
              "maxCrossVenueDivergenceBps": { "type": "number", "minimum": 0, "maximum": 10000, "default": 20 },
              "maxQuoteAgeSeconds": { "type": "number", "minimum": 0, "maximum": 3600, "default": 10 },
              "minHealthyVenues": { "type": "number", "minimum": 1, "maximum": 2, "default": 2 },
              "venue": { "type": "string", "enum": ["coinbase", "gemini"], "description": "Execution venue for the exact order." },
              "side": { "type": "string", "enum": ["buy", "sell"] },
              "orderType": { "type": "string", "enum": ["market", "limit"], "default": "market" },
              "baseSize": { "type": "number", "exclusiveMinimum": 0, "description": "Exact base-asset size, for example 0.25 BTC." },
              "limitPrice": { "type": "number", "exclusiveMinimum": 0, "description": "Required for a limit order." },
              "maxEstimatedSlippageBps": { "type": "number", "minimum": 0, "maximum": 10000, "default": 25 },
              "minDepthCoveragePct": { "type": "number", "minimum": 0, "maximum": 100, "default": 100 },
              "summary": { "type": "string", "maxLength": 1000 },
              "deadline": { "type": "string", "maxLength": 120 }
            },
            "additionalProperties": false
          },
          "action": {
            "type": "object",
            "required": ["kind", "target"],
            "properties": {
              "kind": { "type": "string", "enum": ["trade", "purchase", "transfer", "deploy", "publish", "api_call", "execute", "other"] },
              "target": { "type": "string", "minLength": 2, "maxLength": 240 },
              "summary": { "type": "string", "maxLength": 1000 },
              "deadline": { "type": "string", "maxLength": 120 },
              "jurisdiction": { "type": "string", "maxLength": 120 },
              "stakes": {
                "type": "object",
                "properties": {
                  "value": { "type": "string", "maxLength": 80 },
                  "currency": { "type": "string", "maxLength": 32 },
                  "irreversible": { "type": "boolean" }
                },
                "additionalProperties": false
              },
              "execution": {
                "type": "object",
                "required": ["venue", "side", "baseSize"],
                "properties": {
                  "venue": { "type": "string", "enum": ["coinbase", "gemini"] },
                  "side": { "type": "string", "enum": ["buy", "sell"] },
                  "orderType": { "type": "string", "enum": ["market", "limit"], "default": "market" },
                  "baseSize": { "type": "number", "exclusiveMinimum": 0 },
                  "limitPrice": { "type": "number", "exclusiveMinimum": 0 },
                  "maxEstimatedSlippageBps": { "type": "number", "minimum": 0, "maximum": 10000, "default": 25 },
                  "minDepthCoveragePct": { "type": "number", "minimum": 0, "maximum": 100, "default": 100 }
                },
                "additionalProperties": false
              }
            },
            "additionalProperties": false
          },
          "assumptions": {
            "type": "array",
            "minItems": 1,
            "maxItems": 20,
            "items": {
              "type": "object",
              "required": ["statement"],
              "properties": {
                "id": { "type": "string", "maxLength": 64 },
                "statement": { "type": "string", "minLength": 8, "maxLength": 1000 },
                "assertion": {
                  "type": "object",
                  "required": ["metric", "operator", "value"],
                  "properties": {
                    "metric": {
                      "type": "string",
                      "enum": [
                        "market.coinbase.accepting_orders",
                        "market.coinbase.spread_bps",
                        "market.coinbase.last_trade_age_seconds",
                        "market.gemini.accepting_orders",
                        "market.gemini.spread_bps",
                        "market.coinbase.estimated_slippage_bps",
                        "market.coinbase.depth_coverage_pct",
                        "market.gemini.estimated_slippage_bps",
                        "market.gemini.depth_coverage_pct",
                        "market.cross_venue_mid_deviation_bps",
                        "market.source_count"
                      ]
                    },
                    "operator": { "type": "string", "enum": ["lt", "lte", "eq", "neq", "gte", "gt"] },
                    "value": { "type": ["string", "number", "boolean"] },
                    "unit": { "type": "string", "maxLength": 32 }
                  },
                  "additionalProperties": false
                }
              },
              "additionalProperties": false
            }
          },
          "checkpoint": { "type": "string", "maxLength": 160 }
        },
        "additionalProperties": false
      },
      "PreflightResponse": {
        "type": "object",
        "required": ["protocol", "capability", "action", "verdict", "coverage", "affectedAssumptions", "assumptionResults", "executionGate", "packets", "callerPolicy", "nextCheckpoint", "attestation", "payment"],
        "properties": {
          "protocol": { "const": "butterflydelta-preflight/1.0" },
          "capability": { "const": "delta_preflight" },
          "action": { "type": "object" },
          "verdict": {
            "type": "string",
            "enum": ["ASSUMPTION_PRESSURED", "ASSUMPTION_INVALIDATED", "NO_MATCH_IN_CURRENT_COVERAGE", "INSUFFICIENT_COVERAGE"]
          },
          "coverage": { "type": "object" },
          "affectedAssumptions": { "type": "array" },
          "assumptionResults": {
            "type": "array",
            "description": "Deterministic results for structured machine assertions. HOLDS applies only at the signed observation time and inside declared coverage.",
            "items": {
              "type": "object",
              "properties": {
                "id": { "type": "string" },
                "metric": { "type": "string" },
                "operator": { "type": "string" },
                "expected": {},
                "observed": {},
                "state": { "type": "string", "enum": ["HOLDS", "INVALIDATED", "UNKNOWN"] },
                "reason": { "type": "string" },
                "evidenceIds": { "type": "array", "items": { "type": "string" } }
              }
            }
          },
          "executionGate": {
            "type": "object",
            "required": ["state", "machineAction", "allRequiredAssertionsHold", "meaning"],
            "properties": {
              "state": { "type": "string", "enum": ["PASS", "BLOCK", "UNKNOWN"] },
              "machineAction": { "type": "string", "enum": ["PROCEED_UNDER_CALLER_POLICY", "DO_NOT_SUBMIT", "FAIL_CLOSED"] },
              "allRequiredAssertionsHold": { "type": "boolean" },
              "meaning": { "type": "string" }
            }
          },
          "packets": { "type": "array" },
          "callerPolicy": { "type": "object" },
          "nextCheckpoint": { "type": "string" },
          "attestation": {
            "type": "object",
            "required": ["payload", "canonicalPayload", "signature"],
            "properties": {
              "payload": {
                "type": "object",
                "required": ["scheme", "signer", "issuedAt", "expiresAt", "resultHash", "scope"],
                "properties": {
                  "scheme": { "const": "eip191" },
                  "signer": { "const": "0x29dd177F3D428b99a15Da00f50484A73339166AD" },
                  "issuedAt": { "type": "string", "format": "date-time" },
                  "expiresAt": { "type": "string", "format": "date-time" },
                  "resultHash": { "type": "string" },
                  "scope": { "type": "string" }
                }
              },
              "canonicalPayload": { "type": "string" },
              "signature": { "type": "string" }
            }
          },
          "payment": {
            "type": "object",
            "properties": {
              "protocol": { "type": "string", "enum": ["x402", "mpp"] },
              "settledByMiddleware": { "const": true }
            }
          }
        }
      }
    }
  }
}