{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-apis/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["quickfacts","fact","format","part","tabs","tab"]},"type":"markdown"},"seo":{"title":"Standards & specs","projectTitle":"Vilna Docs","description":"The open standards in every Vilna payload - CAIP identifiers for chains, accounts and assets, and RFC 7807 problem+json errors.","siteUrl":"https://docs.vilna.io","lang":"en-US","image":"https://cdn.vilna.io/docs/og/26103121/en/apis-standards.png","meta":[{"name":"og:type","content":"website"},{"name":"og:site_name","content":"Vilna Documentation"},{"name":"og:image:width","content":"1200"},{"name":"og:image:height","content":"630"},{"name":"twitter:card","content":"summary_large_image"},{"name":"robots","content":"max-image-preview:large"}],"llmstxt":{"title":"Vilna API Documentation","description":"Vilna Platform API monitors public blockchain activity, balances and invoices and delivers signed webhooks. It does not sign or broadcast transactions. VKS separately coordinates account setup, signer approvals and signing, retains signed results and can submit a complete transaction to a node. Node acceptance is not blockchain confirmation. Each API uses its own scoped credential in X-Api-Key. Workspace setup and VKS-key issuance start in the Dashboard.\n","details":{"content":"**Platform monitoring.** Platform observes merchant-controlled addresses,\nsupplied directly or derived from the merchant's extended public key (xPub).\nInvoices report incoming on-chain activity; they do not initiate transfers.\n\n**APIs and their credentials.**\n\n- Platform API (api.vilna.io) - monitor addresses and extended public keys, read\n  balances and transactions, reconcile incoming payments, create invoices, and\n  receive events.\n- Blockchain RPC (rpc.vilna.io) - JSON-RPC and gRPC node access across every\n  supported network behind one key.\n- Management API (mgmt.vilna.io) - published workspace, project, member and key\n  operations, with Dashboard bootstrap and credential grant limits.\n- VKS API (vks.vilna.io) - workspace signers, vaults, accounts, signing requests,\n  signed results and optional asynchronous send. Uses a Dashboard-issued VKS key\n  with vks:access; the public Management API has no VKS-key issuance route.\n\n**Pages with no markdown source**, so they cannot be linked below:\n\n- Product overview: https://docs.vilna.io/\n- All guides: https://docs.vilna.io/guides\n"},"excludeFiles":["legal/terms.md","legal/privacy.md","legal/cookies.md","@l10n/ru/legal/terms.md","@l10n/ru/legal/privacy.md","@l10n/ru/legal/cookies.md"],"sections":[{"title":"Getting Started","description":"What the platform is, how to make a first call, and answers to common questions","includeFiles":["get-started/quickstart.md","get-started/dashboard.md","get-started/core-concepts.md","get-started/members.md","get-started/faq.md"]},{"title":"API Reference","description":"Authentication, permissions, idempotency, errors, standards, and per-service endpoint documentation","includeFiles":["apis/authentication.md","apis/permissions.md","apis/idempotency.md","apis/errors.md","apis/standards.md","apis/networks.md","apis/platform/@v2/index.md","apis/platform/@v2/webhooks.md","apis/platform/@v2/api.yaml","apis/mgmt/index.md","apis/mgmt/api.yaml","apis/vks/index.md","apis/vks/api.yaml","apis/rpc/index.md","apis/rpc/json-rpc.md","apis/rpc/grpc.md"]},{"title":"Developer Guides","description":"Integration patterns, events, notifications, and tooling","includeFiles":["guides/events.md","guides/channels.md","guides/tokens.md","guides/integration-patterns.md","guides/mcp.md","guides/simulation.md","guides/invoices.md","guides/vks.md"]},{"title":"Trust and custody","description":"The non-custodial model in plain terms","includeFiles":["legal/non-custodial.md"]},{"title":"Optional","description":"Background reading and release history","includeFiles":["get-started/blockchain-basics.md","changelog.md"]}]},"priority":0.5,"jsonLd":{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://docs.vilna.io/"},{"@type":"ListItem","position":2,"name":"API Reference","item":"https://docs.vilna.io/apis"},{"@type":"ListItem","position":3,"name":"Standards"}]}]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"standards","__idx":0},"children":["Standards"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Vilna uses CAIP identifiers for chains, accounts and assets, and RFC 7807 for HTTP API errors."]},{"$$mdtype":"Tag","name":"QuickFacts","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Fact","attributes":{"icon":"globe"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["CAIP-2"]}," chains"]}," ",{"$$mdtype":"Tag","name":"Fact","attributes":{"icon":"users"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["CAIP-10"]}," accounts"]}," ",{"$$mdtype":"Tag","name":"Fact","attributes":{"icon":"card"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["CAIP-19"]}," assets"]}," ",{"$$mdtype":"Tag","name":"Fact","attributes":{"icon":"alert"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["RFC 7807"]}," errors"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"caip","level":2,"__idx":1},"children":["CAIP - chain-agnostic identifiers "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["CAIP (Chain Agnostic Improvement Proposals) gives every blockchain, account and asset one identifier shape - so the same code path handles Ethereum, Bitcoin and Solana without per-chain special cases. In a Vilna response, a record points at a chain, an address or a token with one of these ids."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There are three levels, and each builds on the one before it: an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["account"]}," is a chain plus an address; an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["asset"]}," is a chain plus an asset descriptor."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"caip2","level":3,"__idx":2},"children":["CAIP-2 - the blockchain "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The base identifier. It names a chain in two parts:"]},{"$$mdtype":"Tag","name":"Format","attributes":{"line":"namespace:reference","result":"chain_id"},"children":[{"$$mdtype":"Tag","name":"Part","attributes":{"token":"namespace","eg":"eip155"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The chain family - ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eip155"]}," for EVM chains, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bip122"]}," for Bitcoin-like, plus ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["solana"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cosmos"]}," and more."]}]},{"$$mdtype":"Tag","name":"Part","attributes":{"token":"reference","eg":"1"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The specific chain inside that family - the chain ID for EVM, the genesis block hash for Bitcoin."]}]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Chain"},"children":["Chain"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"CAIP-2"},"children":["CAIP-2"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ethereum Mainnet"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eip155:1"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["BNB Smart Chain"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eip155:56"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Polygon"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eip155:137"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Arbitrum One"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eip155:42161"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Bitcoin"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bip122:000000000019d6689c085ae165831e93"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Solana"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"caip10","level":3,"__idx":3},"children":["CAIP-10 - an account "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An address on a specific chain - take a CAIP-2 id and append the address:"]},{"$$mdtype":"Tag","name":"Format","attributes":{"line":"chain_id:address","result":"account_id"},"children":[{"$$mdtype":"Tag","name":"Part","attributes":{"token":"chain_id","eg":"eip155:1"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Any CAIP-2 blockchain id - the chain the account lives on."]}]},{"$$mdtype":"Tag","name":"Part","attributes":{"token":"address","eg":"0x742d35Cc…7B123"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The address on that chain, in its native format (hex for EVM, base58 for Bitcoin and Solana)."]}]}]},{"$$mdtype":"Tag","name":"Tabs","attributes":{},"children":[{"$$mdtype":"Tag","name":"Tab","attributes":{"label":"Ethereum"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"eip155:1:0x742d35Cc6634C0532925a3b844Bc9e7595f7B123\n"},"children":[]}]},{"$$mdtype":"Tag","name":"Tab","attributes":{"label":"Bitcoin"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"bip122:000000000019d6689c085ae165831e93:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa\n"},"children":[]}]},{"$$mdtype":"Tag","name":"Tab","attributes":{"label":"Solana"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp:9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM\n"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"caip19","level":3,"__idx":4},"children":["CAIP-19 - an asset "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Any asset - native coin, token or NFT. It joins a CAIP-2 chain to an asset descriptor with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/"]},":"]},{"$$mdtype":"Tag","name":"Format","attributes":{"line":"chain_id/asset_namespace:asset_reference","result":"asset_id"},"children":[{"$$mdtype":"Tag","name":"Part","attributes":{"token":"chain_id","eg":"eip155:1"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Any CAIP-2 blockchain id - the chain the asset lives on."]}]},{"$$mdtype":"Tag","name":"Part","attributes":{"token":"asset_namespace","eg":"erc20"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The asset type - ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["slip44"]}," for a native coin, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["erc20"]}," for a fungible token, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["erc721"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["erc1155"]}," for NFTs."]}]},{"$$mdtype":"Tag","name":"Part","attributes":{"token":"asset_reference","eg":"0xdAC17F…1ec7"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The asset within that type - a contract address for tokens, or a coin type for native currencies."]}]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Asset"},"children":["Asset"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"CAIP-19"},"children":["CAIP-19"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ETH (native)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eip155:1/slip44:60"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["BTC (native)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bip122:000000000019d6689c085ae165831e93/slip44:0"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["USDT on Ethereum"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["USDC on Ethereum"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["BAYC #101 (NFT)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eip155:1/erc721:0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D/101"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Native currencies use the coin type from the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/satoshilabs/slips/blob/master/slip-0044.md"},"children":["SLIP-44 registry"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["60"]}," = ETH, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["0"]}," = BTC); tokens and NFTs use the contract address, with the token id appended for a single NFT."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"errors","level":2,"__idx":5},"children":["RFC 7807 - error format "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Platform, Management and VKS HTTP APIs use RFC 7807 Problem Details (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/problem+json"]},"). See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/errors#body"},"children":["Errors"]}," for fields, service-specific extensions and recovery guidance. Blockchain RPC uses its ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/rpc/json-rpc#error-handling"},"children":["protocol error model"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"references","level":2,"__idx":6},"children":["References "]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-2.md"},"children":["CAIP-2 Specification"]}," - blockchain ids"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-10.md"},"children":["CAIP-10 Specification"]}," - account ids"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-19.md"},"children":["CAIP-19 Specification"]}," - asset ids"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/satoshilabs/slips/blob/master/slip-0044.md"},"children":["SLIP-44 Registry"]}," - native coin types"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://tools.ietf.org/html/rfc7807"},"children":["RFC 7807"]}," - Problem Details for HTTP APIs"]}]}]},"headings":[{"value":"Standards","id":"standards","depth":1},{"value":"CAIP - chain-agnostic identifiers","id":"caip","depth":2},{"value":"CAIP-2 - the blockchain","id":"caip2","depth":3},{"value":"CAIP-10 - an account","id":"caip10","depth":3},{"value":"CAIP-19 - an asset","id":"caip19","depth":3},{"value":"RFC 7807 - error format","id":"errors","depth":2},{"value":"References","id":"references","depth":2}],"frontmatter":{"seo":{"title":"Standards & specs","description":"The open standards in every Vilna payload - CAIP identifiers for chains, accounts and assets, and RFC 7807 problem+json errors.","priority":0.5,"image":"https://cdn.vilna.io/docs/og/26103121/en/apis-standards.png","jsonLd":{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://docs.vilna.io/"},{"@type":"ListItem","position":2,"name":"API Reference","item":"https://docs.vilna.io/apis"},{"@type":"ListItem","position":3,"name":"Standards"}]}]}}},"lastModified":"2026-10-31T22:07:16.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/apis/standards","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}