{ "openapi": "3.1.0", "info": { "title": "HOOKWATCH - Uniswap v4 hook intelligence", "version": "0.1.0", "description": "Uniswap v4 hook intelligence for Base. Paid endpoints use the x402 exact scheme with USDC. Reports are observations of public on-chain data and are NOT security audits.", "x-guidance": "Paid Uniswap v4 hook intelligence on Base (chain 8453). Pay per call in USDC over x402: GET /v1/v4/hook-check (0.10 USDC) validates a hook address and decodes its permission flags; POST /v1/v4/risk-report (0.50 USDC) returns an evidence-backed risk report for a hook or pool; GET /v1/v4/hook-delta (2.00 USDC) compares a hook's implementation against our observed history; POST /v1/v4/watch (5.00 USDC) records permission, implementation and configuration changes over a period. Every paid route answers an unpaid request with HTTP 402 and a PAYMENT-REQUIRED header (x402 v2). Send the signed payment in PAYMENT-SIGNATURE. GET /v1/sample/report is free and shows the report shape. Unknown facts are reported as UNKNOWN; these reports are not audits.", "contact": { "email": "bradleyswartz317@gmail.com" }, "license": { "name": "MIT" } }, "servers": [ { "url": "https://hookwatch.bradleyswartz317.workers.dev" } ], "tags": [ { "name": "paid" }, { "name": "free" } ], "paths": { "/v1/v4/hook-check": { "get": { "tags": [ "paid" ], "summary": "Quick check (hook address validation + permission decoding)", "operationId": "hookCheck", "parameters": [ { "name": "hook", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "example": "0x0469a4bd3724dc86c9542f4694c976da13c450c0" } }, { "name": "chain_id", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 8453, 84532 ], "example": 8453 } } ], "responses": { "200": { "description": "Observation", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Malformed request (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required (x402 challenge)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402Challenge" } } } } }, "x-x402": { "scheme": "exact", "network": "base", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0xaa6c0571879267B41DCD858f09FaD72D72CacD02", "priceUsdc": "0.10" }, "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.10" }, "protocols": [ { "x402": {} } ] } } }, "/v1/v4/risk-report": { "post": { "tags": [ "paid" ], "summary": "Evidence-backed risk report", "operationId": "riskReport", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "hook" ], "properties": { "hook": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "chain_id": { "type": "integer", "enum": [ 8453, 84532 ] }, "pool_key": { "$ref": "#/components/schemas/PoolKey" } } }, "example": { "hook": "0x0469a4bd3724dc86c9542f4694c976da13c450c0", "chain_id": 8453 } } } }, "responses": { "200": { "description": "Risk report", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Malformed request (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402Challenge" } } } } }, "x-x402": { "scheme": "exact", "network": "base", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0xaa6c0571879267B41DCD858f09FaD72D72CacD02", "priceUsdc": "0.50" }, "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.50" }, "protocols": [ { "x402": {} } ] } } }, "/v1/v4/hook-delta": { "get": { "tags": [ "paid" ], "summary": "Implementation change report (current state vs recorded history)", "operationId": "hookDelta", "parameters": [ { "name": "hook", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "example": "0x0469a4bd3724dc86c9542f4694c976da13c450c0" } }, { "name": "chain_id", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 8453, 84532 ], "example": 8453 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Delta report", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Malformed request (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402Challenge" } } } } }, "x-x402": { "scheme": "exact", "network": "base", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0xaa6c0571879267B41DCD858f09FaD72D72CacD02", "priceUsdc": "2.00" }, "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "2.00" }, "protocols": [ { "x402": {} } ] } } }, "/v1/v4/watch": { "post": { "tags": [ "paid" ], "summary": "Register seven-day monitoring", "operationId": "watch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "hook" ], "properties": { "hook": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "chain_id": { "type": "integer", "enum": [ 8453, 84532 ] }, "pool_key": { "$ref": "#/components/schemas/PoolKey" }, "pool_id": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "days": { "type": "integer", "minimum": 1, "maximum": 90, "default": 7 }, "customer_wallet": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } }, "example": { "hook": "0x0469a4bd3724dc86c9542f4694c976da13c450c0", "chain_id": 8453, "days": 7 } } } }, "responses": { "200": { "description": "Watch registered", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Malformed request (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402Challenge" } } } } }, "x-x402": { "scheme": "exact", "network": "base", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0xaa6c0571879267B41DCD858f09FaD72D72CacD02", "priceUsdc": "5.00" }, "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "5.00" }, "protocols": [ { "x402": {} } ] } } }, "/v1/sample/report": { "get": { "tags": [ "free" ], "security": [], "summary": "Free sample report (limited example dataset)", "operationId": "sampleReport", "responses": { "200": { "description": "Sample report", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/health": { "get": { "tags": [ "free" ], "security": [], "summary": "Liveness", "operationId": "health", "responses": { "200": { "description": "Healthy" } } } }, "/health/deep": { "get": { "tags": [ "free" ], "security": [], "summary": "Deep health (RPC + storage)", "operationId": "healthDeep", "responses": { "200": { "description": "Component status" } } } }, "/v1/stats": { "get": { "tags": [ "free" ], "security": [], "summary": "Revenue and usage dashboard data", "operationId": "stats", "responses": { "200": { "description": "Stats" } } } }, "/v1/changes": { "get": { "tags": [ "free" ], "security": [], "summary": "Recent observed hook changes (public feed)", "description": "The most recent changes we recorded while watching hooks, newest first. This is our observation history, not the entire life of any contract, and it is not a security audit.", "operationId": "changes", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "example": 50 } } ], "responses": { "200": { "description": "Recent changes" } } } }, "/v1/x402/resources": { "get": { "tags": [ "free" ], "security": [], "summary": "x402 resource listing (Bazaar-compatible)", "operationId": "x402Resources", "responses": { "200": { "description": "Resources" } } } } }, "components": { "schemas": { "PoolKey": { "type": "object", "required": [ "currency0", "currency1", "fee", "tickSpacing", "hooks" ], "properties": { "currency0": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "currency1": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "fee": { "type": "integer", "minimum": 0, "maximum": 16777215 }, "tickSpacing": { "type": "integer", "minimum": 1 }, "hooks": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } }, "Error": { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" }, "code": { "type": "string" }, "details": {}, "hint": { "type": "string" } } }, "X402Challenge": { "type": "object", "properties": { "x402Version": { "type": "integer", "const": 2 }, "error": { "type": "string" }, "accepts": { "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string", "const": "exact" }, "network": { "type": "string", "description": "CAIP-2, e.g. eip155:8453" }, "amount": { "type": "string" }, "maxAmountRequired": { "type": "string", "description": "v1 alias of amount" }, "resource": { "type": "string" }, "payTo": { "type": "string" }, "asset": { "type": "string" } } } } } } } } }