Skip to content
/
Add new public key

Vilna API (1.0.0)

Welcome to the Vilna API Reference. This is the complete OpenAPI specification for all API endpoints.

Quick Links

API Endpoints

Asset Management

  • Assets - Discover and manage digital assets

Address Operations

Monitoring and Notifications

System

Need Help?

Visit our documentation portal for detailed guides and examples.

Download OpenAPI description
spec.json
spec.yaml
Overview
URL
https://vilna.io
Vilna API Team
[email protected]
License
Apache 2.0
Terms of Service
Languages
Servers
Mock server
https://docs.vilna.io/_mock/apis/spec/
Production environment
https://{namespace}.vilna.app/{version}/

system

System and service status operations

Operations

blockchain

Operations related to supported blockchains for monitoring and balance queries

Operations

block

Operations for retrieving and filtering blockchain blocks

Operations

token

Manage blockchain tokens such as native and ERC-20 assets

Operations

public_key

Public key (BIP44/49/84) management operations for HD wallets

Operations

Get list of public keys

Request

Returns a list of all registered public keys

Security
ApiKeyAuth
Query
limitinteger[ 1 .. 100 ]

Maximum number of items to return

Default 20
Example: limit=20
pageinteger>= 1

Page number for pagination

Default 1
Example: page=1
searchstring<= 32 characters

Search filter for public keys (partial match, case-insensitive)

Example: search=wallet
sort_bystring

Field to sort results by. Use "-" prefix for descending order

Default "gid"
Enum"gid""-gid""label""-label""derivation_path""-derivation_path""created_at""-created_at""updated_at""-updated_at"
Example: sort_by=gid
curl -i -X GET \
  'https://docs.vilna.io/_mock/apis/spec/public_keys?limit=20&page=1&search=wallet&sort_by=gid' \
  -H 'X-Api-Key: YOUR_API_KEY_HERE'

Responses

Successfully retrieved list of public keys with pagination information

Bodyapplication/json
itemsArray of objects(PublicKey)required

List of public keys

items[].​idstring(uuid)(UUID)required

Unique identifier in UUID format

