Integration patterns

This guide walks through five common integration scenarios. Each pattern describes the goal, the API calls involved, and the sequence of operations. For full request and response schemas, see the Platform API Reference.

Goal: Monitor customer deposit addresses and react to incoming funds in real time.

When to use: Payment platforms, exchange deposit flows, and any service that needs to credit user accounts when crypto arrives.

1. Import your HD wallet public key (POST /public_keys).
2. Generate a unique deposit address for each customer (POST /public_keys/{public_key_id}/addresses/next).
3. Create a webhook notification channel (POST /channels).
4. When funds arrive, Vilna delivers a webhook event to your server.
5. Your server verifies the signature, matches the address to a customer, and credits their account.

# 1. Import xPub
curl -X POST "https://api.vilna.io/v1/public_keys" \
  -H "X-Api-Key: ${VILNA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "xpub6CUGRUonZSQ4TWtTMmzXdrXDtypWKiKp...",
    "label": "Customer Deposits",
    "derivation_path": "m/84h/0h/0h"
  }'

# 2. Generate next address for a new customer
curl -X POST "https://api.vilna.io/v1/public_keys/{pubkey_id}/addresses/next" \
  -H "X-Api-Key: ${VILNA_API_KEY}"

# 3. Create webhook channel
curl -X POST "https://api.vilna.io/v1/channels" \
  -H "X-Api-Key: ${VILNA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Deposit Webhooks",
    "config": {
      "kind": "webhook",
      "url": "https://your-app.example.com/deposits/webhook",
      "headers": {}
    }
  }'

• Use X-Webhook-Event-Id (or the event_id body field) to prevent double-crediting on retries — it is stable across retry attempts.
• Store the mapping between generated addresses and customer IDs in your database.
• Verify webhook signatures before processing. See Authentication.

Goal: Show users an aggregated view of their holdings and recent activity across multiple chains.

When to use: Wallet dashboards, accounting tools, and portfolio analytics products.

1. Import each user address with POST /addresses/external.
2. Poll GET /balances for current holdings.
3. Poll GET /activity for recent balance changes.
4. Use references.tokens and references.blockchains from the response to display token names and chain info without extra lookups.

# Add an address
curl -X POST "https://api.vilna.io/v1/addresses/external" \
  -H "X-Api-Key: ${VILNA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B",
    "chainFamily": "evm",
    "label": "Main Wallet"
  }'

# Fetch balances
curl "https://api.vilna.io/v1/balances?limit=30&page=1" \
  -H "X-Api-Key: ${VILNA_API_KEY}"

# Fetch recent activity
curl "https://api.vilna.io/v1/activity?limit=50&page=1" \
  -H "X-Api-Key: ${VILNA_API_KEY}"

• Use the meta.total_pages value to implement pagination or infinite scroll.
• The references object in each response includes token and chain metadata, so you don't need extra API calls for display names.
• For real-time updates, combine polling with a webhook channel.

Goal: Manage a hierarchical deterministic wallet where new addresses are derived on demand and automatically monitored.

When to use: Custody platforms, exchange hot wallets, and any system that generates addresses from a master public key.

1. Import the extended public key (POST /public_keys) with its derivation path.
2. Whenever you need a fresh address, call POST /public_keys/{public_key_id}/addresses/next.
3. Vilna tracks the derivation index and starts monitoring the new address immediately.
4. Query balances and transactions across all derived addresses using GET /balances and GET /transactions.

# Import the extended public key
curl -X POST "https://api.vilna.io/v1/public_keys" \
  -H "X-Api-Key: ${VILNA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "xpub6BosfCnifzxRT1QKLpFfcUrgWmLqoJcGt...",
    "label": "Exchange Hot Wallet",
    "derivation_path": "m/44h/60h/0h"
  }'

# Generate addresses as needed
curl -X POST "https://api.vilna.io/v1/public_keys/{pubkey_id}/addresses/next" \
  -H "X-Api-Key: ${VILNA_API_KEY}"

• Vilna supports BIP-32, BIP-44, BIP-49, BIP-84, and BIP-86 derivation paths.
• You can import xPub, yPub, or zPub keys depending on the address format you need (legacy, SegWit, native SegWit, Taproot).
• The public key never leaves Vilna unencrypted - private keys are never required.

Goal: Track addresses across several blockchains and filter activity by chain.

When to use: Multi-chain wallets, cross-chain analytics dashboards, and compliance monitoring tools.

1. Check which blockchains are available (GET /blockchains).
2. Register addresses with a chainFamily to monitor them on all chains in that family.
3. Query GET /activity or GET /transactions and filter by chain as needed.
4. Use references.blockchains to display chain metadata.

# List supported chains
curl "https://api.vilna.io/v1/blockchains" \
  -H "X-Api-Key: ${VILNA_API_KEY}"

# Monitor an address on all EVM chains (Ethereum, Polygon, Arbitrum, etc.)
curl -X POST "https://api.vilna.io/v1/addresses/external" \
  -H "X-Api-Key: ${VILNA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B",
    "chainFamily": "evm",
    "label": "Multi-chain Wallet"
  }'

# Get activity across all chains
curl "https://api.vilna.io/v1/activity?limit=30&page=1" \
  -H "X-Api-Key: ${VILNA_API_KEY}"

• EVM addresses (0x-prefixed) can be monitored on all EVM-compatible chains with a single POST /addresses/external call by specifying chainFamily: "evm".
• Non-EVM chains (Bitcoin, Solana, Tron) require chain-specific address formats.
• Each chain is indexed independently, so a single address may have different balances and transaction histories on different chains.

Goal: Receive real-time notifications through multiple channels whenever blockchain activity occurs on monitored addresses.

When to use: Treasury monitoring, compliance alerts, operational dashboards, and on-call systems.

1. Add the addresses you want to watch (POST /addresses/external).
2. Create a webhook channel for your backend (POST /channels with kind: "webhook").
3. Optionally create a Telegram channel for human operators (POST /channels with kind: "telegram").
4. Test both channels (POST /channels/{channel_id}/actions/test).
5. All events on monitored addresses are delivered to every active channel.

# Create a webhook channel
curl -X POST "https://api.vilna.io/v1/channels" \
  -H "X-Api-Key: ${VILNA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend Alerts",
    "config": {
      "kind": "webhook",
      "url": "https://your-app.example.com/alerts/webhook",
      "headers": {}
    }
  }'

# Create a Telegram channel
curl -X POST "https://api.vilna.io/v1/channels" \
  -H "X-Api-Key: ${VILNA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ops Team Telegram",
    "config": {
      "kind": "telegram",
      "bot_token": "987654321:ABCdefGHIjklMNOpqrsTUVwxyz123456789",
      "chat_id": -1001234567890,
      "language": "en",
      "thread_id": 0
    }
  }'

# Test the webhook channel
curl -X POST "https://api.vilna.io/v1/channels/{channel_id}/actions/test" \
  -H "X-Api-Key: ${VILNA_API_KEY}"

• All active channels receive all events. Use server-side filtering in your webhook handler to route or suppress events as needed.
• Webhook channels include HMAC-SHA256 signatures so your backend can verify each delivery. Telegram channels have no equivalent — Telegram is the endpoint, so trust is anchored in who has access to the chat and the bot.
• For high-value accounts, use both channels so that human operators get Telegram alerts while your backend processes events automatically.