{
  "openapi": "3.1.0",
  "info": {
    "title": "Clawy AI Gateway",
    "version": "1.1.0",
    "description": "Clawy gateway v1.1.0 — pay-per-call AI inference via x402 v2 on Base mainnet. GPT-5.5 (OpenAI) and Claude Opus 4.8 (Anthropic) served via direct billing APIs, settled in USDC. No API keys, no signup, no subscriptions. AI agents pay per request; humans can too.",
    "x-guidance": "Three POST endpoints under /v1/chat/* return OpenAI-shaped chat.completion responses. To call any paid endpoint: (1) send POST without payment → server returns 402 with the PAYMENT-REQUIRED response header (base64 JSON with network, asset, amount, payTo — Base mainnet and Solana mainnet are both advertised when SOLANA_ENABLED=1); (2) sign the payment for your chosen network (EIP-3009 transferWithAuthorization on Base, or a Solana transaction on Solana); (3) retry with the signed payload in the X-PAYMENT header. All endpoints accept OpenAI-style messages arrays. Response x_clawy.provider always tells the truth about which backend served the request.",
    "contact": {
      "name": "Clawy AI Gateway",
      "url": "https://clawy.uk"
    },
    "x-logo": {
      "url": "https://clawy.uk/logo.png"
    },
    "x-legal": {
      "imprint": "https://clawy.uk/impressum.html",
      "privacy": "https://clawy.uk/datenschutz.html",
      "terms": "https://clawy.uk/agb.html",
      "withdrawal": "https://clawy.uk/widerruf.html"
    }
  },
  "servers": [
    {
      "url": "https://clawy.uk",
      "description": "Production"
    }
  ],
  "x-discovery": {
    "ownershipProofs": []
  },
  "tags": [
    {
      "name": "inference",
      "description": "Pay-per-call LLM inference via x402 micropayments"
    },
    {
      "name": "health",
      "description": "Free health endpoint"
    }
  ],
  "paths": {
    "/v1/chat/chatgpt": {
      "post": {
        "tags": ["inference"],
        "summary": "GPT-5.5 (gpt-5.5) chat completion via OpenAI — $0.10 per call",
        "description": "OpenAI GPT-5.5 chat completion via the OpenAI API. Returns an OpenAI-shaped `chat.completion` object. Tells the truth about which provider served the request via the `x_clawy.provider` response field. Falls back to Anthropic Haiku if OpenAI returns an error.",
        "operationId": "chatChatgpt",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.100000"
          },
          "protocols": [
            { "x402": {} }
          ]
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ChatRequest" },
              "example": {
                "messages": [
                  { "role": "system", "content": "You are a helpful assistant." },
                  { "role": "user", "content": "Say hello in 5 words." }
                ],
                "max_tokens": 256
              }
            }
          }
        },
        "responses": {
          "402": { "description": "Payment Required. The `PAYMENT-REQUIRED` response header contains a base64-encoded JSON with x402 payment requirements (network, asset, amount, payTo)." },
          "200": {
            "description": "Successful chat completion (after payment verification).",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ChatCompletion" }
              }
            }
          }
        }
      }
    },
    "/v1/chat/opus": {
      "post": {
        "tags": ["inference"],
        "summary": "Claude Opus 4.8 chat completion — $0.15 per call",
        "description": "OpenAI-compatible Claude Opus chat completion. Returns an OpenAI-shaped `chat.completion` object. Tells the truth about which provider served the request via the `x_clawy.provider` response field.",
        "operationId": "chatOpus",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.150000"
          },
          "protocols": [
            { "x402": {} }
          ]
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ChatRequest" }
            }
          }
        },
        "responses": {
          "402": { "description": "Payment Required. The `PAYMENT-REQUIRED` response header contains a base64-encoded JSON with x402 payment requirements." },
          "200": {
            "description": "Successful chat completion (after payment).",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ChatCompletion" }
              }
            }
          }
        }
      }
    },
    "/v1/chat/auto": {
      "post": {
        "tags": ["inference"],
        "summary": "Cost-optimized auto tier — $0.04 per call",
        "description": "Cheapest reliable inference. Always honest in x_clawy.provider/delivery. No-loss guarantee at this price point.",
        "operationId": "chatAuto",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.040000"
          },
          "protocols": [
            { "x402": {} }
          ]
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ChatRequest" }
            }
          }
        },
        "responses": {
          "402": { "description": "Payment Required. The `PAYMENT-REQUIRED` response header contains a base64-encoded JSON with x402 payment requirements." },
          "200": {
            "description": "Successful chat completion (after payment).",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ChatCompletion" }
              }
            }
          }
        }
      }
    },
    "/v1/images/generate": {
      "post": {
        "tags": ["image-generation"],
        "summary": "AI image generation — $0.01 per call (promo, normal $0.05)",
        "description": "Generate images via MiniMax image-01. Single tier — no model selection exposed. Returns OpenAI-shape response with base64-encoded images.",
        "operationId": "imageGenerate",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.010000"
          },
          "protocols": [
            { "x402": {} }
          ]
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["prompt"],
                "properties": {
                  "prompt": { "type": "string", "minLength": 1, "maxLength": 4000, "description": "Text description of the desired image" },
                  "size": { "type": "string", "enum": ["1024x1024", "1024x1792", "1792x1024"], "default": "1024x1024" },
                  "n": { "type": "integer", "minimum": 1, "maximum": 4, "default": 1 }
                }
              }
            }
          }
        },
        "responses": {
          "402": { "description": "Payment Required." },
          "200": {
            "description": "Image generation result (after payment).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "created": { "type": "integer" },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "url": { "type": "string" },
                          "revised_prompt": { "type": "string" }
                        }
                      }
                    },
                    "x_clawy": {
                      "type": "object",
                      "properties": {
                        "provider": { "type": "string" },
                        "delivery": { "type": "string" },
                        "model": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "tags": ["health"],
        "summary": "Free health check — no payment required",
        "description": "Returns server status, configured providers, pricing, and any config warnings. Useful for monitoring and registration checks.",
        "operationId": "health",
        "responses": {
          "200": {
            "description": "Service is up.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean" },
                    "service": { "type": "string" },
                    "version": { "type": "string" },
                    "network": { "type": "string" },
                    "payTo": { "type": "string" },
                    "providers": { "type": "object" },
                    "pricing": { "type": "object" }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ChatRequest": {
        "type": "object",
        "required": ["messages"],
        "properties": {
          "messages": {
            "type": "array",
            "description": "OpenAI-style chat messages array.",
            "items": {
              "type": "object",
              "required": ["role", "content"],
              "properties": {
                "role": { "type": "string", "enum": ["system", "user", "assistant"] },
                "content": { "type": "string", "description": "Message content (1-200000 chars)" }
              }
            }
          },
          "model": { "type": "string", "description": "Optional model override" },
          "max_tokens": { "type": "integer", "description": "Optional token cap", "minimum": 1, "maximum": 16000 },
          "temperature": { "type": "number", "description": "Optional sampling temperature", "minimum": 0, "maximum": 2 },
          "fallback": { "type": "boolean", "description": "Allow fallback to the cost-optimized tier if the primary provider fails" }
        }
      },
      "ChatCompletion": {
        "type": "object",
        "required": ["id", "object", "model", "choices"],
        "properties": {
          "id": { "type": "string", "example": "chatcmpl-clawy-abc123" },
          "object": { "type": "string", "enum": ["chat.completion"] },
          "model": { "type": "string", "example": "gpt-5.5" },
          "choices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": { "type": "integer" },
                "message": {
                  "type": "object",
                  "properties": {
                    "role": { "type": "string", "enum": ["assistant"] },
                    "content": { "type": "string" }
                  }
                },
                "finish_reason": { "type": "string" }
              }
            }
          },
          "usage": {
            "type": "object",
            "properties": {
              "prompt_tokens": { "type": "integer" },
              "completion_tokens": { "type": "integer" },
              "total_tokens": { "type": "integer" }
            }
          },
          "x_clawy": {
            "type": "object",
            "description": "Clawy extension: tells the truth about which provider served the request.",
            "properties": {
              "provider": { "type": "string", "description": "Logical provider label: openai, anthropic, or auto" },
              "delivery": { "type": "string", "example": "codex-cli" }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "x402": {
        "type": "apiKey",
        "in": "header",
        "name": "X-PAYMENT",
        "description": "x402 micropayment. Send a base64-encoded signed payment payload in the `X-PAYMENT` header. The 402 response's `PAYMENT-REQUIRED` header contains the exact payment requirements (network, asset, amount, payTo)."
      }
    }
  },
  "security": [
    { "x402": [] }
  ]
}