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

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

Get list of transactions

Request

Returns a paginated list of transactions based on the provided filters.

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
sort_bystring

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

Default "-created_at"
Enum"transaction_hash""-transaction_hash""block_number""-block_number""initiator""-initiator""target""-target""is_success""-is_success"
Example: sort_by=-created_at
initiator_addressArray of strings(AddressValue)

Filter transactions by initiator addresses (exact match)

Example: initiator_address=0x742d35Cc6b3C0532925a3b8c17c8b4842f6c8E5a&initiator_address=0x123456789abcdef123456789abcdef123456789ab
target_addressArray of strings(AddressValue)

Filter transactions by target addresses (exact match)

Example: target_address=0xdAC17F958D2ee523a2206206994597C13D831ec7&target_address=0x9876543210abcdef9876543210abcdef98765432
addressArray of strings(AddressValue)

Filter transactions where any of the addresses is either initiator or target address

Example: address=0x742d35Cc6b3C0532925a3b8c17c8b4842f6c8E5a&address=0xdAC17F958D2ee523a2206206994597C13D831ec7
chain_gidsArray of strings(ChainGID)

Filter transactions by blockchain chain GIDs

Example: chain_gids=eip155:1&chain_gids=eip155:56&chain_gids=eip155:137
is_successboolean

Filter transactions by success status

Example: is_success=true
curl -i -X GET \
  'https://docs.vilna.io/_mock/apis/spec/transactions?limit=20&page=1&sort_by=-created_at&initiator_address=0x742d35Cc6b3C0532925a3b8c17c8b4842f6c8E5a%2C0x123456789abcdef123456789abcdef123456789ab&target_address=0xdAC17F958D2ee523a2206206994597C13D831ec7%2C0x9876543210abcdef9876543210abcdef98765432&address=0x742d35Cc6b3C0532925a3b8c17c8b4842f6c8E5a%2C0xdAC17F958D2ee523a2206206994597C13D831ec7&chain_gids=eip155%3A1%2Ceip155%3A56%2Ceip155%3A137&is_success=true' \
  -H 'X-Api-Key: YOUR_API_KEY_HERE'

Responses

Successful response returning a list of blockchain transactions

Bodyapplication/json
itemsArray of objects(Transaction)required

List of blockchain transactions with their asset transfers

items[].​transaction_hashstringrequired

Hash of the transaction on the blockchain

Example: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
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[].​chain_familystring(ChainFamily)required

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

Block number containing the transaction

Example: 1974382
items[].​initiatorobject(AddressRef)required

Reference to a blockchain address with minimal system context

items[].​initiator.​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[].​initiator.​is_knownbooleanrequired

Whether this address is known/managed by the system (internal) or external

Example: true
items[].​targetobject(AddressRef)

Reference to a blockchain address with minimal system context

items[].​transfersArray of objects(Transfer)non-emptyrequired

Collection of asset transfers within this transaction (e.g., ERC-20, ETH, BTC outputs, Solana SPL tokens). Always contains at least one transfer.

items[].​transfers[].​asset_gidstring(AssetGID)^[-a-zA-Z0-9]{1,32}:[-a-zA-Z0-9]{1,64}/[-a-zA...required

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"
items[].​transfers[].​sequenceinteger(uint16)>= 0required

Sequential index of the transfer within the transaction, starting from 0. Defines order of transfers and ensures uniqueness per transaction.

Example: 0
items[].​transfers[].​kindstring(TransferKind)required

Type of asset transfer within a blockchain transaction

Enum"native""fungible"
Example: "native"
items[].​transfers[].​senderobject(AddressRef)

Reference to a blockchain address with minimal system context

items[].​transfers[].​recipientobject(AddressRef)

Reference to a blockchain address with minimal system context

items[].​transfers[].​amountstring^[0-9]+$required

Amount transferred in the smallest unit of the asset (without decimal adjustment)

Example: "1000000000000000000"
items[].​transfers[].​metaEVMTransferMeta (object) or BitcoinTransferMeta (object) or SolanaTransferMeta (object) or TronTransferMeta (object)(TransferMeta)

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.

One of:

Metadata specific to EVM (Ethereum Virtual Machine) blockchain transfers.

items[].​is_successbooleanrequired

Whether the transaction executed successfully

Example: true
items[].​created_atstring(date-time)(CreatedAt)required

Timestamp when the resource was created

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

Timestamp when the transaction was confirmed on the blockchain

Example: "2024-01-15T14: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": {
    "page": 1,
    "limit": 20,
    "total": 4,
    "total_pages": 1
  }
}

simulate

Transaction simulation operations for various blockchain networks

asset

Asset management operations for blockchain assets

Operations