{
  "openapi": "3.1.0",
  "info": {
    "title": "GateProxy Balance API",
    "version": "1.0",
    "description": "Check a proxy sub-user's remaining data, straight from each provider. Separate from the ordering API but uses the SAME key (`gpk_live_...`, or `gpk_test_...` for simulated sandbox data). Read-only; never changes orders or balances. Results cached ~60s.\n\nDocs: https://docs.gateproxy.store",
    "contact": {"name": "GateProxy Support", "url": "https://t.me/gateproxybot_support"}
  },
  "servers": [{"url": "https://balance.gateproxy.store/v1"}],
  "security": [{"bearerAuth": []}],
  "components": {
    "securitySchemes": {
      "bearerAuth": {"type": "http", "scheme": "bearer", "description": "Same API key as the ordering API. Test key returns simulated usage."}
    },
    "schemas": {
      "Usage": {
        "type": "object",
        "properties": {
          "product": {"type": "string", "example": "dataimpulse"},
          "name": {"type": "string", "example": "DataImpulse Proxy"},
          "username": {"type": "string", "example": "abc123_cr.ye"},
          "status": {"type": "string", "example": "active"},
          "total": {"type": ["string", "null"], "example": "1GB"},
          "used": {"type": "string", "example": "87.16MB"},
          "remaining": {"type": "string", "example": "936.84MB"},
          "unlimited": {"type": "boolean"},
          "checked_at": {"type": "string", "format": "date-time"},
          "sandbox": {"type": "boolean"}
        }
      },
      "Error": {
        "type": "object",
        "properties": {"error": {"type": "object", "properties": {"code": {"type": "string"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}
      }
    }
  },
  "paths": {
    "/health": {"get": {"summary": "Health check", "security": [], "responses": {"200": {"description": "OK"}}}},
    "/products": {
      "get": {"summary": "Products that support a usage check", "responses": {"200": {"description": "Products", "content": {"application/json": {"schema": {"type": "object", "properties": {"products": {"type": "array", "items": {"type": "object", "properties": {"id": {"type": "string"}, "name": {"type": "string"}}}}}}}}}}}
    },
    "/usage": {
      "get": {
        "summary": "Check a sub-user's remaining data",
        "parameters": [
          {"name": "product", "in": "query", "required": true, "schema": {"type": "string", "enum": ["dataimpulse", "mesh", "9proxy", "nodemaven", "abc", "kafka"]}},
          {"name": "username", "in": "query", "required": true, "schema": {"type": "string"}, "example": "abc123_cr.ye"}
        ],
        "responses": {
          "200": {"description": "Usage", "content": {"application/json": {"schema": {"type": "object", "properties": {"usage": {"$ref": "#/components/schemas/Usage"}, "cached": {"type": "boolean"}}}}}},
          "400": {"description": "Missing product or username"},
          "401": {"description": "Unauthorized"},
          "404": {"description": "Unknown product or sub-user not found"},
          "409": {"description": "Ambiguous username — send the exact login"},
          "429": {"description": "Rate limited"},
          "502": {"description": "Provider API unreachable"}
        }
      },
      "post": {
        "summary": "Check a sub-user's remaining data (JSON body)",
        "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["product", "username"], "properties": {"product": {"type": "string", "example": "mesh"}, "username": {"type": "string", "example": "meshproxyabc123"}}}}}},
        "responses": {"200": {"description": "Usage"}, "400": {"description": "Missing fields"}, "404": {"description": "Not found"}}
      }
    }
  }
}