{
  "openapi": "3.1.0",
  "info": {
    "title": "Peerlytics API",
    "version": "1.0.0",
    "summary": "Analytics, explorer, orderbook, and market data for the ZKP2P peer-to-peer USDC/fiat protocol on Base.",
    "description": "The Peerlytics API provides programmatic access to ZKP2P protocol analytics, the full protocol explorer, the public orderbook, and market data. Responses use a `{ success, data }` envelope. List endpoints return a paginated object inside `data`. Designed for both human integrations and autonomous AI agents.\n\n**Authentication modes:**\n- **API key** — provision via `/account/keys`, pay in advance with credits.\n- **x402** — pay per request in USDC on Base, no account needed. Ideal for agents.\n\n**Pricing:** $0.001 per request for analytics and explorer endpoints (as of 2026-04-10).",
    "termsOfService": "https://peerlytics.xyz/help",
    "contact": {
      "name": "Peerlytics",
      "url": "https://peerlytics.xyz/developers"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://peerlytics.xyz"
    }
  },
  "servers": [
    {
      "url": "https://peerlytics.xyz/api/v1",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "Developer docs, SDKs, and quickstarts",
    "url": "https://peerlytics.xyz/developers"
  },
  "security": [{ "ApiKeyAuth": [] }, { "X402": [] }],
  "tags": [
    { "name": "analytics", "description": "Protocol-level analytics and aggregations." },
    {
      "name": "explorer",
      "description": "Lookup deposits, intents, addresses, makers, verifiers, and vaults."
    },
    {
      "name": "data",
      "description": "Raw deposits, intents, orderbook, activity, and market data feeds."
    },
    { "name": "meta", "description": "Platform and currency catalogs." },
    { "name": "history", "description": "Per-address maker and taker history." },
    { "name": "account", "description": "API key management, credit balance, and checkout." }
  ],
  "paths": {
    "/analytics/summary": {
      "get": {
        "tags": ["analytics"],
        "summary": "Top-line investor summary buckets",
        "description": "Returns pre-computed investor-facing analytics summary for the selected period.",
        "parameters": [{ "$ref": "#/components/parameters/Period" }],
        "responses": {
          "200": { "$ref": "#/components/responses/Envelope" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/analytics/overview": {
      "get": {
        "tags": ["analytics"],
        "summary": "Full investor-facing protocol diligence payload",
        "description": "Rich payload with volume, liquidity, maker/taker splits, currency and platform breakdowns. Accepts `mtd`, `3mtd`, `ytd`, `all`.",
        "parameters": [{ "$ref": "#/components/parameters/Period" }],
        "responses": {
          "200": { "$ref": "#/components/responses/Envelope" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/PaymentRequired" }
        }
      }
    },
    "/analytics/leaderboard": {
      "get": {
        "tags": ["analytics"],
        "summary": "Maker and taker leaderboards",
        "parameters": [
          { "$ref": "#/components/parameters/Period" },
          { "$ref": "#/components/parameters/Limit" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/Envelope" }
        }
      }
    },
    "/analytics/vaults": {
      "get": {
        "tags": ["analytics"],
        "summary": "Vault and rate-manager analytics",
        "description": "Aggregate statistics across all delegation vaults and rate managers, including TVL, volume, fees earned, and fill rate.",
        "responses": {
          "200": { "$ref": "#/components/responses/Envelope" }
        }
      }
    },
    "/explorer/search": {
      "get": {
        "tags": ["explorer"],
        "summary": "Universal search across addresses, intents, deposits, and transactions",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "description": "Address, intent hash, tx hash, ENS name, or deposit id."
          }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/Envelope" }
        }
      }
    },
    "/explorer/deposit/{id}": {
      "get": {
        "tags": ["explorer"],
        "summary": "Deposit details by id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Numeric deposit id (string-safe for large values)."
          }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/Envelope" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/explorer/intent/{hash}": {
      "get": {
        "tags": ["explorer"],
        "summary": "Intent details by hash",
        "parameters": [
          {
            "name": "hash",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{64}$" }
          }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/Envelope" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/explorer/address/{address}": {
      "get": {
        "tags": ["explorer"],
        "summary": "Address profile: combined maker + taker activity",
        "parameters": [{ "$ref": "#/components/parameters/AddressPath" }],
        "responses": {
          "200": { "$ref": "#/components/responses/Envelope" }
        }
      }
    },
    "/explorer/maker/{address}": {
      "get": {
        "tags": ["explorer"],
        "summary": "Maker-specific portfolio and stats",
        "parameters": [{ "$ref": "#/components/parameters/AddressPath" }],
        "responses": {
          "200": { "$ref": "#/components/responses/Envelope" }
        }
      }
    },
    "/explorer/verifier/{address}": {
      "get": {
        "tags": ["explorer"],
        "summary": "Verifier statistics",
        "parameters": [{ "$ref": "#/components/parameters/AddressPath" }],
        "responses": {
          "200": { "$ref": "#/components/responses/Envelope" }
        }
      }
    },
    "/explorer/vault/{id}": {
      "get": {
        "tags": ["explorer"],
        "summary": "Delegation vault / rate-manager detail",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Rate-manager registry id (bytes32 hex)."
          }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/Envelope" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/deposits": {
      "get": {
        "tags": ["data"],
        "summary": "List deposits (paginated)",
        "description": "At least one of `depositor`, `delegate`, `platform`, or `currency` is required.",
        "parameters": [
          { "name": "depositor", "in": "query", "schema": { "type": "string" } },
          { "name": "delegate", "in": "query", "schema": { "type": "string" } },
          { "name": "platform", "in": "query", "schema": { "type": "string" } },
          { "name": "currency", "in": "query", "schema": { "type": "string" } },
          { "$ref": "#/components/parameters/Limit" },
          { "$ref": "#/components/parameters/Offset" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/PaginatedEnvelope" },
          "400": { "$ref": "#/components/responses/BadRequest" }
        }
      }
    },
    "/intents": {
      "get": {
        "tags": ["data"],
        "summary": "List intents (paginated)",
        "parameters": [
          { "name": "depositId", "in": "query", "schema": { "type": "string" } },
          {
            "name": "status",
            "in": "query",
            "schema": { "type": "string", "enum": ["SIGNALED", "FULFILLED", "CANCELLED"] }
          },
          { "$ref": "#/components/parameters/Limit" },
          { "$ref": "#/components/parameters/Offset" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/PaginatedEnvelope" }
        }
      }
    },
    "/orderbook": {
      "get": {
        "tags": ["data"],
        "summary": "Full peer-to-peer orderbook",
        "description": "Returns the canonical `OrderbookEntry` projection with all active deposits by platform, currency, and rate level. Falls back to legacy deposit aggregation during indexer rollout windows.",
        "parameters": [
          { "name": "platform", "in": "query", "schema": { "type": "string" } },
          { "name": "currency", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/Envelope" }
        }
      }
    },
    "/market/summary": {
      "get": {
        "tags": ["data"],
        "summary": "Market intel snapshot",
        "description": "Cross-market rate comparison, percentile rankings, and time-to-fill signals per platform/currency combination.",
        "responses": {
          "200": { "$ref": "#/components/responses/PaginatedEnvelope" }
        }
      }
    },
    "/activity": {
      "get": {
        "tags": ["data"],
        "summary": "Recent signaling and fulfillment events (paginated)",
        "parameters": [{ "$ref": "#/components/parameters/Limit" }],
        "responses": {
          "200": { "$ref": "#/components/responses/PaginatedEnvelope" }
        }
      }
    },
    "/activity/stream": {
      "get": {
        "tags": ["data"],
        "summary": "Server-sent event stream of live protocol activity",
        "responses": {
          "200": {
            "description": "text/event-stream of signaling, fulfillment, and deposit events",
            "content": {
              "text/event-stream": {}
            }
          }
        }
      }
    },
    "/meta/platforms": {
      "get": {
        "tags": ["meta"],
        "summary": "Supported payment platforms catalog",
        "responses": {
          "200": { "$ref": "#/components/responses/Envelope" }
        }
      }
    },
    "/meta/currencies": {
      "get": {
        "tags": ["meta"],
        "summary": "Supported currencies catalog",
        "responses": {
          "200": { "$ref": "#/components/responses/Envelope" }
        }
      }
    },
    "/makers/{address}/history": {
      "get": {
        "tags": ["history"],
        "summary": "Maker history: deposits and fills",
        "parameters": [
          { "$ref": "#/components/parameters/AddressPath" },
          { "$ref": "#/components/parameters/Limit" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/Envelope" }
        }
      }
    },
    "/takers/{address}/history": {
      "get": {
        "tags": ["history"],
        "summary": "Taker history: intents and purchases",
        "parameters": [
          { "$ref": "#/components/parameters/AddressPath" },
          { "$ref": "#/components/parameters/Limit" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/Envelope" }
        }
      }
    },
    "/account/keys": {
      "get": {
        "tags": ["account"],
        "summary": "List API keys for the authenticated account",
        "responses": {
          "200": { "$ref": "#/components/responses/Envelope" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/account/credits": {
      "get": {
        "tags": ["account"],
        "summary": "Current credit balance",
        "responses": {
          "200": { "$ref": "#/components/responses/Envelope" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/account/checkout": {
      "post": {
        "tags": ["account"],
        "summary": "Create a credit top-up checkout session",
        "responses": {
          "200": { "$ref": "#/components/responses/Envelope" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "Period": {
        "name": "period",
        "in": "query",
        "schema": {
          "type": "string",
          "enum": ["mtd", "3mtd", "ytd", "all"]
        },
        "description": "Investor-facing period bucket."
      },
      "Limit": {
        "name": "limit",
        "in": "query",
        "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }
      },
      "Offset": {
        "name": "offset",
        "in": "query",
        "schema": { "type": "integer", "minimum": 0, "default": 0 }
      },
      "AddressPath": {
        "name": "address",
        "in": "path",
        "required": true,
        "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" },
        "description": "EVM address (hex)."
      }
    },
    "responses": {
      "Envelope": {
        "description": "Successful response with data envelope",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": ["success", "data"],
              "properties": {
                "success": { "type": "boolean", "const": true },
                "data": { "type": "object" }
              }
            }
          }
        }
      },
      "PaginatedEnvelope": {
        "description": "Paginated list response",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": ["success", "data"],
              "properties": {
                "success": { "type": "boolean", "const": true },
                "data": {
                  "type": "object",
                  "properties": {
                    "items": { "type": "array", "items": { "type": "object" } },
                    "total": { "type": "integer" },
                    "limit": { "type": "integer" },
                    "offset": { "type": "integer" }
                  }
                }
              }
            }
          }
        }
      },
      "BadRequest": { "$ref": "#/components/responses/ErrorResponse" },
      "Unauthorized": { "$ref": "#/components/responses/ErrorResponse" },
      "PaymentRequired": {
        "description": "No API key credits and no x402 payment provided. Retry with an API key or a valid x402 proof.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "NotFound": { "$ref": "#/components/responses/ErrorResponse" },
      "ErrorResponse": {
        "description": "Error response",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["success", "error"],
        "properties": {
          "success": { "type": "boolean", "const": false },
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": { "type": "string" },
              "message": { "type": "string" }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Provision keys at https://peerlytics.xyz/developers. Pay in advance with credits."
      },
      "X402": {
        "type": "http",
        "scheme": "x402",
        "description": "Pay per request in USDC on Base via the x402 protocol. No account required. See https://peerlytics.xyz/agents for agent integration guides."
      }
    }
  }
}