{
  "openapi": "3.1.0",
  "info": {
    "title": "BitCloudVPS agent API",
    "version": "1.1.0",
    "description": "No-KYC crypto-only VPS / storage / dedicated hosting. Token account -> crypto invoice or x402 (USDC on Base) top-up -> deploy from the prepaid balance. Creating the token accepts the AUP. MCP alternative: POST /mcp (JSON-RPC), tool reference /skills.md."
  },
  "servers": [
    {
      "url": "https://bitcloudvps.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "paths": {
    "/api/health": {
      "get": {
        "summary": "Liveness probe",
        "responses": {
          "200": {
            "description": "ok"
          }
        }
      }
    },
    "/api/agent/account": {
      "post": {
        "summary": "Open a token account (accepts the AUP)",
        "responses": {
          "200": {
            "description": "{account_token}"
          }
        }
      }
    },
    "/api/agent/catalog": {
      "get": {
        "summary": "Coins, top-up limits, x402 support",
        "responses": {
          "200": {
            "description": "catalog"
          }
        }
      }
    },
    "/api/agent/topup": {
      "post": {
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Create a top-up invoice ({usd, coin}) or pay x402",
        "responses": {
          "200": {
            "description": "invoice"
          },
          "402": {
            "description": "x402 challenge"
          }
        }
      }
    },
    "/api/agent/status": {
      "get": {
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Invoice payment status",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "invoice"
          }
        }
      }
    },
    "/api/register": {
      "post": {
        "summary": "Token-only or email+password signup",
        "responses": {
          "200": {
            "description": "account"
          }
        }
      }
    },
    "/api/login": {
      "post": {
        "summary": "Login (token or email+password)",
        "responses": {
          "200": {
            "description": "session"
          }
        }
      }
    },
    "/api/me": {
      "get": {
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Current account + balance",
        "responses": {
          "200": {
            "description": "me"
          }
        }
      }
    },
    "/api/servers": {
      "get": {
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "List the account's servers",
        "responses": {
          "200": {
            "description": "servers"
          }
        }
      }
    },
    "/api/orders": {
      "post": {
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Create an order (balance payment, or coin invoice)",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._-]{8,64}$"
            },
            "description": "Retry-safe: replays the stored response"
          }
        ],
        "responses": {
          "200": {
            "description": "order + invoice"
          },
          "402": {
            "description": "balance shortfall"
          }
        }
      }
    },
    "/api/invoices": {
      "get": {
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Invoice history",
        "responses": {
          "200": {
            "description": "invoices"
          }
        }
      }
    },
    "/api/invoice": {
      "get": {
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "One invoice by id",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "invoice"
          }
        }
      }
    },
    "/api/rates": {
      "get": {
        "summary": "Live coin rates",
        "responses": {
          "200": {
            "description": "rates"
          }
        }
      }
    },
    "/api/tickets": {
      "get": {
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Support tickets",
        "responses": {
          "200": {
            "description": "tickets"
          }
        }
      },
      "post": {
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Open a ticket",
        "responses": {
          "200": {
            "description": "ticket"
          }
        }
      }
    },
    "/api/server-command": {
      "post": {
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Reboot / power / reinstall (idempotency_key required)",
        "responses": {
          "202": {
            "description": "queued"
          }
        }
      },
      "get": {
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Command status",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "command"
          }
        }
      }
    },
    "/api/pay/tx": {
      "post": {
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Bind a txid to a pending invoice",
        "responses": {
          "200": {
            "description": "bound"
          },
          "409": {
            "description": "txid conflict"
          }
        }
      }
    },
    "/api/pay/status": {
      "post": {
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "On-chain check + credit when confirmed",
        "responses": {
          "200": {
            "description": "invoice + pay"
          }
        }
      }
    },
    "/api/pay/fail": {
      "post": {
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Cancel a pending payment attempt",
        "responses": {
          "200": {
            "description": "cancelled"
          }
        }
      }
    }
  }
}