{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["quickfacts","fact","flow","step"]},"type":"markdown"},"seo":{"title":"Tokens and Balances - Verified and Trusted","projectTitle":"Vilna Docs","description":"Which tokens get balances and notifications in Vilna, why a token needs to be verified or trusted, how to read the catalog and add any contract.","siteUrl":"https://docs.vilna.io","lang":"en-US","image":"https://cdn.vilna.io/docs/og/26103121/en/guides-tokens.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":"Guides","item":"https://docs.vilna.io/guides"},{"@type":"ListItem","position":3,"name":"Tokens"}]},{"@type":"TechArticle","headline":"Tokens and Balances - Verified and Trusted","description":"Which tokens get balances and notifications in Vilna, why a token needs to be verified or trusted, how to read the catalog and add any contract.","url":"https://docs.vilna.io/guides/tokens","datePublished":"2026-09-25","dateModified":"2026-10-31","proficiencyLevel":"Beginner","dependencies":"Vilna API key","image":"https://cdn.vilna.io/docs/og/26103121/en/guides-tokens.png","author":{"@id":"https://vilna.io/#organization"},"publisher":{"@id":"https://vilna.io/#organization"}}]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"tokens-and-balances","__idx":0},"children":["Tokens and balances"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Anyone can deploy a token contract, and any contract can send something to your address. Vilna keeps token balances according to its verified list and your project's trust choices. The default notification filter uses those marks too, alongside the selected address's own actions. This page explains the two marks, what they switch on, how to read the catalog and how to add a contract of your own."]},{"$$mdtype":"Tag","name":"QuickFacts","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Fact","attributes":{"icon":"shield"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["is_verified"]}," - the shared list"]}," ",{"$$mdtype":"Tag","name":"Fact","attributes":{"icon":"check-circle"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["is_trusted"]}," - your project's pick"]}," ",{"$$mdtype":"Tag","name":"Fact","attributes":{"icon":"database"},"children":["Balances follow the marks"]}," ",{"$$mdtype":"Tag","name":"Fact","attributes":{"icon":"bell"},"children":["The noise filter uses marks"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"why","level":2,"__idx":1},"children":["Why tokens need a mark "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A catalog entry with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status: supported"]}," means Vilna resolved the contract's name, symbol and decimals and can follow its transfers. It says nothing about whether the token is legitimate. Airdropped tokens with a familiar name, look-alike contracts and plain spam all resolve just fine. If every resolved token drove balances and alerts, a stranger could make your integration react by sending you anything."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["So a token carries two independent marks:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["is_verified"]}," - Vilna's shared list, the same for every project. It is maintained by hand for one exact contract on one exact chain. A name, a symbol or heavy transfer volume never earns it."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["is_trusted"]}," - your project's own selection, set with one call and revoked with another."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Either mark is enough. The native coin of every network (ETH, BNB, BTC, TRX) is always in scope without a mark."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"what-counts","level":2,"__idx":2},"children":["What the marks switch on "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Balances."]}," Vilna keeps balances for the native coins and for every token in your project's scope: verified ones and the ones you trusted. Reading a balance, or seeing a token move through your address, does not widen that scope. A token outside it has no balance rows at all."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Notifications."]}," Every subscription carries ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["is_noise_filtered"]},", on by default. With it on, a notice fires only when one of the selected addresses supplies its own reason: it acted itself (as sender, caller, creator or owner), in which case the tokens involved do not matter and unfamiliar ones simply appear in the payload; or a native coin, a verified token or a trusted token moved on that address. Another address's action, trust or fee never qualifies yours. With the filter off, any activity that touches a selected address notifies, unfamiliar tokens included; that grants no trust and starts no balances. The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/events#noise"},"children":["events guide"]}," covers the filter in full."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Solana networks resolve tokens for the catalog and stop there: no balances and no notifications, whatever the marks say."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"catalog","level":2,"__idx":3},"children":["Reading the catalog "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/token/list-tokens"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /tokens"]}]}," lists the catalog. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scope"]}," decides how much of it you see:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scope=project"]}," for native, verified and trusted assets in your project, or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scope=all"]}," (the default) for the full catalog. Narrow the results by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["chain_gid"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["search"]}," or a ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#tags"},"children":["token tag"]}," through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tag_id"]},". A search match does not grant trust. The operation above provides the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CatalogAsset"]}," schema, complete filters, limits and request examples."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["supported"]}," entry has resolved metadata; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]}," means the identity is known but not fully resolved; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unsupported"]}," means the chain cannot serve it. Name, symbol and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["decimals"]}," are guaranteed for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["supported"]}," entries and may be partially known earlier."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There is no server-side filter for verified tokens alone. To list them, request ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scope=project"]}," and keep the entries whose ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["is_verified"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},", or filter the full catalog on that field."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["decimals"]}," for the exact ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["gid"]},", not a symbol shared across contracts or chains. Keep base-unit strings exact with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BigInt"]}," or an exact decimal library; converting them to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Number"]}," can lose units. Authenticated invoice amounts are raw strings, unlike the structured transaction amounts. The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/invoices#check-invoice-status"},"children":["invoice guide"]}," explains invoice amount representation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For example, one token with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["decimals: 6"]}," has this transaction amount:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{ \"base\": \"1000000\", \"formatted\": \"1.0\" }\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"add","level":2,"__idx":4},"children":["Adding a token "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Two calls. The first puts the contract in the catalog and resolves its metadata from the chain; the second marks it trusted for your project."]},{"$$mdtype":"Tag","name":"Flow","attributes":{},"children":[{"$$mdtype":"Tag","name":"Step","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/token/create-token"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /tokens/{chain_gid}/{asset_path}"]}]}," with no body. The response carries the entry with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status: supported"]},"; a contract that resolves as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unsupported"]}," answers ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]}," instead. A token already in the catalog comes back as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]},"."]}]},{"$$mdtype":"Tag","name":"Step","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/token/trust-token"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /tokens/{chain_gid}/{asset_path}/actions/trust"]}]}," adds it to your project's selection. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}," means the token is not in the catalog yet; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]}," means it is there but not ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["supported"]},"."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use a project key with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api:asset:write"]}," for mutations and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api:asset:read"]}," for catalog reads. Registration and trust are separate intents with separate ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Idempotency-Key"]}," values; save each key and the original inputs before sending. The operation pages above provide schemas and request examples."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After a lost response, retry with the same key and original parameters. Untrust is a separate intent and needs its own key. If replay is unavailable, reconcile catalog and trust state instead of automatically replacing the key. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/idempotency#recovery"},"children":["Idempotency"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["From that moment the token counts for your subscriptions, and balances for every address in the project, current and future, are initialized in the background. Nothing is sent for transactions that happened before: trusting a token creates no notification backlog."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/token/untrust-token"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /tokens/{chain_gid}/{asset_path}/actions/untrust"]}]}," removes your selection and answers ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["204"]},". If no other mark keeps the token in scope, its balances stop and it drops out of your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scope=project"]}," reads; it stays in the full catalog (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scope=all"]},"). Trusting it again starts the balances from scratch rather than resuming the old ones."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["asset_path"]}," is the part of the CAIP-19 id after the chain:"]},{"$$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":"chain_gid"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["chain_gid"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"asset_path"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["asset_path"]}]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ETH"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eip155:1"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["slip44:60"]}]}]},{"$$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"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["USDT on Tron"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tron:728126428"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["trc20:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"tags","level":2,"__idx":5},"children":["Token tags "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A token tag is a named group of tokens inside a project, managed under ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/token_tag/list-token-tags"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /token-tags"]}]},". Tags do not change trust; they exist so that ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /tokens?tag_id=…"]}," can return one group at a time, such as the stablecoins you accept."]}]},"headings":[{"value":"Tokens and balances","id":"tokens-and-balances","depth":1},{"value":"Why tokens need a mark","id":"why","depth":2},{"value":"What the marks switch on","id":"what-counts","depth":2},{"value":"Reading the catalog","id":"catalog","depth":2},{"value":"Adding a token","id":"add","depth":2},{"value":"Token tags","id":"tags","depth":2}],"frontmatter":{"seo":{"title":"Tokens and Balances - Verified and Trusted","description":"Which tokens get balances and notifications in Vilna, why a token needs to be verified or trusted, how to read the catalog and add any contract.","priority":0.5,"image":"https://cdn.vilna.io/docs/og/26103121/en/guides-tokens.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":"Guides","item":"https://docs.vilna.io/guides"},{"@type":"ListItem","position":3,"name":"Tokens"}]},{"@type":"TechArticle","headline":"Tokens and Balances - Verified and Trusted","description":"Which tokens get balances and notifications in Vilna, why a token needs to be verified or trusted, how to read the catalog and add any contract.","url":"https://docs.vilna.io/guides/tokens","datePublished":"2026-09-25","dateModified":"2026-10-31","proficiencyLevel":"Beginner","dependencies":"Vilna API key","image":"https://cdn.vilna.io/docs/og/26103121/en/guides-tokens.png","author":{"@id":"https://vilna.io/#organization"},"publisher":{"@id":"https://vilna.io/#organization"}}]}}},"lastModified":"2026-10-31T22:07:16.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/tokens","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}