keepkey-vault-sdk 1.0.0

package/dist/specs/v2/swagger.json

@@ -0,0 +1,1827 @@
+{
+    "openapi": "3.0.3",
+    "info": {
+        "title": "KeepKey Server API",
+        "description": "KeepKey hardware wallet management server with frontload support",
+        "contact": {
+            "name": "KeepKey",
+            "url": "https://keepkey.com"
+        },
+        "license": {
+            "name": ""
+        },
+        "version": "0.1.0"
+    },
+    "servers": [
+        {
+            "url": "http://localhost:1646",
+            "description": "Local development server"
+        }
+    ],
+    "paths": {
+        "/api/assets": {
+            "get": {
+                "tags": [
+                    "Assets"
+                ],
+                "summary": "List all assets with pagination and filtering",
+                "operationId": "list_assets",
+                "parameters": [
+                    {
+                        "name": "q",
+                        "in": "query",
+                        "description": "Search query for symbol, name, or network name",
+                        "required": false,
+                        "schema": {
+                            "type": "string",
+                            "nullable": true
+                        }
+                    },
+                    {
+                        "name": "network_id",
+                        "in": "query",
+                        "description": "Filter by network ID (e.g., \"eip155:1\")",
+                        "required": false,
+                        "schema": {
+                            "type": "string",
+                            "nullable": true
+                        }
+                    },
+                    {
+                        "name": "asset_type",
+                        "in": "query",
+                        "description": "Filter by asset type (\"native\" or \"token\")",
+                        "required": false,
+                        "schema": {
+                            "type": "string",
+                            "nullable": true
+                        }
+                    },
+                    {
+                        "name": "page",
+                        "in": "query",
+                        "description": "Page number (1-based)",
+                        "required": false,
+                        "schema": {
+                            "type": "integer",
+                            "format": "int64",
+                            "nullable": true
+                        }
+                    },
+                    {
+                        "name": "page_size",
+                        "in": "query",
+                        "description": "Number of items per page",
+                        "required": false,
+                        "schema": {
+                            "type": "integer",
+                            "format": "int64",
+                            "nullable": true
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "List of assets",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/AssetsResponse"
+                                }
+                            }
+                        }
+                    },
+                    "500": {
+                        "description": "Internal server error"
+                    }
+                }
+            }
+        },
+        "/api/assets/network/{network_id}": {
+            "get": {
+                "tags": [
+                    "Assets"
+                ],
+                "summary": "Get assets for a specific network",
+                "operationId": "get_network_assets",
+                "parameters": [
+                    {
+                        "name": "network_id",
+                        "in": "path",
+                        "description": "Network ID (e.g., 'eip155:1')",
+                        "required": true,
+                        "schema": {
+                            "type": "string"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "List of assets for the network",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "array",
+                                    "items": {
+                                        "$ref": "#/components/schemas/AssetInfo"
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    "500": {
+                        "description": "Internal server error"
+                    }
+                }
+            }
+        },
+        "/api/assets/stats": {
+            "get": {
+                "tags": [
+                    "Assets"
+                ],
+                "operationId": "get_asset_stats",
+                "responses": {
+                    "200": {
+                        "description": "Asset statistics",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/AssetStats"
+                                }
+                            }
+                        }
+                    },
+                    "500": {
+                        "description": "Internal server error"
+                    }
+                }
+            }
+        },
+        "/api/assets/{asset_id}": {
+            "get": {
+                "tags": [
+                    "Assets"
+                ],
+                "summary": "Get a specific asset by ID",
+                "operationId": "get_asset",
+                "parameters": [
+                    {
+                        "name": "asset_id",
+                        "in": "path",
+                        "description": "Asset ID (CAIP format)",
+                        "required": true,
+                        "schema": {
+                            "type": "string"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "Asset details",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/AssetInfo"
+                                }
+                            }
+                        }
+                    },
+                    "404": {
+                        "description": "Asset not found"
+                    },
+                    "500": {
+                        "description": "Internal server error"
+                    }
+                }
+            }
+        },
+        "/api/cache/clear": {
+            "post": {
+                "tags": [
+                    "Cache"
+                ],
+                "summary": "Clear all balance cache",
+                "description": "Clears all cached balance data from the database for all devices.",
+                "operationId": "clear_cache",
+                "responses": {
+                    "200": {
+                        "description": "Cache cleared successfully",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/CacheClearResponse"
+                                }
+                            }
+                        }
+                    },
+                    "500": {
+                        "description": "Failed to clear cache"
+                    }
+                }
+            }
+        },
+        "/api/cache/clear/{device_id}": {
+            "post": {
+                "tags": [
+                    "Cache"
+                ],
+                "summary": "Clear device-specific balance cache",
+                "description": "Clears cached balance data for a specific device.",
+                "operationId": "clear_device_cache",
+                "parameters": [
+                    {
+                        "name": "device_id",
+                        "in": "path",
+                        "description": "Device ID to clear cache for",
+                        "required": true,
+                        "schema": {
+                            "type": "string"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "Device cache cleared successfully",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/CacheClearResponse"
+                                }
+                            }
+                        }
+                    },
+                    "500": {
+                        "description": "Failed to clear device cache"
+                    }
+                }
+            }
+        },
+        "/api/cache/resync": {
+            "post": {
+                "tags": [
+                    "Cache"
+                ],
+                "summary": "Force a full resync",
+                "description": "Clears all caches and marks devices for re-frontload. This will force the system\nto re-fetch all data from devices and external sources.",
+                "operationId": "force_resync",
+                "requestBody": {
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "$ref": "#/components/schemas/ForceResyncRequest"
+                            }
+                        }
+                    },
+                    "required": true
+                },
+                "responses": {
+                    "200": {
+                        "description": "Resync initiated successfully",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/CacheClearResponse"
+                                }
+                            }
+                        }
+                    },
+                    "500": {
+                        "description": "Failed to initiate resync"
+                    }
+                }
+            }
+        },
+        "/api/cache/stats": {
+            "get": {
+                "tags": [
+                    "Cache"
+                ],
+                "summary": "Get cache statistics",
+                "description": "Returns detailed statistics about the cache including counts and timestamps.",
+                "operationId": "get_cache_stats",
+                "responses": {
+                    "200": {
+                        "description": "Cache statistics retrieved successfully"
+                    },
+                    "500": {
+                        "description": "Failed to get cache statistics"
+                    }
+                }
+            }
+        },
+        "/api/cache/status": {
+            "get": {
+                "tags": [
+                    "Cache"
+                ],
+                "summary": "Get cache status and statistics",
+                "description": "Returns information about the server's cache status including hit rates and memory usage.",
+                "operationId": "get_cache_status",
+                "responses": {
+                    "200": {
+                        "description": "Cache status retrieved successfully",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/CacheStatusResponse"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/api/data/assets": {
+            "get": {
+                "tags": [
+                    "Data"
+                ],
+                "summary": "Get all assets",
+                "operationId": "get_assets",
+                "parameters": [
+                    {
+                        "name": "chain",
+                        "in": "query",
+                        "description": "Filter by chain (e.g., \"bitcoin\", \"ethereum\")",
+                        "required": false,
+                        "schema": {
+                            "type": "string",
+                            "nullable": true
+                        }
+                    },
+                    {
+                        "name": "include_pubkeys",
+                        "in": "query",
+                        "description": "Include pubkeys in response",
+                        "required": false,
+                        "schema": {
+                            "type": "boolean",
+                            "nullable": true
+                        }
+                    },
+                    {
+                        "name": "include_balances",
+                        "in": "query",
+                        "description": "Include balances in response",
+                        "required": false,
+                        "schema": {
+                            "type": "boolean",
+                            "nullable": true
+                        }
+                    },
+                    {
+                        "name": "limit",
+                        "in": "query",
+                        "description": "Limit number of results",
+                        "required": false,
+                        "schema": {
+                            "type": "integer",
+                            "nullable": true,
+                            "minimum": 0
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "Assets retrieved successfully",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "array",
+                                    "items": {
+                                        "$ref": "#/components/schemas/AssetResponse"
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    "500": {
+                        "description": "Internal server error"
+                    }
+                }
+            }
+        },
+        "/api/data/assets/{caip}": {
+            "get": {
+                "tags": [
+                    "Data"
+                ],
+                "summary": "Get specific asset",
+                "operationId": "get_asset",
+                "responses": {
+                    "200": {
+                        "description": "Asset retrieved successfully",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/AssetResponse"
+                                }
+                            }
+                        }
+                    },
+                    "404": {
+                        "description": "Asset not found"
+                    },
+                    "500": {
+                        "description": "Internal server error"
+                    }
+                }
+            }
+        },
+        "/api/data/balances": {
+            "get": {
+                "tags": [
+                    "Data"
+                ],
+                "summary": "Get balances",
+                "operationId": "get_balances",
+                "responses": {
+                    "200": {
+                        "description": "Balances retrieved successfully",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "array",
+                                    "items": {
+                                        "$ref": "#/components/schemas/BalanceResponse"
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    "500": {
+                        "description": "Internal server error"
+                    }
+                }
+            }
+        },
+        "/api/data/balances/{address}": {
+            "get": {
+                "tags": [
+                    "Data"
+                ],
+                "summary": "Get balances for specific address",
+                "operationId": "get_address_balances",
+                "responses": {
+                    "200": {
+                        "description": "Address balances retrieved successfully",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "array",
+                                    "items": {
+                                        "$ref": "#/components/schemas/BalanceResponse"
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    "500": {
+                        "description": "Internal server error"
+                    }
+                }
+            }
+        },
+        "/api/data/cache/clear": {
+            "post": {
+                "tags": [
+                    "Data"
+                ],
+                "summary": "Clear cache",
+                "operationId": "clear_data_cache",
+                "responses": {
+                    "200": {
+                        "description": "Cache cleared successfully"
+                    },
+                    "500": {
+                        "description": "Internal server error"
+                    }
+                }
+            }
+        },
+        "/api/data/paths": {
+            "get": {
+                "tags": [
+                    "Data"
+                ],
+                "summary": "Get all paths",
+                "operationId": "get_paths",
+                "parameters": [
+                    {
+                        "name": "chain",
+                        "in": "query",
+                        "description": "Filter by chain (e.g., \"bitcoin\", \"ethereum\")",
+                        "required": false,
+                        "schema": {
+                            "type": "string",
+                            "nullable": true
+                        }
+                    },
+                    {
+                        "name": "include_pubkeys",
+                        "in": "query",
+                        "description": "Include pubkeys in response",
+                        "required": false,
+                        "schema": {
+                            "type": "boolean",
+                            "nullable": true
+                        }
+                    },
+                    {
+                        "name": "include_balances",
+                        "in": "query",
+                        "description": "Include balances in response",
+                        "required": false,
+                        "schema": {
+                            "type": "boolean",
+                            "nullable": true
+                        }
+                    },
+                    {
+                        "name": "limit",
+                        "in": "query",
+                        "description": "Limit number of results",
+                        "required": false,
+                        "schema": {
+                            "type": "integer",
+                            "nullable": true,
+                            "minimum": 0
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "Paths retrieved successfully",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "array",
+                                    "items": {
+                                        "$ref": "#/components/schemas/PathResponse"
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    "500": {
+                        "description": "Internal server error"
+                    }
+                }
+            }
+        },
+        "/api/data/paths/{path}": {
+            "get": {
+                "tags": [
+                    "Data"
+                ],
+                "summary": "Get specific path",
+                "operationId": "get_path",
+                "responses": {
+                    "200": {
+                        "description": "Path retrieved successfully",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/PathResponse"
+                                }
+                            }
+                        }
+                    },
+                    "404": {
+                        "description": "Path not found"
+                    },
+                    "500": {
+                        "description": "Internal server error"
+                    }
+                }
+            }
+        },
+        "/api/data/sync": {
+            "post": {
+                "tags": [
+                    "Data"
+                ],
+                "summary": "Trigger manual sync",
+                "operationId": "trigger_sync",
+                "responses": {
+                    "200": {
+                        "description": "Sync triggered successfully"
+                    },
+                    "500": {
+                        "description": "Internal server error"
+                    }
+                }
+            }
+        },
+        "/api/data/sync/status": {
+            "get": {
+                "tags": [
+                    "Data"
+                ],
+                "summary": "Get sync status",
+                "operationId": "get_sync_status",
+                "responses": {
+                    "200": {
+                        "description": "Sync status retrieved successfully"
+                    },
+                    "500": {
+                        "description": "Internal server error"
+                    }
+                }
+            }
+        },
+        "/api/data/wallet": {
+            "get": {
+                "tags": [
+                    "Data"
+                ],
+                "summary": "Get all wallet data",
+                "operationId": "get_wallet_data",
+                "parameters": [
+                    {
+                        "name": "chain",
+                        "in": "query",
+                        "description": "Filter by chain (e.g., \"bitcoin\", \"ethereum\")",
+                        "required": false,
+                        "schema": {
+                            "type": "string",
+                            "nullable": true
+                        }
+                    },
+                    {
+                        "name": "include_pubkeys",
+                        "in": "query",
+                        "description": "Include pubkeys in response",
+                        "required": false,
+                        "schema": {
+                            "type": "boolean",
+                            "nullable": true
+                        }
+                    },
+                    {
+                        "name": "include_balances",
+                        "in": "query",
+                        "description": "Include balances in response",
+                        "required": false,
+                        "schema": {
+                            "type": "boolean",
+                            "nullable": true
+                        }
+                    },
+                    {
+                        "name": "limit",
+                        "in": "query",
+                        "description": "Limit number of results",
+                        "required": false,
+                        "schema": {
+                            "type": "integer",
+                            "nullable": true,
+                            "minimum": 0
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "Wallet data retrieved successfully",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/WalletDataResponse"
+                                }
+                            }
+                        }
+                    },
+                    "500": {
+                        "description": "Internal server error"
+                    }
+                }
+            }
+        },
+        "/api/devices": {
+            "get": {
+                "tags": [
+                    "Devices"
+                ],
+                "summary": "List all connected devices",
+                "operationId": "list_devices",
+                "responses": {
+                    "200": {
+                        "description": "List of connected devices",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/DevicesResponse"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/api/devices/{device_id}": {
+            "get": {
+                "tags": [
+                    "Devices"
+                ],
+                "summary": "Get a specific device by ID",
+                "operationId": "get_device",
+                "parameters": [
+                    {
+                        "name": "device_id",
+                        "in": "path",
+                        "description": "Device identifier",
+                        "required": true,
+                        "schema": {
+                            "type": "string"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "Device information",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/DeviceInfo"
+                                }
+                            }
+                        }
+                    },
+                    "404": {
+                        "description": "Device not found"
+                    }
+                }
+            }
+        },
+        "/api/health": {
+            "get": {
+                "tags": [
+                    "Health"
+                ],
+                "summary": "Health check endpoint",
+                "operationId": "health",
+                "responses": {
+                    "200": {
+                        "description": "Server health status",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/HealthResponse"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v2/networks": {
+            "get": {
+                "tags": [
+                    "v2"
+                ],
+                "summary": "List all supported networks",
+                "description": "Returns all blockchain networks supported by the KeepKey server.\nData is loaded from the data crate's blockchains.json configuration.\nThis endpoint returns cached data instantly without device communication.",
+                "operationId": "list_networks",
+                "responses": {
+                    "200": {
+                        "description": "List of supported networks",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "array",
+                                    "items": {
+                                        "$ref": "#/components/schemas/NetworkInfo"
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    "500": {
+                        "description": "Failed to load blockchain configuration"
+                    }
+                }
+            }
+        },
+        "/api/v2/pubkeys": {
+            "get": {
+                "tags": [
+                    "v2"
+                ],
+                "summary": "List all cached pubkeys and addresses",
+                "description": "Returns all pubkeys/addresses from the cache without device communication.\nData is returned from fast in-memory cache.",
+                "operationId": "list_pubkeys",
+                "responses": {
+                    "200": {
+                        "description": "List of cached pubkeys",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/PubkeysResponse"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/auth/pair": {
+            "post": {
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Pair endpoint (stub)",
+                "operationId": "pair",
+                "requestBody": {
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "$ref": "#/components/schemas/PairRequest"
+                            }
+                        }
+                    },
+                    "required": true
+                },
+                "responses": {
+                    "200": {
+                        "description": "Pairing successful",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/PairResponse"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/auth/verify": {
+            "get": {
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Verify endpoint (stub)",
+                "operationId": "verify",
+                "responses": {
+                    "200": {
+                        "description": "Verification successful",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/VerifyResponse"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/spec/swagger.json": {
+            "get": {
+                "tags": [
+                    "Spec"
+                ],
+                "summary": "Swagger spec endpoint (stub)",
+                "operationId": "swagger_spec",
+                "responses": {
+                    "200": {
+                        "description": "Swagger specification"
+                    }
+                }
+            }
+        },
+        "/system/getPublicKey": {
+            "post": {
+                "tags": [
+                    "System"
+                ],
+                "summary": "Get public key (legacy endpoint)",
+                "description": "Legacy endpoint that maps to the same functionality as get-public-key",
+                "operationId": "get_public_key_legacy",
+                "requestBody": {
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "$ref": "#/components/schemas/GetPublicKeyRequest"
+                            }
+                        }
+                    },
+                    "required": true
+                },
+                "responses": {
+                    "200": {
+                        "description": "Public key retrieved successfully",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/GetPublicKeyResponse"
+                                }
+                            }
+                        }
+                    },
+                    "400": {
+                        "description": "Invalid request"
+                    },
+                    "401": {
+                        "description": "PIN required"
+                    },
+                    "404": {
+                        "description": "No device found"
+                    },
+                    "408": {
+                        "description": "Device timeout"
+                    },
+                    "500": {
+                        "description": "Internal server error"
+                    }
+                }
+            }
+        },
+        "/system/info/get-features": {
+            "post": {
+                "tags": [
+                    "System"
+                ],
+                "summary": "Get device features",
+                "description": "Returns the features and capabilities of the connected device.\nFeatures are cached in memory for 5 minutes for fast subsequent requests.",
+                "operationId": "get_features",
+                "responses": {
+                    "200": {
+                        "description": "Device features retrieved successfully",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/DeviceFeaturesResponse"
+                                }
+                            }
+                        }
+                    },
+                    "404": {
+                        "description": "No device found"
+                    },
+                    "408": {
+                        "description": "Device timeout"
+                    },
+                    "500": {
+                        "description": "Internal server error"
+                    }
+                }
+            }
+        },
+        "/system/info/get-public-key": {
+            "post": {
+                "tags": [
+                    "System"
+                ],
+                "summary": "Get public key from device",
+                "description": "Derives a public key (xpub) from the device for the specified derivation path",
+                "operationId": "get_public_key",
+                "requestBody": {
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "$ref": "#/components/schemas/GetPublicKeyRequest"
+                            }
+                        }
+                    },
+                    "required": true
+                },
+                "responses": {
+                    "200": {
+                        "description": "Public key retrieved successfully",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/GetPublicKeyResponse"
+                                }
+                            }
+                        }
+                    },
+                    "400": {
+                        "description": "Invalid request"
+                    },
+                    "401": {
+                        "description": "PIN required"
+                    },
+                    "404": {
+                        "description": "No device found"
+                    },
+                    "408": {
+                        "description": "Device timeout"
+                    },
+                    "500": {
+                        "description": "Internal server error"
+                    }
+                }
+            }
+        }
+    },
+    "components": {
+        "schemas": {
+            "AssetInfo": {
+                "type": "object",
+                "required": [
+                    "asset_id",
+                    "network_id",
+                    "symbol",
+                    "name",
+                    "network_name",
+                    "precision",
+                    "asset_type"
+                ],
+                "properties": {
+                    "asset_id": {
+                        "type": "string"
+                    },
+                    "asset_type": {
+                        "type": "string"
+                    },
+                    "color": {
+                        "type": "string",
+                        "nullable": true
+                    },
+                    "contract_address": {
+                        "type": "string",
+                        "nullable": true
+                    },
+                    "explorer": {
+                        "type": "string",
+                        "nullable": true
+                    },
+                    "explorer_address_link": {
+                        "type": "string",
+                        "nullable": true
+                    },
+                    "explorer_tx_link": {
+                        "type": "string",
+                        "nullable": true
+                    },
+                    "explorer_xpub_link": {
+                        "type": "string",
+                        "nullable": true
+                    },
+                    "icon": {
+                        "type": "string",
+                        "nullable": true
+                    },
+                    "name": {
+                        "type": "string"
+                    },
+                    "network_id": {
+                        "type": "string"
+                    },
+                    "network_name": {
+                        "type": "string"
+                    },
+                    "precision": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "symbol": {
+                        "type": "string"
+                    }
+                }
+            },
+            "AssetResponse": {
+                "type": "object",
+                "description": "Response for asset data",
+                "required": [
+                    "caip",
+                    "chain",
+                    "symbol",
+                    "name",
+                    "decimals"
+                ],
+                "properties": {
+                    "caip": {
+                        "type": "string"
+                    },
+                    "chain": {
+                        "type": "string"
+                    },
+                    "contract_address": {
+                        "type": "string",
+                        "nullable": true
+                    },
+                    "decimals": {
+                        "type": "integer",
+                        "format": "int32",
+                        "minimum": 0
+                    },
+                    "icon": {
+                        "type": "string",
+                        "nullable": true
+                    },
+                    "name": {
+                        "type": "string"
+                    },
+                    "price_usd": {
+                        "type": "number",
+                        "format": "double",
+                        "nullable": true
+                    },
+                    "symbol": {
+                        "type": "string"
+                    }
+                }
+            },
+            "AssetStats": {
+                "type": "object",
+                "description": "Get asset statistics",
+                "required": [
+                    "total_assets",
+                    "total_networks",
+                    "native_assets",
+                    "token_assets"
+                ],
+                "properties": {
+                    "last_updated": {
+                        "type": "string",
+                        "nullable": true
+                    },
+                    "native_assets": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "token_assets": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "total_assets": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "total_networks": {
+                        "type": "integer",
+                        "format": "int64"
+                    }
+                }
+            },
+            "AssetsResponse": {
+                "type": "object",
+                "required": [
+                    "assets",
+                    "total",
+                    "page",
+                    "page_size",
+                    "total_pages"
+                ],
+                "properties": {
+                    "assets": {
+                        "type": "array",
+                        "items": {
+                            "$ref": "#/components/schemas/AssetInfo"
+                        }
+                    },
+                    "page": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "page_size": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "total": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "total_pages": {
+                        "type": "integer",
+                        "format": "int64"
+                    }
+                }
+            },
+            "BalanceResponse": {
+                "type": "object",
+                "description": "Response for balance data",
+                "required": [
+                    "address",
+                    "caip",
+                    "balance",
+                    "last_updated"
+                ],
+                "properties": {
+                    "address": {
+                        "type": "string"
+                    },
+                    "balance": {
+                        "type": "string"
+                    },
+                    "caip": {
+                        "type": "string"
+                    },
+                    "last_updated": {
+                        "type": "string"
+                    },
+                    "value_usd": {
+                        "type": "number",
+                        "format": "double",
+                        "nullable": true
+                    }
+                }
+            },
+            "CacheClearResponse": {
+                "type": "object",
+                "description": "Cache clear response",
+                "required": [
+                    "message",
+                    "entries_cleared",
+                    "resync_triggered"
+                ],
+                "properties": {
+                    "entries_cleared": {
+                        "type": "integer",
+                        "description": "Number of entries cleared",
+                        "minimum": 0
+                    },
+                    "message": {
+                        "type": "string",
+                        "description": "Status message"
+                    },
+                    "resync_triggered": {
+                        "type": "boolean",
+                        "description": "Whether a resync was triggered"
+                    }
+                }
+            },
+            "CacheStatusResponse": {
+                "type": "object",
+                "description": "Cache status response",
+                "required": [
+                    "address_cache_count",
+                    "xpub_cache_count",
+                    "uptime_seconds",
+                    "cache_hit_rate",
+                    "cache_hits",
+                    "cache_misses",
+                    "memory_usage_mb"
+                ],
+                "properties": {
+                    "address_cache_count": {
+                        "type": "integer",
+                        "description": "Number of cached addresses",
+                        "minimum": 0
+                    },
+                    "cache_hit_rate": {
+                        "type": "number",
+                        "format": "double",
+                        "description": "Cache hit rate as percentage"
+                    },
+                    "cache_hits": {
+                        "type": "integer",
+                        "format": "int64",
+                        "description": "Total cache hits",
+                        "minimum": 0
+                    },
+                    "cache_misses": {
+                        "type": "integer",
+                        "format": "int64",
+                        "description": "Total cache misses",
+                        "minimum": 0
+                    },
+                    "memory_usage_mb": {
+                        "type": "integer",
+                        "format": "int64",
+                        "description": "Memory usage estimate in MB",
+                        "minimum": 0
+                    },
+                    "uptime_seconds": {
+                        "type": "integer",
+                        "format": "int64",
+                        "description": "Server uptime in seconds",
+                        "minimum": 0
+                    },
+                    "xpub_cache_count": {
+                        "type": "integer",
+                        "description": "Number of cached xpubs",
+                        "minimum": 0
+                    }
+                }
+            },
+            "DataQuery": {
+                "type": "object",
+                "description": "Query parameters for data endpoints",
+                "properties": {
+                    "chain": {
+                        "type": "string",
+                        "description": "Filter by chain (e.g., \"bitcoin\", \"ethereum\")",
+                        "nullable": true
+                    },
+                    "include_balances": {
+                        "type": "boolean",
+                        "description": "Include balances in response",
+                        "nullable": true
+                    },
+                    "include_pubkeys": {
+                        "type": "boolean",
+                        "description": "Include pubkeys in response",
+                        "nullable": true
+                    },
+                    "limit": {
+                        "type": "integer",
+                        "description": "Limit number of results",
+                        "nullable": true,
+                        "minimum": 0
+                    }
+                }
+            },
+            "DeviceFeatures": {
+                "type": "object",
+                "required": [
+                    "bootloader_mode",
+                    "initialized",
+                    "pin_protection",
+                    "passphrase_protection"
+                ],
+                "properties": {
+                    "bootloader_mode": {
+                        "type": "boolean"
+                    },
+                    "firmware_version": {
+                        "type": "string",
+                        "nullable": true
+                    },
+                    "initialized": {
+                        "type": "boolean"
+                    },
+                    "label": {
+                        "type": "string",
+                        "nullable": true
+                    },
+                    "model": {
+                        "type": "string",
+                        "nullable": true
+                    },
+                    "passphrase_protection": {
+                        "type": "boolean"
+                    },
+                    "pin_protection": {
+                        "type": "boolean"
+                    },
+                    "vendor": {
+                        "type": "string",
+                        "nullable": true
+                    }
+                }
+            },
+            "DeviceFeaturesResponse": {
+                "type": "object",
+                "description": "Device features response",
+                "required": [
+                    "features",
+                    "success"
+                ],
+                "properties": {
+                    "features": {
+                        "description": "Device features information"
+                    },
+                    "success": {
+                        "type": "boolean",
+                        "description": "Success flag"
+                    }
+                }
+            },
+            "DeviceInfo": {
+                "type": "object",
+                "required": [
+                    "device_id",
+                    "vendor_id",
+                    "product_id",
+                    "status",
+                    "initialized"
+                ],
+                "properties": {
+                    "device_id": {
+                        "type": "string"
+                    },
+                    "features": {
+                        "allOf": [
+                            {
+                                "$ref": "#/components/schemas/DeviceFeatures"
+                            }
+                        ],
+                        "nullable": true
+                    },
+                    "initialized": {
+                        "type": "boolean"
+                    },
+                    "product_id": {
+                        "type": "integer",
+                        "format": "int32",
+                        "minimum": 0
+                    },
+                    "serial_number": {
+                        "type": "string",
+                        "nullable": true
+                    },
+                    "status": {
+                        "type": "string"
+                    },
+                    "vendor_id": {
+                        "type": "integer",
+                        "format": "int32",
+                        "minimum": 0
+                    }
+                }
+            },
+            "DevicesResponse": {
+                "type": "object",
+                "required": [
+                    "devices",
+                    "total"
+                ],
+                "properties": {
+                    "devices": {
+                        "type": "array",
+                        "items": {
+                            "$ref": "#/components/schemas/DeviceInfo"
+                        }
+                    },
+                    "total": {
+                        "type": "integer",
+                        "minimum": 0
+                    }
+                }
+            },
+            "ForceResyncRequest": {
+                "type": "object",
+                "description": "Force resync request",
+                "properties": {
+                    "trigger_frontload": {
+                        "type": "boolean",
+                        "description": "Whether to trigger frontload after clearing cache"
+                    }
+                }
+            },
+            "GetPublicKeyRequest": {
+                "type": "object",
+                "description": "Request for getting public key/xpub",
+                "required": [
+                    "addressN"
+                ],
+                "properties": {
+                    "addressN": {
+                        "type": "array",
+                        "items": {
+                            "type": "integer",
+                            "format": "int32",
+                            "minimum": 0
+                        },
+                        "description": "Derivation path as array of numbers (supports both addressN and address_n)"
+                    },
+                    "coin": {
+                        "type": "string",
+                        "description": "Coin name (e.g., \"Bitcoin\")",
+                        "nullable": true
+                    },
+                    "script_type": {
+                        "type": "string",
+                        "description": "Script type for address derivation",
+                        "nullable": true
+                    },
+                    "show_display": {
+                        "type": "boolean",
+                        "description": "Whether to show on device display",
+                        "nullable": true
+                    },
+                    "symbol": {
+                        "type": "string",
+                        "description": "Symbol (e.g., \"BTC\")",
+                        "nullable": true
+                    }
+                }
+            },
+            "GetPublicKeyResponse": {
+                "type": "object",
+                "description": "Response for getting public key/xpub",
+                "required": [
+                    "xpub",
+                    "node"
+                ],
+                "properties": {
+                    "node": {
+                        "$ref": "#/components/schemas/PublicKeyNode"
+                    },
+                    "serialized_path": {
+                        "type": "string",
+                        "description": "Serialized public key",
+                        "nullable": true
+                    },
+                    "xpub": {
+                        "type": "string",
+                        "description": "Extended public key (xpub)"
+                    }
+                }
+            },
+            "HealthResponse": {
+                "type": "object",
+                "required": [
+                    "status",
+                    "ready",
+                    "syncing",
+                    "timestamp",
+                    "apiVersion",
+                    "version",
+                    "supportedChains"
+                ],
+                "properties": {
+                    "apiVersion": {
+                        "type": "integer",
+                        "format": "int32",
+                        "minimum": 0
+                    },
+                    "ready": {
+                        "type": "boolean"
+                    },
+                    "status": {
+                        "type": "string"
+                    },
+                    "supportedChains": {
+                        "type": "array",
+                        "items": {
+                            "type": "string"
+                        }
+                    },
+                    "syncing": {
+                        "type": "boolean"
+                    },
+                    "timestamp": {
+                        "$ref": "#/components/schemas/chrono.DateTime"
+                    },
+                    "version": {
+                        "type": "string"
+                    }
+                }
+            },
+            "NetworkInfo": {
+                "type": "object",
+                "required": [
+                    "network_id",
+                    "name",
+                    "symbol",
+                    "gas_asset_caip"
+                ],
+                "properties": {
+                    "gas_asset_caip": {
+                        "type": "string"
+                    },
+                    "name": {
+                        "type": "string"
+                    },
+                    "network_id": {
+                        "type": "string"
+                    },
+                    "symbol": {
+                        "type": "string"
+                    }
+                }
+            },
+            "PairRequest": {
+                "type": "object",
+                "properties": {
+                    "api_key": {
+                        "type": "string",
+                        "nullable": true
+                    },
+                    "name": {
+                        "type": "string",
+                        "nullable": true
+                    }
+                }
+            },
+            "PairResponse": {
+                "type": "object",
+                "required": [
+                    "success"
+                ],
+                "properties": {
+                    "success": {
+                        "type": "boolean"
+                    }
+                }
+            },
+            "PathResponse": {
+                "type": "object",
+                "description": "Response for path data",
+                "required": [
+                    "path",
+                    "chain",
+                    "address_n"
+                ],
+                "properties": {
+                    "address": {
+                        "type": "string",
+                        "nullable": true
+                    },
+                    "address_n": {
+                        "type": "array",
+                        "items": {
+                            "type": "integer",
+                            "format": "int32",
+                            "minimum": 0
+                        }
+                    },
+                    "balance": {
+                        "type": "string",
+                        "nullable": true
+                    },
+                    "chain": {
+                        "type": "string"
+                    },
+                    "path": {
+                        "type": "string"
+                    },
+                    "pubkey": {
+                        "type": "string",
+                        "nullable": true
+                    },
+                    "script_type": {
+                        "type": "string",
+                        "nullable": true
+                    }
+                }
+            },
+            "PubkeyEntry": {
+                "type": "object",
+                "required": [
+                    "network_id",
+                    "network_name",
+                    "is_utxo_based",
+                    "path"
+                ],
+                "properties": {
+                    "address": {
+                        "type": "string",
+                        "nullable": true
+                    },
+                    "is_utxo_based": {
+                        "type": "boolean"
+                    },
+                    "network_id": {
+                        "type": "string"
+                    },
+                    "network_name": {
+                        "type": "string"
+                    },
+                    "path": {
+                        "type": "string"
+                    },
+                    "pubkey": {
+                        "type": "string",
+                        "nullable": true
+                    },
+                    "xpub": {
+                        "type": "string",
+                        "nullable": true
+                    }
+                }
+            },
+            "PubkeysResponse": {
+                "type": "object",
+                "required": [
+                    "pubkeys",
+                    "total"
+                ],
+                "properties": {
+                    "pubkeys": {
+                        "type": "array",
+                        "items": {
+                            "$ref": "#/components/schemas/PubkeyEntry"
+                        }
+                    },
+                    "total": {
+                        "type": "integer",
+                        "minimum": 0
+                    }
+                }
+            },
+            "PublicKeyNode": {
+                "type": "object",
+                "description": "Public key node information",
+                "required": [
+                    "public_key",
+                    "chain_code",
+                    "depth",
+                    "parent_fingerprint",
+                    "child_num"
+                ],
+                "properties": {
+                    "chain_code": {
+                        "type": "string",
+                        "description": "Chain code in hex"
+                    },
+                    "child_num": {
+                        "type": "integer",
+                        "format": "int32",
+                        "description": "Child number",
+                        "minimum": 0
+                    },
+                    "depth": {
+                        "type": "integer",
+                        "format": "int32",
+                        "description": "Depth in derivation path",
+                        "minimum": 0
+                    },
+                    "parent_fingerprint": {
+                        "type": "integer",
+                        "format": "int32",
+                        "description": "Parent fingerprint",
+                        "minimum": 0
+                    },
+                    "public_key": {
+                        "type": "string",
+                        "description": "Public key in hex"
+                    }
+                }
+            },
+            "VerifyResponse": {
+                "type": "object",
+                "required": [
+                    "success",
+                    "api_key"
+                ],
+                "properties": {
+                    "api_key": {
+                        "type": "string"
+                    },
+                    "success": {
+                        "type": "boolean"
+                    }
+                }
+            },
+            "WalletDataResponse": {
+                "type": "object",
+                "description": "Response for wallet data",
+                "required": [
+                    "paths",
+                    "assets",
+                    "balances"
+                ],
+                "properties": {
+                    "assets": {
+                        "type": "array",
+                        "items": {
+                            "$ref": "#/components/schemas/AssetResponse"
+                        }
+                    },
+                    "balances": {
+                        "type": "array",
+                        "items": {
+                            "$ref": "#/components/schemas/BalanceResponse"
+                        }
+                    },
+                    "paths": {
+                        "type": "array",
+                        "items": {
+                            "$ref": "#/components/schemas/PathResponse"
+                        }
+                    },
+                    "total_value_usd": {
+                        "type": "number",
+                        "format": "double",
+                        "nullable": true
+                    }
+                }
+            }
+        }
+    },
+    "tags": [
+        {
+            "name": "Health",
+            "description": "Health check endpoints"
+        },
+        {
+            "name": "Devices",
+            "description": "Device management endpoints"
+        },
+        {
+            "name": "Auth",
+            "description": "Authentication endpoints"
+        },
+        {
+            "name": "Portfolio",
+            "description": "Portfolio and balance endpoints"
+        },
+        {
+            "name": "Cache",
+            "description": "Cache status and statistics"
+        },
+        {
+            "name": "Assets",
+            "description": "Asset metadata and information"
+        },
+        {
+            "name": "Data",
+            "description": "Comprehensive wallet data management"
+        },
+        {
+            "name": "Swaps",
+            "description": "Swap tracking and history"
+        },
+        {
+            "name": "Spec",
+            "description": "API specification"
+        }
+    ]
+}