openapi: 3.0.3
info:
  version: 1.0.0
  title: Vilna API
  description: >
    Добро пожаловать в справочник Vilna API. Это полная спецификация OpenAPI для
    всех endpoints API.


    Быстрые ссылки


    - [Обзор API](/apis/) - Введение и концепции

    - [Руководство по безопасности](/apis/security) - Аутентификация и
    верификация webhook

    - [Стандарты CAIP](/apis/caip-standards) - Стандарты идентификации активов

    - [Руководство быстрого старта](/guides/quickstart) - Пошаговая инструкция
    интеграции


    **API Endpoints**


    Управление активами


    - **[Активы](#tag/asset)** - Обнаружение и управление цифровыми активами


    Операции с адресами


    - **[Адреса](#tag/address)** - Управление блокчейн-адресами

    - **[Расширенные публичные ключи](#tag/xpub)** - Управление HD кошельками

    - Поддержка массовых операций


    Мониторинг и уведомления

    - **[Каналы](#tag/channel)** - Настройка endpoints для уведомлений

    - **[Подписки](#tag/subscription)** - Управление подписками на события

    - **[Транзакции](#tag/transaction)** - Мониторинг транзакций


    Система

    - **[Блокчейны](#tag/blockchain)** - Информация о поддерживаемых блокчейнах

    - **[Системный статус](#tag/system)** - Проверка здоровья и информация о
    версии


    **Нужна помощь?**


    Посетите наш [портал документации](/apis/) для подробных руководств и
    примеров.
  contact:
    email: support@vilna.io
    name: Vilna API Team
    url: https://vilna.io
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: https://docs.vilna.io/legal/terms
servers:
  - url: https://{namespace}.vilna.app/{version}
    description: Production environment
    variables:
      namespace:
        default: demo
        description: This value is assigned by the service provider.
      version:
        default: v1
        description: API version
security:
  - ApiKeyAuth: []
tags:
  - name: system
    description: System and service status operations
  - name: blockchain
    description: >-
      Operations related to supported blockchains for monitoring and balance
      queries
  - name: block
    description: Operations for retrieving and filtering blockchain blocks
  - name: token
    description: Manage blockchain tokens such as native and ERC-20 assets
  - name: public_key
    description: Public key (BIP44/49/84) management operations for HD wallets
  - name: address
    description: Address management operations for tracking blockchain addresses
  - name: notification_channel
    description: >-
      Notification delivery channel management for alerts and event
      notifications
  - name: transaction
    description: Blockchain transaction tracking and monitoring operations
  - name: simulate
    description: Transaction simulation operations for various blockchain networks
  - name: asset
    description: Asset management operations for blockchain assets
paths:
  /blockchains:
    get:
      description: >
        Returns a list of blockchains that are actively supported for monitoring
        and balance queries.


        These are the blockchains where the system can track address balances,
        detect transactions, and send

        notifications about balance changes. While tokens can be sent on many
        blockchains, only those listed

        here have the infrastructure to monitor addresses and provide real-time
        updates.
      operationId: listBlockchains
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/sortBlockchains'
        - $ref: '#/components/parameters/blockchainsFilterSearch'
        - $ref: '#/components/parameters/blockchainsFilterFamilies'
        - $ref: '#/components/parameters/blockchainsFilterIsActive'
      responses:
        '200':
          $ref: '#/components/responses/blockchains_list_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        default:
          $ref: '#/components/responses/problem'
      summary: Get list of supported blockchains
      tags:
        - blockchain
    post:
      description: >
        Creates a new blockchain for monitoring and balance queries.


        The blockchain must exist in the reference data with the provided
        chain_gid (CAIP-2 format).

        If the blockchain is not supported in the reference data, the request
        will be rejected.
      operationId: createBlockchain
      requestBody:
        description: Blockchain creation request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_blockchain_request'
      responses:
        '200':
          $ref: '#/components/responses/blockchain_response'
        '201':
          $ref: '#/components/responses/blockchain_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        '404':
          $ref: '#/components/responses/not_found_problem'
        default:
          $ref: '#/components/responses/problem'
      summary: Create a new supported blockchain
      tags:
        - blockchain
  /blockchains/{chain_gid}:
    get:
      description: >
        Returns details of a specific blockchain by its chain identifier.


        This endpoint retrieves information about a blockchain that is supported
        for monitoring

        and balance queries. The blockchain must be actively configured in the
        system.
      operationId: getBlockchain
      parameters:
        - $ref: '#/components/parameters/chainGID'
      responses:
        '200':
          $ref: '#/components/responses/blockchain_response'
        '404':
          $ref: '#/components/responses/not_found_problem'
        default:
          $ref: '#/components/responses/problem'
      summary: Get a single blockchain
      tags:
        - blockchain
  /blockchains/{chain_gid}/actions/activate:
    post:
      summary: Activate blockchain
      description: |
        Activates a blockchain for monitoring and processing by workers.
      operationId: activateBlockchain
      tags:
        - blockchain
      parameters:
        - $ref: '#/components/parameters/chainGID'
      responses:
        '200':
          description: Blockchain activated successfully
        '204':
          description: Blockchain was already active
        '404':
          $ref: '#/components/responses/not_found_problem'
        default:
          $ref: '#/components/responses/problem'
  /blockchains/{chain_gid}/actions/deactivate:
    post:
      summary: Deactivate blockchain
      description: |
        Deactivates a blockchain from monitoring and processing by workers.
      operationId: deactivateBlockchain
      tags:
        - blockchain
      parameters:
        - $ref: '#/components/parameters/chainGID'
      responses:
        '200':
          description: Blockchain deactivated successfully
        '204':
          description: Blockchain was already inactive
        '404':
          $ref: '#/components/responses/not_found_problem'
        default:
          $ref: '#/components/responses/problem'
  /blockchains/{chain_gid}/evm:
    patch:
      summary: Update EVM blockchain configuration
      description: Update the configuration of an existing EVM-compatible blockchain
      operationId: patchEVMBlockchain
      tags:
        - blockchain
      parameters:
        - $ref: '#/components/parameters/chainGID'
      requestBody:
        $ref: '#/components/requestBodies/update_evm_config_request'
      responses:
        '200':
          $ref: '#/components/responses/blockchain_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        '404':
          $ref: '#/components/responses/not_found_problem'
        default:
          $ref: '#/components/responses/problem'
  /blockchains/{chain_gid}/solana:
    patch:
      summary: Update Solana blockchain configuration
      description: Update the configuration of an existing Solana blockchain
      operationId: patchSolanaBlockchain
      tags:
        - blockchain
      parameters:
        - $ref: '#/components/parameters/chainGID'
      requestBody:
        $ref: '#/components/requestBodies/update_solana_config_request'
      responses:
        '200':
          $ref: '#/components/responses/blockchain_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        '404':
          $ref: '#/components/responses/not_found_problem'
        default:
          $ref: '#/components/responses/problem'
  /blockchains/{chain_gid}/tron:
    patch:
      summary: Update Tron blockchain configuration
      description: Update the configuration of an existing Tron blockchain
      operationId: patchTronBlockchain
      tags:
        - blockchain
      parameters:
        - $ref: '#/components/parameters/chainGID'
      requestBody:
        $ref: '#/components/requestBodies/update_tron_config_request'
      responses:
        '200':
          $ref: '#/components/responses/blockchain_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        '404':
          $ref: '#/components/responses/not_found_problem'
        default:
          $ref: '#/components/responses/problem'
  /blockchains/{chain_gid}/bitcoin:
    patch:
      summary: Update Bitcoin blockchain configuration
      description: Update the configuration of an existing Bitcoin blockchain
      operationId: patchBitcoinBlockchain
      tags:
        - blockchain
      parameters:
        - $ref: '#/components/parameters/chainGID'
      requestBody:
        $ref: '#/components/requestBodies/update_bitcoin_config_request'
      responses:
        '200':
          $ref: '#/components/responses/blockchain_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        '404':
          $ref: '#/components/responses/not_found_problem'
        default:
          $ref: '#/components/responses/problem'
  /blocks:
    get:
      description: |
        Returns a paginated list of blocks from all or specified blockchains.
      operationId: listBlocks
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/sortBlocks'
        - $ref: '#/components/parameters/blocksFilterChainGIDs'
        - $ref: '#/components/parameters/blocksFilterStatuses'
        - $ref: '#/components/parameters/blocksFilterFromBlock'
        - $ref: '#/components/parameters/blocksFilterToBlock'
      responses:
        '200':
          $ref: '#/components/responses/blocks_list_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        default:
          $ref: '#/components/responses/problem'
      summary: Get blocks across blockchains
      tags:
        - blockchain
        - block
  /blocks/{chain_gid}/{block_number}:
    get:
      description: >-
        Returns details of a specific block by its number for a given
        blockchain.
      operationId: getBlock
      parameters:
        - $ref: '#/components/parameters/chainGID'
        - $ref: '#/components/parameters/blockNumber'
      responses:
        '200':
          $ref: '#/components/responses/block_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        '404':
          $ref: '#/components/responses/not_found_problem'
        default:
          $ref: '#/components/responses/problem'
      summary: Get a specific block
      tags:
        - blockchain
        - block
  /public_keys:
    get:
      summary: Get list of public keys
      description: Returns a list of all registered public keys
      operationId: listPublicKeys
      tags:
        - public_key
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/publicKeysFilterSearch'
        - $ref: '#/components/parameters/sortPublicKeys'
      responses:
        '200':
          $ref: '#/components/responses/public_keys_list_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        default:
          $ref: '#/components/responses/problem'
    post:
      summary: Add new public key
      description: >
        Add a new public key for generating HD wallet addresses.

        The key must include its derivation path following BIP44/49/84 standards

        to identify the address type and blockchain network.

        Currently, only Bitcoin-based extended public keys (xpub, ypub, zpub)
        are supported.
      operationId: createPublicKey
      tags:
        - public_key
      requestBody:
        $ref: '#/components/requestBodies/create_public_key_request'
      responses:
        '200':
          $ref: '#/components/responses/create_public_key_response'
        '201':
          $ref: '#/components/responses/create_public_key_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        default:
          $ref: '#/components/responses/problem'
  /public_keys/{public_key_id}:
    delete:
      summary: Delete a public key
      description: Delete a public key by its unique identifier
      operationId: deletePublicKey
      parameters:
        - $ref: '#/components/parameters/publicKeyID'
      responses:
        '204':
          $ref: '#/components/responses/no_content_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        '404':
          $ref: '#/components/responses/not_found_problem'
        default:
          $ref: '#/components/responses/problem'
      tags:
        - public_key
    get:
      summary: Get a public key by ID
      description: Returns detailed information about a specific public key
      operationId: getPublicKey
      parameters:
        - $ref: '#/components/parameters/publicKeyID'
      responses:
        '200':
          $ref: '#/components/responses/public_key_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        '404':
          $ref: '#/components/responses/not_found_problem'
        default:
          $ref: '#/components/responses/problem'
      tags:
        - public_key
    patch:
      summary: Update public key label
      description: Update the label of an existing public key
      operationId: patchPublicKey
      parameters:
        - $ref: '#/components/parameters/publicKeyID'
      requestBody:
        $ref: '#/components/requestBodies/update_public_key_request'
      responses:
        '200':
          $ref: '#/components/responses/update_public_key_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        '404':
          $ref: '#/components/responses/not_found_problem'
        default:
          $ref: '#/components/responses/problem'
      tags:
        - public_key
  /public_keys/{public_key_id}/addresses:
    get:
      summary: Get addresses derived from public key
      description: |
        Returns a list of all addresses derived from this public key.
        These are HD addresses generated using the public key's derivation path
        and various indexes. The addresses are sorted by index by default.
      operationId: listPublicKeyAddresses
      tags:
        - public_key
        - address
      parameters:
        - $ref: '#/components/parameters/publicKeyID'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/sortAddresses'
        - $ref: '#/components/parameters/addressesFilterFormats'
        - $ref: '#/components/parameters/addressesFilterSearch'
        - $ref: '#/components/parameters/addressesFilterIsArchived'
      responses:
        '200':
          $ref: '#/components/responses/hd_addresses_list_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        '404':
          $ref: '#/components/responses/not_found_problem'
        default:
          $ref: '#/components/responses/problem'
    post:
      summary: Generate addresses from public key
      description: >
        Generates multiple HD addresses from the public key using either
        specific indexes or a range.

        The address format is automatically determined based on the public key's
        derivation path.


        You can specify either:

        - A list of specific indexes to generate addresses for

        - A range (from/to) to generate consecutive addresses


        If neither is specified, generates a single address at the next
        available index.
      operationId: generatePublicKeyAddresses
      tags:
        - public_key
        - address
      parameters:
        - $ref: '#/components/parameters/publicKeyID'
      requestBody:
        $ref: '#/components/requestBodies/generate_hd_addresses_request'
      responses:
        '200':
          $ref: '#/components/responses/generate_addresses_response'
        '201':
          $ref: '#/components/responses/generate_addresses_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        '404':
          $ref: '#/components/responses/not_found_problem'
        '422':
          $ref: '#/components/responses/precondition_problem'
        default:
          $ref: '#/components/responses/problem'
  /public_keys/{public_key_id}/addresses/next:
    post:
      summary: Generate next address from public key
      description: >
        Generates the next HD address from the public key by automatically
        determining the next available index.


        The system finds the highest existing index and generates the next
        sequential address. This is ideal for

        payment processing systems that need unique addresses for each
        transaction without manual index tracking.
      operationId: generateNextPublicKeyAddress
      tags:
        - public_key
        - address
      parameters:
        - $ref: '#/components/parameters/publicKeyID'
      requestBody:
        $ref: '#/components/requestBodies/generate_next_hd_address_request'
      responses:
        '200':
          $ref: '#/components/responses/hd_address_response'
        '201':
          $ref: '#/components/responses/hd_address_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        '404':
          $ref: '#/components/responses/not_found_problem'
        '422':
          $ref: '#/components/responses/precondition_problem'
        default:
          $ref: '#/components/responses/problem'
  /addresses:
    get:
      summary: Get list of all addresses
      description: |
        Returns a list of all addresses (both HD and external).
        This endpoint provides a unified view of all addresses in the system.
      operationId: listAddresses
      tags:
        - address
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/sortAddresses'
        - $ref: '#/components/parameters/addressesFilterFormats'
        - $ref: '#/components/parameters/addressesFilterSearch'
        - $ref: '#/components/parameters/addressesFilterKind'
        - $ref: '#/components/parameters/addressesFilterIsArchived'
      responses:
        '200':
          $ref: '#/components/responses/addresses_list_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        default:
          $ref: '#/components/responses/problem'
  /addresses/external:
    post:
      summary: Import external address
      description: >
        Imports an external address that is not derived from a public key.

        This is useful for tracking addresses from hardware wallets, exchanges,
        or other external sources.


        The address format must be specified to ensure proper validation across
        different blockchain ecosystems.
      operationId: createExternalAddress
      tags:
        - address
      requestBody:
        $ref: '#/components/requestBodies/create_external_address_request'
      responses:
        '200':
          $ref: '#/components/responses/external_address_response'
        '201':
          $ref: '#/components/responses/external_address_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        default:
          $ref: '#/components/responses/problem'
  /addresses/hd:
    get:
      summary: Get all HD addresses
      description: >
        Returns a list of all HD addresses derived from all public keys in the
        system.

        This endpoint provides a consolidated view of all HD addresses across
        all public keys,

        with support for filtering, sorting and pagination.
      operationId: listHDAddresses
      tags:
        - address
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/sortAddresses'
        - $ref: '#/components/parameters/addressesFilterFormats'
        - $ref: '#/components/parameters/addressesFilterSearch'
        - $ref: '#/components/parameters/addressesFilterIsArchived'
      responses:
        '200':
          $ref: '#/components/responses/hd_addresses_list_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        default:
          $ref: '#/components/responses/problem'
  /addresses/{address}:
    delete:
      description: >-
        Permanently deletes an address by its blockchain address. This action
        cannot be undone.
      operationId: deleteAddress
      parameters:
        - $ref: '#/components/parameters/address'
      responses:
        '204':
          $ref: '#/components/responses/no_content_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        '404':
          $ref: '#/components/responses/not_found_problem'
        default:
          $ref: '#/components/responses/problem'
      summary: Delete an address
      tags:
        - address
    get:
      description: Returns details of a specific address by its blockchain address
      operationId: getAddress
      parameters:
        - $ref: '#/components/parameters/address'
      responses:
        '200':
          $ref: '#/components/responses/address_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        '404':
          $ref: '#/components/responses/not_found_problem'
        default:
          $ref: '#/components/responses/problem'
      summary: Get a single address
      tags:
        - address
    patch:
      description: Updates address
      operationId: patchAddress
      parameters:
        - $ref: '#/components/parameters/address'
      requestBody:
        $ref: '#/components/requestBodies/update_address_request'
      responses:
        '204':
          $ref: '#/components/responses/no_content_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        '404':
          $ref: '#/components/responses/not_found_problem'
        default:
          $ref: '#/components/responses/problem'
      summary: Update address metadata
      tags:
        - address
  /addresses/{address}/hd:
    get:
      summary: Get HD address representation
      description: >
        Returns details of an address as HD address type. This endpoint will
        return

        the HD-specific information for an address including derivation details,

        public key reference, and HD metadata.


        If the address exists but is not an HD address, returns 404.

        If the address doesn't exist at all, also returns 404.
      operationId: getHDAddress
      tags:
        - address
      parameters:
        - $ref: '#/components/parameters/address'
      responses:
        '200':
          $ref: '#/components/responses/hd_address_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        '404':
          $ref: '#/components/responses/not_found_problem'
        default:
          $ref: '#/components/responses/problem'
  /addresses/{address}/external:
    get:
      summary: Get external address representation
      description: >
        Returns details of an address as external address type. This endpoint
        will return

        the external-specific information for an address including any imported
        metadata

        and external address properties.


        If the address exists but is not an external address, returns 404.

        If the address doesn't exist at all, also returns 404.
      operationId: getExternalAddress
      tags:
        - address
      parameters:
        - $ref: '#/components/parameters/address'
      responses:
        '200':
          $ref: '#/components/responses/external_address_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        '404':
          $ref: '#/components/responses/not_found_problem'
        default:
          $ref: '#/components/responses/problem'
  /addresses/{address}/balances:
    get:
      description: >
        Retrieve current balances for all active assets that have been
        discovered on the given address.


        The response is a simple key-value map where:

        - Key: Asset identifier (CAIP-19 format)

        - Value: Balance as a decimal string
      operationId: getAddressBalances
      parameters:
        - $ref: '#/components/parameters/address'
      responses:
        '200':
          $ref: '#/components/responses/address_balances_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        '404':
          $ref: '#/components/responses/not_found_problem'
        default:
          $ref: '#/components/responses/problem'
      summary: Get all active asset balances for an address
      tags:
        - address
  /assets:
    get:
      operationId: listAssets
      summary: Get list of all assets
      description: >-
        Returns a paginated list of all blockchain assets with filtering
        options.
      tags:
        - asset
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/sortAssets'
        - $ref: '#/components/parameters/assetsFilterChainGIDs'
        - $ref: '#/components/parameters/assetsFilterNamespaces'
        - $ref: '#/components/parameters/assetsFilterStatuses'
      responses:
        '200':
          $ref: '#/components/responses/assets_list_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        default:
          $ref: '#/components/responses/problem'
  /assets/{chain_gid}/{asset_path}/actions/archive:
    post:
      operationId: archiveAsset
      summary: Archive an asset
      description: >-
        Archives an asset by its Global Identifier (GID), removing it from
        active listings
      tags:
        - asset
      parameters:
        - $ref: '#/components/parameters/chainGID'
        - $ref: '#/components/parameters/assetPath'
      responses:
        '200':
          description: Asset activated successfully
        '204':
          description: Asset was already active
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        '404':
          $ref: '#/components/responses/not_found_problem'
        default:
          $ref: '#/components/responses/problem'
  /assets/{chain_gid}/{asset_path}/actions/restore:
    post:
      operationId: restoreAsset
      summary: Restore an archived asset
      description: >-
        Restores a previously archived asset by its Global Identifier (GID),
        making it active again
      tags:
        - asset
      parameters:
        - $ref: '#/components/parameters/chainGID'
        - $ref: '#/components/parameters/assetPath'
      responses:
        '200':
          description: Asset deactivated successfully
        '204':
          description: Asset was already inactive
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        '404':
          $ref: '#/components/responses/not_found_problem'
        default:
          $ref: '#/components/responses/problem'
  /tokens:
    get:
      operationId: listTokens
      summary: Get list of all known tokens
      description: >-
        Returns a list of all token assets. Includes native tokens and ERC-20
        tokens.
      tags:
        - token
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/sortTokens'
        - $ref: '#/components/parameters/tokensFilterSearch'
        - $ref: '#/components/parameters/tokensFilterChainGIDs'
      responses:
        '200':
          $ref: '#/components/responses/tokens_list_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        default:
          $ref: '#/components/responses/problem'
  /tokens/{chain_gid}/{asset_path}:
    post:
      operationId: createToken
      summary: Create a new token
      description: >-
        Creates a new token using its CAIP-19 identifier and automatically
        retrieves its metadata (name, symbol, decimals, type) from the
        blockchain.
      tags:
        - token
      parameters:
        - $ref: '#/components/parameters/chainGID'
        - $ref: '#/components/parameters/assetPath'
      responses:
        '200':
          $ref: '#/components/responses/token_response'
        '201':
          $ref: '#/components/responses/token_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        '404':
          $ref: '#/components/responses/not_found_problem'
        default:
          $ref: '#/components/responses/problem'
    get:
      operationId: getToken
      summary: Get details of a specific token
      description: Returns detailed information about the specified token asset.
      tags:
        - token
      parameters:
        - $ref: '#/components/parameters/chainGID'
        - $ref: '#/components/parameters/assetPath'
      responses:
        '200':
          $ref: '#/components/responses/token_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        '404':
          $ref: '#/components/responses/not_found_problem'
        default:
          $ref: '#/components/responses/problem'
  /transactions:
    get:
      operationId: listTransactions
      summary: Get list of transactions
      description: Returns a paginated list of transactions based on the provided filters.
      tags:
        - transaction
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/sortTransactions'
        - $ref: '#/components/parameters/transactionsFilterInitiatorAddress'
        - $ref: '#/components/parameters/transactionsFilterTargetAddress'
        - $ref: '#/components/parameters/transactionsFilterAddress'
        - $ref: '#/components/parameters/transactionsFilterChainGIDs'
        - $ref: '#/components/parameters/transactionsFilterIsSuccess'
      responses:
        '200':
          $ref: '#/components/responses/transactions_list_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        default:
          $ref: '#/components/responses/problem'
  /notification_channels:
    get:
      summary: Get list of notification channels
      description: Returns a paginated list of all notification delivery channels
      operationId: listNotificationChannels
      tags:
        - notification_channel
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/notificationChannelsFilterKind'
        - $ref: '#/components/parameters/notificationChannelsFilterArchived'
        - $ref: '#/components/parameters/notificationChannelsFilterSearch'
        - $ref: '#/components/parameters/sortNotificationChannels'
      responses:
        '200':
          $ref: '#/components/responses/notification_channels_list_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        default:
          $ref: '#/components/responses/problem'
  /notification_channels/nats:
    post:
      summary: Create NATS notification channel
      description: Creates a new NATS notification channel for subject-based messaging
      operationId: createNATSChannel
      tags:
        - notification_channel
      requestBody:
        $ref: '#/components/requestBodies/create_nats_channel_request'
      responses:
        '200':
          $ref: '#/components/responses/notification_channel_response'
        '201':
          $ref: '#/components/responses/notification_channel_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        default:
          $ref: '#/components/responses/problem'
  /notification_channels/nats/{notification_channel_id}:
    patch:
      summary: Update NATS notification channel
      description: Update the configuration of an existing NATS notification channel
      operationId: patchNATSChannel
      tags:
        - notification_channel
      parameters:
        - $ref: '#/components/parameters/notificationChannelID'
      requestBody:
        $ref: '#/components/requestBodies/update_nats_channel_request'
      responses:
        '200':
          $ref: '#/components/responses/notification_channel_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        '404':
          $ref: '#/components/responses/not_found_problem'
        default:
          $ref: '#/components/responses/problem'
  /notification_channels/telegram:
    post:
      summary: Create Telegram notification channel
      description: Creates a new Telegram notification channel for bot message delivery
      operationId: createTelegramChannel
      tags:
        - notification_channel
      requestBody:
        $ref: '#/components/requestBodies/create_telegram_channel_request'
      responses:
        '200':
          $ref: '#/components/responses/notification_channel_response'
        '201':
          $ref: '#/components/responses/notification_channel_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        default:
          $ref: '#/components/responses/problem'
  /notification_channels/telegram/{notification_channel_id}:
    patch:
      summary: Update Telegram notification channel
      description: Update the configuration of an existing Telegram notification channel
      operationId: patchTelegramChannel
      tags:
        - notification_channel
      parameters:
        - $ref: '#/components/parameters/notificationChannelID'
      requestBody:
        $ref: '#/components/requestBodies/update_telegram_channel_request'
      responses:
        '200':
          $ref: '#/components/responses/notification_channel_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        '404':
          $ref: '#/components/responses/not_found_problem'
        default:
          $ref: '#/components/responses/problem'
  /notification_channels/webhook:
    post:
      summary: Create Webhook notification channel
      description: Creates a new Webhook notification channel for HTTP callback delivery
      operationId: createWebhookChannel
      tags:
        - notification_channel
      requestBody:
        $ref: '#/components/requestBodies/create_webhook_channel_request'
      responses:
        '200':
          $ref: '#/components/responses/notification_channel_response'
        '201':
          $ref: '#/components/responses/notification_channel_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        default:
          $ref: '#/components/responses/problem'
  /notification_channels/webhook/{notification_channel_id}:
    patch:
      summary: Update Webhook notification channel
      description: Update the configuration of an existing Webhook notification channel
      operationId: patchWebhookChannel
      tags:
        - notification_channel
      parameters:
        - $ref: '#/components/parameters/notificationChannelID'
      requestBody:
        $ref: '#/components/requestBodies/update_webhook_channel_request'
      responses:
        '200':
          $ref: '#/components/responses/notification_channel_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        '404':
          $ref: '#/components/responses/not_found_problem'
        default:
          $ref: '#/components/responses/problem'
  /notification_channels/{notification_channel_id}:
    get:
      summary: Get notification channel by ID
      description: Returns detailed information about a specific notification channel
      operationId: getNotificationChannel
      tags:
        - notification_channel
      parameters:
        - $ref: '#/components/parameters/notificationChannelID'
      responses:
        '200':
          $ref: '#/components/responses/notification_channel_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        '404':
          $ref: '#/components/responses/not_found_problem'
        default:
          $ref: '#/components/responses/problem'
    delete:
      summary: Delete notification channel
      description: Delete a notification channel by its unique identifier
      operationId: deleteNotificationChannel
      tags:
        - notification_channel
      parameters:
        - $ref: '#/components/parameters/notificationChannelID'
      responses:
        '204':
          $ref: '#/components/responses/no_content_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        '404':
          $ref: '#/components/responses/not_found_problem'
        default:
          $ref: '#/components/responses/problem'
  /notification_channels/{notification_channel_id}/actions/archive:
    post:
      summary: Archive notification channel
      description: >-
        Archives (disables) a notification channel while preserving its
        configuration
      operationId: archiveNotificationChannel
      tags:
        - notification_channel
      parameters:
        - $ref: '#/components/parameters/notificationChannelID'
      responses:
        '204':
          $ref: '#/components/responses/no_content_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        '404':
          $ref: '#/components/responses/not_found_problem'
        default:
          $ref: '#/components/responses/problem'
  /notification_channels/{notification_channel_id}/actions/restore:
    post:
      summary: Restore notification channel
      description: Restores an archived notification channel, making it active again
      operationId: restoreNotificationChannel
      tags:
        - notification_channel
      parameters:
        - $ref: '#/components/parameters/notificationChannelID'
      responses:
        '204':
          $ref: '#/components/responses/no_content_response'
        '400':
          $ref: '#/components/responses/invalid_request_problem'
        '404':
          $ref: '#/components/responses/not_found_problem'
        default:
          $ref: '#/components/responses/problem'
  /version:
    get:
      description: Returns the current version of the vilna API service.
      operationId: getVersion
      responses:
        '200':
          $ref: '#/components/responses/version_response'
        '400':
          description: Invalid request (e.g., unsupported query parameter)
          $ref: '#/components/responses/invalid_request_problem'
        default:
          $ref: '#/components/responses/problem'
      security: []
      summary: Get API version
      tags:
        - system
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: API key for authentication
  parameters:
    limit:
      description: Maximum number of items to return
      in: query
      name: limit
      required: false
      schema:
        default: 20
        example: 20
        maximum: 100
        minimum: 1
        type: integer
    page:
      description: Page number for pagination
      in: query
      name: page
      required: false
      schema:
        default: 1
        example: 1
        minimum: 1
        type: integer
    sortBlockchains:
      name: sort_by
      in: query
      description: Field to sort results by. Use "-" prefix for descending order
      required: false
      schema:
        enum:
          - gid
          - '-gid'
          - name
          - '-name'
          - short_name
          - '-short_name'
          - full_name
          - '-full_name'
        example: name
        default: name
        type: string
    blockchainsFilterSearch:
      name: search
      in: query
      description: >-
        Performs a partial, case-insensitive match on blockchain name or short
        name fields.
      required: false
      schema:
        type: string
        maxLength: 64
        example: ethereum
    blockchainsFilterFamilies:
      name: families
      in: query
      description: Comma-separated list of chain families to include.
      required: false
      style: form
      explode: true
      schema:
        type: array
        items:
          $ref: '#/components/schemas/ChainFamily'
      example:
        - evm
        - bitcoin
    blockchainsFilterIsActive:
      name: is_active
      in: query
      description: >-
        When true, returns only active blockchains (being processed by workers).
        When false, returns only inactive ones.
      required: false
      schema:
        type: boolean
        example: true
    chainGID:
      name: chain_gid
      in: path
      description: Blockchain identifier in CAIP-2 format (namespace:reference)
      required: true
      schema:
        $ref: '#/components/schemas/ChainGID'
    sortBlocks:
      name: sort_by
      in: query
      description: Field to sort results by. Use "-" prefix for descending order
      required: false
      schema:
        enum:
          - number
          - '-number'
          - status
          - '-status'
        example: number
        default: number
        type: string
    blocksFilterChainGIDs:
      name: chain_gids
      in: query
      description: Comma-separated list of chain GIDs to filter blocks by.
      required: false
      style: form
      explode: true
      schema:
        type: array
        items:
          $ref: '#/components/schemas/ChainGID'
      example:
        - eip155:1
        - eip155:137
    blocksFilterStatuses:
      name: statuses
      in: query
      description: Comma-separated list of block statuses to include.
      required: false
      style: form
      explode: true
      schema:
        type: array
        items:
          type: string
          enum:
            - new
            - fetched
            - processed
            - confirmed
            - reorged
      example:
        - confirmed
        - processed
    blocksFilterFromBlock:
      name: from_block
      in: query
      description: Start from this block number (inclusive).
      required: false
      schema:
        type: integer
        format: int64
        minimum: 0
        example: 18500000
    blocksFilterToBlock:
      name: to_block
      in: query
      description: End at this block number (inclusive).
      required: false
      schema:
        type: integer
        format: int64
        minimum: 0
        example: 18500100
    blockNumber:
      name: block_number
      in: path
      description: Block number/height on the blockchain
      required: true
      schema:
        type: integer
        format: int64
        minimum: 0
        example: 18500000
    publicKeysFilterSearch:
      name: search
      in: query
      description: Search filter for public keys (partial match, case-insensitive)
      required: false
      schema:
        type: string
        maxLength: 32
        example: wallet
    sortPublicKeys:
      name: sort_by
      in: query
      description: Field to sort results by. Use "-" prefix for descending order
      required: false
      schema:
        type: string
        enum:
          - gid
          - '-gid'
          - label
          - '-label'
          - derivation_path
          - '-derivation_path'
          - created_at
          - '-created_at'
          - updated_at
          - '-updated_at'
        default: gid
        example: gid
    publicKeyID:
      name: public_key_id
      in: path
      description: Unique identifier (UUID) of the public key.
      required: true
      schema:
        $ref: '#/components/schemas/UUID'
    sortAddresses:
      name: sort_by
      in: query
      description: Field to sort results by. Use "-" prefix for descending order
      required: false
      schema:
        type: string
        enum:
          - label
          - '-label'
          - address
          - '-address'
          - created_at
          - '-created_at'
          - updated_at
          - '-updated_at'
        default: '-created_at'
        example: '-created_at'
    addressesFilterFormats:
      name: formats
      in: query
      description: Comma-separated list of address formats to include.
      required: false
      style: form
      explode: true
      schema:
        type: array
        items:
          $ref: '#/components/schemas/AddressFormat'
      example:
        - p2wpkh
        - evm
    addressesFilterSearch:
      name: search
      in: query
      description: Performs a partial, case-insensitive match on address or label fields.
      required: false
      schema:
        type: string
        maxLength: 100
        example: bc1q
    addressesFilterIsArchived:
      name: is_archived
      in: query
      description: >-
        When true, returns only archived addresses. When false, returns only
        active ones.
      required: false
      schema:
        type: boolean
        example: false
    addressesFilterKind:
      name: kind
      in: query
      description: Filter by address kind (`hd` or `external`).
      required: false
      schema:
        $ref: '#/components/schemas/AddressKind'
    address:
      name: address
      in: path
      description: >-
        Blockchain address in its native format (e.g.,
        0x8521E8b15eCEF4D4269Fded3E6694225E096959E for EVM chains)
      required: true
      schema:
        $ref: '#/components/schemas/AddressValue'
    sortAssets:
      name: sort_by
      in: query
      description: Field to sort results by. Use "-" prefix for descending order
      required: false
      schema:
        type: string
        enum:
          - gid
          - '-gid'
          - namespace
          - '-namespace'
          - reference
          - '-reference'
          - status
          - '-status'
          - created_at
          - '-created_at'
        default: '-created_at'
        example: '-created_at'
    assetsFilterChainGIDs:
      name: chain_gids
      in: query
      description: Filter assets by blockchain chain GIDs
      required: false
      style: form
      explode: true
      schema:
        type: array
        items:
          $ref: '#/components/schemas/ChainGID'
        example:
          - eip155:1
          - eip155:56
          - eip155:137
    assetsFilterNamespaces:
      name: namespaces
      in: query
      description: Filter assets by asset namespaces
      required: false
      style: form
      explode: true
      schema:
        type: array
        items:
          $ref: '#/components/schemas/AssetNamespace'
        example:
          - erc20
          - bep20
    assetsFilterStatuses:
      name: statuses
      in: query
      description: Filter assets by status
      required: false
      style: form
      explode: true
      schema:
        type: array
        items:
          $ref: '#/components/schemas/AssetStatus'
        example:
          - active
          - unknown
    assetPath:
      name: asset_path
      in: path
      description: >-
        Asset type identifier in CAIP-19 format
        (asset_namespace:asset_reference)
      required: true
      schema:
        $ref: '#/components/schemas/AssetPath'
    sortTokens:
      name: sort_by
      in: query
      description: Field to sort results by. Use "-" prefix for descending order
      required: false
      schema:
        type: string
        enum:
          - gid
          - '-gid'
          - address
          - '-address'
          - decimals
          - '-decimals'
          - name
          - '-name'
          - symbol
          - '-symbol'
          - created_at
          - '-created_at'
        default: created_at
        example: created_at
    tokensFilterSearch:
      name: search
      in: query
      description: >-
        Search filter for token address, symbols, or names (partial match,
        case-insensitive)
      required: false
      schema:
        type: string
        maxLength: 32
        example: USDT
    tokensFilterChainGIDs:
      name: chain_gids
      in: query
      description: Filter tokens by blockchain chain GIDs
      required: false
      style: form
      explode: true
      schema:
        type: array
        items:
          $ref: '#/components/schemas/ChainGID'
        example:
          - eip155:1
          - eip155:56
          - eip155:137
    sortTransactions:
      name: sort_by
      in: query
      description: Field to sort results by. Use "-" prefix for descending order
      required: false
      schema:
        type: string
        enum:
          - transaction_hash
          - '-transaction_hash'
          - block_number
          - '-block_number'
          - initiator
          - '-initiator'
          - target
          - '-target'
          - is_success
          - '-is_success'
          - confirmed_at
          - '-confirmed_at'
          - created_at
          - '-created_at'
        default: '-created_at'
        example: '-created_at'
    transactionsFilterInitiatorAddress:
      name: initiator_address
      in: query
      description: Filter transactions by initiator addresses (exact match)
      required: false
      style: form
      explode: true
      schema:
        type: array
        items:
          $ref: '#/components/schemas/AddressValue'
        example:
          - '0x742d35Cc6b3C0532925a3b8c17c8b4842f6c8E5a'
          - '0x123456789abcdef123456789abcdef123456789ab'
    transactionsFilterTargetAddress:
      name: target_address
      in: query
      description: Filter transactions by target addresses (exact match)
      required: false
      style: form
      explode: true
      schema:
        type: array
        items:
          $ref: '#/components/schemas/AddressValue'
        example:
          - '0xdAC17F958D2ee523a2206206994597C13D831ec7'
          - '0x9876543210abcdef9876543210abcdef98765432'
    transactionsFilterAddress:
      name: address
      in: query
      description: >-
        Filter transactions where any of the addresses is either initiator or
        target address
      required: false
      style: form
      explode: true
      schema:
        type: array
        items:
          $ref: '#/components/schemas/AddressValue'
        example:
          - '0x742d35Cc6b3C0532925a3b8c17c8b4842f6c8E5a'
          - '0xdAC17F958D2ee523a2206206994597C13D831ec7'
    transactionsFilterChainGIDs:
      name: chain_gids
      in: query
      description: Filter transactions by blockchain chain GIDs
      required: false
      style: form
      explode: true
      schema:
        type: array
        items:
          $ref: '#/components/schemas/ChainGID'
        example:
          - eip155:1
          - eip155:56
          - eip155:137
    transactionsFilterIsSuccess:
      name: is_success
      in: query
      description: Filter transactions by success status
      required: false
      schema:
        type: boolean
        example: true
    notificationChannelsFilterKind:
      name: kind
      in: query
      required: false
      description: |
        Filter notification channels by their delivery type.

        When specified, only channels of the given type will be returned:
        - `nats` — NATS subject-based messaging channels
        - `telegram` — Telegram bot message delivery channels
        - `webhook` — HTTP webhook callback channels
      schema:
        $ref: '#/components/schemas/NotificationChannelKind'
      example: webhook
    notificationChannelsFilterArchived:
      name: is_archived
      in: query
      required: false
      description: >
        Filter notification channels by their archived status.


        - `true` — Returns only archived (disabled) channels

        - `false` — Returns only active (enabled) channels

        - Omit parameter — Returns both active and archived channels


        Archived channels are temporarily disabled but retain their
        configuration

        for potential reactivation later.
      schema:
        type: boolean
      example: false
    notificationChannelsFilterSearch:
      name: search
      in: query
      required: false
      description: >
        Search notification channels by name using case-insensitive pattern
        matching.


        The search is performed on the channel name field using SQL ILIKE
        pattern matching:

        - Partial matches are supported

        - Case-insensitive search

        - Whitespace is normalized


        Examples:

        - `"webhook"` — matches channels with "webhook" in the name

        - `"prod"` — matches "Production Alerts", "prod-monitoring", etc.

        - `"alert"` — matches "System Alerts", "Critical Alert Channel", etc.
      schema:
        type: string
        minLength: 1
        maxLength: 128
      example: production
    sortNotificationChannels:
      name: sort_by
      in: query
      description: Field to sort results by. Use "-" prefix for descending order
      required: false
      schema:
        type: string
        enum:
          - name
          - '-name'
          - kind
          - '-kind'
          - created_at
          - '-created_at'
          - updated_at
          - '-updated_at'
        default: '-created_at'
        example: name
    notificationChannelID:
      name: notification_channel_id
      in: path
      description: Unique identifier (UUID) of the notification channel.
      required: true
      schema:
        $ref: '#/components/schemas/UUID'
  schemas:
    ChainFamily:
      description: >
        Chain family that identifies blockchain ecosystems united by common
        protocol or account model.


        **Available families:**

        - `evm`: Ethereum Virtual Machine-based blockchains

        - `bitcoin`: Bitcoin and Bitcoin-compatible networks

        - `solana`: Solana blockchain ecosystem

        - `tron`: Tron blockchain ecosystem


        The chain family is used to determine which blockchain ecosystem

        the address belongs to and how it should be generated or validated.
      enum:
        - evm
        - bitcoin
        - solana
        - tron
      example: evm
      type: string
    ChainGID:
      type: string
      description: >
        Blockchain identifier according to
        [CAIP-2](https://chainagnostic.org/CAIPs/caip-2).


        The **chain_gid** is a case-sensitive string uniquely identifying a
        blockchain.

        It is composed of:

        - **namespace** — a short identifier describing an ecosystem or standard
        (e.g. `eip155`, `cosmos`)

        - **reference** — an identifier for a specific blockchain within that
        namespace


        **Syntax**

        ```

        chain_id = namespace ":" reference

        namespace = [-a-z0-9]{3,8}

        reference = [-_a-zA-Z0-9]{1,32}

        ```


        **Examples**

        - `eip155:1` — Ethereum mainnet

        - `eip155:56` — Binance Smart Chain

        - `cosmos:cosmoshub-4` — Cosmos Hub mainnet

        - `bip122:000000000019d6689c085ae165831e93` — Bitcoin mainnet
      pattern: ^[a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32}$
      example: eip155:1
    Blockchain:
      description: >
        Represents a blockchain that is supported for monitoring and balance
        queries.

        Not all blockchains where tokens can be sent are supported - only those
        with active

        monitoring infrastructure can track balances and send notifications
        about balance changes.
      properties:
        gid:
          $ref: '#/components/schemas/ChainGID'
        image_url:
          description: URL to blockchain logo image
          example: https://cdn.vilna.io/assets/eip155:1/logo.png
          format: uri
          type: string
        name:
          description: Unique identifier name for the blockchain (e.g., `ethereum`)
          example: ethereum
          type: string
        short_name:
          description: Short abbreviation for the blockchain (e.g., `eth`)
          example: eth
          type: string
        is_active:
          description: Whether the blockchain is actively being processed
          example: true
          type: boolean
      required:
        - gid
        - name
        - short_name
        - image_url
        - is_active
      type: object
    PaginationMeta:
      properties:
        limit:
          description: Number of items per page
          example: 20
          type: integer
          format: uint
          minimum: 1
        page:
          description: Current page number
          example: 1
          type: integer
          format: uint
          minimum: 1
        total:
          description: Total number of items available
          example: 42
          type: integer
          format: uint
          minimum: 0
        total_pages:
          description: Total number of pages available
          example: 3
          type: integer
          format: uint
          minimum: 0
      required:
        - total
        - page
        - limit
        - total_pages
      type: object
    create_blockchain_request:
      description: Request to create a new blockchain for monitoring and balance queries
      properties:
        chain_gid:
          $ref: '#/components/schemas/ChainGID'
      required:
        - chain_gid
      type: object
    EVMEndpointURL:
      type: string
      format: uri
      description: EVM blockchain RPC endpoint URL for API calls
      example: https://ethereum-rpc.publicnode.com
    EVMWebSocketURL:
      type: string
      format: uri
      description: EVM blockchain WebSocket endpoint URL for real-time subscriptions
      example: wss://ethereum-rpc.publicnode.com
    SolanaEndpointURL:
      type: string
      format: uri
      description: Solana blockchain RPC endpoint URL for API calls
      example: https://solana-rpc.publicnode.com
    SolanaWebSocketURL:
      type: string
      format: uri
      description: Solana blockchain WebSocket endpoint URL for real-time subscriptions
      example: wss://solana-rpc.publicnode.com
    TronEVMEndpointURL:
      type: string
      format: uri
      description: Tron blockchain RPC endpoint URL for API calls
      example: https://tron-rpc.publicnode.com
    BitcoinEndpointURL:
      type: string
      format: uri
      description: Bitcoin blockchain RPC endpoint URL for API calls
      example: https://bitcoin-rpc.publicnode.com
    Block:
      description: >
        Represents a blockchain block with its processing status.

        Tracks blocks through their lifecycle from discovery to confirmation or
        reorganization.
      properties:
        chain_gid:
          $ref: '#/components/schemas/ChainGID'
          description: Blockchain identifier this block belongs to
        number:
          description: Block number/height on the blockchain
          type: integer
          format: int64
          example: 18500000
        hash:
          description: >-
            Block hash identifier unique per blockchain (null if not yet
            fetched)
          type: string
          example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
        status:
          description: |
            Current processing status of the block:
            - `new`: Block has been discovered but not yet fetched
            - `processed`: Block transactions have been analyzed and stored
            - `confirmed`: Block has reached minimum required confirmations
            - `reorged`: Block has been reorganized (chain reorg occurred)
          type: string
          enum:
            - new
            - processed
            - confirmed
            - reorged
          example: confirmed
      required:
        - chain_gid
        - number
        - status
      type: object
    UUID:
      description: Unique identifier in UUID format
      example: 550e8400-e29b-41d4-a716-446655440000
      format: uuid
      type: string
    PublicKeyValue:
      description: >
        Extended public key encoded in Base58Check format, compliant with

        BIP32 and SLIP-0132 specifications.


        An extended public key allows deriving a hierarchy of child public keys

        and addresses without exposing the corresponding private keys.


        Supported prefixes and address derivation types:


        **Mainnet**

        - **xpub** — Legacy P2PKH (BIP44), addresses typically starting with `1`

        - **ypub** — SegWit P2SH-P2WPKH (BIP49), addresses typically starting
        with `3`

        - **zpub** — Native SegWit P2WPKH (BIP84), addresses typically starting
        with `bc1`


        **Testnet**

        - **tpub** — Legacy P2PKH (BIP44)

        - **upub** — SegWit P2SH-P2WPKH (BIP49)

        - **vpub** — Native SegWit P2WPKH (BIP84)


        The prefix defines both the address derivation scheme and the target
        network

        (mainnet or testnet). The actual address format depends on the selected

        derivation path and network parameters.
      example: >-
        xpub6EFxzN6ZgMCZ1PxeRigmAhm2UBGzXtZNgznCEaWuEt9efBpJwAXFA4ZckBdR1pdMQ1pBgsey7ebjToZ5gYXveftB3zwoQ8NvEkimvyaz34i
      type: string
      pattern: ^(xpub|ypub|zpub|tpub|vpub|upub)[1-9A-HJ-NP-Za-km-z]{100,108}$
    PublicKeyLabel:
      description: User-friendly label for the public key
      example: Main Wallet
      maxLength: 32
      minLength: 1
      type: string
    DerivationPath:
      description: >
        HD wallet derivation path that identifies the address type, blockchain
        network, and account.

        Follows BIP44/49/84 standards with format: m / purpose' / coin_type' /
        account' / change


        The purpose field indicates the address type:

        - 44' for P2PKH addresses (Legacy)

        - 49' for P2SH-P2WPKH addresses (SegWit)

        - 84' for P2WPKH addresses (Native SegWit)


        Common examples:

        - m/44'/0'/0'/0 — Bitcoin Legacy external addresses

        - m/44'/0'/0'/1 — Bitcoin Legacy change addresses

        - m/49'/0'/0'/0 — Bitcoin SegWit external addresses

        - m/84'/0'/0'/0 — Bitcoin Native SegWit external addresses

        - m/44'/60'/0'/0 — Ethereum or Binance Smart Chain (BEP20) addresses

        - m/44'/137'/0'/0 — Polygon addresses

        - m/44'/714'/0'/0 — Binance Chain (BEP2) addresses


        The coin_type value follows SLIP-0044 registered coin types (e.g., 0 for
        Bitcoin, 60 for Ethereum, 137 for Polygon, 714 for Binance Chain).
      example: m/84'/0'/0'/0
      pattern: ^m/(44|49|84)'/\d+'\/\d+'\/\d+$
      type: string
    CreatedAt:
      description: Timestamp when the resource was created
      example: '2024-01-15T10:30:00Z'
      format: date-time
      type: string
    UpdatedAt:
      description: Timestamp when the resource was last updated
      example: '2024-01-15T10:30:00Z'
      format: date-time
      type: string
    PublicKey:
      type: object
      description: >
        Represents a hierarchical deterministic (HD) public key derived at a
        specific BIP32/44/49/84 path.

        Each public key corresponds to a particular derivation path (e.g.,
        m/44'/0'/0'/0)

        and allows generation of child addresses without exposing the private
        key.


        Currently, only **Bitcoin-based extended public keys** are supported.


        **Supported formats:**

        - **xpub** — Legacy P2PKH (BIP44)

        - **ypub** — SegWit P2SH-P2WPKH (BIP49)

        - **zpub** — Native SegWit P2WPKH (BIP84)


        These keys follow BIP32 serialization in Base58 format and can derive

        multiple child addresses for the specified account and change level.


        **Note:**

        EVM-compatible networks (e.g., Ethereum, BNB Smart Chain, Polygon) may
        use

        raw SECP256k1 public keys in the future (`0x04...` or `0x02...` /
        `0x03...`),

        but such formats are not yet supported in this API.


        The derivation path identifies the address type, blockchain network, and
        account:

        - **purpose** — defines the address type (44', 49', 84')

        - **coin_type** — identifies the blockchain (0' = Bitcoin, 60' =
        Ethereum, 137' = Polygon, 714' = BSC)

        - **account** — logical account index (usually 0')

        - **change** — 0 for external (receiving), 1 for internal (change)
        addresses
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        value:
          $ref: '#/components/schemas/PublicKeyValue'
        label:
          $ref: '#/components/schemas/PublicKeyLabel'
        derivation_path:
          $ref: '#/components/schemas/DerivationPath'
        created_at:
          $ref: '#/components/schemas/CreatedAt'
        updated_at:
          $ref: '#/components/schemas/UpdatedAt'
      required:
        - id
        - value
        - label
        - derivation_path
        - created_at
        - updated_at
    AddressFormat:
      description: >
        Blockchain address format that determines how the address should be
        interpreted and validated:


        **EVM-compatible blockchains:**

        - `evm`: Ethereum Virtual Machine compatible address (Ethereum, BSC,
        Polygon, Arbitrum, etc.)
          - Format: 0x followed by 40 hexadecimal characters
          - Example: `0x742d35Cc6634C0532925a3b844Bc454e4438f44e`

        **Solana:**

        - `solana`: Solana address
          - Format: Base58 encoded, 32-44 characters
          - Example: `5EYCAe5ijiHbZBU14TyKHADUrkaAfc4ZyTXKRVKp49F8`

        **Tron:**

        - `tron`: Tron address
          - Format: Base58 encoded, starts with T
          - Example: `TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH`

        **Bitcoin mainnet formats:**

        - `p2pkh`: Pay-to-Public-Key-Hash (Legacy)
          - Format: Starts with 1
          - Example: `1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa`

        - `p2sh`: Pay-to-Script-Hash
          - Format: Starts with 3
          - Example: `3Do92Dmff87UuY9Yiu2iFG2Kj9bpRaeJSF`

        - `p2wpkh`: Pay-to-Witness-Public-Key-Hash (Native SegWit)
          - Format: Starts with bc1q
          - Example: `bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh`

        - `p2wsh`: Pay-to-Witness-Script-Hash (Native SegWit)
          - Format: Starts with bc1q
          - Example: `bc1qrp33g0q4c70atj6hy6wuahcwxryadxw3kvjahxxxgf7rflwdlcjqqtf3a0`

        **Bitcoin testnet formats:**

        - `p2pkh-testnet`: Pay-to-Public-Key-Hash (Legacy testnet)
          - Format: Starts with m or n
          - Example: `mipcBbFg9gMiCh81Kj8tqqdgoZub1ZJRfn`

        - `p2sh-testnet`: Pay-to-Script-Hash (testnet)
          - Format: Starts with 2
          - Example: `2MzQwSSnBHWHqSAqtTVQ6v47XtaisrJa1Vc`

        - `p2wpkh-testnet`: Pay-to-Witness-Public-Key-Hash (Native SegWit
        testnet)
          - Format: Starts with tb1q
          - Example: `tb1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh`

        - `p2wsh-testnet`: Pay-to-Witness-Script-Hash (Native SegWit testnet)
          - Format: Starts with tb1q
          - Example: `tb1qrp33g0q4c70atj6hy6wuahcwxryadxw3kvjahxxxgf7rflwdlcjqqtf3a0`
      enum:
        - evm
        - solana
        - tron
        - p2pkh
        - p2sh
        - p2wpkh
        - p2wsh
        - p2pkh-testnet
        - p2sh-testnet
        - p2wpkh-testnet
        - p2wsh-testnet
      example: p2wpkh
      type: string
    AddressValue:
      description: >
        A blockchain address in its native format. This is a generic schema for
        any blockchain address,

        including addresses, smart contract addresses, and token contract
        addresses.


        The actual format depends on the blockchain network:


        - **EVM chains** (Ethereum, BSC, Polygon, etc.): 0x followed by 40
        hexadecimal characters
          - Example: `0x8521E8b15eCEF4D4269Fded3E6694225E096959E`

        - **Bitcoin**: Various formats depending on address type
          - P2PKH (Legacy): Starts with 1, Example: `1GxHzNEymq1MLhxpdWAMJLN1UusYJ2Sy45`
          - P2SH (Wrapped SegWit): Starts with 3, Example: `3Do92Dmff87UuY9Yiu2iFG2Kj9bpRaeJSF`
          - P2WPKH (Native SegWit): Starts with bc1, Example: `bc1q8faxe8g4u2v67qfwf9d8xhyl5tkkkphvet6r08`

        - **Solana**: Base58 encoded, 32-44 characters
          - Example: `5EYCAe5ijiHbZBU14TyKHADUrkaAfc4ZyTXKRVKp49F8`

        - **Tron**: Base58 encoded addresses starting with T
          - Example: `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t`

        - **Cosmos ecosystem**: Bech32 format with chain-specific prefix
          - Example: `cosmos1vx8knpllrj7n963p9ttd80w47kpacrhuts497x`

        This schema is intentionally generic to support addresses from any
        blockchain.

        The specific validation rules depend on the blockchain network and
        address type.
      example: '0x8521E8b15eCEF4D4269Fded3E6694225E096959E'
      maxLength: 128
      minLength: 1
      type: string
      pattern: ^[a-zA-Z0-9]+$
    AddressLabel:
      description: User-friendly label for the address
      example: user_45_deposit
      maxLength: 32
      type: string
      nullable: true
    AddressKind:
      description: >
        Kind of address in the system:

        - `hd`: HD (Hierarchical Deterministic) address derived from an extended
        public key

        - `external`: External address imported directly without derivation
      enum:
        - hd
        - external
      example: hd
      type: string
    AddressMeta:
      type: object
      description: >
        Optional metadata as key-value pairs for storing additional information
        about the address.

        Total size of all keys and values combined must not exceed 1000
        characters.


        Common use cases:

        - Tracking user associations (user_id, account_id)

        - Recording source information (exchange, wallet, service)

        - Business logic flags (archived, locked, category)

        - Custom application data
      additionalProperties:
        type: string
      example:
        user_id: '12345'
        source: exchange
        category: trading
    Address:
      type: object
      description: |
        Represents a blockchain address that can be monitored for transactions.
        This is a generalized address entity that contains common properties
        for all address types in the system.
      properties:
        value:
          $ref: '#/components/schemas/AddressValue'
        format:
          $ref: '#/components/schemas/AddressFormat'
        label:
          $ref: '#/components/schemas/AddressLabel'
        kind:
          $ref: '#/components/schemas/AddressKind'
        meta:
          $ref: '#/components/schemas/AddressMeta'
        created_at:
          $ref: '#/components/schemas/CreatedAt'
        updated_at:
          $ref: '#/components/schemas/UpdatedAt'
      required:
        - value
        - format
        - kind
        - created_at
        - updated_at
    HDAddress:
      allOf:
        - $ref: '#/components/schemas/Address'
        - type: object
          properties:
            public_key_id:
              $ref: '#/components/schemas/UUID'
              description: ID of the public key used to derive this HD address
            derivation_index:
              description: Address index in the HD wallet derivation sequence
              example: 45
              minimum: 0
              type: integer
          required:
            - public_key_id
            - derivation_index
      description: >
        An address derived from a hierarchical deterministic (HD) wallet public
        key.

        These addresses are generated using BIP32/44/49/84 standards and include

        derivation information (public key reference and index). The specific

        BIP standard used determines the address type:

        - BIP44: Legacy P2PKH addresses

        - BIP49: SegWit P2SH-P2WPKH addresses

        - BIP84: Native SegWit P2WPKH addresses

        Commonly used for generating deposit addresses for users while
        maintaining

        control of the master key offline.
    ChainFamilyForGeneration:
      description: >
        Chain family that identifies blockchain ecosystems united by common
        protocol or account model for address generation.


        **Available families for generation:**

        - `evm`: Ethereum Virtual Machine-based blockchains

        - `bitcoin`: Bitcoin and Bitcoin-compatible networks

        - `tron`: Tron blockchain ecosystem


        Note: Solana is not supported for HD address generation from public
        keys.


        The chain family is used to determine which blockchain ecosystem

        the address belongs to and how it should be generated or validated.
      enum:
        - evm
        - bitcoin
        - tron
      example: evm
      type: string
    ExternalAddress:
      allOf:
        - $ref: '#/components/schemas/Address'
        - type: object
      description: |
        An external address that was imported directly into the system.
        These addresses are not derived from a public key and don't have an
        associated derivation path. Typically used for watching addresses
        from external wallets or services.
    AssetNamespace:
      type: string
      enum:
        - erc20
        - trc20
        - bep20
        - token
        - slip44
      description: Asset namespace type
      example: erc20
    AssetStatus:
      type: string
      enum:
        - active
        - unknown
        - invalid
      description: Current status of the asset
      example: active
    AssetGID:
      description: >
        Asset identifier in CAIP-19 format. Identifies a asset across
        blockchains.

        Format: `<chain_gid>/<asset_namespace>:<asset_reference>`

        Examples: - Ethereum ETH: `eip155:1/slip44:60` - Ethereum USDT ERC-20:
        `eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7`
      example: eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7
      pattern: >-
        ^[-a-zA-Z0-9]{1,32}:[-a-zA-Z0-9]{1,64}/[-a-zA-Z0-9]{1,64}:[-a-zA-Z0-9]{1,128}$
      type: string
    Asset:
      type: object
      required:
        - gid
        - status
        - created_at
        - updated_at
      properties:
        gid:
          $ref: '#/components/schemas/AssetGID'
        status:
          $ref: '#/components/schemas/AssetStatus'
        created_at:
          $ref: '#/components/schemas/CreatedAt'
        updated_at:
          $ref: '#/components/schemas/UpdatedAt'
    AssetPath:
      type: string
      description: >
        A unique identifier for an asset type within a blockchain, based on
        [CAIP-19](https://chainagnostic.org/CAIPs/caip-19).

        This identifies the type of asset, such as a cryptocurrency or a token
        standard.


        The identifier combines two parts with a colon (`:`):

        - **Namespace**: the system or standard the asset belongs to (e.g.,
        `erc20`, `erc721`, `slip44`)

        - **Reference**: the specific asset identifier within that namespace
        (e.g., a token contract address or numeric ID)


        **Syntax**

        ```

        asset_id = asset_namespace ":" asset_reference

        asset_namespace = [-a-z0-9]{3,8}

        asset_reference = [-.%a-zA-Z0-9]{1,128}

        ```


        **Examples**

        - `slip44:60` — Ether (Ethereum’s native currency)

        - `erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F` — DAI ERC-20 token

        - `erc721:0x06012c8cf97BEaD5deAe237070F9587f8E7A266d` — CryptoKitties
        NFT collection
      pattern: ^[a-z0-9]{3,8}:[-.%a-zA-Z0-9]{1,128}$
      example: erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F
    TokenDecimals:
      description: Number of decimal places for the token (e.g., 6 for USDT, 18 for ETH)
      example: 6
      maximum: 18
      minimum: 0
      type: integer
    TokenName:
      description: Full token name (e.g., "Tether USD", "Ethereum", "Binance Coin")
      example: Tether USD
      type: string
    TokenSymbol:
      description: Token symbol (e.g., "USDT", "ETH", "BNB")
      example: USDT
      type: string
    Token:
      title: Token
      type: object
      description: >
        Represents a fungible blockchain token (e.g., ERC-20, BEP-20). Contains
        token-specific properties such as decimals, name, and symbol.
      properties:
        gid:
          $ref: '#/components/schemas/AssetGID'
        decimals:
          $ref: '#/components/schemas/TokenDecimals'
        name:
          $ref: '#/components/schemas/TokenName'
        symbol:
          $ref: '#/components/schemas/TokenSymbol'
        created_at:
          $ref: '#/components/schemas/CreatedAt'
      required:
        - gid
        - decimals
        - name
        - symbol
        - created_at
    AddressRef:
      type: object
      description: Reference to a blockchain address with minimal system context
      properties:
        value:
          $ref: '#/components/schemas/AddressValue'
        is_known:
          description: >-
            Whether this address is known/managed by the system (internal) or
            external
          type: boolean
          example: true
      required:
        - value
        - is_known
    TransferKind:
      type: string
      description: Type of asset transfer within a blockchain transaction
      enum:
        - native
        - fungible
      example: native
      x-enum-descriptions:
        native: >-
          Transfer of the blockchain's native cryptocurrency (e.g., ETH, BNB,
          MATIC)
        fungible: Transfer of fungible tokens (e.g., ERC-20, BEP-20, ERC-1155)
    EVMTransferMeta:
      type: object
      description: >-
        Metadata specific to EVM (Ethereum Virtual Machine) blockchain
        transfers.
      properties:
        log_index:
          type: integer
          description: >-
            Index of the log entry that generated this transfer (for token
            transfers)
          format: uint32
          example: 2
      additionalProperties: false
    BitcoinTransferMeta:
      type: object
      description: Metadata specific to Bitcoin blockchain transfers.
      properties:
        script_type:
          type: string
          description: Type of script used in the transfer
          enum:
            - P2PKH
            - P2SH
            - P2WPKH
            - P2WSH
            - P2TR
            - UNKNOWN
          example: P2WPKH
        is_coinbase:
          type: boolean
          description: Whether this transfer is from a coinbase transaction
          example: false
      additionalProperties: false
    SolanaTransferMeta:
      type: object
      description: Metadata specific to Solana blockchain transfers.
      properties:
        program_id:
          type: string
          description: Public key of the program that executed this transfer
          pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
          example: '11111111111111111111111111111112'
        instruction_index:
          type: integer
          description: Index of the instruction within the transaction
          format: uint32
          example: 0
      additionalProperties: false
    TronTransferMeta:
      type: object
      description: Metadata specific to Tron blockchain transfers.
      properties: {}
      additionalProperties: false
    TransferMeta:
      type: object
      description: >
        Additional blockchain-specific metadata for the transfer. The structure
        varies based on the blockchain's

        technical requirements and available transaction data. This field
        contains essential metadata that helps

        identify and process transfers within the context of their respective
        blockchain ecosystems.
      oneOf:
        - $ref: '#/components/schemas/EVMTransferMeta'
        - $ref: '#/components/schemas/BitcoinTransferMeta'
        - $ref: '#/components/schemas/SolanaTransferMeta'
        - $ref: '#/components/schemas/TronTransferMeta'
    Transfer:
      type: object
      description: >
        Represents a single asset transfer within a blockchain transaction.
        Covers native coins, fungible tokens, and in future NFT/semi-fungible
        assets.
      properties:
        asset_gid:
          description: Unique identifier of the transferred asset
          $ref: '#/components/schemas/AssetGID'
        sequence:
          description: >
            Sequential index of the transfer within the transaction, starting
            from 0. Defines order of transfers and ensures uniqueness per
            transaction.
          type: integer
          format: uint16
          minimum: 0
          example: 0
        kind:
          $ref: '#/components/schemas/TransferKind'
        sender:
          description: >
            Address that sent the asset. Null if the transfer originates from
            protocol/system (e.g., mint, coinbase).
          $ref: '#/components/schemas/AddressRef'
        recipient:
          description: >
            Address that received the asset. Null if the transfer does not have
            a direct recipient (e.g., burned, gas, contract execution without
            recipient).
          $ref: '#/components/schemas/AddressRef'
        amount:
          description: >-
            Amount transferred in the smallest unit of the asset (without
            decimal adjustment)
          type: string
          pattern: ^[0-9]+$
          example: '1000000000000000000'
        meta:
          description: Additional blockchain-specific metadata for the transfer
          $ref: '#/components/schemas/TransferMeta'
      required:
        - asset_gid
        - sequence
        - kind
        - amount
    Transaction:
      type: object
      description: >
        Represents a blockchain transaction containing one or more asset
        transfers. Tracks the transaction details including initiator, target,
        block, and execution status.
      properties:
        transaction_hash:
          description: Hash of the transaction on the blockchain
          type: string
          example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
        chain_gid:
          $ref: '#/components/schemas/ChainGID'
        chain_family:
          $ref: '#/components/schemas/ChainFamily'
        block_number:
          description: Block number containing the transaction
          type: integer
          format: uint64
          example: 1974382
        initiator:
          description: >
            Account that authorized the transaction (signer or fee payer).
            Nullable for networks that allow protocol-originated transactions.
          $ref: '#/components/schemas/AddressRef'
        target:
          description: >
            Primary execution target (contract, program, or recipient). Null for
            networks that do not have an execution target (e.g., UTXO-based
            chains like Bitcoin).
          $ref: '#/components/schemas/AddressRef'
        transfers:
          description: >
            Collection of asset transfers within this transaction (e.g., ERC-20,
            ETH, BTC outputs, Solana SPL tokens). Always contains at least one
            transfer.
          type: array
          items:
            $ref: '#/components/schemas/Transfer'
          minItems: 1
        is_success:
          description: Whether the transaction executed successfully
          type: boolean
          example: true
        created_at:
          $ref: '#/components/schemas/CreatedAt'
        confirmed_at:
          description: Timestamp when the transaction was confirmed on the blockchain
          type: string
          format: date-time
          example: '2024-01-15T14:30:00Z'
      required:
        - transaction_hash
        - chain_gid
        - chain_family
        - initiator
        - transfers
        - is_success
        - created_at
    NotificationChannelKind:
      type: string
      description: >
        Defines the type of notification delivery channel.


        Each kind determines the transport mechanism and configuration
        structure:

        - **nats** — NATS subject-based messaging for internal microservice
        communication

        - **telegram** — Telegram bot message delivery to chats or direct
        messages

        - **webhook** — HTTP POST callbacks to external endpoints
      enum:
        - nats
        - telegram
        - webhook
      example: webhook
    NotificationChannelName:
      type: string
      description: >
        User-defined human-readable name for the notification channel.


        Used to identify and distinguish between different notification
        channels.

        The name should be descriptive and help users understand the purpose

        or destination of the channel.
      minLength: 1
      maxLength: 255
      example: Production Alerts Webhook
    NATSServerURL:
      type: string
      format: uri
      description: >
        NATS server URL for connection.


        Specifies the NATS server endpoint where notifications will be
        published.

        Supports various NATS URL formats:

        - `nats://localhost:4222` - Standard NATS connection

        - `nats://user:pass@nats.example.com:4222` - With authentication


        **Security Note:**

        URLs containing credentials should be handled securely and may be

        masked in API responses.
      example: nats://nats.example.com:4222
    NATSSubject:
      type: string
      description: >
        NATS subject (topic) where notifications will be published.


        Subjects are hierarchical and use dot notation (e.g.,
        "notifications.alerts.critical").

        Wildcards can be used for subscription patterns:

        - `*` matches any single token

        - `>` matches any number of tokens at the end


        Examples:

        - "notifications.system.alerts"

        - "events.user.created"

        - "monitoring.metrics.cpu"
      minLength: 1
      maxLength: 255
      example: notifications.webhooks.delivery
    NATSChannelConfig:
      type: object
      description: >
        Configuration for NATS notification channels.


        NATS channels deliver notifications through subject-based messaging,

        typically used for internal microservice communication and event
        distribution.


        The subject defines the NATS topic where notifications will be
        published.

        Subscribers can listen to specific subjects or use wildcards for pattern
        matching.


        The URL specifies which NATS server to connect to for message
        publishing.
      properties:
        url:
          $ref: '#/components/schemas/NATSServerURL'
        subject:
          $ref: '#/components/schemas/NATSSubject'
      required:
        - url
        - subject
      additionalProperties: false
    TelegramBotToken:
      type: string
      description: |
        Telegram Bot API token obtained from @BotFather.

        Format: {bot_id}:{auth_token}
        Example: "123456789:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"

        **Security Note:**
        This is sensitive data and should be handled securely.
        In some API responses, this may be masked or omitted.
      pattern: ^\d{7,12}:[A-Za-z0-9_-]{35}$
      example: 123456789:ABCDEFGHIJKLMNOPQRSTUVWXYZ123456789
    TelegramChatID:
      type: integer
      format: int64
      description: |
        Telegram chat ID where notifications will be sent.

        Chat ID formats:
        - Private chats (positive numbers)
        - Group chats (negative numbers)
        - Channel chats (negative numbers starting with -100)

        You can obtain chat IDs by:
        - Adding the bot to a chat and using /start command
        - Using Telegram Bot API methods like getUpdates
        - Using @userinfobot for user/chat information
      example: -1001234567890
    TelegramChannelConfig:
      type: object
      description: >
        Configuration for Telegram notification channels.


        Telegram channels deliver notifications through the Telegram Bot API,

        sending messages to specific chats, channels, or direct messages to
        users.


        Requires a bot token (obtained from @BotFather) and a chat ID where

        messages should be delivered. Chat IDs can be for:

        - Private chats (positive numbers)

        - Group chats (negative numbers)

        - Channel chats (negative numbers starting with -100)
      properties:
        bot_token:
          $ref: '#/components/schemas/TelegramBotToken'
        chat_id:
          $ref: '#/components/schemas/TelegramChatID'
      required:
        - bot_token
        - chat_id
      additionalProperties: false
    WebhookURL:
      type: string
      format: uri
      description: |
        HTTP/HTTPS URL endpoint where notification webhooks will be sent.

        The URL must be accessible from the notification service and should
        accept POST requests with JSON payloads. Only HTTP and HTTPS protocols
        are supported for security reasons.

        **Security Note:**
        URLs containing sensitive information (API keys in query params)
        should use headers for authentication instead.
      example: https://api.example.com/webhooks/notifications
    WebhookHeaders:
      type: object
      description: |
        Optional HTTP headers to include with webhook requests.

        Commonly used for:
        - Authentication: "Authorization: Bearer token"
        - Content type: "Content-Type: application/json"
        - API keys: "X-API-Key: your-api-key"
        - Custom headers for routing or identification

        **Security Note:**
        Sensitive headers (tokens, API keys) should be handled securely
        and may be masked in API responses.
      additionalProperties:
        type: string
      example:
        Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        Content-Type: application/json
        X-API-Key: your-secret-api-key
    WebhookChannelConfig:
      type: object
      description: >
        Configuration for Webhook notification channels.


        Webhook channels deliver notifications via HTTP POST requests to
        external endpoints.

        This is commonly used for integrating with external systems, monitoring
        tools,

        or triggering actions in third-party applications.


        The webhook will receive notification payloads as JSON in the request
        body.

        Optional headers can be configured for authentication or content type
        specification.
      properties:
        url:
          $ref: '#/components/schemas/WebhookURL'
        headers:
          $ref: '#/components/schemas/WebhookHeaders'
      required:
        - url
        - headers
      additionalProperties: false
    NotificationChannelConfig:
      type: object
      description: >
        Configuration structure for notification channels. The exact schema
        depends on the channel kind.


        Each channel type has specific configuration requirements:

        - **NATS channels** require a subject for message routing

        - **Telegram channels** require bot token and chat ID for message
        delivery

        - **Webhook channels** require URL and optional headers/authentication
      oneOf:
        - $ref: '#/components/schemas/NATSChannelConfig'
        - $ref: '#/components/schemas/TelegramChannelConfig'
        - $ref: '#/components/schemas/WebhookChannelConfig'
    NotificationChannel:
      type: object
      description: >
        Represents a notification delivery channel that defines how and where
        notification events are sent.


        Channels can be configured to deliver notifications through various
        transports:

        - **NATS** — Subject-based messaging for internal microservice
        communication

        - **Telegram** — Bot-based message delivery to Telegram chats/users

        - **Webhook** — HTTP POST callbacks to external endpoints


        Each channel has a specific configuration structure based on its type
        (kind) and can be

        temporarily disabled by archiving without losing the configuration.


        **Security Note:**

        Sensitive configuration data (bot tokens, webhook URLs) should be
        handled securely

        and may be masked or omitted in certain API responses.
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        kind:
          $ref: '#/components/schemas/NotificationChannelKind'
        name:
          $ref: '#/components/schemas/NotificationChannelName'
        config:
          $ref: '#/components/schemas/NotificationChannelConfig'
        is_archived:
          type: boolean
          description: Indicates whether the notification channel is archived (disabled)
          example: false
        created_at:
          $ref: '#/components/schemas/CreatedAt'
        updated_at:
          $ref: '#/components/schemas/UpdatedAt'
      required:
        - id
        - kind
        - name
        - config
        - is_archived
        - created_at
        - updated_at
    VersionInfo:
      properties:
        version:
          description: Current API version
          example: 1.0.0
          type: string
      required:
        - version
      type: object
  responses:
    problem:
      content:
        application/problem+json:
          schema:
            properties:
              detail:
                description: >-
                  A human-readable explanation specific to this occurrence of
                  the problem
                example: An unexpected error occurred while processing your request
                type: string
              instance:
                description: >-
                  A URI reference that identifies the specific occurrence of the
                  problem
                example: /errors/1234567890
                type: string
              status:
                description: The HTTP status code
                example: 500
                type: integer
              title:
                description: A short, human-readable summary of the problem type
                example: Internal Server Error
                type: string
              type:
                description: A URI reference that identifies the problem type
                example: https://api.vilna.io/problems/internal-error
                format: uri
                type: string
            required:
              - type
              - title
              - status
            type: object
      description: Unexpected error
    blockchains_list_response:
      content:
        application/json:
          example:
            items:
              - name: Ethereum
                gid: eip155:1
                image_url: >-
                  https://raw.githubusercontent.com/vilna-io/icons/refs/heads/main/chains/ethereum.svg
                short_name: eth
                is_active: true
              - name: Ethereum Sepolia
                gid: eip155:11155111
                image_url: >-
                  https://raw.githubusercontent.com/vilna-io/icons/refs/heads/main/chains/ethereum-sepolia.svg
                short_name: eth-sepolia
                is_active: true
              - name: Arbitrum One
                gid: eip155:42161
                image_url: >-
                  https://raw.githubusercontent.com/vilna-io/icons/refs/heads/main/chains/arbitrum.svg
                short_name: arb
                is_active: true
              - name: Arbitrum Goerli
                gid: eip155:421613
                image_url: >-
                  https://raw.githubusercontent.com/vilna-io/icons/refs/heads/main/chains/arbitrum-goerli.svg
                short_name: arb-goerli
                is_active: false
              - name: Optimism
                gid: eip155:10
                image_url: >-
                  https://raw.githubusercontent.com/vilna-io/icons/refs/heads/main/chains/optimism.svg
                short_name: op
                is_active: true
              - name: Optimism Goerli
                gid: eip155:420
                image_url: >-
                  https://raw.githubusercontent.com/vilna-io/icons/refs/heads/main/chains/optimism-goerli.svg
                short_name: op-goerli
                is_active: false
              - name: Base
                gid: eip155:8453
                image_url: >-
                  https://raw.githubusercontent.com/vilna-io/icons/refs/heads/main/chains/base.svg
                short_name: base
                is_active: true
              - name: Base Sepolia
                gid: eip155:84531
                image_url: >-
                  https://raw.githubusercontent.com/vilna-io/icons/refs/heads/main/chains/base-sepolia.svg
                short_name: base-sepolia
                is_active: false
              - name: BNB Smart Chain
                gid: eip155:56
                image_url: >-
                  https://raw.githubusercontent.com/vilna-io/icons/refs/heads/main/chains/binance-smart-chain.svg
                short_name: bsc
                is_active: true
              - name: BNB Smart Chain Testnet
                gid: eip155:97
                image_url: >-
                  https://raw.githubusercontent.com/vilna-io/icons/refs/heads/main/chains/binance-smart-chain-testnet.svg
                short_name: bsc-testnet
                is_active: false
              - name: Polygon
                gid: eip155:137
                image_url: >-
                  https://raw.githubusercontent.com/vilna-io/icons/refs/heads/main/chains/polygon.svg
                short_name: matic
                is_active: true
              - name: Polygon Mumbai
                gid: eip155:80001
                image_url: >-
                  https://raw.githubusercontent.com/vilna-io/icons/refs/heads/main/chains/polygon-mumbai.svg
                short_name: matic-mumbai
                is_active: false
              - name: Avalanche
                gid: eip155:43114
                image_url: >-
                  https://raw.githubusercontent.com/vilna-io/icons/refs/heads/main/chains/avalanche.svg
                short_name: avax
                is_active: true
              - name: Bitcoin
                gid: bip122:000000000019d6689c085ae165831e93
                image_url: >-
                  https://raw.githubusercontent.com/vilna-io/icons/refs/heads/main/chains/bitcoin.svg
                short_name: btc
                is_active: true
              - name: Litecoin
                gid: bip122:12a765e31ffd4059bada1e25190f6e98
                image_url: >-
                  https://raw.githubusercontent.com/vilna-io/icons/refs/heads/main/chains/litecoin.svg
                short_name: ltc
                is_active: false
              - name: Bitcoin Cash
                gid: bip122:000000000000000000651ef99cb9fcbe
                image_url: >-
                  https://raw.githubusercontent.com/vilna-io/icons/refs/heads/main/chains/bitcoin-cash.svg
                short_name: bch
                is_active: false
              - name: Dogecoin
                gid: bip122:1a91e3dace36e2be3bf030a65679fe82
                image_url: >-
                  https://raw.githubusercontent.com/vilna-io/icons/refs/heads/main/chains/dogecoin.svg
                short_name: doge
                is_active: false
              - name: Dash
                gid: bip122:00000fffffffffffffffffffffffffff
                image_url: >-
                  https://raw.githubusercontent.com/vilna-io/icons/refs/heads/main/chains/dash.svg
                short_name: dash
                is_active: false
              - name: Zcash
                gid: bip122:00040fe8f07f617ccf58bb4dfc6e6dc9
                image_url: >-
                  https://raw.githubusercontent.com/vilna-io/icons/refs/heads/main/chains/zcash.svg
                short_name: zec
                is_active: false
              - name: Solana
                gid: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
                image_url: >-
                  https://raw.githubusercontent.com/vilna-io/icons/refs/heads/main/chains/solana.svg
                short_name: sol
                is_active: true
              - name: Cosmos Hub
                gid: cosmos:cosmoshub-4
                image_url: >-
                  https://raw.githubusercontent.com/vilna-io/icons/refs/heads/main/chains/cosmos.svg
                short_name: atom
                is_active: false
              - name: Cardano
                gid: cardano:mainnet
                image_url: >-
                  https://raw.githubusercontent.com/vilna-io/icons/refs/heads/main/chains/cardano.svg
                short_name: ada
                is_active: false
              - name: Tron
                gid: tron:mainnet
                image_url: >-
                  https://raw.githubusercontent.com/vilna-io/icons/refs/heads/main/chains/tron.svg
                short_name: trx
                is_active: true
              - name: NEAR Protocol
                gid: near:mainnet
                image_url: >-
                  https://raw.githubusercontent.com/vilna-io/icons/refs/heads/main/chains/near-protocol.svg
                short_name: near
                is_active: false
              - name: TON
                gid: ton:mainnet
                image_url: >-
                  https://raw.githubusercontent.com/vilna-io/icons/refs/heads/main/chains/ton.svg
                short_name: ton
                is_active: false
              - name: Monero
                gid: monero:mainnet
                image_url: >-
                  https://raw.githubusercontent.com/vilna-io/icons/refs/heads/main/chains/monero.svg
                short_name: xmr
                is_active: false
              - name: Tezos
                gid: tezos:mainnet
                image_url: >-
                  https://raw.githubusercontent.com/vilna-io/icons/refs/heads/main/chains/tezos.svg
                short_name: xtz
                is_active: false
            meta:
              limit: 20
              page: 1
              total: 50
              total_pages: 3
          schema:
            properties:
              items:
                items:
                  $ref: '#/components/schemas/Blockchain'
                type: array
              meta:
                $ref: '#/components/schemas/PaginationMeta'
            required:
              - items
              - meta
            type: object
      description: List of supported blockchains for monitoring and balance queries
    invalid_request_problem:
      description: Bad request (e.g., missing or invalid fields)
      content:
        application/problem+json:
          schema:
            type: object
            required:
              - type
              - title
              - status
            properties:
              type:
                type: string
                format: uri
                description: A URI reference that identifies the problem type
                example: https://docs.vilna.io/apis/problems/invalid-request
              title:
                type: string
                description: A short, human-readable summary of the problem type
                example: Invalid Request
              status:
                type: integer
                description: The HTTP status code
                example: 400
              detail:
                type: string
                description: >-
                  A human-readable explanation specific to this occurrence of
                  the problem
                example: Validation error
              instance:
                type: string
                description: >-
                  A URI reference that identifies the specific occurrence of the
                  problem
                example: /errors?id=XXXXXX-xxxxx
              fields:
                type: array
                description: List of invalid fields in the request
                items:
                  type: object
                  required:
                    - name
                    - reason
                  properties:
                    name:
                      type: string
                      description: The name of the invalid field
                      example: meta
                    reason:
                      type: string
                      description: Why this field is invalid
                      example: >-
                        Exceeded maximum data size — must not exceed 1000
                        characters
    blockchain_response:
      description: Successfully created blockchain
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Blockchain'
    not_found_problem:
      description: Not Found - The requested resource does not exist
      content:
        application/problem+json:
          schema:
            type: object
            required:
              - type
              - title
              - status
            properties:
              type:
                type: string
                format: uri
                description: A URI reference that identifies the problem type
                example: https://docs.vilna.io/apis/problems/not-found
              title:
                type: string
                description: A short, human-readable summary of the problem type
                example: Not Found
              status:
                type: integer
                description: The HTTP status code
                example: 404
              detail:
                type: string
                description: >-
                  A human-readable explanation specific to this occurrence of
                  the problem
                example: The requested resource was not found
              instance:
                type: string
                description: >-
                  A URI reference that identifies the specific occurrence of the
                  problem
                example: /errors?id=XXXXXX-xxxxx
    blocks_list_response:
      content:
        application/json:
          example:
            items:
              - chain_gid: eip155:1
                number: 18500000
                hash: >-
                  0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
                status: confirmed
              - chain_gid: eip155:1
                number: 18499999
                hash: >-
                  0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890
                status: processed
              - chain_gid: eip155:1
                number: 18499997
                status: new
              - chain_gid: eip155:1
                number: 18499996
                hash: >-
                  0x9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba
                status: confirmed
            meta:
              limit: 20
              page: 1
              total: 18500001
              total_pages: 925001
          schema:
            properties:
              items:
                items:
                  $ref: '#/components/schemas/Block'
                type: array
              meta:
                $ref: '#/components/schemas/PaginationMeta'
            required:
              - items
              - meta
            type: object
      description: List of blockchain blocks with their processing status
    block_response:
      description: Single blockchain block
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Block'
          example:
            chain_gid: eip155:1
            number: 18500000
            hash: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
            status: confirmed
    public_keys_list_response:
      content:
        application/json:
          examples:
            multiple_keys:
              summary: List with multiple public keys
              value:
                items:
                  - id: 550e8400-e29b-41d4-a716-446655440000
                    value: >-
                      xpub6EFxzN6ZgMCZ1PxeRigmAhm2UBGzXtZNgznCEaWuEt9efBpJwAXFA4ZckBdR1pdMQ1pBgsey7ebjToZ5gYXveftB3zwoQ8NvEkimvyaz34i
                    label: Main Bitcoin Wallet
                    derivation_path: m/44'/0'/0'/0
                    created_at: '2025-01-15T12:00:00Z'
                    updated_at: '2025-01-15T12:00:00Z'
                  - id: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
                    value: >-
                      ypub6ZtCaoXpd9GqwDpovQU2XHwiTRFRiZdH6uCN5FUbR9hm8uVq4An6z1JyAfWAhx62D2QzuZAXLPXSDEZPHR81TFwGK6skZYjihxo1MYcqQra
                    label: SegWit Wallet
                    derivation_path: m/49'/0'/0'/1
                    created_at: '2025-01-14T10:30:00Z'
                    updated_at: '2025-01-14T10:30:00Z'
                  - id: 7ba7b820-9dad-11d1-80b4-00c04fd430c8
                    value: >-
                      zpub6svdUH71uTR9YXumEJroNo51GfHdASMmzKFafeBr51yEzf4gj4cPBafQDjk18AGTZSfhXi8uMuuZKpSdmzHjZDTDCVK3KjVYj1NKUTFfCkk
                    label: Native SegWit Wallet
                    derivation_path: m/84'/0'/0'/0
                    created_at: '2025-01-13T09:15:00Z'
                    updated_at: '2025-01-13T09:15:00Z'
                  - id: 8ca8c850-9dad-11d1-80b4-00c04fd430c8
                    value: >-
                      xpub6F7C1ZtQ411zykk6KTEoQMqfNdxiSA4uxAwAoqFanijnAavqQvVmh5zZCH6Swhdbzt2HuMRLx4chEVRZu9ic4Cnkkq5AsQcmjeMASk6FLqf
                    label: Ethereum Wallet
                    derivation_path: m/44'/60'/0'/0
                    created_at: '2025-01-12T14:20:00Z'
                    updated_at: '2025-01-12T14:20:00Z'
                  - id: 9da9d860-9dad-11d1-80b4-00c04fd430c8
                    value: >-
                      xpub6Dm2HNwvdJF1JcJ4eXvmvmgXqoTp6LG8CN32Xx3uppekAfPxZ8Es6doee9KkA6BLeSM3LgU3wXjjb5RaqSwtSBVBKETtQfcsx9dibMdEqGS
                    label: Polygon Wallet
                    derivation_path: m/44'/60'/2'/0
                    created_at: '2025-01-11T16:45:00Z'
                    updated_at: '2025-01-11T16:45:00Z'
                meta:
                  limit: 20
                  page: 1
                  total: 5
                  total_pages: 1
            empty_list:
              summary: Empty list
              value:
                items: []
                meta:
                  limit: 20
                  page: 1
                  total: 0
                  total_pages: 0
            paginated:
              summary: Paginated results
              value:
                items:
                  - id: 550e8400-e29b-41d4-a716-446655440000
                    value: >-
                      xpub6EFxzN6ZgMCZ1PxeRigmAhm2UBGzXtZNgznCEaWuEt9efBpJwAXFA4ZckBdR1pdMQ1pBgsey7ebjToZ5gYXveftB3zwoQ8NvEkimvyaz34i
                    label: BTC Legacy Wallet 1
                    derivation_path: m/44'/0'/0'/0
                    created_at: '2025-01-15T12:00:00Z'
                    updated_at: '2025-01-15T12:00:00Z'
                  - id: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
                    value: >-
                      xpub6EyLdA5Szo7bTF4Lsc1zuMNVirc5V9EZMcMRv2vU85hK4Zd8H4gQF1cVqBNJGn1orqYVpF22sxuWxmxns5UXL9fzZ1VPMpFcJna6thysmDM
                    label: BTC Legacy Wallet 2
                    derivation_path: m/44'/0'/1'/0
                    created_at: '2025-01-14T10:30:00Z'
                    updated_at: '2025-01-14T10:30:00Z'
                meta:
                  limit: 2
                  page: 2
                  total: 10
                  total_pages: 5
          schema:
            properties:
              items:
                description: List of public keys
                items:
                  $ref: '#/components/schemas/PublicKey'
                type: array
              meta:
                $ref: '#/components/schemas/PaginationMeta'
            required:
              - items
              - meta
            type: object
      description: Successfully retrieved list of public keys with pagination information
    create_public_key_response:
      content:
        application/json:
          examples:
            bitcoin_legacy:
              summary: Created Bitcoin Legacy public key
              value:
                id: 550e8400-e29b-41d4-a716-446655440000
                value: >-
                  xpub6EFxzN6ZgMCZ1PxeRigmAhm2UBGzXtZNgznCEaWuEt9efBpJwAXFA4ZckBdR1pdMQ1pBgsey7ebjToZ5gYXveftB3zwoQ8NvEkimvyaz34i
                label: Main Bitcoin Wallet
                derivation_path: m/44'/0'/0'/0
                created_at: '2025-01-15T12:00:00Z'
                updated_at: '2025-01-15T12:00:00Z'
            bitcoin_segwit:
              summary: Created Bitcoin SegWit public key
              value:
                id: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
                value: >-
                  ypub6ZtCaoXpd9GqsJMiFThRchS8RXiyRBD3WxyoZhhnKF9n198VSV8U38TPrrhMenYSXZGU4N8Q5J1XYEjc4JKr8Dj1BtvhCjNTRxPimrfCN4T
                label: SegWit Savings
                derivation_path: m/49'/0'/0'/0
                created_at: '2025-01-15T12:05:00Z'
                updated_at: '2025-01-15T12:05:00Z'
            bitcoin_native_segwit:
              summary: Created Bitcoin Native SegWit public key
              value:
                id: 7ba7b820-9dad-11d1-80b4-00c04fd430c8
                value: >-
                  zpub6svdUH71uTR9YXumEJroNo51GfHdASMmzKFafeBr51yEzf4gj4cPBafQDjk18AGTZSfhXi8uMuuZKpSdmzHjZDTDCVK3KjVYj1NKUTFfCkk
                label: Lightning Wallet
                derivation_path: m/84'/0'/0'/0
                created_at: '2025-01-15T12:10:00Z'
                updated_at: '2025-01-15T12:10:00Z'
            ethereum:
              summary: Created Ethereum public key
              value:
                id: 8ca8c850-9dad-11d1-80b4-00c04fd430c8
                value: >-
                  xpub6EFxzN6ZgMCZ1PxeRigmAhm2UBGzXtZNgznCEaWuEt9efBpJwAXFA4ZckBdR1pdMQ1pBgsey7ebjToZ5gYXveftB3zwoQ8NvEkimvyaz34i
                label: ETH Trading
                derivation_path: m/44'/60'/0'/0
                created_at: '2025-01-15T12:15:00Z'
                updated_at: '2025-01-15T12:15:00Z'
            bnb_smart_chain:
              summary: Created BNB Smart Chain public key
              value:
                id: 9da9d860-9dad-11d1-80b4-00c04fd430c8
                value: >-
                  xpub6E9yb4KbMfmHD6GNVNmF8w5kGRtRgRw9yfPskJYScpMSujrzk5VYFM7UYiiz6dG7c6Gj9GjKGG4JWAdjpfumwDtvB73VWYPTacztJqhnfVM
                label: BSC DeFi Wallet
                derivation_path: m/44'/60'/1'/0
                created_at: '2025-01-15T12:20:00Z'
                updated_at: '2025-01-15T12:20:00Z'
            polygon:
              summary: Created Polygon public key
              value:
                id: aea0e870-9dad-11d1-80b4-00c04fd430c8
                value: >-
                  xpub6Dm2HNwvdJF1JcJ4eXvmvmgXqoTp6LG8CN32Xx3uppekAfPxZ8Es6doee9KkA6BLeSM3LgU3wXjjb5RaqSwtSBVBKETtQfcsx9dibMdEqGS
                label: Polygon Gaming
                derivation_path: m/44'/60'/2'/0
                created_at: '2025-01-15T12:25:00Z'
                updated_at: '2025-01-15T12:25:00Z'
          schema:
            $ref: '#/components/schemas/PublicKey'
      description: Public key successfully created
    public_key_response:
      content:
        application/json:
          examples:
            legacy_bitcoin:
              summary: Bitcoin Legacy public key (BIP44)
              value:
                id: 550e8400-e29b-41d4-a716-446655440000
                value: >-
                  xpub6EFxzN6ZgMCZ1PxeRigmAhm2UBGzXtZNgznCEaWuEt9efBpJwAXFA4ZckBdR1pdMQ1pBgsey7ebjToZ5gYXveftB3zwoQ8NvEkimvyaz34i
                label: Main Bitcoin Wallet
                derivation_path: m/44'/0'/0'/0
                created_at: '2025-01-15T12:00:00Z'
                updated_at: '2025-01-15T12:00:00Z'
            segwit_bitcoin:
              summary: Bitcoin SegWit public key (BIP49)
              value:
                id: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
                value: >-
                  ypub6ZtCaoXpd9GqsJMiFThRchS8RXiyRBD3WxyoZhhnKF9n198VSV8U38TPrrhMenYSXZGU4N8Q5J1XYEjc4JKr8Dj1BtvhCjNTRxPimrfCN4T
                label: SegWit Wallet
                derivation_path: m/49'/0'/0'/1
                created_at: '2025-01-14T10:30:00Z'
                updated_at: '2025-01-14T10:30:00Z'
            native_segwit:
              summary: Bitcoin Native SegWit public key (BIP84)
              value:
                id: 7ba7b820-9dad-11d1-80b4-00c04fd430c8
                value: >-
                  zpub6svdUH71uTR9YXumEJroNo51GfHdASMmzKFafeBr51yEzf4gj4cPBafQDjk18AGTZSfhXi8uMuuZKpSdmzHjZDTDCVK3KjVYj1NKUTFfCkk
                label: Native SegWit Wallet
                derivation_path: m/84'/0'/0'/0
                created_at: '2025-01-13T09:15:00Z'
                updated_at: '2025-01-13T09:15:00Z'
            ethereum:
              summary: Ethereum public key
              value:
                id: 8ca8c850-9dad-11d1-80b4-00c04fd430c8
                value: >-
                  xpub6EFxzN6ZgMCZ1PxeRigmAhm2UBGzXtZNgznCEaWuEt9efBpJwAXFA4ZckBdR1pdMQ1pBgsey7ebjToZ5gYXveftB3zwoQ8NvEkimvyaz34i
                label: Ethereum Wallet
                derivation_path: m/44'/60'/0'/0
                created_at: '2025-01-12T14:20:00Z'
                updated_at: '2025-01-12T14:20:00Z'
          schema:
            $ref: '#/components/schemas/PublicKey'
      description: Successfully retrieved public key information
    no_content_response:
      description: The request was successful but there is no content to return
    update_public_key_response:
      content:
        application/json:
          examples:
            updated_label:
              summary: Successfully updated public key label
              value:
                id: 550e8400-e29b-41d4-a716-446655440000
                value: >-
                  xpub6EFxzN6ZgMCZ1PxeRigmAhm2UBGzXtZNgznCEaWuEt9efBpJwAXFA4ZckBdR1pdMQ1pBgsey7ebjToZ5gYXveftB3zwoQ8NvEkimvyaz34i
                label: Updated Bitcoin Wallet Label
                derivation_path: m/44'/0'/0'/0
                created_at: '2025-01-15T12:00:00Z'
                updated_at: '2025-01-15T14:30:00Z'
            ethereum_updated:
              summary: Updated Ethereum wallet label
              value:
                id: 8ca8c850-9dad-11d1-80b4-00c04fd430c8
                value: >-
                  xpub6F7C1ZtQ411zykk6KTEoQMqfNdxiSA4uxAwAoqFanijnAavqQvVmh5zZCH6Swhdbzt2HuMRLx4chEVRZu9ic4Cnkkq5AsQcmjeMASk6FLqf
                label: Primary ETH Wallet
                derivation_path: m/44'/60'/0'/0
                created_at: '2025-01-12T14:20:00Z'
                updated_at: '2025-01-15T16:45:00Z'
            segwit_updated:
              summary: Updated SegWit wallet label
              value:
                id: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
                value: >-
                  ypub6ZtCaoXpd9GqsJMiFThRchS8RXiyRBD3WxyoZhhnKF9n198VSV8U38TPrrhMenYSXZGU4N8Q5J1XYEjc4JKr8Dj1BtvhCjNTRxPimrfCN4T
                label: Cold Storage SegWit
                derivation_path: m/49'/0'/0'/1
                created_at: '2025-01-14T10:30:00Z'
                updated_at: '2025-01-15T17:00:00Z'
          schema:
            $ref: '#/components/schemas/PublicKey'
      description: Public key successfully updated
    hd_addresses_list_response:
      content:
        application/json:
          examples:
            hd_addresses:
              summary: List of HD addresses derived from public key
              value:
                items:
                  - value: bc1q8faxe8g4u2v67qfwf9d8xhyl5tkkkphvet6r08
                    format: p2wpkh
                    kind: hd
                    label: user_45_deposit
                    meta:
                      user_id: '45'
                      purpose: deposit
                    public_key_id: 7ca7b850-9dad-11d1-80b4-00c04fd430c8
                    derivation_index: 0
                    created_at: '2025-07-03T12:45:00Z'
                    updated_at: '2025-07-03T13:15:22Z'
                  - value: bc1q39vtx8qt39ztrx0j9rm6f5lz56qze0c68qafhu
                    format: p2wpkh
                    kind: hd
                    label: user_46_deposit
                    meta:
                      user_id: '46'
                      purpose: deposit
                    public_key_id: 8da8d860-9dad-11d1-80b4-00c04fd430c8
                    derivation_index: 1
                    created_at: '2025-07-02T10:30:00Z'
                    updated_at: '2025-07-04T09:15:00Z'
                  - value: bc1qnc8aj03r2letsdzfmhmr99v5sw6mys7jgz7huh
                    format: p2wpkh
                    kind: hd
                    label: null
                    meta:
                      archived: 'true'
                    public_key_id: 9ea9e870-9dad-11d1-80b4-00c04fd430c8
                    derivation_index: 15
                    created_at: '2025-07-01T08:15:00Z'
                    updated_at: '2025-07-05T16:20:00Z'
                meta:
                  limit: 20
                  page: 1
                  total: 3
                  total_pages: 1
            empty_list:
              summary: No addresses derived yet
              value:
                items: []
                meta:
                  limit: 20
                  page: 1
                  total: 0
                  total_pages: 0
            paginated:
              summary: Paginated HD addresses
              value:
                items:
                  - value: bc1qjq73wzhhzt40250678hwpzgrrucutkx77ze37d
                    format: p2wpkh
                    kind: hd
                    label: payment_100
                    meta: {}
                    public_key_id: afa0f880-9dad-11d1-80b4-00c04fd430c8
                    derivation_index: 100
                    created_at: '2025-07-05T15:30:00Z'
                    updated_at: '2025-07-05T15:30:00Z'
                  - value: bc1qn3gcnfneeje42ywwv0nzcpsghe7nam306vrqa7
                    format: p2wpkh
                    kind: hd
                    label: payment_101
                    meta: {}
                    public_key_id: b0b1f890-9dad-11d1-80b4-00c04fd430c8
                    derivation_index: 101
                    created_at: '2025-07-05T15:30:00Z'
                    updated_at: '2025-07-05T15:30:00Z'
                meta:
                  limit: 2
                  page: 10
                  total: 150
                  total_pages: 75
            mixed_public_keys:
              summary: HD addresses from multiple public keys
              value:
                items:
                  - value: bc1q8faxe8g4u2v67qfwf9d8xhyl5tkkkphvet6r08
                    format: p2wpkh
                    kind: hd
                    label: alice_wallet
                    meta:
                      user: alice
                      type: savings
                    public_key_id: 7ca7b850-9dad-11d1-80b4-00c04fd430c8
                    derivation_index: 0
                    created_at: '2025-07-01T10:00:00Z'
                    updated_at: '2025-07-01T10:00:00Z'
                  - value: bc1q39vtx8qt39ztrx0j9rm6f5lz56qze0c68qafhu
                    format: p2wpkh
                    kind: hd
                    label: bob_wallet
                    meta:
                      user: bob
                      type: checking
                    public_key_id: 8da8d860-9dad-11d1-80b4-00c04fd430c8
                    derivation_index: 5
                    created_at: '2025-07-02T11:00:00Z'
                    updated_at: '2025-07-02T11:00:00Z'
                  - value: bc1qnc8aj03r2letsdzfmhmr99v5sw6mys7jgz7huh
                    format: p2wpkh
                    kind: hd
                    label: charlie_wallet
                    meta:
                      user: charlie
                      type: trading
                    public_key_id: 9ea9e870-9dad-11d1-80b4-00c04fd430c8
                    derivation_index: 10
                    created_at: '2025-07-03T12:00:00Z'
                    updated_at: '2025-07-03T12:00:00Z'
                  - value: 3Do92Dmff87UuY9Yiu2iFG2Kj9bpRaeJSF
                    format: p2sh
                    kind: hd
                    label: dave_segwit
                    meta:
                      user: dave
                      type: hodl
                    public_key_id: afa0f880-9dad-11d1-80b4-00c04fd430c8
                    derivation_index: 0
                    created_at: '2025-07-04T13:00:00Z'
                    updated_at: '2025-07-04T13:00:00Z'
                  - value: 1GxHzNEymq1MLhxpdWAMJLN1UusYJ2Sy45
                    format: p2pkh
                    kind: hd
                    label: eve_legacy
                    meta:
                      user: eve
                      type: legacy
                    public_key_id: b0b1f890-9dad-11d1-80b4-00c04fd430c8
                    derivation_index: 3
                    created_at: '2025-07-05T14:00:00Z'
                    updated_at: '2025-07-05T14:00:00Z'
                meta:
                  limit: 20
                  page: 1
                  total: 237
                  total_pages: 12
          schema:
            type: object
            properties:
              items:
                type: array
                items:
                  $ref: '#/components/schemas/HDAddress'
                description: List of HD addresses derived from the public key
              meta:
                $ref: '#/components/schemas/PaginationMeta'
            required:
              - items
              - meta
      description: Successfully retrieved list of HD addresses derived from the public key
    generate_addresses_response:
      content:
        application/json:
          examples:
            bitcoin_addresses:
              summary: Generated Bitcoin addresses
              value:
                items:
                  - bc1q39vtx8qt39ztrx0j9rm6f5lz56qze0c68qafhu
                  - bc1qnc8aj03r2letsdzfmhmr99v5sw6mys7jgz7huh
                  - bc1qjq73wzhhzt40250678hwpzgrrucutkx77ze37d
                count: 3
            ethereum_addresses:
              summary: Generated Ethereum addresses
              value:
                items:
                  - '0x8521E8b15eCEF4D4269Fded3E6694225E096959E'
                  - '0xCa79F73628E5D46Cc2c0F6CcD3a3F934d3cE66B7'
                  - '0x2cD2cEA3B87C8d256AB74Db8F0E9e6E838001293'
                count: 3
            single_address:
              summary: Single generated address
              value:
                items:
                  - bc1q8faxe8g4u2v67qfwf9d8xhyl5tkkkphvet6r08
                count: 1
          schema:
            type: object
            required:
              - items
              - count
            properties:
              items:
                type: array
                description: Array of generated address values
                items:
                  type: string
                  description: Address value (e.g., Bitcoin address, Ethereum address)
                  example: '0x8521E8b15eCEF4D4269Fded3E6694225E096959E'
              count:
                type: integer
                description: Number of addresses generated
                minimum: 0
                example: 3
      description: Addresses generated successfully
    precondition_problem:
      description: >-
        Precondition Failed - The request could not be completed due to a
        business logic constraint
      content:
        application/problem+json:
          schema:
            type: object
            required:
              - type
              - title
              - status
            properties:
              type:
                type: string
                format: uri
                description: A URI reference that identifies the problem type
                example: https://docs.vilna.io/apis/problems/precondition-failed
              title:
                type: string
                description: A short, human-readable summary of the problem type
                example: Precondition Failed
              status:
                type: integer
                description: The HTTP status code
                example: 422
              detail:
                type: string
                description: >-
                  A human-readable explanation specific to this occurrence of
                  the problem
                example: >-
                  Cannot generate mainnet address from a key with format
                  secp256k1
              instance:
                type: string
                description: >-
                  A URI reference that identifies the specific occurrence of the
                  problem
                example: /errors?id=XXXXXX-xxxxx
              fields:
                type: array
                description: Details about the failed precondition
                items:
                  type: object
                  required:
                    - name
                    - reason
                  properties:
                    name:
                      type: string
                      description: The field or context where the precondition failed
                      example: format
                    reason:
                      type: string
                      description: Explanation of why the precondition failed
                      example: >-
                        Cannot generate the Bitcoin address from a key with
                        format EVM
    hd_address_response:
      content:
        application/json:
          examples:
            next_address:
              summary: Successfully generated next HD address
              value:
                value: bc1q8faxe8g4u2v67qfwf9d8xhyl5tkkkphvet6r08
                format: p2wpkh
                kind: hd
                label: 'Customer Payment #12345'
                meta:
                  customer_id: cust_12345
                  order_id: ord_67890
                public_key_id: 7ca7b850-9dad-11d1-80b4-00c04fd430c8
                derivation_index: 47
                created_at: '2025-07-05T17:00:00Z'
                updated_at: '2025-07-05T17:00:00Z'
            next_address_no_label:
              summary: Generated next HD address without label
              value:
                value: bc1q39vtx8qt39ztrx0j9rm6f5lz56qze0c68qafhu
                format: p2wpkh
                kind: hd
                label: null
                meta: {}
                public_key_id: 8da8d860-9dad-11d1-80b4-00c04fd430c8
                derivation_index: 0
                created_at: '2025-07-05T17:15:00Z'
                updated_at: '2025-07-05T17:15:00Z'
            legacy_address:
              summary: HD address with legacy format
              value:
                value: 1GxHzNEymq1MLhxpdWAMJLN1UusYJ2Sy45
                format: p2pkh
                kind: hd
                label: Legacy deposit
                meta:
                  type: legacy
                  note: for compatibility
                public_key_id: 9ea9e870-9dad-11d1-80b4-00c04fd430c8
                derivation_index: 5
                created_at: '2025-07-05T17:30:00Z'
                updated_at: '2025-07-05T17:30:00Z'
            segwit_address:
              summary: HD address with SegWit format
              value:
                value: 3Do92Dmff87UuY9Yiu2iFG2Kj9bpRaeJSF
                format: p2sh
                kind: hd
                label: SegWit payment
                meta:
                  invoice_id: inv_2025_001
                public_key_id: afa0f880-9dad-11d1-80b4-00c04fd430c8
                derivation_index: 12
                created_at: '2025-07-05T18:00:00Z'
                updated_at: '2025-07-05T18:00:00Z'
          schema:
            $ref: '#/components/schemas/HDAddress'
      description: HD address successfully created
    addresses_list_response:
      content:
        application/json:
          examples:
            mixed_addresses:
              summary: Response containing both HD and external addresses
              value:
                items:
                  - value: bc1q8faxe8g4u2v67qfwf9d8xhyl5tkkkphvet6r08
                    created_at: '2025-07-03T12:45:00Z'
                    format: p2wpkh
                    label: user_45_deposit
                    kind: hd
                    meta:
                      user_id: '45'
                      purpose: deposit
                    updated_at: '2025-07-03T13:15:22Z'
                  - value: '0xCa79F73628E5D46Cc2c0F6CcD3a3F934d3cE66B7'
                    created_at: '2025-07-03T14:20:00Z'
                    format: evm
                    label: cold_wallet
                    kind: external
                    meta:
                      source: binance
                      type: withdrawal
                    updated_at: '2025-07-03T14:20:00Z'
                  - value: bc1q39vtx8qt39ztrx0j9rm6f5lz56qze0c68qafhu
                    created_at: '2025-07-02T10:30:00Z'
                    format: p2wpkh
                    label: user_46_deposit
                    kind: hd
                    meta:
                      user_id: '46'
                      archived: 'true'
                    updated_at: '2025-07-04T09:15:00Z'
                meta:
                  limit: 20
                  page: 1
                  total: 3
                  total_pages: 1
          schema:
            properties:
              items:
                description: List of addresses
                items:
                  $ref: '#/components/schemas/Address'
                type: array
              meta:
                $ref: '#/components/schemas/PaginationMeta'
            required:
              - items
              - meta
            type: object
      description: Successful response containing a list of addresses
    external_address_response:
      content:
        application/json:
          examples:
            created_external:
              summary: Successfully created external address
              value:
                value: '0x8521E8b15eCEF4D4269Fded3E6694225E096959E'
                format: evm
                kind: external
                label: treasury_wallet
                meta:
                  purpose: treasury
                  multisig: 'false'
                created_at: '2025-07-05T14:30:00Z'
                updated_at: '2025-07-05T14:30:00Z'
            bitcoin_external:
              summary: Bitcoin external address
              value:
                value: bc1q8faxe8g4u2v67qfwf9d8xhyl5tkkkphvet6r08
                format: p2wpkh
                kind: external
                label: hardware_wallet
                meta:
                  device: trezor
                  account: '0'
                created_at: '2025-07-05T15:00:00Z'
                updated_at: '2025-07-05T15:00:00Z'
            solana_external:
              summary: Solana external address
              value:
                value: 5EYCAe5ijiHbZBU14TyKHADUrkaAfc4ZyTXKRVKp49F8
                format: solana
                kind: external
                label: phantom_wallet
                meta:
                  wallet: phantom
                  network: mainnet
                created_at: '2025-07-05T15:30:00Z'
                updated_at: '2025-07-05T15:30:00Z'
          schema:
            $ref: '#/components/schemas/ExternalAddress'
      description: External address successfully created
    address_response:
      content:
        application/json:
          examples:
            external_address:
              summary: External address
              value:
                value: '0x8521E8b15eCEF4D4269Fded3E6694225E096959E'
                created_at: '2025-07-03T14:20:00Z'
                format: evm
                label: cold_wallet
                kind: external
                meta:
                  source: binance
                  type: withdrawal
                updated_at: '2025-07-03T14:20:00Z'
            hd_address:
              summary: HD address derived from public key
              value:
                value: bc1q8faxe8g4u2v67qfwf9d8xhyl5tkkkphvet6r08
                created_at: '2025-07-03T12:45:00Z'
                format: p2wpkh
                label: user_45_deposit
                kind: hd
                meta:
                  user_id: '45'
                  purpose: deposit
                updated_at: '2025-07-03T13:15:22Z'
          schema:
            $ref: '#/components/schemas/Address'
      description: Successful address response
    address_balances_response:
      content:
        application/json:
          examples:
            empty_response:
              summary: Address with no active assets or all zero balances
              value: {}
            ethereum_address:
              summary: Ethereum address with ETH and tokens
              value:
                eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48: '5000.00'
                eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7: '12345.67'
                eip155:1/slip44:60: '2.5432'
            multi_chain_address:
              summary: Address with assets across multiple chains
              value:
                eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7: '1000.0'
                eip155:1/slip44:60: '0.5'
                eip155:137/slip44:60: '10.0'
                eip155:56/slip44:60: '1.234'
          schema:
            additionalProperties:
              description: >-
                Balance in human-readable decimal format (adjusted for token
                decimals)
              example: '123.456789'
              pattern: ^[0-9]+(\.[0-9]+)?$
              type: string
            description: |
              Map of asset GIDs to their balances. Only includes:
              - Assets with `active` status
              - Assets with non-zero balances

              Excludes assets with `pending`, `blocked`, or `ignored` status.
            type: object
      description: Active asset balances for the address
    assets_list_response:
      description: List of assets with pagination metadata
      content:
        application/json:
          schema:
            type: object
            required:
              - items
              - meta
            properties:
              items:
                type: array
                items:
                  $ref: '#/components/schemas/Asset'
                description: Array of asset objects
              meta:
                $ref: '#/components/schemas/PaginationMeta'
          example:
            items:
              - gid: eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7
                status: active
                created_at: '2024-01-15T10:30:00Z'
                updated_at: '2024-01-15T12:45:00Z'
              - gid: eip155:1/slip44:60
                status: active
                created_at: '2024-01-14T09:15:00Z'
                updated_at: '2024-01-14T09:15:00Z'
            meta:
              total: 150
              page: 1
              limit: 100
              total_pages: 2
    tokens_list_response:
      description: Successful response returning a list of token entities
      content:
        application/json:
          schema:
            type: object
            required:
              - items
              - meta
            properties:
              items:
                type: array
                description: >-
                  List of tokens managed in the system, including native coins
                  and token contracts (e.g., ERC-20, BEP-20)
                items:
                  $ref: '#/components/schemas/Token'
              meta:
                $ref: '#/components/schemas/PaginationMeta'
          examples:
            mixed_tokens:
              summary: Mixed native and contract token entities
              value:
                items:
                  - gid: eip155:1/slip44:60
                    symbol: ETH
                    name: Ethereum
                    decimals: 18
                    created_at: '2024-01-01T00:00:00Z'
                  - gid: eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7
                    symbol: USDT
                    name: Tether USD
                    decimals: 6
                    created_at: '2024-01-02T12:00:00Z'
                meta:
                  page: 1
                  limit: 20
                  total: 2
                  total_pages: 1
    token_response:
      description: Successful response returning a single token entity
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Token'
          examples:
            ethereum_token:
              summary: Ethereum native token
              value:
                gid: eip155:1/slip44:60
                symbol: ETH
                name: Ethereum
                decimals: 18
                created_at: '2024-01-01T00:00:00Z'
            usdt_token:
              summary: USDT ERC-20 token
              value:
                gid: eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7
                symbol: USDT
                name: Tether USD
                decimals: 6
                created_at: '2024-01-02T12:00:00Z'
    transactions_list_response:
      description: Successful response returning a list of blockchain transactions
      content:
        application/json:
          schema:
            type: object
            required:
              - items
              - meta
            properties:
              items:
                type: array
                description: List of blockchain transactions with their asset transfers
                items:
                  $ref: '#/components/schemas/Transaction'
              meta:
                $ref: '#/components/schemas/PaginationMeta'
          examples:
            mixed_transactions:
              summary: Mixed transactions with different transfer types and networks
              value:
                items:
                  - transaction_hash: >-
                      0x181de044827b9e421149d70f5ebaecfc070d169931b79ce5112cd9f401c2ee76
                    chain_gid: eip155:1
                    chain_family: evm
                    block_number: 24142875
                    initiator:
                      value: '0x02fEA98494cCB2D12F32DD2ce652e831a61F8353'
                      is_known: true
                    target:
                      value: '0xdAC17F958D2ee523a2206206994597C13D831ec7'
                      is_known: false
                    transfers:
                      - sequence: 0
                        kind: fungible
                        sender:
                          value: '0x02fEA98494cCB2D12F32DD2ce652e831a61F8353'
                          is_known: true
                        recipient:
                          value: '0x61ed4B62E03798305818607C7160B2AbFF15cFeD'
                          is_known: true
                        amount: '50500000'
                        asset_gid: >-
                          eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7
                        meta:
                          log_index: 632
                    is_success: true
                    confirmed_at: '2026-01-01T22:49:59Z'
                    created_at: '2026-01-01T22:49:59Z'
                  - transaction_hash: >-
                      0x43ae9aff8b94b4ea3d9cb91b0e5ae9ac6686acadaf08182e8ce4340d56bf2652
                    chain_gid: eip155:56
                    chain_family: evm
                    block_number: 73740000
                    initiator:
                      value: '0xB8c24300a00753586Ae7C7d63D090Afb36Eb8259'
                      is_known: false
                    target:
                      value: '0x9Dd546e437bb73f45bAa1C45E032d60567cCF74d'
                      is_known: true
                    transfers:
                      - sequence: 0
                        kind: native
                        sender:
                          value: '0xB8c24300a00753586Ae7C7d63D090Afb36Eb8259'
                          is_known: false
                        recipient:
                          value: '0x9Dd546e437bb73f45bAa1C45E032d60567cCF74d'
                          is_known: true
                        amount: '2972545000000000000'
                        asset_gid: eip155:56/erc20:714
                    is_success: false
                    confirmed_at: '2026-01-01T22:40:50Z'
                    created_at: '2026-01-01T22:40:50Z'
                  - transaction_hash: >-
                      ec019d74d6336711a694a6f184bf245ca55abd2e531f32c01ab41c2f350a9313
                    chain_gid: bip122:000000000019d6689c085ae165831e93
                    chain_family: bitcoin
                    block_number: 930485
                    initiator:
                      value: 1BsJZUo37PYdR6vMyvL81mXdXQ5wfb6qiP
                      is_known: false
                    transfers:
                      - sequence: 0
                        kind: native
                        sender:
                          value: 1BsJZUo37PYdR6vMyvL81mXdXQ5wfb6qiP
                          is_known: false
                        recipient:
                          value: 1GrwDkr33gT6LuumniYjKEGjTLhsL5kmqC
                          is_known: false
                        amount: '546'
                        asset_gid: bip122:000000000019d6689c085ae165831e93/slip44:0
                        meta:
                          script_type: P2PKH
                          is_coinbase: false
                      - sequence: 1
                        kind: native
                        sender:
                          value: >-
                            bc1p4mv92fse0dxvnyf65fc4k5sqzyc6s04dhkka944a6rfsxd398x7q9ndnnj
                          is_known: false
                        recipient:
                          value: >-
                            bc1p4mv92fse0dxvnyf65fc4k5sqzyc6s04dhkka944a6rfsxd398x7q9ndnnj
                          is_known: false
                        amount: '3182228'
                        asset_gid: bip122:000000000019d6689c085ae165831e93/slip44:0
                        meta:
                          script_type: P2WPKH
                          is_coinbase: false
                    is_success: true
                    confirmed_at: '2026-01-02T12:10:35Z'
                    created_at: '2026-01-02T12:10:35Z'
                  - transaction_hash: >-
                      3eRSHgWHPALSeudtJSavtWqx7UUXMExZyDqbaEPjy7Cbc35kK4ysd5t2eFRSmP6EeQtSzkNbBQAhyDuHYbwM8TFW
                    chain_gid: solana:mainnet
                    chain_family: solana
                    block_number: 390702324
                    initiator:
                      value: D89hHJT5Aqyx1trP6EnGY9jJUB3whgnq3aUvvCqedvzf
                      is_known: true
                    target:
                      value: '11111111111111111111111111111111'
                      is_known: false
                    transfers:
                      - sequence: 0
                        kind: native
                        sender:
                          value: D89hHJT5Aqyx1trP6EnGY9jJUB3whgnq3aUvvCqedvzf
                          is_known: true
                        recipient:
                          value: A3baUSSDQmMEqA7gDBeFtkCrWjHc7YCQ6q5F8rgZSzkr
                          is_known: false
                        amount: '5680000'
                        asset_gid: solana:mainnet/slip44:501
                        meta:
                          program_id: '11111111111111111111111111111112'
                          instruction_index: 0
                    is_success: true
                    confirmed_at: '2026-01-02T00:00:16Z'
                    created_at: '2026-01-02T00:00:16Z'
                meta:
                  page: 1
                  limit: 20
                  total: 4
                  total_pages: 1
    notification_channels_list_response:
      description: List of notification channels with pagination
      content:
        application/json:
          schema:
            type: object
            properties:
              items:
                type: array
                items:
                  $ref: '#/components/schemas/NotificationChannel'
              meta:
                $ref: '#/components/schemas/PaginationMeta'
            required:
              - items
              - meta
          examples:
            mixed_channels:
              summary: List of different notification channels
              value:
                items:
                  - id: 550e8400-e29b-41d4-a716-446655440000
                    kind: webhook
                    name: Production Alerts Webhook
                    config:
                      url: https://api.example.com/webhooks/notifications
                      headers:
                        Authorization: Bearer token123
                    is_archived: false
                    created_at: '2024-01-15T10:30:00Z'
                    updated_at: '2024-01-15T10:30:00Z'
                  - id: 550e8400-e29b-41d4-a716-446655440001
                    kind: telegram
                    name: Critical Alerts Bot
                    config:
                      bot_token: 123456789:ABCDEFGHIJKLMNOPQRSTUVWXYZ123456789
                      chat_id: -1001234567890
                    is_archived: false
                    created_at: '2024-01-15T09:15:00Z'
                    updated_at: '2024-01-15T09:15:00Z'
                  - id: 550e8400-e29b-41d4-a716-446655440002
                    kind: nats
                    name: System Events NATS
                    config:
                      url: nats://nats.example.com:4222
                      subject: notifications.system.events
                    is_archived: true
                    created_at: '2024-01-15T08:00:00Z'
                    updated_at: '2024-01-15T11:45:00Z'
                meta:
                  page: 1
                  limit: 30
                  total: 15
                  total_pages: 1
    notification_channel_response:
      description: Notification channel details
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotificationChannel'
          examples:
            nats_channel:
              summary: NATS notification channel
              value:
                id: 550e8400-e29b-41d4-a716-446655440000
                kind: nats
                name: System Alerts NATS
                config:
                  url: nats://nats.example.com:4222
                  subject: notifications.system.alerts
                is_archived: false
                created_at: '2024-01-15T10:30:00Z'
                updated_at: '2024-01-15T10:30:00Z'
            telegram_channel:
              summary: Telegram notification channel
              value:
                id: 550e8400-e29b-41d4-a716-446655440001
                kind: telegram
                name: Production Alerts
                config:
                  bot_token: 123456789:ABCDEFGHIJKLMNOPQRSTUVWXYZ123456789
                  chat_id: -1001234567890
                is_archived: false
                created_at: '2024-01-15T10:30:00Z'
                updated_at: '2024-01-15T10:30:00Z'
            webhook_channel:
              summary: Webhook notification channel
              value:
                id: 550e8400-e29b-41d4-a716-446655440002
                kind: webhook
                name: Production Alerts Webhook
                config:
                  url: https://api.example.com/webhooks/notifications
                  headers:
                    Authorization: Bearer token123
                    X-API-Key: secret-key
                is_archived: false
                created_at: '2024-01-15T10:30:00Z'
                updated_at: '2024-01-15T10:30:00Z'
    version_response:
      content:
        application/json:
          example:
            version: 1.0.0
          schema:
            $ref: '#/components/schemas/VersionInfo'
      description: Service version info
  requestBodies:
    update_evm_config_request:
      required: true
      content:
        application/json:
          schema:
            type: object
            description: Request to update an existing EVM blockchain configuration
            properties:
              endpoint_url:
                $ref: '#/components/schemas/EVMEndpointURL'
              websocket_url:
                $ref: '#/components/schemas/EVMWebSocketURL'
            minProperties: 1
            additionalProperties: false
          examples:
            update_endpoint_only:
              summary: Update only RPC endpoint
              value:
                endpoint_url: https://ethereum-rpc.publicnode.com
            update_websocket_only:
              summary: Update only WebSocket endpoint
              value:
                websocket_url: wss://ethereum-rpc.publicnode.com
            update_all:
              summary: Update both endpoints
              value:
                endpoint_url: https://ethereum-rpc.publicnode.com
                websocket_url: wss://ethereum-rpc.publicnode.com
    update_solana_config_request:
      required: true
      content:
        application/json:
          schema:
            type: object
            description: Request to update an existing Solana blockchain configuration
            properties:
              endpoint_url:
                $ref: '#/components/schemas/SolanaEndpointURL'
              websocket_url:
                $ref: '#/components/schemas/SolanaWebSocketURL'
            minProperties: 1
            additionalProperties: false
          examples:
            update_endpoint_only:
              summary: Update only RPC endpoint
              value:
                endpoint_url: https://solana-rpc.publicnode.com
            update_websocket_only:
              summary: Update only WebSocket endpoint
              value:
                websocket_url: wss://solana-rpc.publicnode.com
            update_all:
              summary: Update both endpoints
              value:
                endpoint_url: https://solana-rpc.publicnode.com
                websocket_url: wss://solana-rpc.publicnode.com
    update_tron_config_request:
      required: true
      content:
        application/json:
          schema:
            type: object
            description: Request to update an existing Tron blockchain configuration
            properties:
              evm_endpoint_url:
                $ref: '#/components/schemas/TronEVMEndpointURL'
            minProperties: 1
            additionalProperties: false
          examples:
            update_endpoint_only:
              summary: Update only RPC endpoint
              value:
                evm_endpoint_url: https://evm-rpc.example.com
            update_all:
              summary: Update both endpoints
              value:
                evm_endpoint_url: https://evm-rpc.example.com
    update_bitcoin_config_request:
      required: true
      content:
        application/json:
          schema:
            type: object
            description: Request to update an existing Bitcoin blockchain configuration
            properties:
              endpoint_url:
                $ref: '#/components/schemas/BitcoinEndpointURL'
            minProperties: 1
            additionalProperties: false
          examples:
            update_endpoint:
              summary: Update RPC endpoint
              value:
                endpoint_url: https://bitcoin-rpc.publicnode.com
            update_endpoint_alternative:
              summary: Update to alternative provider
              value:
                endpoint_url: https://bitcoin-rpc.publicnode.com
    create_public_key_request:
      content:
        application/json:
          schema:
            properties:
              derivation_path:
                $ref: '#/components/schemas/DerivationPath'
              label:
                $ref: '#/components/schemas/PublicKeyLabel'
              value:
                $ref: '#/components/schemas/PublicKeyValue'
            required:
              - value
              - label
              - derivation_path
            type: object
          examples:
            xpub_example:
              summary: Legacy public key (BIP44)
              value:
                derivation_path: m/44'/0'/0'/0
                label: My Legacy Wallet
                value: >-
                  xpub6F7C1ZtQ411zykk6KTEoQMqfNdxiSA4uxAwAoqFanijnAavqQvVmh5zZCH6Swhdbzt2HuMRLx4chEVRZu9ic4Cnkkq5AsQcmjeMASk6FLqf
            ypub_example:
              summary: SegWit P2SH-P2WPKH (BIP49)
              value:
                derivation_path: m/49'/0'/0'/0
                label: My SegWit Wallet
                value: >-
                  ypub6ZtCaoXpd9GqsJMiFThRchS8RXiyRBD3WxyoZhhnKF9n198VSV8U38TPrrhMenYSXZGU4N8Q5J1XYEjc4JKr8Dj1BtvhCjNTRxPimrfCN4T
            zpub_example:
              summary: Native SegWit P2WPKH (BIP84)
              value:
                derivation_path: m/84'/0'/0'/0
                label: My Native SegWit Wallet
                value: >-
                  zpub6svdUH71uTR9YXumEJroNo51GfHdASMmzKFafeBr51yEzf4gj4cPBafQDjk18AGTZSfhXi8uMuuZKpSdmzHjZDTDCVK3KjVYj1NKUTFfCkk
      description: Request body for adding a new extended public key (HD wallet)
      required: true
    update_public_key_request:
      content:
        application/json:
          schema:
            properties:
              label:
                $ref: '#/components/schemas/PublicKeyLabel'
              is_archived:
                description: If true, marks the public key as archived
                type: boolean
                example: false
            required:
              - label
            type: object
      description: >-
        Request body for updating an existing public key. The label and archived
        status can be modified.
      required: true
    generate_hd_addresses_request:
      content:
        application/json:
          schema:
            type: object
            properties:
              range:
                description: Range definition for HD address generation
                type: object
                properties:
                  startIndex:
                    description: Starting index (inclusive)
                    type: integer
                    minimum: 0
                    example: 100
                  count:
                    description: Number of addresses to generate
                    type: integer
                    minimum: 1
                    maximum: 10000
                    example: 50
                required:
                  - startIndex
                  - count
              chainFamily:
                $ref: '#/components/schemas/ChainFamilyForGeneration'
            required:
              - range
              - chainFamily
      description: >-
        Request to generate HD addresses from the public key. Specify a start
        index, count, and chain namespace to generate addresses for.
      required: true
    generate_next_hd_address_request:
      description: >-
        Request to generate the next HD address from the public key. The system
        will automatically determine the next available index.
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              chainFamily:
                $ref: '#/components/schemas/ChainFamilyForGeneration'
              label:
                $ref: '#/components/schemas/AddressLabel'
              meta:
                $ref: '#/components/schemas/AddressMeta'
            required:
              - chainFamily
            example:
              chainFamily: evm
              meta:
                user_id: '100'
                type: deposit
    create_external_address_request:
      content:
        application/json:
          schema:
            type: object
            properties:
              value:
                $ref: '#/components/schemas/AddressValue'
                description: Address value to import
              chainFamily:
                $ref: '#/components/schemas/ChainFamily'
              label:
                $ref: '#/components/schemas/AddressLabel'
              meta:
                $ref: '#/components/schemas/AddressMeta'
            required:
              - value
              - chainFamily
      description: >-
        Request to import an external address that is not derived from a public
        key
      required: true
    update_address_request:
      content:
        application/json:
          schema:
            properties:
              label:
                $ref: '#/components/schemas/AddressLabel'
              meta:
                $ref: '#/components/schemas/AddressMeta'
            type: object
      description: Request to update address metadata
      required: true
    create_nats_channel_request:
      required: true
      content:
        application/json:
          schema:
            type: object
            description: Request to create a new NATS notification channel
            properties:
              name:
                $ref: '#/components/schemas/NotificationChannelName'
              url:
                $ref: '#/components/schemas/NATSServerURL'
              subject:
                $ref: '#/components/schemas/NATSSubject'
            required:
              - name
              - url
              - subject
            additionalProperties: false
          examples:
            system_alerts:
              summary: System alerts channel
              value:
                name: System Alerts NATS
                url: nats://nats.example.com:4222
                subject: notifications.system.alerts
    update_nats_channel_request:
      required: true
      content:
        application/json:
          schema:
            type: object
            description: Request to update an existing NATS notification channel
            properties:
              name:
                $ref: '#/components/schemas/NotificationChannelName'
              url:
                $ref: '#/components/schemas/NATSServerURL'
              subject:
                $ref: '#/components/schemas/NATSSubject'
            minProperties: 1
            additionalProperties: false
          examples:
            update_name_only:
              summary: Update only channel name
              value:
                name: Updated NATS Channel
            update_config:
              summary: Update NATS configuration
              value:
                url: nats://new-nats.example.com:4222
                subject: notifications.updated.topic
            update_all:
              summary: Update all fields
              value:
                name: Production NATS Channel
                url: nats://prod-nats.example.com:4222
                subject: notifications.production.alerts
    create_telegram_channel_request:
      required: true
      content:
        application/json:
          schema:
            type: object
            description: Request to create a new Telegram notification channel
            properties:
              name:
                $ref: '#/components/schemas/NotificationChannelName'
              bot_token:
                $ref: '#/components/schemas/TelegramBotToken'
              chat_id:
                $ref: '#/components/schemas/TelegramChatID'
            required:
              - name
              - bot_token
              - chat_id
            additionalProperties: false
          examples:
            production_alerts:
              summary: Production alerts channel
              value:
                name: Production Alerts
                bot_token: 987654321:ABCDEFGHIJKLMNOPQRSTUVWXYZ123456789
                chat_id: -1001234567890
    update_telegram_channel_request:
      required: true
      content:
        application/json:
          schema:
            type: object
            description: Request to update an existing Telegram notification channel
            properties:
              name:
                $ref: '#/components/schemas/NotificationChannelName'
              bot_token:
                $ref: '#/components/schemas/TelegramBotToken'
              chat_id:
                $ref: '#/components/schemas/TelegramChatID'
            minProperties: 1
            additionalProperties: false
          examples:
            update_name_only:
              summary: Update only channel name
              value:
                name: Updated Telegram Channel
            update_bot_token:
              summary: Update bot token
              value:
                bot_token: 123456789:ABCDEFGHIJKLMNOPQRSTUVWXYZ123456789
            update_chat:
              summary: Update chat ID
              value:
                chat_id: -1009876543210
            update_all:
              summary: Update all fields
              value:
                name: Production Telegram Alerts
                bot_token: 987654321:ABCDEFGHIJKLMNOPQRSTUVWXYZ123456789
                chat_id: -1001234567890
    create_webhook_channel_request:
      required: true
      content:
        application/json:
          schema:
            type: object
            description: Request to create a new Webhook notification channel
            properties:
              name:
                $ref: '#/components/schemas/NotificationChannelName'
              url:
                $ref: '#/components/schemas/WebhookURL'
              headers:
                $ref: '#/components/schemas/WebhookHeaders'
            required:
              - name
              - url
              - headers
            additionalProperties: false
          examples:
            production_webhook:
              summary: Production webhook channel
              value:
                name: Production Alerts Webhook
                url: >-
                  https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
                headers:
                  Authorization: Bearer token123
    update_webhook_channel_request:
      required: true
      content:
        application/json:
          schema:
            type: object
            description: Request to update an existing Webhook notification channel
            properties:
              name:
                $ref: '#/components/schemas/NotificationChannelName'
              url:
                $ref: '#/components/schemas/WebhookURL'
              headers:
                $ref: '#/components/schemas/WebhookHeaders'
            minProperties: 1
            additionalProperties: false
          examples:
            update_name_only:
              summary: Update only channel name
              value:
                name: Updated Webhook Channel
            update_url:
              summary: Update webhook URL
              value:
                url: https://new-webhook.example.com/notifications
            update_headers:
              summary: Update webhook headers
              value:
                headers:
                  Authorization: Bearer new-token-xyz123
                  X-Custom-Header: new-value
            update_all:
              summary: Update all fields
              value:
                name: Production Webhook Alerts
                url: >-
                  https://prod-hooks.slack.com/services/T00000000/B00000000/YYYYYYYYYYYYYYYYYYYYYYYY
                headers:
                  Authorization: Bearer prod-token-abc789
