{
  "openapi": "3.1.0",
  "info": {
    "title": "BV-7X Bitcoin Signal Oracle API",
    "version": "1.0.0",
    "description": "Autonomous Bitcoin direction oracle with 60%+ verified accuracy, on-chain EAS attestations, daily Polymarket wagers, and ERC-8004 trustless agent identity. Predictions are attested on Base chain before outcomes are known.",
    "contact": {
      "name": "BV-7X",
      "url": "https://bv7x.ai"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://bv7x.ai",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/bv7x/openclaw/signal": {
      "get": {
        "operationId": "getSignal",
        "summary": "Get BTC signal (public — direction gated)",
        "description": "Returns market context and signal metadata. Direction is GATED for public access. Hold 500M+ BV7X or use Commerce API for full signal.",
        "parameters": [
          {
            "name": "horizon",
            "in": "query",
            "schema": { "type": "string", "enum": ["2d", "3d", "7d"], "default": "7d" },
            "description": "Prediction horizon"
          }
        ],
        "responses": {
          "200": {
            "description": "Signal response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SignalResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/bv7x/scorecard": {
      "get": {
        "operationId": "getScorecard",
        "summary": "Get prediction scorecard and track record",
        "description": "Public prediction history with accuracy stats, recent predictions, outcomes, and Polymarket comparison. Free and unauthenticated.",
        "parameters": [
          {
            "name": "horizon",
            "in": "query",
            "schema": { "type": "integer", "enum": [1, 2, 3, 7], "default": 7 },
            "description": "Horizon filter in days"
          }
        ],
        "responses": {
          "200": {
            "description": "Scorecard with predictions and stats",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScorecardResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/bv7x/onchain-oracle/latest": {
      "get": {
        "operationId": "getLatestAttestation",
        "summary": "Latest on-chain prediction attestation",
        "description": "Returns the most recent EAS attestation with IPFS metadata, attestation UID, and resolution status.",
        "responses": {
          "200": {
            "description": "Latest attestation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AttestationResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/bv7x/onchain-oracle/history": {
      "get": {
        "operationId": "getAttestationHistory",
        "summary": "Paginated attestation history",
        "description": "On-chain prediction attestation history with UIDs, outcomes, and gas costs.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 },
            "description": "Number of attestations to return"
          }
        ],
        "responses": {
          "200": {
            "description": "Attestation history",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Attestation" }
                    },
                    "count": { "type": "integer" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/bv7x/onchain-oracle/verify/{uid}": {
      "get": {
        "operationId": "verifyAttestation",
        "summary": "Verify an on-chain attestation by UID",
        "description": "Decode and verify a prediction or resolution attestation from Base chain EAS contract. Returns decoded schema data.",
        "parameters": [
          {
            "name": "uid",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{64}$" },
            "description": "EAS attestation UID"
          }
        ],
        "responses": {
          "200": {
            "description": "Decoded attestation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "data": {
                      "type": "object",
                      "properties": {
                        "uid": { "type": "string" },
                        "attester": { "type": "string" },
                        "schema": { "type": "string" },
                        "schemaVersion": { "type": "string" },
                        "decoded": { "type": "array" }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": { "description": "Attestation not found" }
        }
      }
    },
    "/api/bv7x/onchain-oracle/stats": {
      "get": {
        "operationId": "getAttestationStats",
        "summary": "Aggregate on-chain attestation statistics",
        "description": "Total published predictions, resolved outcomes, accuracy, and gas usage from on-chain attestation tracker.",
        "responses": {
          "200": {
            "description": "Attestation stats",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "data": {
                      "type": "object",
                      "properties": {
                        "totalPublished": { "type": "integer" },
                        "totalResolved": { "type": "integer" },
                        "totalGasWei": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/btc-price": {
      "get": {
        "operationId": "getBtcPrice",
        "summary": "Current BTC price and 24h change",
        "responses": {
          "200": {
            "description": "BTC price data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "price": { "type": "number" },
                    "change24h": { "type": "number" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/fear-greed": {
      "get": {
        "operationId": "getFearGreed",
        "summary": "Bitcoin Fear & Greed Index",
        "responses": {
          "200": {
            "description": "Fear & Greed data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "value": { "type": "integer", "minimum": 0, "maximum": 100 },
                    "classification": { "type": "string", "enum": ["Extreme Fear", "Fear", "Neutral", "Greed", "Extreme Greed"] }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/etf-flows": {
      "get": {
        "operationId": "getEtfFlows",
        "summary": "Bitcoin ETF flow data (7d and 30d)",
        "responses": {
          "200": {
            "description": "ETF flow data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "flow7d": { "type": "number" },
                    "flow30d": { "type": "number" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/bv7x/agent/identity": {
      "get": {
        "operationId": "getAgentIdentity",
        "summary": "ERC-8004 agent identity and registration",
        "description": "On-chain agent identity: agent ID, wallet, registry addresses, and agent card metadata.",
        "responses": {
          "200": {
            "description": "Agent identity",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "registered": { "type": "boolean" },
                    "agentId": { "type": "integer" },
                    "chain": { "type": "string" },
                    "wallet": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/bv7x/agent/reputation": {
      "get": {
        "operationId": "getAgentReputation",
        "summary": "ERC-8004 agent reputation score",
        "description": "On-chain reputation from ReputationRegistry: feedback count, average score, logged from Polymarket wager outcomes.",
        "responses": {
          "200": {
            "description": "Reputation summary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "registered": { "type": "boolean" },
                    "agentId": { "type": "integer" },
                    "reputation": {
                      "type": "object",
                      "properties": {
                        "totalFeedback": { "type": "integer" },
                        "averageScore": { "type": "number" }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/bv7x/commerce/offerings": {
      "get": {
        "operationId": "getCommerceOfferings",
        "summary": "List available commerce offerings",
        "description": "All purchasable intelligence products with USDC pricing on Base mainnet.",
        "responses": {
          "200": {
            "description": "Commerce offerings",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "offerings": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": { "type": "string" },
                          "description": { "type": "string" },
                          "priceDisplay": { "type": "string" },
                          "example": { "type": "string" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/bv7x/commerce/purchase": {
      "post": {
        "operationId": "purchaseOffering",
        "summary": "Purchase an intelligence offering with USDC",
        "description": "Submit a USDC payment transaction hash to purchase a BV-7X intelligence product. Verifies on-chain payment before delivering data.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["offering", "txHash", "wallet"],
                "properties": {
                  "offering": {
                    "type": "string",
                    "enum": ["bv7x_signal_with_proof", "bv7x_verified_track_record", "bv7x_analysis_report", "bv7x_crowd_vs_oracle", "bv7x_daily_macro_review", "bv7x_alpha_brief"]
                  },
                  "txHash": { "type": "string", "description": "USDC transfer tx hash on Base" },
                  "wallet": { "type": "string", "description": "Buyer wallet address" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Intelligence data delivered" },
          "400": { "description": "Invalid request or payment" },
          "402": { "description": "Payment required or insufficient" }
        }
      }
    },
    "/api/bv7x/a2a/tasks/send": {
      "post": {
        "operationId": "sendA2ATask",
        "summary": "Send an A2A task for execution",
        "description": "Create and execute a task using BV-7X skills. Supports predict_btc_direction, verify_prediction, get_track_record, get_market_context.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["skill"],
                "properties": {
                  "skill": {
                    "type": "string",
                    "enum": ["predict_btc_direction", "verify_prediction", "get_track_record", "get_market_context"]
                  },
                  "input": { "type": "object", "description": "Skill-specific input parameters" },
                  "metadata": { "type": "object", "description": "Optional metadata from requesting agent" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Task result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "jsonrpc": { "type": "string" },
                    "result": {
                      "type": "object",
                      "properties": {
                        "id": { "type": "string" },
                        "status": { "type": "string", "enum": ["completed", "failed"] },
                        "skill": { "type": "string" },
                        "result": { "type": "object" }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/bv7x/a2a/tasks/{id}": {
      "get": {
        "operationId": "getA2ATask",
        "summary": "Get A2A task status and result",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" }
          }
        ],
        "responses": {
          "200": { "description": "Task status and result" },
          "404": { "description": "Task not found" }
        }
      }
    },
    "/api/bv7x/oracle/verify": {
      "post": {
        "operationId": "verifyWallet",
        "summary": "Verify wallet for token-gated oracle access",
        "description": "Sign an EIP-191 message to prove BV7X token holdings. Returns a session token for subsequent oracle API calls. Requires 500M BV7X (basic) or 1B BV7X (premium).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["wallet", "signature", "timestamp"],
                "properties": {
                  "wallet": { "type": "string", "description": "Ethereum wallet address" },
                  "signature": { "type": "string", "description": "EIP-191 signature of access message" },
                  "timestamp": { "type": "integer", "description": "Unix timestamp (ms) — must be within 5 minutes" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session token issued",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "token": { "type": "string" },
                    "tier": { "type": "string", "enum": ["basic", "premium"] },
                    "expires_in": { "type": "integer" }
                  }
                }
              }
            }
          },
          "403": { "description": "Insufficient BV7X balance" }
        }
      }
    },
    "/api/bv7x/oracle": {
      "get": {
        "operationId": "getOracleBasic",
        "summary": "Basic oracle signal (500M BV7X required)",
        "description": "Latest BTC direction prediction with confidence score. Requires Bearer token from /oracle/verify.",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          {
            "name": "horizon",
            "in": "query",
            "schema": { "type": "string", "enum": ["2d", "3d", "7d"], "default": "7d" }
          }
        ],
        "responses": {
          "200": {
            "description": "Signal data",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/OracleBasicResponse" }
              }
            }
          },
          "401": { "description": "Authentication required" }
        }
      }
    },
    "/api/bv7x/oracle/premium": {
      "get": {
        "operationId": "getOraclePremium",
        "summary": "Premium oracle signal (1B BV7X required)",
        "description": "Full signal breakdown with parsimonious model details, thresholds, regime, and prediction market data.",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          {
            "name": "horizon",
            "in": "query",
            "schema": { "type": "string", "enum": ["2d", "3d", "7d"], "default": "7d" }
          }
        ],
        "responses": {
          "200": { "description": "Premium signal data" },
          "401": { "description": "Authentication required" },
          "403": { "description": "Premium tier required (1B BV7X)" }
        }
      }
    },
    "/api/bv7x/copy-trade/next": {
      "get": {
        "operationId": "getCopyTradeNext",
        "summary": "Next trade intent for agent replication (1B BV7X)",
        "description": "Returns structured trade intent with direction, confidence, Kelly sizing, and Polymarket token IDs. Designed for autonomous agent copy-trading.",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          {
            "name": "horizon",
            "in": "query",
            "schema": { "type": "string", "enum": ["2d", "3d", "7d"], "default": "7d" }
          }
        ],
        "responses": {
          "200": { "description": "Trade intent (or null if HOLD)" },
          "401": { "description": "Authentication required (1B BV7X)" },
          "403": { "description": "Premium tier required" }
        }
      }
    },
    "/api/bv7x/copy-trade/history": {
      "get": {
        "operationId": "getCopyTradeHistory",
        "summary": "Recent trade intents with outcomes (1B BV7X)",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 30, "maximum": 90 } }
        ],
        "responses": {
          "200": { "description": "Array of historical trade intents" },
          "401": { "description": "Authentication required" }
        }
      }
    },
    "/api/bv7x/copy-trade/status": {
      "get": {
        "operationId": "getCopyTradeStatus",
        "summary": "Copy-trade service status and push channel info (public)",
        "responses": {
          "200": { "description": "Service status with WebSocket and webhook details" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Session token from POST /api/bv7x/oracle/verify (requires 500M+ BV7X)"
      }
    },
    "schemas": {
      "SignalResponse": {
        "type": "object",
        "properties": {
          "signal": { "type": "string", "enum": ["BUY", "SELL", "HOLD", "GATED"], "description": "Signal direction (GATED for public)" },
          "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
          "timestamp": { "type": "string", "format": "date-time" },
          "btcPrice": { "type": "number" },
          "fearGreed": { "type": "integer" },
          "regime": { "type": "string" },
          "model_version": { "type": "string" }
        }
      },
      "ScorecardResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "summary": {
            "type": "object",
            "properties": {
              "totalPredictions": { "type": "integer" },
              "resolved": { "type": "integer" },
              "wins": { "type": "integer" },
              "losses": { "type": "integer" },
              "accuracy": { "type": "number" },
              "dedupedTotal": { "type": "integer" },
              "dedupedAccuracy": { "type": "number" },
              "streak": {
                "type": "object",
                "properties": {
                  "count": { "type": "integer" },
                  "type": { "type": "string", "enum": ["WIN", "LOSS"] }
                }
              }
            }
          },
          "predictions": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Prediction" }
          }
        }
      },
      "Prediction": {
        "type": "object",
        "properties": {
          "date": { "type": "string" },
          "direction": { "type": "string", "enum": ["UP", "DOWN"] },
          "confidence": { "type": "number" },
          "btcPrice": { "type": "number" },
          "status": { "type": "string", "enum": ["WIN", "LOSS", "HOLD", "PENDING"] },
          "outcome": {
            "type": "object",
            "nullable": true,
            "properties": {
              "actualReturn": { "type": "number" },
              "actualDirection": { "type": "string" },
              "correct": { "type": "boolean" }
            }
          }
        }
      },
      "Attestation": {
        "type": "object",
        "properties": {
          "date": { "type": "string" },
          "predictionId": { "type": "string" },
          "uid": { "type": "string" },
          "txHash": { "type": "string" },
          "cid": { "type": "string" },
          "direction": { "type": "string" },
          "confidence": { "type": "number" },
          "btcPrice": { "type": "number" },
          "resolved": { "type": "boolean" },
          "correct": { "type": "boolean" },
          "resolutionPrice": { "type": "number" },
          "returnBps": { "type": "integer" }
        }
      },
      "AttestationResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "data": { "$ref": "#/components/schemas/Attestation" }
        }
      },
      "OracleBasicResponse": {
        "type": "object",
        "properties": {
          "signal": { "type": "string", "enum": ["BUY", "SELL", "HOLD"] },
          "confidence": { "type": "number" },
          "timestamp": { "type": "string", "format": "date-time" },
          "accuracy_7d": { "type": "number", "nullable": true },
          "model_version": { "type": "string" },
          "horizon": { "type": "string" },
          "access": {
            "type": "object",
            "properties": {
              "tier": { "type": "string" },
              "wallet": { "type": "string" },
              "requirement": { "type": "string" }
            }
          }
        }
      }
    }
  },
  "externalDocs": {
    "description": "BV-7X Agent Card (ERC-8004)",
    "url": "https://bv7x.ai/.well-known/agent-card.json"
  },
  "x-bv7x-extensions": {
    "websocket": {
      "url": "wss://bv7x.ai/ws/signal",
      "description": "Real-time signal events via WebSocket",
      "events": ["signal.new", "signal.resolved", "wager.placed", "wager.settled", "attestation.created", "regime.changed"]
    },
    "regime_api": {
      "current": "GET /api/bv7x/regime",
      "history": "GET /api/bv7x/regime/history",
      "description": "Market regime classification — 7 regimes with per-regime thresholds"
    },
    "webhooks": {
      "register": "POST /api/bv7x/webhooks/register",
      "list": "GET /api/bv7x/webhooks",
      "remove": "DELETE /api/bv7x/webhooks/{id}",
      "description": "Push events to registered callback URLs with HMAC-SHA256 signatures"
    }
  }
}