{
  "openapi": "3.1.0",
  "info": {
    "title": "CryptoCardy REST API",
    "version": "1.0.0",
    "description": "REST API for generating a unique seed, issuing a virtual card in pending_top_up state, and returning a funding wallet address. Seed authentication uses the X-Seed header.",
    "contact": { "url": "https://cryptocardy.com/contact" },
    "license": { "name": "Proprietary", "url": "https://cryptocardy.com/tos" }
  },
  "servers": [{ "url": "https://cryptocardy.com/v1/api" }],
  "components": {
    "securitySchemes": {
      "seed": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Seed",
        "description": "Unique seed credential. Store securely and send with requests that require identification."
      }
    },
    "schemas": {
      "Card": {
        "type": "object",
        "required": ["state", "network", "card_number", "cvv_masked", "expiry"],
        "properties": {
          "state": { "type": "string", "enum": ["pending_top_up"] },
          "network": { "type": "string", "enum": ["visa", "mastercard"] },
          "card_number": { "type": "string", "description": "Formatted PAN", "examples": ["4916 5301 2345 2039"] },
          "cvv_masked": { "type": "string", "description": "CVV value (masked/limited display)", "examples": ["601"] },
          "expiry": { "type": "string", "examples": ["05/31"] }
        }
      },
      "Wallet": {
        "type": "object",
        "required": ["asset", "address"],
        "properties": {
          "asset": { "type": "string", "examples": ["BTC"] },
          "address": { "type": "string", "examples": ["bc1qqsm6nsu62yqv535fx6m7amh2l8xpwmgse66jn0"] }
        }
      },
      "GenerateResponse": {
        "type": "object",
        "required": ["success", "request_id", "seed", "card", "wallet", "created_at"],
        "properties": {
          "success": { "type": "boolean", "const": true },
          "request_id": { "type": "string", "examples": ["req_bb0ade3fea54"] },
          "seed": { "type": "string", "examples": ["c4f4-6e88-036c-761c"] },
          "card": { "$ref": "#/components/schemas/Card" },
          "wallet": { "$ref": "#/components/schemas/Wallet" },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "Error": {
        "type": "object",
        "required": ["success", "error"],
        "properties": {
          "success": { "type": "boolean", "const": false },
          "error": { "type": "string" }
        }
      }
    }
  },
  "paths": {
    "/": {
      "get": {
        "summary": "Generate seed + card + funding wallet",
        "description": "Returns a unique seed, a virtual card in pending_top_up state, and a funding wallet address based on the requested asset.",
        "parameters": [
          {
            "name": "card",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "enum": ["visa", "mastercard"] },
            "description": "Card network preference."
          },
          {
            "name": "asset",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "Funding asset preference (e.g. BTC, ETH, USDT-ERC20, USDT-SOL, SOL, XMR)."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/GenerateResponse" }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Generate seed + card + funding wallet (POST)",
        "description": "Same as GET /. Accepts query params or JSON body.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "card": { "type": "string", "enum": ["visa", "mastercard"] },
                  "asset": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/GenerateResponse" }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    }
  }
}