Skip to content

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

Get blocks across blockchains

Request

Returns a paginated list of blocks from all or specified blockchains.

Security
ApiKeyAuth
Query
pageinteger>= 1

Page number for pagination

Default 1
Example: page=1
limitinteger[ 1 .. 100 ]

Maximum number of items to return

Default 20
Example: limit=20
sort_bystring

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

Default "number"
Enum"number""-number""status""-status"
Example: sort_by=number
chain_gidsArray of strings(ChainGID)

Comma-separated list of chain GIDs to filter blocks by.

Example: chain_gids=eip155:1&chain_gids=eip155:137
statusesArray of strings

Comma-separated list of block statuses to include.

Items Enum"new""fetched""processed""confirmed""reorged"
Example: statuses=confirmed&statuses=processed
from_blockinteger(int64)>= 0

Start from this block number (inclusive).

Example: from_block=18500000
to_blockinteger(int64)>= 0

End at this block number (inclusive).

Example: to_block=18500100
curl -i -X GET \
  'https://docs.vilna.io/_mock/apis/spec/blocks?page=1&limit=20&sort_by=number&chain_gids=eip155%3A1%2Ceip155%3A137&statuses=confirmed%2Cprocessed&from_block=18500000&to_block=18500100' \
  -H 'X-Api-Key: YOUR_API_KEY_HERE'

Responses

List of blockchain blocks with their processing status

Bodyapplication/json
itemsArray of objects(Block)required
items[].​chain_gidstring(ChainGID)^[a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32}$required

Blockchain identifier according to 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
Example: "eip155:1"
items[].​numberinteger(int64)required

Block number/height on the blockchain

Example: 18500000
items[].​hashstring

Block hash identifier unique per blockchain (null if not yet fetched)

Example: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
items[].​statusstringrequired

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)
Enum"new""processed""confirmed""reorged"
Example: "confirmed"
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": 18500001,
    "total_pages": 925001
  }
}

Get a specific block

Request

Returns details of a specific block by its number for a given blockchain.

Security
ApiKeyAuth
Path
chain_gidstring(ChainGID)^[a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32}$required

Blockchain identifier in CAIP-2 format (namespace:reference)

Example: eip155:1
block_numberinteger(int64)>= 0required

Block number/height on the blockchain

Example: 18500000
curl -i -X GET \
  https://docs.vilna.io/_mock/apis/spec/blocks/eip155:1/18500000 \
  -H 'X-Api-Key: YOUR_API_KEY_HERE'

Responses

Single blockchain block

Bodyapplication/json
chain_gidstring(ChainGID)^[a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32}$required

Blockchain identifier according to 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
Example: "eip155:1"
numberinteger(int64)required

Block number/height on the blockchain

Example: 18500000
hashstring

Block hash identifier unique per blockchain (null if not yet fetched)

Example: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
statusstringrequired

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)
Enum"new""processed""confirmed""reorged"
Example: "confirmed"
Response
application/json
{
  "chain_gid": "eip155:1",
  "number": 18500000,
  "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "status": "confirmed"
}

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

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