{
  "openapi": "3.0.3",
  "info": {
    "title": "Handshake58 DRAIN Protocol API",
    "description": "API for discovering service providers and their pricing on the Handshake58 marketplace. Agents use this to find providers (LLM, scraping, image, VPN, etc.), get pricing, and integrate with the DRAIN micropayment protocol.",
    "version": "1.0.0",
    "contact": {
      "name": "Handshake58",
      "url": "https://handshake58.com",
      "email": "info@handshake58.com"
    }
  },
  "servers": [
    {
      "url": "https://handshake58.com",
      "description": "Production server"
    }
  ],
  "paths": {
    "/api/mcp/providers": {
      "get": {
        "operationId": "listProviders",
        "summary": "List service providers with models and pricing",
        "description": "Returns approved online providers with models and pricing. Filter by category or model to reduce response size. Response includes a _filters field describing all available query parameters.",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "description": "Filter by provider category",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["llm", "image", "audio", "video", "code", "multi-modal", "scraping", "search", "data", "scheduling", "network", "forecasting", "other"]
            }
          },
          {
            "name": "model",
            "in": "query",
            "description": "Filter by model name (partial match, case-insensitive). Example: gpt-4o",
            "required": false,
            "schema": { "type": "string" }
          },
          {
            "name": "tier",
            "in": "query",
            "description": "Filter by provider tier",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["bittensor", "community"]
            }
          },
          {
            "name": "minScore",
            "in": "query",
            "description": "Minimum Bittensor incentive score (0-1)",
            "required": false,
            "schema": { "type": "number", "minimum": 0, "maximum": 1 }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Max number of results (default and max: 200)",
            "required": false,
            "schema": { "type": "integer", "default": 200, "maximum": 200 }
          }
        ],
        "responses": {
          "200": {
            "description": "List of providers",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProvidersResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/validator/registry": {
      "get": {
        "operationId": "getValidatorRegistry",
        "summary": "Lightweight miner registry for validators",
        "description": "Returns all approved online miners with Bittensor fields (uid, hotkey), categories (main + sub), and model counts. No model pricing details. Cached for 5 minutes.",
        "responses": {
          "200": {
            "description": "Validator miner registry",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "version": { "type": "string" },
                    "updated": { "type": "string", "format": "date-time" },
                    "miners": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string" },
                          "name": { "type": "string" },
                          "tier": { "type": "string" },
                          "category": { "type": "string" },
                          "additionalCategories": { "type": "array", "items": { "type": "string" } },
                          "apiUrl": { "type": "string" },
                          "wallet": { "type": "string" },
                          "hotkey": { "type": "string", "nullable": true },
                          "uid": { "type": "integer", "nullable": true },
                          "score": { "type": "number" },
                          "online": { "type": "boolean" },
                          "inferenceOnline": { "type": "boolean" },
                          "latencyMs": { "type": "integer", "nullable": true },
                          "lastChecked": { "type": "string", "format": "date-time", "nullable": true },
                          "modelCount": { "type": "integer" }
                        }
                      }
                    },
                    "count": { "type": "integer" },
                    "onlineCount": { "type": "integer" },
                    "subnet": { "type": "integer" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/agent": {
      "get": {
        "operationId": "getAgentInfo",
        "summary": "Agent discovery endpoint",
        "description": "Quick discovery endpoint for AI agents. Returns essential information about the Handshake58 platform and how to get started.",
        "responses": {
          "200": {
            "description": "Agent discovery info",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentInfo"
                }
              }
            }
          }
        }
      }
    },
    "/api/directory/providers": {
      "get": {
        "operationId": "getDirectoryProviders",
        "summary": "Get directory providers",
        "description": "Returns the full list of providers in the directory with detailed information.",
        "responses": {
          "200": {
            "description": "Provider directory",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ProvidersResponse": {
        "type": "object",
        "properties": {
          "version": {
            "type": "string",
            "example": "1.0"
          },
          "count": {
            "type": "integer",
            "description": "Number of providers returned"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "providers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Provider"
            }
          },
          "_meta": {
            "$ref": "#/components/schemas/ProtocolMeta"
          }
        }
      },
      "Provider": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique provider ID"
          },
          "name": {
            "type": "string",
            "description": "Human-readable provider name",
            "example": "HS58-OpenAI"
          },
          "description": {
            "type": "string"
          },
          "apiUrl": {
            "type": "string",
            "format": "uri",
            "description": "Base URL for API requests"
          },
          "providerAddress": {
            "type": "string",
            "description": "Ethereum address for payment channel. Must be unique per Bittensor miner.",
            "example": "0xCCf2a94EcC6002b8Dd9d161ef15Bb4ABD5cD9E41"
          },
          "category": {
            "type": "string",
            "description": "Provider service category",
            "enum": ["llm", "image", "audio", "video", "code", "multi-modal", "scraping", "search", "data", "scheduling", "network", "forecasting", "other"],
            "example": "llm"
          },
          "chainId": {
            "type": "integer",
            "description": "Blockchain chain ID",
            "example": 137
          },
          "status": {
            "type": "object",
            "properties": {
              "online": {
                "type": "boolean"
              },
              "lastChecked": {
                "type": "string",
                "format": "date-time"
              },
              "latencyMs": {
                "type": "integer"
              }
            }
          },
          "models": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Model"
            }
          }
        }
      },
      "Model": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Model identifier for API requests",
            "example": "gpt-4o"
          },
          "name": {
            "type": "string"
          },
          "pricing": {
            "type": "object",
            "properties": {
              "inputPer1kTokens": {
                "type": "string",
                "description": "Cost per 1K input tokens in USDC",
                "example": "0.00375"
              },
              "outputPer1kTokens": {
                "type": "string",
                "description": "Cost per 1K output tokens in USDC",
                "example": "0.015"
              },
              "currency": {
                "type": "string",
                "example": "USDC"
              },
              "decimals": {
                "type": "integer",
                "example": 6
              }
            }
          }
        }
      },
      "ProtocolMeta": {
        "type": "object",
        "properties": {
          "protocol": {
            "type": "string",
            "example": "DRAIN"
          },
          "network": {
            "type": "string",
            "example": "polygon"
          },
          "contract": {
            "type": "string",
            "description": "DRAIN smart contract address",
            "example": "0x0C2B3aA1e80629D572b1f200e6DF3586B3946A8A"
          },
          "directoryUrl": {
            "type": "string",
            "format": "uri"
          },
          "marketplaceUrl": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "AgentInfo": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "Handshake58 DRAIN Protocol"
          },
          "purpose": {
            "type": "string"
          },
          "quick_start": {
            "type": "string",
            "description": "First step for agents"
          },
          "endpoints": {
            "type": "object",
            "properties": {
              "providers": {
                "type": "string"
              },
              "docs": {
                "type": "string"
              },
              "openapi": {
                "type": "string"
              }
            }
          },
          "contract": {
            "type": "string"
          },
          "sdk": {
            "type": "string"
          }
        }
      }
    }
  }
}