FAQ

Vilna supports Bitcoin, Ethereum, BNB Smart Chain, Polygon, Avalanche, Arbitrum, Optimism, Base, Solana, TRON, TON, and more. Call GET /blockchains for the current list.

Sign up at app.vilna.io, create a workspace and project, then generate an API key with the permissions you need. The platform is free to use during the early access period. For help, contact support@vilna.io.

The Vilna API requires an API key sent in the X-Api-Key header for all requests. See the Authentication guide for details.

External addresses are imported directly - you provide the full address string. HD addresses are derived from an extended public key (xPub) using BIP-32/44 standards, allowing you to generate new addresses programmatically without exposing private keys.

Yes. For EVM-compatible chains, specifying chainFamily: "evm" when creating the address in Vilna automatically monitors it on all active EVM networks.

All amounts in the Vilna API have two fields:

• base - the raw integer value as a string (e.g., "1000000")
• formatted - human-readable value with decimals applied (e.g., "1.0" for USDT with 6 decimals)

Always use base for calculations and formatted for display.

Vilna supports two notification types: Webhooks (HTTP POST to your endpoint) and Telegram (bot messages to a chat). See the Notification Channels guide for setup instructions.

Check the X-Webhook-Signature header — it has Stripe format t=<unix-seconds>,v1=<hex> and carries the HMAC-SHA256 of the raw request body. The timestamp inside the header is what you compare against the current time to reject replays; X-Webhook-Event-Id is your dedup key across retries. See Authentication for the full verification code and required client behaviors.

Yes. Use the Vilna test action to send a sample payload to your channel:

curl -X POST "https://api.vilna.io/v1/channels/{channel_id}/actions/test" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "event_type": "transaction_detected" }'

The official TypeScript SDK (@vilna/sdk) is available on npm. For other languages, you can generate a client from the OpenAPI specification using tools like openapi-generator or oapi-codegen.

No. The Vilna SDK provides convenience methods and full TypeScript type safety, but you can call the REST API directly from any language using standard HTTP.

The @vilna-io/storage-client is a separate npm package for web applications that need to interact with the Vilna Storage browser extension (wallet). It handles extension detection, connection, and transaction signing.

Chain Agnostic Improvement Proposals (CAIP) is a set of standards for identifying blockchains, accounts, and assets across different networks. Vilna uses CAIP throughout its API:

See CAIP Standards for the full reference.

The Vilna API returns all errors in RFC 7807 Problem Details format. See Errors & Troubleshooting for the full error reference and troubleshooting tips.