{
  "openapi": "3.0.0",
  "info": {
    "title": "CryptoWallet API",
    "version": "4.0.0",
    "description": "Multi-chain crypto wallet API (non-custodial). Клиент сам деривит mnemonic и шлёт публичные адреса; сервер хранит только адреса и строит unsigned tx для отправки. Auth via JWT (cookie/Bearer), issued by external auth-service (BITOK)."
  },
  "servers": [
    { "url": "/api", "description": "API root" }
  ],
  "tags": [
    { "name": "System", "description": "Health & service info" },
    { "name": "Wallets", "description": "User wallet records" },
    { "name": "Wallet Ops", "description": "Per-chain balance / transactions / send" },
    { "name": "BTC", "description": "Bitcoin RPC proxy (Blockstream)" },
    { "name": "TRON", "description": "TRON RPC proxy (TronGrid)" },
    { "name": "Solana", "description": "Solana swap proxy (Jupiter)" },
    { "name": "TRON Swap", "description": "TRON swap proxy (SunSwap + FeeSwapRouter)" },
    { "name": "BSC", "description": "BSC swap proxy (PancakeSwap V2)" },
    { "name": "Relay", "description": "Cross-chain bridges (Relay Protocol)" }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" },
      "cookieAuth": { "type": "apiKey", "in": "cookie", "name": "access_token" }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": false },
          "error": { "type": "string" }
        }
      },
      "SuccessEmpty": {
        "type": "object",
        "properties": { "success": { "type": "boolean", "example": true } }
      },
      "HealthResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" } } }
        }
      },
      "Chain": {
        "type": "string",
        "enum": ["ETH", "BTC", "SOL", "TRX", "BSC"]
      },
      "Wallet": {
        "type": "object",
        "properties": {
          "chain": { "$ref": "#/components/schemas/Chain" },
          "address": { "type": "string" },
          "derivationPath": { "type": "string", "description": "BIP32 path, например m/44'/60'/0'/0/0" }
        }
      },
      "WalletInput": {
        "type": "object",
        "required": ["chain", "address", "derivationPath"],
        "properties": {
          "chain": { "$ref": "#/components/schemas/Chain" },
          "address": { "type": "string", "maxLength": 64, "description": "Публичный адрес (chain-specific checksum-валидируется)" },
          "derivationPath": { "type": "string", "maxLength": 64, "description": "BIP32 m/.. (например m/44'/60'/0'/0/0)" }
        }
      },
      "CreateWalletsRequest": {
        "type": "object",
        "required": ["wallets"],
        "properties": {
          "wallets": {
            "type": "array", "minItems": 1, "maxItems": 20,
            "items": { "$ref": "#/components/schemas/WalletInput" }
          }
        }
      },
      "WalletsResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/Wallet" } }
        }
      },
      "BalanceResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": {
            "type": "object",
            "properties": {
              "chain": { "$ref": "#/components/schemas/Chain" },
              "address": { "type": "string" },
              "native": { "type": "string", "description": "Balance в smallest units (sat/wei/lamports/sun)" },
              "tokens": {
                "type": "object",
                "additionalProperties": { "type": "string" },
                "example": { "USDT": "12345678" }
              }
            }
          }
        }
      },
      "Transaction": {
        "type": "object",
        "properties": {
          "txid": { "type": "string" },
          "timestamp": { "type": "integer", "nullable": true, "description": "Unix seconds" },
          "direction": { "type": "string", "enum": ["in", "out", "self"] },
          "amount": { "type": "string", "nullable": true },
          "token": { "type": "string", "nullable": true },
          "from": { "type": "string", "nullable": true },
          "to": { "type": "string", "nullable": true }
        }
      },
      "TransactionsResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } }
        }
      },
      "SendRequest": {
        "type": "object",
        "required": ["to", "amount"],
        "properties": {
          "to": { "type": "string", "description": "Recipient address" },
          "amount": { "type": "string", "description": "Amount в smallest units" },
          "token": { "type": "string", "nullable": true, "description": "Например USDT для TRC20/ERC20/BEP20. Без token = native (TRX/ETH/BNB/BTC)" }
        }
      },
      "UnsignedTxResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "data": {
            "type": "object",
            "description": "Unsigned tx — формат зависит от chain (kind: btc | tron | evm | solana). Клиент подписывает приватом и broadcast'ит через соответствующий /api/{btc,tron}/broadcast endpoint или RPC своей цепи."
          }
        }
      }
    }
  },
  "security": [
    { "cookieAuth": [] },
    { "bearerAuth": [] }
  ],
  "paths": {
    "/health": {
      "get": {
        "summary": "Liveness check",
        "tags": ["System"],
        "security": [],
        "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } }
      }
    },

    "/wallets": {
      "get": {
        "summary": "Get all wallets of authenticated user",
        "tags": ["Wallets"],
        "responses": {
          "200": { "description": "List of wallets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletsResponse" } } } },
          "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },

    "/wallets/create": {
      "post": {
        "summary": "Upsert wallets для авторизованного юзера",
        "description": "Клиент сам генерит mnemonic и деривит публичные адреса (BIP44 для ETH/BSC/BTC/TRX/SOL). Тело — массив `{chain, address, derivationPath}`. На конфликт (user_id, chain) сервер обновляет address+derivationPath. Mnemonic клиенту не нужно слать — сервер её не хранит.",
        "tags": ["Wallets"],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWalletsRequest" } } }
        },
        "responses": {
          "201": { "description": "Created/updated (вернёт сохранённые адреса)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletsResponse" } } } },
          "400": { "description": "Invalid input (chain/address/derivationPath)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "401": { "description": "Not authenticated" }
        }
      }
    },

    "/wallets/{chain}/balance": {
      "get": {
        "summary": "Balance for user wallet in chain",
        "tags": ["Wallet Ops"],
        "parameters": [{ "name": "chain", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Chain" } }],
        "responses": {
          "200": { "description": "Balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceResponse" } } } },
          "404": { "description": "Wallet for this chain not found" },
          "502": { "description": "Upstream RPC error" }
        }
      }
    },

    "/wallets/{chain}/transactions": {
      "get": {
        "summary": "Transaction history for user wallet in chain",
        "tags": ["Wallet Ops"],
        "parameters": [
          { "name": "chain", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Chain" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }
        ],
        "responses": {
          "200": { "description": "List of transactions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionsResponse" } } } },
          "404": { "description": "Wallet for this chain not found" }
        }
      }
    },

    "/wallets/{chain}/send": {
      "post": {
        "summary": "Build unsigned send transaction (non-custodial)",
        "description": "Возвращает unsigned tx. Клиент подписывает приватным ключом и broadcast'ит через /api/{btc,tron}/broadcast или RPC своей цепи.",
        "tags": ["Wallet Ops"],
        "parameters": [{ "name": "chain", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Chain" } }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendRequest" } } }
        },
        "responses": {
          "200": { "description": "Unsigned tx", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnsignedTxResponse" } } } },
          "400": { "description": "Invalid input" },
          "404": { "description": "Wallet not found" },
          "502": { "description": "Upstream RPC error" }
        }
      }
    },

    "/btc/utxos/{address}": {
      "get": {
        "summary": "Confirmed UTXOs for Bitcoin address",
        "tags": ["BTC"],
        "parameters": [{ "name": "address", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "UTXOs" }, "401": { "description": "Not authenticated" } }
      }
    },
    "/btc/fee-estimates": {
      "get": {
        "summary": "Bitcoin fee estimates (sat/vB)",
        "tags": ["BTC"],
        "responses": { "200": { "description": "fast/normal/slow" }, "401": { "description": "Not authenticated" } }
      }
    },
    "/btc/broadcast": {
      "post": {
        "summary": "Broadcast raw signed Bitcoin tx",
        "tags": ["BTC"],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["hex"], "properties": { "hex": { "type": "string" } } } } } },
        "responses": { "200": { "description": "txid" }, "400": { "description": "Invalid hex" } }
      }
    },

    "/tron/account/{address}": {
      "get": {
        "summary": "TRON account info + USDT (TRC20) balance",
        "tags": ["TRON"],
        "parameters": [{ "name": "address", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Account data" } }
      }
    },
    "/tron/createtransaction": {
      "post": {
        "summary": "Build unsigned TRX transfer",
        "tags": ["TRON"],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["owner_address", "to_address", "amount"], "properties": { "owner_address": { "type": "string" }, "to_address": { "type": "string" }, "amount": { "type": "integer" } } } } } },
        "responses": { "200": { "description": "Unsigned tx" } }
      }
    },
    "/tron/triggersmartcontract": {
      "post": {
        "summary": "Build unsigned TRC20 contract call",
        "tags": ["TRON"],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } },
        "responses": { "200": { "description": "Unsigned tx" } }
      }
    },
    "/tron/broadcasttransaction": {
      "post": {
        "summary": "Broadcast signed TRON tx",
        "tags": ["TRON"],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } },
        "responses": { "200": { "description": "Result" } }
      }
    },

    "/sol/swap/quote": {
      "get": {
        "summary": "Jupiter swap quote (Solana)",
        "tags": ["Solana"],
        "parameters": [
          { "name": "inputMint", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "outputMint", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "amount", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "slippageBps", "in": "query", "required": true, "schema": { "type": "integer" } }
        ],
        "responses": { "200": { "description": "Quote" } }
      }
    },
    "/sol/swap/build": {
      "post": {
        "summary": "Jupiter swap build",
        "tags": ["Solana"],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["quoteResponse", "userPublicKey"], "properties": { "quoteResponse": { "type": "object" }, "userPublicKey": { "type": "string" } } } } } },
        "responses": { "200": { "description": "Swap tx" } }
      }
    },

    "/tron/swap/quote": {
      "get": {
        "summary": "TRON swap quote (TRX <-> USDT)",
        "tags": ["TRON Swap"],
        "parameters": [
          { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "enum": ["TRX", "USDT"] } },
          { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "enum": ["TRX", "USDT"] } },
          { "name": "amount", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Quote" } }
      }
    },
    "/tron/swap/build": {
      "post": {
        "summary": "Build TRON swap transactions",
        "tags": ["TRON Swap"],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["from", "to", "amount", "amountOutMin", "userAddress"], "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "amount": { "type": "string" }, "amountOutMin": { "type": "string" }, "userAddress": { "type": "string" } } } } } },
        "responses": { "200": { "description": "Unsigned txs" } }
      }
    },
    "/tron/swap/broadcast": {
      "post": {
        "summary": "Broadcast signed TRON swap",
        "tags": ["TRON Swap"],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["signedTransaction"], "properties": { "signedTransaction": { "type": "object" } } } } } },
        "responses": { "200": { "description": "Result" } }
      }
    },

    "/bsc/swap/quote": {
      "get": {
        "summary": "BSC swap quote (PancakeSwap V2)",
        "tags": ["BSC"],
        "parameters": [
          { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "enum": ["BNB", "USDT", "DOGE"] } },
          { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "enum": ["BNB", "USDT", "DOGE"] } },
          { "name": "amount", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Quote" } }
      }
    },
    "/bsc/swap/build": {
      "post": {
        "summary": "Build BSC swap transactions",
        "tags": ["BSC"],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["from", "to", "amount", "amountOutMin", "userAddress"], "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "amount": { "type": "string" }, "amountOutMin": { "type": "string" }, "userAddress": { "type": "string" } } } } } },
        "responses": { "200": { "description": "Unsigned txs" } }
      }
    },

    "/relay/quote/v2": {
      "get": { "summary": "Relay bridge quote", "tags": ["Relay"], "responses": { "200": { "description": "Quote" } } }
    },
    "/relay/intents/status/v3": {
      "get": { "summary": "Relay intent status", "tags": ["Relay"], "responses": { "200": { "description": "Status" } } }
    },
    "/relay/execute/{action}": {
      "post": {
        "summary": "Relay execute",
        "tags": ["Relay"],
        "parameters": [{ "name": "action", "in": "path", "required": true, "schema": { "type": "string" } }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } },
        "responses": { "200": { "description": "Result" } }
      }
    }
  }
}