# Vilna API Welcome to the Vilna API Reference. This is the complete OpenAPI specification for all API endpoints. Quick Links - [API Overview](/apis/) - Introduction and concepts - [Security Guide](/apis/security) - Authentication and webhook verification - [CAIP Standards](/apis/caip-standards) - Asset identification standards - [Quick Start Guide](/guides/quickstart) - Step-by-step integration tutorial **API Endpoints** Asset Management - **[Assets](#tag/asset)** - Discover and manage digital assets Address Operations - **[Addresses](#tag/address)** - Manage blockchain addresses - **[Extended Public Keys](#tag/xpub)** - HD wallet management Monitoring and Notifications - **[Transactions](#tag/transaction)** - Transaction monitoring System - **[Blockchains](#tag/blockchain)** - Information on supported blockchains - **[System Status](#tag/system)** - Health checks and version info **Need Help?** Visit our [documentation portal](/apis/) for detailed guides and examples. Version: 1.0.0 License: Apache 2.0 ## Servers Production environment ``` https://{namespace}.vilna.app/{version} ``` Variables: - `namespace`: This value is assigned by the service provider. Default: "demo" - `version`: API version Default: "v1" ## Security ### ApiKeyAuth API key for authentication Type: apiKey In: header Name: X-Api-Key ## Download OpenAPI description [Vilna API](https://docs.vilna.io/_bundle/apis/spec.yaml) ## system System and service status operations ### Get API version - [GET /version](https://docs.vilna.io/apis/spec/system/getversion.md): Returns the current version of the vilna API service. ## blockchain Operations related to supported blockchains for monitoring and balance queries ### Get list of supported blockchains - [GET /blockchains](https://docs.vilna.io/apis/spec/blockchain/listblockchains.md): 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. ### Create a new supported blockchain - [POST /blockchains](https://docs.vilna.io/apis/spec/blockchain/createblockchain.md): 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. ### Get a single blockchain - [GET /blockchains/{chain_gid}](https://docs.vilna.io/apis/spec/blockchain/getblockchain.md): 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. ### Activate blockchain - [POST /blockchains/{chain_gid}/actions/activate](https://docs.vilna.io/apis/spec/blockchain/activateblockchain.md): Activates a blockchain for monitoring and processing by workers. ### Deactivate blockchain - [POST /blockchains/{chain_gid}/actions/deactivate](https://docs.vilna.io/apis/spec/blockchain/deactivateblockchain.md): Deactivates a blockchain from monitoring and processing by workers. ### Update EVM blockchain configuration - [PATCH /blockchains/{chain_gid}/evm](https://docs.vilna.io/apis/spec/blockchain/patchevmblockchain.md): Update the configuration of an existing EVM-compatible blockchain ### Update Solana blockchain configuration - [PATCH /blockchains/{chain_gid}/solana](https://docs.vilna.io/apis/spec/blockchain/patchsolanablockchain.md): Update the configuration of an existing Solana blockchain ### Update Tron blockchain configuration - [PATCH /blockchains/{chain_gid}/tron](https://docs.vilna.io/apis/spec/blockchain/patchtronblockchain.md): Update the configuration of an existing Tron blockchain ### Update Bitcoin blockchain configuration - [PATCH /blockchains/{chain_gid}/bitcoin](https://docs.vilna.io/apis/spec/blockchain/patchbitcoinblockchain.md): Update the configuration of an existing Bitcoin blockchain ### Get blocks across blockchains - [GET /blocks](https://docs.vilna.io/apis/spec/blockchain/listblocks.md): Returns a paginated list of blocks from all or specified blockchains. ### Get a specific block - [GET /blocks/{chain_gid}/{block_number}](https://docs.vilna.io/apis/spec/blockchain/getblock.md): Returns details of a specific block by its number for a given blockchain. ### Get blocks across blockchains - [GET /blocks](https://docs.vilna.io/apis/spec/block/listblocks.md): Returns a paginated list of blocks from all or specified blockchains. ### Get a specific block - [GET /blocks/{chain_gid}/{block_number}](https://docs.vilna.io/apis/spec/block/getblock.md): Returns details of a specific block by its number for a given blockchain. ## block Operations for retrieving and filtering blockchain blocks ### Get blocks across blockchains - [GET /blocks](https://docs.vilna.io/apis/spec/blockchain/listblocks.md): Returns a paginated list of blocks from all or specified blockchains. ### Get a specific block - [GET /blocks/{chain_gid}/{block_number}](https://docs.vilna.io/apis/spec/blockchain/getblock.md): Returns details of a specific block by its number for a given blockchain. ### Get blocks across blockchains - [GET /blocks](https://docs.vilna.io/apis/spec/block/listblocks.md): Returns a paginated list of blocks from all or specified blockchains. ### Get a specific block - [GET /blocks/{chain_gid}/{block_number}](https://docs.vilna.io/apis/spec/block/getblock.md): Returns details of a specific block by its number for a given blockchain. ## token Manage blockchain tokens such as native and ERC-20 assets ### Get list of all known tokens - [GET /tokens](https://docs.vilna.io/apis/spec/token/listtokens.md): Returns a list of all token assets. Includes native tokens and ERC-20 tokens. ### Create a new token - [POST /tokens/{chain_gid}/{asset_path}](https://docs.vilna.io/apis/spec/token/createtoken.md): Creates a new token using its CAIP-19 identifier and automatically retrieves its metadata (name, symbol, decimals, type) from the blockchain. ### Get details of a specific token - [GET /tokens/{chain_gid}/{asset_path}](https://docs.vilna.io/apis/spec/token/gettoken.md): Returns detailed information about the specified token asset. ## public_key Public key (BIP44/49/84) management operations for HD wallets ### Get list of public keys - [GET /public_keys](https://docs.vilna.io/apis/spec/public_key/listpublickeys.md): Returns a list of all registered public keys ### Add new public key - [POST /public_keys](https://docs.vilna.io/apis/spec/public_key/createpublickey.md): 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. ### Delete a public key - [DELETE /public_keys/{public_key_id}](https://docs.vilna.io/apis/spec/public_key/deletepublickey.md): Delete a public key by its unique identifier ### Get a public key by ID - [GET /public_keys/{public_key_id}](https://docs.vilna.io/apis/spec/public_key/getpublickey.md): Returns detailed information about a specific public key ### Update public key label - [PATCH /public_keys/{public_key_id}](https://docs.vilna.io/apis/spec/public_key/patchpublickey.md): Update the label of an existing public key ### Get addresses derived from public key - [GET /public_keys/{public_key_id}/addresses](https://docs.vilna.io/apis/spec/public_key/listpublickeyaddresses.md): 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. ### Generate addresses from public key - [POST /public_keys/{public_key_id}/addresses](https://docs.vilna.io/apis/spec/public_key/generatepublickeyaddresses.md): 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. ### Generate next address from public key - [POST /public_keys/{public_key_id}/addresses/next](https://docs.vilna.io/apis/spec/public_key/generatenextpublickeyaddress.md): 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. ### Get addresses derived from public key - [GET /public_keys/{public_key_id}/addresses](https://docs.vilna.io/apis/spec/address/listpublickeyaddresses.md): 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. ### Generate addresses from public key - [POST /public_keys/{public_key_id}/addresses](https://docs.vilna.io/apis/spec/address/generatepublickeyaddresses.md): 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. ### Generate next address from public key - [POST /public_keys/{public_key_id}/addresses/next](https://docs.vilna.io/apis/spec/address/generatenextpublickeyaddress.md): 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. ## address Address management operations for tracking blockchain addresses ### Get addresses derived from public key - [GET /public_keys/{public_key_id}/addresses](https://docs.vilna.io/apis/spec/public_key/listpublickeyaddresses.md): 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. ### Generate addresses from public key - [POST /public_keys/{public_key_id}/addresses](https://docs.vilna.io/apis/spec/public_key/generatepublickeyaddresses.md): 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. ### Generate next address from public key - [POST /public_keys/{public_key_id}/addresses/next](https://docs.vilna.io/apis/spec/public_key/generatenextpublickeyaddress.md): 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. ### Get addresses derived from public key - [GET /public_keys/{public_key_id}/addresses](https://docs.vilna.io/apis/spec/address/listpublickeyaddresses.md): 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. ### Generate addresses from public key - [POST /public_keys/{public_key_id}/addresses](https://docs.vilna.io/apis/spec/address/generatepublickeyaddresses.md): 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. ### Generate next address from public key - [POST /public_keys/{public_key_id}/addresses/next](https://docs.vilna.io/apis/spec/address/generatenextpublickeyaddress.md): 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. ### Get list of all addresses - [GET /addresses](https://docs.vilna.io/apis/spec/address/listaddresses.md): Returns a list of all addresses (both HD and external). This endpoint provides a unified view of all addresses in the system. ### Import external address - [POST /addresses/external](https://docs.vilna.io/apis/spec/address/createexternaladdress.md): 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. ### Get all HD addresses - [GET /addresses/hd](https://docs.vilna.io/apis/spec/address/listhdaddresses.md): 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. ### Delete an address - [DELETE /addresses/{address}](https://docs.vilna.io/apis/spec/address/deleteaddress.md): Permanently deletes an address by its blockchain address. This action cannot be undone. ### Get a single address - [GET /addresses/{address}](https://docs.vilna.io/apis/spec/address/getaddress.md): Returns details of a specific address by its blockchain address ### Update address metadata - [PATCH /addresses/{address}](https://docs.vilna.io/apis/spec/address/patchaddress.md): Updates address ### Get HD address representation - [GET /addresses/{address}/hd](https://docs.vilna.io/apis/spec/address/gethdaddress.md): 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. ### Get external address representation - [GET /addresses/{address}/external](https://docs.vilna.io/apis/spec/address/getexternaladdress.md): 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. ### Get all active asset balances for an address - [GET /addresses/{address}/balances](https://docs.vilna.io/apis/spec/address/getaddressbalances.md): 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 ## notification_channel Notification delivery channel management for alerts and event notifications ### Get list of notification channels - [GET /notification_channels](https://docs.vilna.io/apis/spec/notification_channel/listnotificationchannels.md): Returns a paginated list of all notification delivery channels ### Create NATS notification channel - [POST /notification_channels/nats](https://docs.vilna.io/apis/spec/notification_channel/createnatschannel.md): Creates a new NATS notification channel for subject-based messaging ### Update NATS notification channel - [PATCH /notification_channels/nats/{notification_channel_id}](https://docs.vilna.io/apis/spec/notification_channel/patchnatschannel.md): Update the configuration of an existing NATS notification channel ### Create Telegram notification channel - [POST /notification_channels/telegram](https://docs.vilna.io/apis/spec/notification_channel/createtelegramchannel.md): Creates a new Telegram notification channel for bot message delivery ### Update Telegram notification channel - [PATCH /notification_channels/telegram/{notification_channel_id}](https://docs.vilna.io/apis/spec/notification_channel/patchtelegramchannel.md): Update the configuration of an existing Telegram notification channel ### Create Webhook notification channel - [POST /notification_channels/webhook](https://docs.vilna.io/apis/spec/notification_channel/createwebhookchannel.md): Creates a new Webhook notification channel for HTTP callback delivery ### Update Webhook notification channel - [PATCH /notification_channels/webhook/{notification_channel_id}](https://docs.vilna.io/apis/spec/notification_channel/patchwebhookchannel.md): Update the configuration of an existing Webhook notification channel ### Get notification channel by ID - [GET /notification_channels/{notification_channel_id}](https://docs.vilna.io/apis/spec/notification_channel/getnotificationchannel.md): Returns detailed information about a specific notification channel ### Delete notification channel - [DELETE /notification_channels/{notification_channel_id}](https://docs.vilna.io/apis/spec/notification_channel/deletenotificationchannel.md): Delete a notification channel by its unique identifier ### Archive notification channel - [POST /notification_channels/{notification_channel_id}/actions/archive](https://docs.vilna.io/apis/spec/notification_channel/archivenotificationchannel.md): Archives (disables) a notification channel while preserving its configuration ### Restore notification channel - [POST /notification_channels/{notification_channel_id}/actions/restore](https://docs.vilna.io/apis/spec/notification_channel/restorenotificationchannel.md): Restores an archived notification channel, making it active again ## transaction Blockchain transaction tracking and monitoring operations ### Get list of transactions - [GET /transactions](https://docs.vilna.io/apis/spec/transaction/listtransactions.md): Returns a paginated list of transactions based on the provided filters. ## asset Asset management operations for blockchain assets ### Get list of all assets - [GET /assets](https://docs.vilna.io/apis/spec/asset/listassets.md): Returns a paginated list of all blockchain assets with filtering options. ### Archive an asset - [POST /assets/{chain_gid}/{asset_path}/actions/archive](https://docs.vilna.io/apis/spec/asset/archiveasset.md): Archives an asset by its Global Identifier (GID), removing it from active listings ### Restore an archived asset - [POST /assets/{chain_gid}/{asset_path}/actions/restore](https://docs.vilna.io/apis/spec/asset/restoreasset.md): Restores a previously archived asset by its Global Identifier (GID), making it active again