Blockchain basics for developers

Learn how addresses, public keys, amounts and confirmations appear in Vilna’s API. No blockchain experience is required. Already familiar with these concepts? Start with Core concepts.

Forget the hype for a moment. For an integration, a blockchain is just a shared record book that everyone can read and no one can secretly edit. New transactions extend that record; reorganizations can replace recent blocks.

Three properties are all you need to hold in your head:

A public ledger can be monitored using an address, without the wallet owner's permission. Platform monitoring reads that public data.

Reading a chain yourself means running nodes, indexing blocks, handling reorgs and decoding every transaction format, all of it per chain. Platform does that for supported networks and returns normalized data. Platform monitoring observes the chain:

For an address controlled by one private key, the relationship between the key and address looks like this:

The takeaway for integration: the address and public key are safe to share; the private key is not. Platform monitoring uses the public side: provide a public key or address to watch it. It does not need the private key.

Address formats can suggest a chain family, but the address alone does not identify the network. Check the chain identifier as well as the address before sending:

One convenient detail of EVM chains: a single 0x… address works on every EVM network. The same Ethereum address can receive funds on Polygon, Arbitrum or Base without any change.

When you register an address with Vilna you pass input.chain_family (evm, bitcoin or tron; solana registers the address and resolves its tokens, without balances or transactions) and the exact format is auto-detected from the value; see the Platform API for the endpoints.

Real products need a fresh address per customer, sometimes thousands of them. Generating and backing up thousands of independent secrets is unmanageable. HD wallets (Hierarchical Deterministic) solve this with a single starting secret.

You begin with one seed phrase, typically 12 or 24 words. From that seed, the wallet can generate an unlimited tree of key pairs. Deterministic means the same seed always produces the same keys, in the same order, forever. A derivation path is the route down that tree to one specific key: pick a branch at each level and you arrive at a single address:

One seed backup covers the derived addresses; a fresh address per customer is the exchange monitoring pattern.

To let Vilna generate and watch that tree of addresses without ever touching the secret, you share an extended public key: a special public key that can produce child addresses (and only addresses, never signatures). Bitcoin has three flavours, one per address style:

For EVM chains you use an xPub (BIP-44). For Bitcoin Taproot there is no single-letter prefix; use an xPub with the Taproot path below.

A derivation path is the "address inside the tree", like a folder path that points at one exact key. It reads left to right, narrowing from the master key down to a single address:

The apostrophe (') after a number means hardened: a safety feature that stops a child key from being used to work backward to its parent. You will mostly copy known-good paths rather than hand-build them:

Import the extended public key with POST/public-keys, then call POST/public-keys/{public_key_id}/addresses with "chain_family": "evm", "selection": {"kind": "next"} in the body to mint the next address in the sequence. Each one is registered for monitoring automatically.

Most wallets can export an extended public key. The three most common sources:

Export the public key using your wallet. Never send a seed phrase or private key to Vilna. Then register the extended public key and derive addresses; the operation pages contain parameters and request examples.

With dozens of chains and thousands of tokens, a phrase like "USDT on BSC" isn't precise enough for code to act on: there are test networks, bridged copies and look-alike contracts. So Vilna leans on two open standards that turn any chain or asset into one exact, unambiguous string you and the API both agree on: CAIP-2 names a chain, and CAIP-19 names an asset on that chain.

You rarely type these by hand; Vilna returns them ready-made in every response. The goal here is just to recognize one when you see it. Read it left to right: a chain, optionally followed by the asset living on it.

One distinction worth holding onto, because it shapes how balances and fees work. Every chain has one built-in currency, plus any number of tokens layered on top:

The supported chain list is available from the Platform API.

Blockchains store amounts as whole numbers in a coin's smallest unit (think cents, not dollars, but often with 18 decimal places). Many transaction and balance amounts have two fields:

{
  "base": "1500000000000000000",
  "formatted": "1.5"
}

• base - the raw integer in the smallest unit (wei for ETH, satoshi for BTC). Exact, never rounded.
• formatted - the human-readable decimal, ready to print in a UI.

Invoice amount fields differ; see Core concepts.

A transaction isn't trustworthy the instant it's sent. It earns certainty as the chain grows on top of it. Understanding these stages is what stops you from crediting money that later disappears:

Confirmation and finality rules differ by network. Choose a confirmation policy for your application rather than treating a fixed block count as a universal guarantee.