{
  "openapi": "3.0.0",
  "info": {
    "title": "BlockWire API",
    "version": "1.0.0",
    "description": "Real-time blockchain event infrastructure for AI agents on Base. Services: (1) Event Monitoring - new contracts, liquidity events, price movements, large transfers, NFT mints; (2) Data Access - webhook push delivery, feed API ($0.002/request), replay API ($0.005/request), status API (free), subscribe API; (3) Verification - on-chain attestations, hash chain verification (free), attestation history (free), HMAC webhook signatures.",
    "contact": {
      "email": "support@echorift.xyz"
    }
  },
  "servers": [
    {
      "url": "https://blockwire.echorift.xyz",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/feed": {
      "get": {
        "summary": "Get recent blockchain events",
        "description": "Returns recent blockchain events. Requires x402 payment ($0.002 per request).",
        "operationId": "getFeed",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000,
              "default": 50
            },
            "description": "Maximum number of events to return"
          },
          {
            "name": "types",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated event types (contracts, liquidity, prices, transfers, nfts)"
          },
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Unix timestamp to filter events"
          }
        ],
        "responses": {
          "200": {
            "description": "Events retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeedResponse"
                }
              }
            }
          },
          "402": {
            "description": "Payment required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequired"
                }
              }
            }
          }
        }
      }
    },
    "/api/replay": {
      "get": {
        "summary": "Replay historical events",
        "description": "Retrieve historical events for a block range with attestation proofs. Requires x402 payment ($0.005 per request).",
        "operationId": "replay",
        "parameters": [
          {
            "name": "from_block",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "Starting block number"
          },
          {
            "name": "to_block",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "Ending block number"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 100
            },
            "description": "Maximum number of events"
          }
        ],
        "responses": {
          "200": {
            "description": "Events retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReplayResponse"
                }
              }
            }
          },
          "402": {
            "description": "Payment required"
          }
        }
      }
    },
    "/api/subscribe": {
      "get": {
        "summary": "Get subscription information",
        "description": "Returns subscription pricing and configuration",
        "operationId": "getSubscribeInfo",
        "responses": {
          "200": {
            "description": "Subscription information",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscribeInfo"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Subscribe to webhooks",
        "description": "Generate transaction data for on-chain subscription. Client must submit transaction.",
        "operationId": "subscribe",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubscribeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Transaction data generated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscribeResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/status": {
      "get": {
        "summary": "Get system status",
        "description": "Returns system health and metrics (free)",
        "operationId": "getStatus",
        "responses": {
          "200": {
            "description": "Status information",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatusResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/attestations": {
      "get": {
        "summary": "Get attestation history",
        "description": "Returns on-chain attestation history (free)",
        "operationId": "getAttestations",
        "parameters": [
          {
            "name": "from_block",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "to_block",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Attestations retrieved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AttestationResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/attestations/verify": {
      "get": {
        "summary": "Verify an attestation",
        "description": "Verify a batch hash against on-chain attestations (free)",
        "operationId": "verifyAttestation",
        "parameters": [
          {
            "name": "batch_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from_block",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "to_block",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Verification result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerificationResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BlockWireEvent": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": ["new_contract", "liquidity_added", "liquidity_removed", "price_movement", "large_transfer", "nft_mint"]
          },
          "address": {
            "type": "string"
          },
          "block": {
            "type": "integer"
          },
          "txHash": {
            "type": "string"
          },
          "timestamp": {
            "type": "integer"
          },
          "data": {
            "type": "object"
          }
        }
      },
      "FeedResponse": {
        "type": "object",
        "properties": {
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BlockWireEvent"
            }
          },
          "batchId": {
            "type": "string"
          },
          "blockRange": {
            "type": "object",
            "properties": {
              "start": {
                "type": "integer"
              },
              "end": {
                "type": "integer"
              }
            }
          },
          "count": {
            "type": "integer"
          }
        }
      },
      "ReplayResponse": {
        "type": "object",
        "properties": {
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BlockWireEvent"
            }
          },
          "blockRange": {
            "type": "object"
          },
          "count": {
            "type": "integer"
          },
          "attestationProof": {
            "type": "object"
          }
        }
      },
      "StatusResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": ["operational", "degraded", "down"]
          },
          "lastPoll": {
            "type": "integer",
            "nullable": true
          },
          "lastProcessedBlock": {
            "type": "integer",
            "nullable": true
          },
          "activeSubscribers": {
            "type": "integer"
          }
        }
      },
      "AttestationResponse": {
        "type": "object",
        "properties": {
          "attestations": {
            "type": "array"
          },
          "count": {
            "type": "integer"
          }
        }
      },
      "VerificationResponse": {
        "type": "object",
        "properties": {
          "verified": {
            "type": "boolean"
          },
          "batchId": {
            "type": "string"
          },
          "computedHash": {
            "type": "string"
          },
          "onChain": {
            "type": "object"
          }
        }
      },
      "SubscribeRequest": {
        "type": "object",
        "required": ["webhookUrl", "eventTypes", "hours", "signature", "signer"],
        "properties": {
          "webhookUrl": {
            "type": "string",
            "format": "uri"
          },
          "eventTypes": {
            "oneOf": [
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              {
                "type": "integer"
              }
            ]
          },
          "hours": {
            "type": "integer",
            "minimum": 1,
            "maximum": 8760
          },
          "signature": {
            "type": "string"
          },
          "signer": {
            "type": "string"
          }
        }
      },
      "SubscribeResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "transaction": {
            "type": "object",
            "properties": {
              "to": {
                "type": "string"
              },
              "data": {
                "type": "string"
              }
            }
          },
          "estimatedCost": {
            "type": "object"
          }
        }
      },
      "SubscribeInfo": {
        "type": "object",
        "properties": {
          "registryAddress": {
            "type": "string"
          },
          "hourlyRateWei": {
            "type": "string"
          },
          "paymentToken": {
            "type": "string"
          },
          "eventTypes": {
            "type": "object"
          }
        }
      },
      "PaymentRequired": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "payment": {
            "type": "object"
          }
        }
      }
    }
  }
}