{
  "openapi": "3.1.0",
  "info": {
    "title": "Alkimi Community Data API",
    "version": "1.0.0",
    "description": "Public API for aggregated Alkimi Ad Platform statistics: daily transaction counts, ad impression counts, and protocol revenue. No authentication required; rate-limited per client.",
    "contact": {
      "url": "https://docs.alkimi.org/docs/resources/community-data-api"
    }
  },
  "servers": [{ "url": "https://api.alkimi.org" }],
  "paths": {
    "/api/v1/public/data": {
      "get": {
        "operationId": "getData",
        "summary": "Get aggregated community statistics",
        "description": "Returns daily aggregated Alkimi Ad Platform statistics (transactions, impressions, revenue in USD and tokens) for an inclusive date range. Maximum range is 31 days and endDate must not precede startDate. Rate limits are reported via X-RateLimit-Remaining, X-RateLimit-Reset, and X-Daily-Quota-Remaining response headers.",
        "parameters": [
          {
            "name": "startDate",
            "in": "query",
            "required": true,
            "description": "Start date of the requested period, YYYY-MM-DD.",
            "schema": { "type": "string", "format": "date" }
          },
          {
            "name": "endDate",
            "in": "query",
            "required": true,
            "description": "End date of the requested period, YYYY-MM-DD. At most 31 days after startDate.",
            "schema": { "type": "string", "format": "date" }
          }
        ],
        "responses": {
          "200": {
            "description": "Daily statistics for the requested range.",
            "headers": {
              "X-RateLimit-Remaining": {
                "description": "Requests remaining in the current window.",
                "schema": { "type": "integer" }
              },
              "X-RateLimit-Reset": {
                "description": "Unix timestamp when the window resets.",
                "schema": { "type": "integer" }
              },
              "X-Daily-Quota-Remaining": {
                "description": "Requests remaining today.",
                "schema": { "type": "integer" }
              }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/DataResponse" }
              }
            }
          },
          "400": {
            "description": "Invalid or missing parameters (bad date format, range over 31 days, endDate before startDate).",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Rate limit or daily quota exceeded.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "DataResponse": {
        "type": "object",
        "required": ["status", "data"],
        "properties": {
          "status": {
            "type": "string",
            "description": "\"Success\" on success."
          },
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/DailyStat" }
          }
        }
      },
      "DailyStat": {
        "type": "object",
        "required": ["date", "txnCount", "imprCount"],
        "properties": {
          "date": {
            "type": "string",
            "format": "date",
            "description": "Day the row aggregates, YYYY-MM-DD."
          },
          "txnCount": {
            "type": "integer",
            "description": "Number of on-chain transactions."
          },
          "imprCount": {
            "type": "integer",
            "description": "Number of ad impressions."
          },
          "alkimiRevenueInUSD": {
            "type": "string",
            "description": "Protocol revenue in USD, decimal string."
          },
          "alkimiRevenueInTokens": {
            "type": "string",
            "description": "Protocol revenue in ALKIMI tokens, decimal string; the literal string \"null\" when unavailable."
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable code, e.g. ERR_INVALID_REQUEST_PARAMETER."
              },
              "message": {
                "type": "string",
                "description": "Human-readable summary."
              },
              "details": {
                "type": "object",
                "description": "Field-level validation errors when applicable.",
                "properties": {
                  "errors": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "field": { "type": "string" },
                        "message": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}