Integration patterns

Choose a workflow based on what your application needs to record: user deposits, wallet holdings or invoice receipts. Vilna monitors addresses you control; your application decides when to credit a user or fulfill an order.

Use a project API key with the grants required by each linked operation. For every mutation, persist its Idempotency-Key, exact body and business intent before sending. Retry an unknown outcome with the same values; see Idempotency. The linked operation pages provide schemas, generated request examples and Try it.

• Exchanges and crypto-banks: assign deposit addresses and maintain an internal ledger.
• Exchangers and payment desks: reconcile holdings across wallets and supported networks.
• Individuals and freelancers: monitor incoming transfers and track invoice receipts.

Use a deposit address per user and retain the mapping between the returned address and your user record. Have your extended public key ready, plus an HTTPS receiver that verifies webhook signatures.

1. Register your extended public key, then derive addresses for the selected chain family. Choose selection.kind: next for the next unused index, or a range for an explicit allocation. Save the returned public-key ID, canonical address values and derivation indexes with their user mappings. Reuse the saved intent when retrying an allocation.
2. Create a webhook channel with your HTTPS URL and payload_version: v2. Save its ID, name and webhook secret immediately. Test the channel for the selected family and check the receiver's signed delivery and 2xx response. Test acceptance does not prove delivery, and a channel alone does not subscribe to real events.
3. Create the first subscription using that channel ID, the selected family and a block trigger with after_blocks: 0. Set filters.chain_gids for the networks you support and, if needed, filters.address_tag_ids for the deposit address group. Save its ID and configuration. This subscription provides an early inclusion signal for matching transactions.
4. Optionally create a second subscription with the same scope and a network trigger for a later confirmation signal. Give this subscription its own saved intent. One subscription does not send both stages; early inclusion alone is not finality.
5. Verify each delivery and handle duplicate event IDs. Match incoming transfer events to the saved user/address mapping and reconcile the current transaction before final credit, after a delivery gap or after a reorganization. Your ledger's confirmation policy determines whether and when provisional credit becomes available.

The result is a traceable deposit record tied to an address, transaction and user. See trigger semantics and the reconciliation workflow for handling confirmation changes. Do not treat a channel test or an early notification as evidence of a completed deposit.

Build a treasury view from the addresses you control. Start by registering each external address, or derive addresses from a registered extended public key as above. Retain their returned canonical values and labels.

1. Search balances for one supported family, supplying the addresses to inspect. Narrow results with chain_gids or asset_gids when useful. Read every result page using page and limit; a single response is not a complete treasury snapshot.
2. Repeat the search separately for each supported family you use. A request for evm can cover eligible EVM networks, but does not include Bitcoin or Tron holdings. Respect the operation's address and filter limits when batching requests.
3. Use Summarize balances for project totals within one family, also following pagination. Keep asset_gid with every amount so holdings from different networks or assets remain distinguishable. Use base integer strings for arithmetic and formatted for display.
4. Add a channel and subscription using the deposit workflow for change notifications. Use List transactions and balance reads to reconcile your records after delivery gaps. Review is_sync before treating a balance as synchronized.

The result is a view assembled from family-scoped, paginated reads. Monitoring and notifications do not execute an exchange or move funds between wallets.

Register the addresses you control, then create a channel and subscription as described above to follow incoming transfers. Your receiver can route verified events to your own notification system.

For a client invoice:

1. Choose an already registered address and the asset to reconcile. Read token metadata to obtain decimals before calculating the amount.
2. Create an invoice with that address, asset_gid, a positive base-unit integer string in amount and an appropriate expiration time. Keep the expiration time unchanged on retries, along with the original body and idempotency key. Use metadata to retain your own order reference.
3. Save the returned invoice ID and read the invoice to reconcile its lifecycle. In the authenticated response, amount and confirmed_amount are base-unit integer strings. Compare them with integer arithmetic and use status to determine lifecycle completion.
4. Read holdings separately for each supported family through Search balances, following all pages.

An invoice records a request and reconciles on-chain receipts at your address. See Invoices for underpayments, expiration and the distinction between lifecycle status and confirmed receipts.

Plan for duplicate deliveries and delivery gaps. Separate subscriptions can provide early and later signals, but your application must reconcile chain state before crediting. Invoice completion follows its own lifecycle. Check Limits and quotas for resource limits, time windows and resend cooldowns before choosing recovery behavior.