Example: "550e8400-e29b-41d4-a716-446655440000"
items[].​valuestring(PublicKeyValue)^(xpub|ypub|zpub|tpub|vpub|upub)[1-9A-HJ-NP-Z...required

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"
items[].​labelstring(PublicKeyLabel)[ 1 .. 32 ] charactersrequired

User-friendly label for the public key

Example: "Main Wallet"
items[].​derivation_pathstring(DerivationPath)^m/(44|49|84)'/\d+'\/\d+'\/\d+$required

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"
items[].​created_atstring(date-time)(CreatedAt)required

Timestamp when the resource was created

Example: "2024-01-15T10:30:00Z"
items[].​updated_atstring(date-time)(UpdatedAt)required

Timestamp when the resource was last updated

Example: "2024-01-15T10:30:00Z"
metaobject(PaginationMeta)required
meta.​limitinteger(uint)>= 1required

Number of items per page

Example: 20
meta.​pageinteger(uint)>= 1required

Current page number

Example: 1
meta.​totalinteger(uint)>= 0required

Total number of items available

Example: 42
meta.​total_pagesinteger(uint)>= 0required

Total number of pages available

Example: 3
Response
application/json
{
  "items": [
    { … },
    { … },
    { … },
    { … },
    { … }
  ],
  "meta": {
    "limit": 20,
    "page": 1,
    "total": 5,
    "total_pages": 1
  }
}

Add new public key

Request

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.

Security
ApiKeyAuth
Bodyapplication/jsonrequired

Request body for adding a new extended public key (HD wallet)

derivation_pathstring(DerivationPath)^m/(44|49|84)'/\d+'\/\d+'\/\d+$required

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"
labelstring(PublicKeyLabel)[ 1 .. 32 ] charactersrequired

User-friendly label for the public key

Example: "Main Wallet"
valuestring(PublicKeyValue)^(xpub|ypub|zpub|tpub|vpub|upub)[1-9A-HJ-NP-Z...required

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"
curl -i -X POST \
  https://docs.vilna.io/_mock/apis/spec/public_keys \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: YOUR_API_KEY_HERE' \
  -d '{
    "derivation_path": "m/44'\''/0'\''/0'\''/0",
    "label": "My Legacy Wallet",
    "value": "xpub6F7C1ZtQ411zykk6KTEoQMqfNdxiSA4uxAwAoqFanijnAavqQvVmh5zZCH6Swhdbzt2HuMRLx4chEVRZu9ic4Cnkkq5AsQcmjeMASk6FLqf"
  }'

Responses

Public key successfully created

Bodyapplication/json
idstring(uuid)(UUID)required

Unique identifier in UUID format

Example: "550e8400-e29b-41d4-a716-446655440000"
valuestring(PublicKeyValue)^(xpub|ypub|zpub|tpub|vpub|upub)[1-9A-HJ-NP-Z...required

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"
labelstring(PublicKeyLabel)[ 1 .. 32 ] charactersrequired

User-friendly label for the public key

Example: "Main Wallet"
derivation_pathstring(DerivationPath)^m/(44|49|84)'/\d+'\/\d+'\/\d+$required

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"
created_atstring(date-time)(CreatedAt)required

Timestamp when the resource was created

Example: "2024-01-15T10:30:00Z"
updated_atstring(date-time)(UpdatedAt)required

Timestamp when the resource was last updated

Example: "2024-01-15T10:30:00Z"
Response
application/json
{
  "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"
}

Delete a public key

Request

Delete a public key by its unique identifier

Security
ApiKeyAuth
Path
public_key_idstring(uuid)(UUID)required

Unique identifier (UUID) of the public key.

Example: 550e8400-e29b-41d4-a716-446655440000
curl -i -X DELETE \
  https://docs.vilna.io/_mock/apis/spec/public_keys/550e8400-e29b-41d4-a716-446655440000 \
  -H 'X-Api-Key: YOUR_API_KEY_HERE'

Responses

The request was successful but there is no content to return

Response
No content

Get a public key by ID

Request

Returns detailed information about a specific public key

Security
ApiKeyAuth
Path
public_key_idstring(uuid)(UUID)required

Unique identifier (UUID) of the public key.

Example: 550e8400-e29b-41d4-a716-446655440000
curl -i -X GET \
  https://docs.vilna.io/_mock/apis/spec/public_keys/550e8400-e29b-41d4-a716-446655440000 \
  -H 'X-Api-Key: YOUR_API_KEY_HERE'

Responses

Successfully retrieved public key information

Bodyapplication/json
idstring(uuid)(UUID)required

Unique identifier in UUID format

Example: "550e8400-e29b-41d4-a716-446655440000"
valuestring(PublicKeyValue)^(xpub|ypub|zpub|tpub|vpub|upub)[1-9A-HJ-NP-Z...required

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"
labelstring(PublicKeyLabel)[ 1 .. 32 ] charactersrequired

User-friendly label for the public key

Example: "Main Wallet"
derivation_pathstring(DerivationPath)^m/(44|49|84)'/\d+'\/\d+'\/\d+$required

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"
created_atstring(date-time)(CreatedAt)required

Timestamp when the resource was created

Example: "2024-01-15T10:30:00Z"
updated_atstring(date-time)(UpdatedAt)required

Timestamp when the resource was last updated

Example: "2024-01-15T10:30:00Z"
Response
application/json
{
  "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"
}

Update public key label

Request

Update the label of an existing public key

Security
ApiKeyAuth
Path
public_key_idstring(uuid)(UUID)required

Unique identifier (UUID) of the public key.

Example: 550e8400-e29b-41d4-a716-446655440000
Bodyapplication/jsonrequired

Request body for updating an existing public key. The label and archived status can be modified.

labelstring(PublicKeyLabel)[ 1 .. 32 ] charactersrequired

User-friendly label for the public key

Example: "Main Wallet"
is_archivedboolean

If true, marks the public key as archived

Example: false
curl -i -X PATCH \
  https://docs.vilna.io/_mock/apis/spec/public_keys/550e8400-e29b-41d4-a716-446655440000 \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: YOUR_API_KEY_HERE' \
  -d '{
    "label": "Main Wallet",
    "is_archived": false
  }'

Responses

Public key successfully updated

Bodyapplication/json
idstring(uuid)(UUID)required

Unique identifier in UUID format

Example: "550e8400-e29b-41d4-a716-446655440000"
valuestring(PublicKeyValue)^(xpub|ypub|zpub|tpub|vpub|upub)[1-9A-HJ-NP-Z...required

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"
labelstring(PublicKeyLabel)[ 1 .. 32 ] charactersrequired

User-friendly label for the public key

Example: "Main Wallet"
derivation_pathstring(DerivationPath)^m/(44|49|84)'/\d+'\/\d+'\/\d+$required

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"
created_atstring(date-time)(CreatedAt)required

Timestamp when the resource was created

Example: "2024-01-15T10:30:00Z"
updated_atstring(date-time)(UpdatedAt)required

Timestamp when the resource was last updated

Example: "2024-01-15T10:30:00Z"
Response
application/json
{
  "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"
}

Get addresses derived from public key

Request

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.

Security
ApiKeyAuth
Path
public_key_idstring(uuid)(UUID)required

Unique identifier (UUID) of the public key.

Example: 550e8400-e29b-41d4-a716-446655440000
Query
limitinteger[ 1 .. 100 ]

Maximum number of items to return

Default 20
Example: limit=20
pageinteger>= 1

Page number for pagination

Default 1
Example: page=1
sort_bystring

Field to sort results by. Use "-" prefix for descending order

Default "-created_at"
Enum"label""-label""address""-address""created_at""-created_at""updated_at""-updated_at"
Example: sort_by=-created_at
formatsArray of strings(AddressFormat)

Comma-separated list of address formats to include.

Items Enum"evm""solana""tron""p2pkh""p2sh""p2wpkh""p2wsh""p2pkh-testnet""p2sh-testnet""p2wpkh-testnet"
Example: formats=p2wpkh&formats=evm
searchstring<= 100 characters

Performs a partial, case-insensitive match on address or label fields.

Example: search=bc1q
is_archivedboolean

When true, returns only archived addresses. When false, returns only active ones.

Example: is_archived=false
curl -i -X GET \
  'https://docs.vilna.io/_mock/apis/spec/public_keys/550e8400-e29b-41d4-a716-446655440000/addresses?limit=20&page=1&sort_by=-created_at&formats=p2wpkh%2Cevm&search=bc1q&is_archived=false' \
  -H 'X-Api-Key: YOUR_API_KEY_HERE'

Responses

Successfully retrieved list of HD addresses derived from the public key

Bodyapplication/json
itemsArray of objects(HDAddress)required

List of HD addresses derived from the public key

items[].​valuestring(AddressValue)[ 1 .. 128 ] characters^[a-zA-Z0-9]+$required

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"
items[].​formatstring(AddressFormat)required

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"
Example: "p2wpkh"
items[].​labelstring or null(AddressLabel)<= 32 characters

User-friendly label for the address

Example: "user_45_deposit"
items[].​kindstring(AddressKind)required

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"
items[].​metaobject(AddressMeta)

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
Example: {"user_id":"12345","source":"exchange","category":"trading"}
items[].​created_atstring(date-time)(CreatedAt)required

Timestamp when the resource was created

Example: "2024-01-15T10:30:00Z"
items[].​updated_atstring(date-time)(UpdatedAt)required

Timestamp when the resource was last updated

Example: "2024-01-15T10:30:00Z"
items[].​public_key_idstring(uuid)(UUID)required

Unique identifier in UUID format

Example: "550e8400-e29b-41d4-a716-446655440000"
items[].​derivation_indexinteger>= 0required

Address index in the HD wallet derivation sequence

Example: 45
metaobject(PaginationMeta)required
meta.​limitinteger(uint)>= 1required

Number of items per page

Example: 20
meta.​pageinteger(uint)>= 1required

Current page number

Example: 1
meta.​totalinteger(uint)>= 0required

Total number of items available

Example: 42
meta.​total_pagesinteger(uint)>= 0required

Total number of pages available

Example: 3
Response
application/json
{
  "items": [
    { … },
    { … },
    { … }
  ],
  "meta": {
    "limit": 20,
    "page": 1,
    "total": 3,
    "total_pages": 1
  }
}

Generate addresses from public key

Request

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.

Security
ApiKeyAuth
Path
public_key_idstring(uuid)(UUID)required

Unique identifier (UUID) of the public key.

Example: 550e8400-e29b-41d4-a716-446655440000
Bodyapplication/jsonrequired

Request to generate HD addresses from the public key. Specify a start index, count, and chain namespace to generate addresses for.

rangeobjectrequired

Range definition for HD address generation

range.​startIndexinteger>= 0required

Starting index (inclusive)

Example: 100
range.​countinteger[ 1 .. 10000 ]required

Number of addresses to generate

Example: 50
chainFamilystring(ChainFamilyForGeneration)required

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"
curl -i -X POST \
  https://docs.vilna.io/_mock/apis/spec/public_keys/550e8400-e29b-41d4-a716-446655440000/addresses \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: YOUR_API_KEY_HERE' \
  -d '{
    "range": {
      "startIndex": 100,
      "count": 50
    },
    "chainFamily": "evm"
  }'

Responses

Addresses generated successfully

Bodyapplication/json
itemsArray of stringsrequired

Array of generated address values

Example: ["0x8521E8b15eCEF4D4269Fded3E6694225E096959E"]
countinteger>= 0required

Number of addresses generated

Example: 3
Response
application/json
{
  "items": [
    "bc1q39vtx8qt39ztrx0j9rm6f5lz56qze0c68qafhu",
    "bc1qnc8aj03r2letsdzfmhmr99v5sw6mys7jgz7huh",
    "bc1qjq73wzhhzt40250678hwpzgrrucutkx77ze37d"
  ],
  "count": 3
}

Generate next address from public key

Request

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.

Security
ApiKeyAuth
Path
public_key_idstring(uuid)(UUID)required

Unique identifier (UUID) of the public key.

Example: 550e8400-e29b-41d4-a716-446655440000
Bodyapplication/jsonrequired

Request to generate the next HD address from the public key. The system will automatically determine the next available index.

chainFamilystring(ChainFamilyForGeneration)required

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"
labelstring or null(AddressLabel)<= 32 characters

User-friendly label for the address

Example: "user_45_deposit"
metaobject(AddressMeta)

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
Example: {"user_id":"12345","source":"exchange","category":"trading"}
curl -i -X POST \
  https://docs.vilna.io/_mock/apis/spec/public_keys/550e8400-e29b-41d4-a716-446655440000/addresses/next \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: YOUR_API_KEY_HERE' \
  -d '{
    "chainFamily": "evm",
    "meta": {
      "user_id": "100",
      "type": "deposit"
    }
  }'

Responses

HD address successfully created

Bodyapplication/json
valuestring(AddressValue)[ 1 .. 128 ] characters^[a-zA-Z0-9]+$required

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"
formatstring(AddressFormat)required

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"
Example: "p2wpkh"
labelstring or null(AddressLabel)<= 32 characters

User-friendly label for the address

Example: "user_45_deposit"
kindstring(AddressKind)required

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"
metaobject(AddressMeta)

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
Example: {"user_id":"12345","source":"exchange","category":"trading"}
created_atstring(date-time)(CreatedAt)required

Timestamp when the resource was created

Example: "2024-01-15T10:30:00Z"
updated_atstring(date-time)(UpdatedAt)required

Timestamp when the resource was last updated

Example: "2024-01-15T10:30:00Z"
public_key_idstring(uuid)(UUID)required

Unique identifier in UUID format

Example: "550e8400-e29b-41d4-a716-446655440000"
derivation_indexinteger>= 0required

Address index in the HD wallet derivation sequence

Example: 45
Response
application/json
{
  "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"
}

address

Address management operations for tracking blockchain addresses

Operations

notification_channel

Notification delivery channel management for alerts and event notifications

Operations

transaction

Blockchain transaction tracking and monitoring operations

Operations

simulate

Transaction simulation operations for various blockchain networks

asset

Asset management operations for blockchain assets

Operations