{ "openapi": "3.1.0", "info": { "version": "0.27.5", "title": "Platform API", "description": "Vilna Platform API. Monitor blockchain addresses, track transactions, manage invoices, and receive notifications across multiple chains.\n\n**Quick Links**\n\n- [Security Guide](/apis/platform/security) - Authentication and webhook verification\n- [CAIP Standards](/apis/platform/caip-standards) - Asset identification standards\n- [Quick Start Guide](/guides/quickstart) - Step-by-step integration tutorial\n\n**Endpoints**\n\nActivity & Balances\n\n- **[Activity](#tag/activity)** - Balance changes across tracked addresses\n- **[Balances](#tag/balance)** - Current balances and historical snapshots for charts\n\nAddress Operations\n\n- **[Addresses](#tag/address)** - List, import, update, and delete tracked addresses\n- **[Extended Public Keys](#tag/public_key)** - HD wallet management\n\nTransactions\n\n- **[Transactions](#tag/transaction)** - Transaction listing and detailed inspection with events\n\nPayments\n\n- **[Invoices](#tag/invoice)** - Create and manage payment invoices\n\nMonitoring & Notifications\n\n- **[Notification Channels](#tag/channel)** - Configure alert delivery via webhooks, Telegram, etc.\n- **[Notification Subscriptions](#tag/subscription)** - Bind channels to event types for targeted alert routing\n\nAsset Management\n\n- **[Tokens](#tag/token)** - Token metadata for supported asset types\n\nInfrastructure\n\n- **[Blockchains](#tag/blockchain)** - Supported blockchains and their metadata\n- **[Simulate](#tag/simulate)** - Transaction simulation\n- **[Version](#tag/version)** - Service version info\n\n**Array Query Parameters**\n\nFilters that accept multiple values (`chain_gid`, `asset_gid`, `address`, `hash`, etc.) use repeated keys:\n\n- ✅ `?chain_gid=eip155:1&chain_gid=eip155:56`\n- ❌ `?chain_gid=eip155:1,eip155:56`\n\nThis follows the OpenAPI default (`style: form, explode: true`).\n\n**Need Help?**\n\nVisit our [documentation portal](/apis/platform/) for detailed guides and examples.\n", "contact": { "email": "support@vilna.io", "name": "Vilna API Team", "url": "https://vilna.io" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" }, "termsOfService": "https://docs.vilna.io/legal/terms" }, "servers": [ { "url": "https://api.vilna.io/v1", "description": "Vilna API." } ], "security": [ { "Auth": [] } ], "tags": [ { "name": "version", "x-displayName": "Version", "description": "Service version information." }, { "name": "blockchain", "x-displayName": "Blockchains", "description": "Supported blockchains and their metadata.", "x-keywords": { "includes": [ "supported blockchains", "supported networks", "chain list", "CAIP-2" ] } }, { "name": "token", "x-displayName": "Tokens", "description": "Token metadata (symbols, decimals, names) for supported asset types.", "x-keywords": { "includes": [ "token list", "token metadata", "ERC-20", "fungible tokens", "CAIP-19" ] } }, { "name": "public_key", "x-displayName": "Extended Public Keys", "description": "Register extended public keys (BIP44/49/84) and derive HD addresses.", "x-keywords": { "includes": [ "xpub", "extended public key", "HD wallet", "BIP-44", "hierarchical deterministic" ] } }, { "name": "address", "x-displayName": "Addresses", "description": "List, import, update, and delete tracked blockchain addresses.", "x-keywords": { "includes": [ "wallet address", "address monitoring", "track address", "watch address" ] } }, { "name": "channel", "x-displayName": "Notification Channels", "description": "Configure alert delivery via webhooks, Telegram, and other channels.", "x-keywords": { "includes": [ "webhook", "blockchain webhook", "http callback", "telegram notifications", "blockchain alerts" ] } }, { "name": "subscription", "x-displayName": "Notification Subscriptions", "description": "Bind channels to event types for targeted alert routing.", "x-keywords": { "includes": [ "notification subscription", "alert subscription", "event routing", "notification filter" ] } }, { "name": "activity", "x-displayName": "Activity", "description": "Balance changes across tracked addresses, filterable by chain and asset.", "x-keywords": { "includes": [ "asset movements", "balance changes", "balance deltas", "transaction feed" ] } }, { "name": "balance", "x-displayName": "Balances", "description": "Current balances for tracked addresses, filterable by chain and asset.", "x-keywords": { "includes": [ "wallet balance", "token balance", "address balance", "multi-chain balance" ] } }, { "name": "transaction", "x-displayName": "Transactions", "description": "Transaction listing and details with canonical events and balance deltas.", "x-keywords": { "includes": [ "transaction history", "transaction details", "blockchain transaction", "transaction events" ] } }, { "name": "invoice", "x-displayName": "Invoices", "description": "Create and track crypto payment invoices.", "x-keywords": { "includes": [ "crypto payment", "payment request", "crypto invoice", "payment monitoring", "payment reconciliation" ] } }, { "name": "token_tag", "x-displayName": "Token Tags", "description": "Named collections of tokens. Pass a tag ID to list endpoints to filter results by membership.", "x-keywords": { "includes": [ "token tag", "token watchlist", "token collection", "batch filter" ] } }, { "name": "address_tag", "x-displayName": "Address Tags", "description": "Named collections of addresses. Pass a tag ID to list endpoints to filter results by membership.", "x-keywords": { "includes": [ "address tag", "address watchlist", "address collection", "batch filter" ] } }, { "name": "simulate", "x-displayName": "Simulation", "description": "Simulate EVM transactions before sending.", "x-keywords": { "includes": [ "transaction simulation", "simulate ethereum transaction", "dry run", "EVM simulation", "gas estimation", "eth_call" ] } } ], "paths": { "/blockchains": { "get": { "summary": "List blockchains", "description": "List supported blockchains with filtering and pagination.", "operationId": "list-blockchains", "security": [ { "Auth": [ "api:blockchain:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/sortBlockchains" }, { "$ref": "#/components/parameters/blockchainsFilterSearch" }, { "$ref": "#/components/parameters/blockchainsFilterFamilies" } ], "responses": { "200": { "$ref": "#/components/responses/blockchains_list_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "default": { "$ref": "#/components/responses/problem" } }, "tags": [ "blockchain" ] } }, "/blockchains/{chain_gid}": { "get": { "summary": "Get blockchain", "description": "Get blockchain details by chain GID.", "operationId": "get-blockchain", "security": [ { "Auth": [ "api:blockchain:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/chainGID" } ], "responses": { "200": { "$ref": "#/components/responses/blockchain_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "default": { "$ref": "#/components/responses/problem" } }, "tags": [ "blockchain" ] } }, "/public_keys": { "get": { "summary": "List public keys", "description": "List registered extended public keys with filtering and pagination.", "operationId": "list-public-keys", "security": [ { "Auth": [ "api:public_key:read" ] } ], "tags": [ "public_key" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/publicKeysFilterSearch" }, { "$ref": "#/components/parameters/sortPublicKeys" } ], "responses": { "200": { "$ref": "#/components/responses/public_keys_list_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "default": { "$ref": "#/components/responses/problem" } } }, "post": { "summary": "Create public key", "description": "Register an extended public key for HD address derivation.", "operationId": "create-public-key", "security": [ { "Auth": [ "api:public_key:write" ] } ], "tags": [ "public_key" ], "requestBody": { "$ref": "#/components/requestBodies/create_public_key_request" }, "responses": { "200": { "$ref": "#/components/responses/create_public_key_response" }, "201": { "$ref": "#/components/responses/create_public_key_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "422": { "$ref": "#/components/responses/precondition_problem" }, "default": { "$ref": "#/components/responses/problem" } } } }, "/public_keys/{public_key_id}": { "delete": { "summary": "Delete public key", "description": "Delete a registered public key by ID.", "operationId": "delete-public-key", "security": [ { "Auth": [ "api:public_key:delete" ] } ], "parameters": [ { "$ref": "#/components/parameters/publicKeyID" } ], "responses": { "204": { "$ref": "#/components/responses/no_content_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "default": { "$ref": "#/components/responses/problem" } }, "tags": [ "public_key" ] }, "get": { "summary": "Get public key", "description": "Get public key details by ID.", "operationId": "get-public-key", "security": [ { "Auth": [ "api:public_key:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/publicKeyID" } ], "responses": { "200": { "$ref": "#/components/responses/public_key_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "default": { "$ref": "#/components/responses/problem" } }, "tags": [ "public_key" ] }, "patch": { "summary": "Update public key", "description": "Update public key metadata.", "operationId": "patch-public-key", "security": [ { "Auth": [ "api:public_key:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/publicKeyID" } ], "requestBody": { "$ref": "#/components/requestBodies/update_public_key_request" }, "responses": { "200": { "$ref": "#/components/responses/update_public_key_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "default": { "$ref": "#/components/responses/problem" } }, "tags": [ "public_key" ] } }, "/public_keys/{public_key_id}/children": { "post": { "summary": "Create child public key", "description": "Derive and register a child key from an account-level public key.\nThe server derives the child extended public key using BIP-32 derivation — no cryptography\nneeded on the client side.\n\nIf a standalone key with the same derived value already exists in the project, it is adopted\nas a child of this account key.\n\nOnly applicable to account-level keys (depth-3).\n", "operationId": "create-public-key-child", "security": [ { "Auth": [ "api:public_key:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/publicKeyID" } ], "requestBody": { "$ref": "#/components/requestBodies/create_public_key_child_request" }, "responses": { "200": { "$ref": "#/components/responses/create_public_key_child_response" }, "201": { "$ref": "#/components/responses/create_public_key_child_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "422": { "$ref": "#/components/responses/precondition_problem" }, "default": { "$ref": "#/components/responses/problem" } }, "tags": [ "public_key" ] } }, "/public_keys/{public_key_id}/addresses": { "get": { "summary": "List public key addresses", "description": "List addresses derived from the public key.", "operationId": "list-public-key-addresses", "security": [ { "Auth": [ "api:public_key:read" ] } ], "tags": [ "public_key", "address" ], "parameters": [ { "$ref": "#/components/parameters/publicKeyID" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/sortAddresses" }, { "$ref": "#/components/parameters/addressesFilterFormats" }, { "$ref": "#/components/parameters/addressesFilterSearch" }, { "$ref": "#/components/parameters/addressesFilterTagIDs" } ], "responses": { "200": { "$ref": "#/components/responses/hd_addresses_list_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "default": { "$ref": "#/components/responses/problem" } } }, "post": { "summary": "Generate public key addresses", "description": "Generate one or more addresses for the public key by indexes or range.", "operationId": "generate-public-key-addresses", "security": [ { "Auth": [ "api:address:write" ] } ], "tags": [ "public_key", "address" ], "parameters": [ { "$ref": "#/components/parameters/publicKeyID" } ], "requestBody": { "$ref": "#/components/requestBodies/generate_hd_addresses_request" }, "responses": { "200": { "$ref": "#/components/responses/generate_addresses_response" }, "201": { "$ref": "#/components/responses/generate_addresses_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "422": { "$ref": "#/components/responses/precondition_problem" }, "default": { "$ref": "#/components/responses/problem" } } } }, "/public_keys/{public_key_id}/addresses/next": { "post": { "summary": "Generate next address from public key", "description": "Generate the next sequential address for the public key.", "operationId": "generate-next-public-key-address", "security": [ { "Auth": [ "api:address:write" ] } ], "tags": [ "public_key", "address" ], "parameters": [ { "$ref": "#/components/parameters/publicKeyID" } ], "requestBody": { "$ref": "#/components/requestBodies/generate_next_hd_address_request" }, "responses": { "200": { "$ref": "#/components/responses/hd_address_response" }, "201": { "$ref": "#/components/responses/hd_address_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "422": { "$ref": "#/components/responses/precondition_problem" }, "default": { "$ref": "#/components/responses/problem" } } } }, "/addresses": { "get": { "summary": "List addresses", "description": "List tracked addresses (HD and external) with filtering and pagination.", "operationId": "list-addresses", "security": [ { "Auth": [ "api:address:read" ] } ], "tags": [ "address" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/sortAddresses" }, { "$ref": "#/components/parameters/addressesFilterFormats" }, { "$ref": "#/components/parameters/addressesFilterSearch" }, { "$ref": "#/components/parameters/addressesFilterKind" }, { "$ref": "#/components/parameters/addressesFilterTagIDs" } ], "responses": { "200": { "$ref": "#/components/responses/addresses_list_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "default": { "$ref": "#/components/responses/problem" } } } }, "/addresses/external": { "post": { "summary": "Create external address", "description": "Import an externally managed address for tracking.", "operationId": "create-external-address", "security": [ { "Auth": [ "api:address:write" ] } ], "tags": [ "address" ], "requestBody": { "$ref": "#/components/requestBodies/create_external_address_request" }, "responses": { "200": { "$ref": "#/components/responses/external_address_response" }, "201": { "$ref": "#/components/responses/external_address_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "409": { "$ref": "#/components/responses/conflict_problem" }, "default": { "$ref": "#/components/responses/problem" } } } }, "/addresses/external/resolve": { "post": { "summary": "Resolve external address from public key", "description": "Compute a blockchain address from a raw public key and create an external address. The public key is used only for address computation and is not stored. If an address with the computed value already exists, returns the existing one.\n", "operationId": "resolve-external-address", "security": [ { "Auth": [ "api:address:write" ] } ], "tags": [ "address" ], "requestBody": { "$ref": "#/components/requestBodies/resolve_external_address_request" }, "responses": { "200": { "$ref": "#/components/responses/external_address_response" }, "201": { "$ref": "#/components/responses/external_address_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "409": { "$ref": "#/components/responses/conflict_problem" }, "default": { "$ref": "#/components/responses/problem" } } } }, "/addresses/hd": { "get": { "summary": "List HD addresses", "description": "List only HD-derived addresses (excludes external). Use GET /addresses for all types.", "operationId": "list-hd-addresses", "security": [ { "Auth": [ "api:address:read" ] } ], "tags": [ "address" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/sortAddresses" }, { "$ref": "#/components/parameters/addressesFilterFormats" }, { "$ref": "#/components/parameters/addressesFilterSearch" }, { "$ref": "#/components/parameters/addressesFilterTagIDs" } ], "responses": { "200": { "$ref": "#/components/responses/hd_addresses_list_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "default": { "$ref": "#/components/responses/problem" } } } }, "/addresses/{address}": { "delete": { "summary": "Delete address", "description": "Delete a tracked address. This operation is irreversible.", "operationId": "delete-address", "security": [ { "Auth": [ "api:address:delete" ] } ], "parameters": [ { "$ref": "#/components/parameters/address" } ], "responses": { "204": { "$ref": "#/components/responses/no_content_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "409": { "$ref": "#/components/responses/conflict_problem" }, "default": { "$ref": "#/components/responses/problem" } }, "tags": [ "address" ] }, "get": { "summary": "Get address", "description": "Get tracked address details by address value.", "operationId": "get-address", "security": [ { "Auth": [ "api:address:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/address" } ], "responses": { "200": { "$ref": "#/components/responses/address_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "default": { "$ref": "#/components/responses/problem" } }, "tags": [ "address" ] }, "patch": { "summary": "Update address", "description": "Update tracked address metadata.", "operationId": "patch-address", "security": [ { "Auth": [ "api:address:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/address" } ], "requestBody": { "$ref": "#/components/requestBodies/update_address_request" }, "responses": { "204": { "$ref": "#/components/responses/no_content_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "default": { "$ref": "#/components/responses/problem" } }, "tags": [ "address" ] } }, "/addresses/{address}/balances": { "get": { "summary": "List address balances", "description": "List current balances for active assets on the address.", "operationId": "list-address-balances", "security": [ { "Auth": [ "api:address:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/address" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/sortBalances" } ], "responses": { "200": { "$ref": "#/components/responses/address_balances_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "default": { "$ref": "#/components/responses/problem" } }, "tags": [ "address" ] } }, "/addresses/{address}/utxos": { "get": { "summary": "List address UTXOs", "description": "List unspent Bitcoin outputs held by the address.", "operationId": "list-address-utxos", "security": [ { "Auth": [ "api:address:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/address" }, { "$ref": "#/components/parameters/utxoFilterChainGIDs" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/sortBitcoinUTXOs" } ], "responses": { "200": { "$ref": "#/components/responses/address_utxos_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "default": { "$ref": "#/components/responses/problem" } }, "tags": [ "address" ] } }, "/tokens": { "get": { "summary": "List tokens", "description": "List tracked tokens with filtering and pagination.", "operationId": "list-tokens", "security": [ { "Auth": [ "api:asset:read" ] } ], "tags": [ "token" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/sortTokens" }, { "$ref": "#/components/parameters/tokensFilterSearch" }, { "$ref": "#/components/parameters/tokensFilterChainGIDs" }, { "$ref": "#/components/parameters/tokensFilterTagIDs" } ], "responses": { "200": { "$ref": "#/components/responses/tokens_list_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "default": { "$ref": "#/components/responses/problem" } } } }, "/tokens/{chain_gid}/{asset_path}": { "post": { "summary": "Create token", "description": "Create a token by chain GID and asset path. Metadata is resolved from chain data.", "operationId": "create-token", "security": [ { "Auth": [ "api:asset:write" ] } ], "tags": [ "token" ], "parameters": [ { "$ref": "#/components/parameters/chainGID" }, { "$ref": "#/components/parameters/assetPath" } ], "responses": { "200": { "$ref": "#/components/responses/token_response" }, "201": { "$ref": "#/components/responses/token_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "422": { "$ref": "#/components/responses/precondition_problem" }, "default": { "$ref": "#/components/responses/problem" } } }, "get": { "summary": "Get token", "description": "Get token details by chain GID and asset path.", "operationId": "get-token", "security": [ { "Auth": [ "api:asset:read" ] } ], "tags": [ "token" ], "parameters": [ { "$ref": "#/components/parameters/chainGID" }, { "$ref": "#/components/parameters/assetPath" } ], "responses": { "200": { "$ref": "#/components/responses/token_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "default": { "$ref": "#/components/responses/problem" } } } }, "/activity": { "get": { "summary": "List activity", "description": "List balance changes across tracked addresses with filtering and pagination.", "operationId": "list-activity", "security": [ { "Auth": [ "api:transaction:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/activityFilterAddresses" }, { "$ref": "#/components/parameters/activityFilterAssetGIDs" }, { "$ref": "#/components/parameters/activityFilterChainGIDs" }, { "$ref": "#/components/parameters/activityFilterHashes" }, { "$ref": "#/components/parameters/activityFilterDirection" }, { "$ref": "#/components/parameters/activityFilterDateFrom" }, { "$ref": "#/components/parameters/activityFilterDateTo" }, { "$ref": "#/components/parameters/sortActivity" } ], "responses": { "200": { "$ref": "#/components/responses/activity_list_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "default": { "$ref": "#/components/responses/problem" } }, "tags": [ "activity" ] } }, "/balances": { "get": { "summary": "List balances", "description": "List current balances for tracked addresses with filtering and pagination.", "operationId": "list-balances", "security": [ { "Auth": [ "api:balance:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/sortBalances" }, { "$ref": "#/components/parameters/balanceFilterAddresses" }, { "$ref": "#/components/parameters/balanceFilterAssetGIDs" }, { "$ref": "#/components/parameters/balanceFilterChainGIDs" } ], "responses": { "200": { "$ref": "#/components/responses/balances_list_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "default": { "$ref": "#/components/responses/problem" } }, "tags": [ "balance" ] } }, "/transactions": { "get": { "summary": "List transactions", "description": "List blockchain transactions with filtering, sorting, and pagination.", "operationId": "list-transactions", "security": [ { "Auth": [ "api:transaction:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/transactionFilterChainGIDs" }, { "$ref": "#/components/parameters/transactionFilterHashes" }, { "$ref": "#/components/parameters/transactionFilterBlockNumbers" }, { "$ref": "#/components/parameters/transactionFilterIsSuccess" }, { "$ref": "#/components/parameters/transactionFilterIsConfirmed" }, { "$ref": "#/components/parameters/transactionFilterAddresses" }, { "$ref": "#/components/parameters/transactionFilterTagIDs" }, { "$ref": "#/components/parameters/sortTransactions" } ], "responses": { "200": { "$ref": "#/components/responses/transactions_list_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "default": { "$ref": "#/components/responses/problem" } }, "tags": [ "transaction" ] } }, "/transactions/{chain_gid}/{hash}": { "get": { "summary": "Get transaction", "description": "Get transaction details with events and balance changes.", "operationId": "get-transaction", "security": [ { "Auth": [ "api:transaction:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/chainGID" }, { "$ref": "#/components/parameters/hash" } ], "responses": { "200": { "$ref": "#/components/responses/transaction_details_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "default": { "$ref": "#/components/responses/problem" } }, "tags": [ "transaction" ] } }, "/simulate/evm/{chain_gid}": { "post": { "summary": "Simulate EVM transactions", "description": "Simulate one or more EVM transactions and return execution results.", "operationId": "simulate-evm", "security": [ { "Auth": [ "api:simulate:call" ] } ], "tags": [ "simulate" ], "parameters": [ { "$ref": "#/components/parameters/chainGID" } ], "requestBody": { "$ref": "#/components/requestBodies/simulate_evm_request" }, "responses": { "200": { "$ref": "#/components/responses/simulate_evm_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "422": { "$ref": "#/components/responses/precondition_problem" }, "default": { "$ref": "#/components/responses/problem" } } } }, "/invoices": { "get": { "summary": "List invoices", "description": "List invoices with filtering and pagination.", "operationId": "list-invoices", "security": [ { "Auth": [ "api:invoice:read" ] } ], "tags": [ "invoice" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/invoicesFilterStatuses" }, { "$ref": "#/components/parameters/sortInvoices" } ], "responses": { "200": { "$ref": "#/components/responses/invoices_list_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "default": { "$ref": "#/components/responses/problem" } } }, "post": { "summary": "Create invoice", "description": "Create a payment invoice for a specific address and token.\nThe address must belong to the current project and must not have an active invoice.\n", "operationId": "create-invoice", "security": [ { "Auth": [ "api:invoice:write" ] } ], "tags": [ "invoice" ], "requestBody": { "$ref": "#/components/requestBodies/create_invoice_request" }, "responses": { "200": { "$ref": "#/components/responses/invoice_response" }, "201": { "$ref": "#/components/responses/invoice_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "409": { "$ref": "#/components/responses/conflict_problem" }, "422": { "$ref": "#/components/responses/precondition_problem" }, "default": { "$ref": "#/components/responses/problem" } } } }, "/invoices/{invoice_id}": { "get": { "summary": "Get invoice", "description": "Get full invoice details including merchant notes and metadata.", "operationId": "get-invoice", "security": [ { "Auth": [ "api:invoice:read" ] } ], "tags": [ "invoice" ], "parameters": [ { "$ref": "#/components/parameters/invoiceID" } ], "responses": { "200": { "$ref": "#/components/responses/invoice_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "default": { "$ref": "#/components/responses/problem" } } }, "delete": { "summary": "Delete invoice", "description": "Delete an invoice once it's in a terminal status: `confirmed`, `cancelled`, or `expired`.\n\nActive invoices (`pending`, `underpaid`) must be cancelled first. `paid` and `overpaid`\nare in-between states — wait until the invoice settles to `confirmed`, or reverts on a reorg,\nbefore deleting it.\n\nThe invoice's status history and ledger entries are deleted with it. On-chain records are untouched.\n", "operationId": "delete-invoice", "security": [ { "Auth": [ "api:invoice:delete" ] } ], "tags": [ "invoice" ], "parameters": [ { "$ref": "#/components/parameters/invoiceID" } ], "responses": { "204": { "$ref": "#/components/responses/no_content_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "422": { "$ref": "#/components/responses/precondition_problem" }, "default": { "$ref": "#/components/responses/problem" } } } }, "/invoices/{invoice_id}/actions/cancel": { "post": { "summary": "Cancel invoice", "description": "Cancel an active invoice. Only invoices in `pending` or `underpaid` status can be cancelled.\nCancelling frees the address for new invoices.\n\nThis operation is idempotent: cancelling an already-cancelled invoice returns 204.\n", "operationId": "cancel-invoice", "security": [ { "Auth": [ "api:invoice:write" ] } ], "tags": [ "invoice" ], "parameters": [ { "$ref": "#/components/parameters/invoiceID" } ], "requestBody": { "$ref": "#/components/requestBodies/cancel_invoice_request" }, "responses": { "204": { "$ref": "#/components/responses/no_content_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "422": { "$ref": "#/components/responses/precondition_problem" }, "default": { "$ref": "#/components/responses/problem" } } } }, "/public/invoices/{invoice_id}": { "get": { "summary": "Get public invoice", "description": "Public endpoint for payers. Returns invoice details needed for payment.\nNo authentication required — the invoice UUID is the access token.\n", "operationId": "get-public-invoice", "tags": [ "invoice" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/invoiceID" } ], "responses": { "200": { "$ref": "#/components/responses/public_invoice_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "default": { "$ref": "#/components/responses/problem" } } } }, "/channels": { "get": { "summary": "List channels", "description": "List channels with filtering and pagination.", "operationId": "list-channels", "security": [ { "Auth": [ "api:channel:read" ] } ], "tags": [ "channel" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/channelsFilterKind" }, { "$ref": "#/components/parameters/channelsFilterSearch" }, { "$ref": "#/components/parameters/sortChannels" } ], "responses": { "200": { "$ref": "#/components/responses/channels_list_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "default": { "$ref": "#/components/responses/problem" } } }, "post": { "summary": "Create channel", "description": "Create a channel. Channel schema is selected by `config.kind`.", "operationId": "create-channel", "security": [ { "Auth": [ "api:channel:write" ] } ], "tags": [ "channel" ], "requestBody": { "$ref": "#/components/requestBodies/create_channel_request" }, "responses": { "200": { "$ref": "#/components/responses/channel_created_response" }, "201": { "$ref": "#/components/responses/channel_created_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "default": { "$ref": "#/components/responses/problem" } } } }, "/channels/{channel_id}": { "get": { "summary": "Get channel", "description": "Get channel details by ID.", "operationId": "get-channel", "security": [ { "Auth": [ "api:channel:read" ] } ], "tags": [ "channel" ], "parameters": [ { "$ref": "#/components/parameters/channelID" } ], "responses": { "200": { "$ref": "#/components/responses/channel_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "default": { "$ref": "#/components/responses/problem" } } }, "delete": { "summary": "Delete channel", "description": "Delete a channel by ID.", "operationId": "delete-channel", "security": [ { "Auth": [ "api:channel:delete" ] } ], "tags": [ "channel" ], "parameters": [ { "$ref": "#/components/parameters/channelID" } ], "responses": { "204": { "$ref": "#/components/responses/no_content_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "default": { "$ref": "#/components/responses/problem" } } }, "patch": { "summary": "Update channel", "description": "Update channel metadata or configuration.", "operationId": "patch-channel", "security": [ { "Auth": [ "api:channel:write" ] } ], "tags": [ "channel" ], "parameters": [ { "$ref": "#/components/parameters/channelID" } ], "requestBody": { "$ref": "#/components/requestBodies/update_channel_config_request" }, "responses": { "200": { "$ref": "#/components/responses/channel_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "default": { "$ref": "#/components/responses/problem" } } } }, "/channels/{channel_id}/actions/test": { "post": { "summary": "Test channel", "description": "Sends a test event through the channel and returns the log entry ID. Check the channel logs endpoint to see whether delivery succeeded.", "operationId": "test-channel", "security": [ { "Auth": [ "api:channel:write" ] } ], "tags": [ "channel" ], "parameters": [ { "$ref": "#/components/parameters/channelID" } ], "requestBody": { "$ref": "#/components/requestBodies/test_channel_request" }, "responses": { "200": { "$ref": "#/components/responses/test_channel_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "409": { "$ref": "#/components/responses/conflict_problem" }, "422": { "$ref": "#/components/responses/precondition_problem" }, "default": { "$ref": "#/components/responses/problem" } } } }, "/channels/{channel_id}/logs": { "get": { "summary": "List channel delivery logs", "description": "List delivery logs for a channel with filtering and pagination.", "operationId": "list-channel-logs", "security": [ { "Auth": [ "api:channel:read" ] } ], "tags": [ "channel" ], "parameters": [ { "$ref": "#/components/parameters/channelID" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/channelLogsFilterEventType" }, { "$ref": "#/components/parameters/channelLogsFilterIsSuccess" }, { "$ref": "#/components/parameters/sortChannelLogs" } ], "responses": { "200": { "$ref": "#/components/responses/channel_logs_list_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "default": { "$ref": "#/components/responses/problem" } } } }, "/channels/{channel_id}/webhook-secrets": { "get": { "summary": "Get webhook signing secrets", "description": "Returns the channel's signing secrets: always a `current` secret, plus a\n`previous` secret during the 24-hour rotation overlap window.\n\nOnly valid for channels with `kind=webhook`; otherwise returns 400.\n", "operationId": "get-channel-webhook-secrets", "security": [ { "Auth": [ "api:channel:read" ] } ], "tags": [ "channel" ], "parameters": [ { "$ref": "#/components/parameters/channelID" } ], "responses": { "200": { "$ref": "#/components/responses/channel_webhook_secrets_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "default": { "$ref": "#/components/responses/problem" } } } }, "/channels/{channel_id}/webhook-secrets/actions/rotate": { "post": { "summary": "Rotate webhook signing secret", "description": "Issues a new signing secret, demotes the existing current to previous for\na 24-hour overlap window, and returns the new plaintext value. The\nplaintext is returned only here; store it immediately.\n\nDuring the overlap window outgoing webhooks are signed with both secrets:\nthe `X-Webhook-Signature` header carries two `v1=` entries, so receivers\nthat verify with either secret keep accepting deliveries.\n\nReturns 409 if a previous secret is still within its overlap window;\nend it via `deleteChannelPreviousWebhookSecret` before rotating again.\n\nOnly valid for channels with `kind=webhook`; otherwise returns 400.\n", "operationId": "rotate-channel-webhook-secret", "security": [ { "Auth": [ "api:channel:write" ] } ], "tags": [ "channel" ], "parameters": [ { "$ref": "#/components/parameters/channelID" } ], "responses": { "200": { "$ref": "#/components/responses/rotate_channel_webhook_secret_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "409": { "$ref": "#/components/responses/conflict_problem" }, "default": { "$ref": "#/components/responses/problem" } } } }, "/channels/{channel_id}/webhook-secrets/previous": { "delete": { "summary": "Delete previous webhook signing secret", "description": "Ends the rotation overlap window early. After this call, outgoing webhooks\nare signed only with the current secret.\n\nIdempotent: if there is no previous secret (the channel has never been\nrotated, or it was already deleted), the response is still 204.\n\nOnly valid for channels with `kind=webhook`; otherwise returns 400.\n", "operationId": "delete-channel-previous-webhook-secret", "security": [ { "Auth": [ "api:channel:write" ] } ], "tags": [ "channel" ], "parameters": [ { "$ref": "#/components/parameters/channelID" } ], "responses": { "204": { "$ref": "#/components/responses/no_content_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "default": { "$ref": "#/components/responses/problem" } } } }, "/subscriptions": { "get": { "summary": "List subscriptions", "description": "List subscriptions with filtering and pagination.", "operationId": "list-subscriptions", "security": [ { "Auth": [ "api:subscription:read" ] } ], "tags": [ "subscription" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/subscriptionsFilterChannelID" }, { "$ref": "#/components/parameters/subscriptionsFilterEventType" }, { "$ref": "#/components/parameters/subscriptionsFilterEnabled" }, { "$ref": "#/components/parameters/subscriptionsFilterSearch" }, { "$ref": "#/components/parameters/sortSubscriptions" } ], "responses": { "200": { "$ref": "#/components/responses/subscriptions_list_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "default": { "$ref": "#/components/responses/problem" } } }, "post": { "summary": "Create subscription", "description": "Create a subscription binding a channel to an event type.", "operationId": "create-subscription", "security": [ { "Auth": [ "api:subscription:write" ] } ], "tags": [ "subscription" ], "requestBody": { "$ref": "#/components/requestBodies/create_subscription_request" }, "responses": { "200": { "$ref": "#/components/responses/subscription_response" }, "201": { "$ref": "#/components/responses/subscription_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "default": { "$ref": "#/components/responses/problem" } } } }, "/subscriptions/{subscription_id}": { "get": { "summary": "Get subscription", "description": "Get subscription details by ID.", "operationId": "get-subscription", "security": [ { "Auth": [ "api:subscription:read" ] } ], "tags": [ "subscription" ], "parameters": [ { "$ref": "#/components/parameters/subscriptionID" } ], "responses": { "200": { "$ref": "#/components/responses/subscription_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "default": { "$ref": "#/components/responses/problem" } } }, "delete": { "summary": "Delete subscription", "description": "Delete a subscription by ID.", "operationId": "delete-subscription", "security": [ { "Auth": [ "api:subscription:delete" ] } ], "tags": [ "subscription" ], "parameters": [ { "$ref": "#/components/parameters/subscriptionID" } ], "responses": { "204": { "$ref": "#/components/responses/no_content_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "default": { "$ref": "#/components/responses/problem" } } }, "patch": { "summary": "Update subscription", "description": "Update subscription name or enabled status.", "operationId": "patch-subscription", "security": [ { "Auth": [ "api:subscription:write" ] } ], "tags": [ "subscription" ], "parameters": [ { "$ref": "#/components/parameters/subscriptionID" } ], "requestBody": { "$ref": "#/components/requestBodies/update_subscription_request" }, "responses": { "200": { "$ref": "#/components/responses/subscription_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "default": { "$ref": "#/components/responses/problem" } } } }, "/token_tags": { "get": { "summary": "List token tags", "description": "List token tags with pagination.", "operationId": "list-token-tags", "security": [ { "Auth": [ "api:token_tag:read" ] } ], "tags": [ "token_tag" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/sortTokenTags" }, { "$ref": "#/components/parameters/tokenTagsFilterSearch" } ], "responses": { "200": { "$ref": "#/components/responses/token_tags_list_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "default": { "$ref": "#/components/responses/problem" } } }, "post": { "summary": "Create token tag", "description": "Create a named collection of tokens within a project. Tag names are\nunique per project (case-insensitive). Creating a tag whose name already\nexists returns the existing tag.\n", "operationId": "create-token-tag", "security": [ { "Auth": [ "api:token_tag:write" ] } ], "tags": [ "token_tag" ], "requestBody": { "$ref": "#/components/requestBodies/create_token_tag_request" }, "responses": { "200": { "$ref": "#/components/responses/token_tag_response" }, "201": { "$ref": "#/components/responses/token_tag_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "default": { "$ref": "#/components/responses/problem" } } } }, "/token_tags/{token_tag_id}": { "get": { "summary": "Get token tag", "description": "Get a token tag.", "operationId": "get-token-tag", "security": [ { "Auth": [ "api:token_tag:read" ] } ], "tags": [ "token_tag" ], "parameters": [ { "$ref": "#/components/parameters/tokenTagID" } ], "responses": { "200": { "$ref": "#/components/responses/token_tag_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "default": { "$ref": "#/components/responses/problem" } } }, "patch": { "summary": "Update token tag", "description": "Rename a token tag.", "operationId": "patch-token-tag", "security": [ { "Auth": [ "api:token_tag:write" ] } ], "tags": [ "token_tag" ], "parameters": [ { "$ref": "#/components/parameters/tokenTagID" } ], "requestBody": { "$ref": "#/components/requestBodies/update_token_tag_request" }, "responses": { "200": { "$ref": "#/components/responses/token_tag_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "default": { "$ref": "#/components/responses/problem" } } }, "delete": { "summary": "Delete token tag", "description": "Delete a token tag.", "operationId": "delete-token-tag", "security": [ { "Auth": [ "api:token_tag:delete" ] } ], "tags": [ "token_tag" ], "parameters": [ { "$ref": "#/components/parameters/tokenTagID" } ], "responses": { "204": { "$ref": "#/components/responses/no_content_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "default": { "$ref": "#/components/responses/problem" } } } }, "/token_tags/{token_tag_id}/actions/add": { "post": { "summary": "Add assets to token tag", "description": "Add tokens to a token tag by asset GID.", "operationId": "add-token-tag-assets", "security": [ { "Auth": [ "api:token_tag:write" ] } ], "tags": [ "token_tag" ], "parameters": [ { "$ref": "#/components/parameters/tokenTagID" } ], "requestBody": { "$ref": "#/components/requestBodies/add_token_tag_assets_request" }, "responses": { "204": { "$ref": "#/components/responses/no_content_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "default": { "$ref": "#/components/responses/problem" } } } }, "/token_tags/{token_tag_id}/actions/remove": { "post": { "summary": "Remove assets from token tag", "description": "Remove tokens from a token tag by asset GID.", "operationId": "remove-token-tag-assets", "security": [ { "Auth": [ "api:token_tag:write" ] } ], "tags": [ "token_tag" ], "parameters": [ { "$ref": "#/components/parameters/tokenTagID" } ], "requestBody": { "$ref": "#/components/requestBodies/remove_token_tag_assets_request" }, "responses": { "204": { "$ref": "#/components/responses/no_content_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "default": { "$ref": "#/components/responses/problem" } } } }, "/address_tags": { "get": { "summary": "List address tags", "description": "List address tags with pagination.", "operationId": "list-address-tags", "security": [ { "Auth": [ "api:address_tag:read" ] } ], "tags": [ "address_tag" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/sortAddressTags" }, { "$ref": "#/components/parameters/addressTagsFilterSearch" } ], "responses": { "200": { "$ref": "#/components/responses/address_tags_list_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "default": { "$ref": "#/components/responses/problem" } } }, "post": { "summary": "Create address tag", "description": "Create a named collection of addresses within a project. Tag names are\nunique per project (case-insensitive). Creating a tag whose name already\nexists returns the existing tag.\n", "operationId": "create-address-tag", "security": [ { "Auth": [ "api:address_tag:write" ] } ], "tags": [ "address_tag" ], "requestBody": { "$ref": "#/components/requestBodies/create_address_tag_request" }, "responses": { "200": { "$ref": "#/components/responses/address_tag_response" }, "201": { "$ref": "#/components/responses/address_tag_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "default": { "$ref": "#/components/responses/problem" } } } }, "/address_tags/{address_tag_id}": { "get": { "summary": "Get address tag", "description": "Get an address tag.", "operationId": "get-address-tag", "security": [ { "Auth": [ "api:address_tag:read" ] } ], "tags": [ "address_tag" ], "parameters": [ { "$ref": "#/components/parameters/addressTagID" } ], "responses": { "200": { "$ref": "#/components/responses/address_tag_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "default": { "$ref": "#/components/responses/problem" } } }, "patch": { "summary": "Update address tag", "description": "Rename an address tag.", "operationId": "patch-address-tag", "security": [ { "Auth": [ "api:address_tag:write" ] } ], "tags": [ "address_tag" ], "parameters": [ { "$ref": "#/components/parameters/addressTagID" } ], "requestBody": { "$ref": "#/components/requestBodies/update_address_tag_request" }, "responses": { "200": { "$ref": "#/components/responses/address_tag_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "default": { "$ref": "#/components/responses/problem" } } }, "delete": { "summary": "Delete address tag", "description": "Delete an address tag.", "operationId": "delete-address-tag", "security": [ { "Auth": [ "api:address_tag:delete" ] } ], "tags": [ "address_tag" ], "parameters": [ { "$ref": "#/components/parameters/addressTagID" } ], "responses": { "204": { "$ref": "#/components/responses/no_content_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "default": { "$ref": "#/components/responses/problem" } } } }, "/address_tags/{address_tag_id}/actions/add": { "post": { "summary": "Add addresses to address tag", "description": "Add addresses to an address tag by address value.", "operationId": "add-address-tag-addresses", "security": [ { "Auth": [ "api:address_tag:write" ] } ], "tags": [ "address_tag" ], "parameters": [ { "$ref": "#/components/parameters/addressTagID" } ], "requestBody": { "$ref": "#/components/requestBodies/add_address_tag_addresses_request" }, "responses": { "204": { "$ref": "#/components/responses/no_content_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "default": { "$ref": "#/components/responses/problem" } } } }, "/address_tags/{address_tag_id}/actions/remove": { "post": { "summary": "Remove addresses from address tag", "description": "Remove addresses from an address tag by address value.", "operationId": "remove-address-tag-addresses", "security": [ { "Auth": [ "api:address_tag:write" ] } ], "tags": [ "address_tag" ], "parameters": [ { "$ref": "#/components/parameters/addressTagID" } ], "requestBody": { "$ref": "#/components/requestBodies/remove_address_tag_addresses_request" }, "responses": { "204": { "$ref": "#/components/responses/no_content_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "401": { "$ref": "#/components/responses/unauthorized_problem" }, "403": { "$ref": "#/components/responses/forbidden_problem" }, "404": { "$ref": "#/components/responses/not_found_problem" }, "default": { "$ref": "#/components/responses/problem" } } } }, "/version": { "get": { "summary": "Get service version", "description": "Get the current API version.", "operationId": "get-version", "security": [], "responses": { "200": { "$ref": "#/components/responses/version_response" }, "400": { "$ref": "#/components/responses/invalid_request_problem" }, "default": { "$ref": "#/components/responses/problem" } }, "tags": [ "version" ] } } }, "components": { "securitySchemes": { "Auth": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "API key for authenticating requests. Include your key in the `X-Api-Key` header. Keys can be created in the Vilna Dashboard or via the Management API. The scopes listed per operation indicate which permissions the key must have.\n" } }, "parameters": { "limit": { "description": "Maximum number of items to return.", "in": "query", "name": "limit", "required": false, "schema": { "default": 30, "example": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, "page": { "description": "Page number for pagination.", "in": "query", "name": "page", "required": false, "schema": { "default": 1, "example": 1, "minimum": 1, "type": "integer" } }, "sortBlockchains": { "name": "sort_by", "in": "query", "description": "Field to sort results by. Use `-` prefix for descending order.", "required": false, "schema": { "type": "string", "enum": [ "gid", "-gid", "name", "-name", "short_name", "-short_name" ], "example": "name", "default": "name" } }, "blockchainsFilterSearch": { "name": "search", "in": "query", "description": "Filter blockchains by name or short name (partial match, case-insensitive).", "required": false, "schema": { "type": "string", "maxLength": 32, "example": "ethereum" } }, "blockchainsFilterFamilies": { "name": "family", "in": "query", "description": "Filter blockchains by chain family.", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ChainFamily" } }, "example": [ "evm" ] }, "chainGID": { "name": "chain_gid", "in": "path", "description": "Blockchain identifier in CAIP-2 format (namespace:reference).", "required": true, "schema": { "$ref": "#/components/schemas/ChainGID" } }, "publicKeysFilterSearch": { "name": "search", "in": "query", "description": "Filter public keys by label (partial match, case-insensitive).", "required": false, "schema": { "type": "string", "maxLength": 32, "example": "wallet" } }, "sortPublicKeys": { "name": "sort_by", "in": "query", "description": "Field to sort results by. Use `-` prefix for descending order.", "required": false, "schema": { "type": "string", "enum": [ "id", "-id", "label", "-label", "created_at", "-created_at", "updated_at", "-updated_at" ], "default": "-created_at", "example": "created_at" } }, "publicKeyID": { "name": "public_key_id", "in": "path", "description": "Unique identifier (UUID) of the public key.", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, "sortAddresses": { "name": "sort_by", "in": "query", "description": "Field to sort results by. Use `-` prefix for descending order.", "required": false, "schema": { "type": "string", "enum": [ "label", "-label", "value", "-value", "created_at", "-created_at", "updated_at", "-updated_at" ], "default": "-created_at", "example": "created_at" } }, "addressesFilterFormats": { "name": "format", "in": "query", "description": "Filter addresses by address format.", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AddressFormat" } }, "example": [ "p2wpkh" ] }, "addressesFilterSearch": { "name": "search", "in": "query", "description": "Filter addresses by value or label (partial match, case-insensitive).", "required": false, "schema": { "type": "string", "maxLength": 64, "example": "bc1q" } }, "addressesFilterTagIDs": { "name": "tag_id", "in": "query", "description": "Filter addresses by tag identifier (UUID). Repeat the parameter to pass\nmultiple values; addresses tagged with any of them are returned (OR semantics).\n", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/UUID" } }, "example": [ "0199ce7e-d9e7-7c01-9c2a-9d0010eaa1cc" ] }, "addressesFilterKind": { "name": "kind", "in": "query", "description": "Filter by address kind (`hd` or `external`).", "required": false, "schema": { "$ref": "#/components/schemas/AddressKind" } }, "address": { "name": "address", "in": "path", "description": "Blockchain address in its native format (e.g., 0x8521E8b15eCEF4D4269Fded3E6694225E096959E for EVM chains).", "required": true, "schema": { "$ref": "#/components/schemas/AddressValue" } }, "sortBalances": { "name": "sort_by", "in": "query", "description": "Field to sort results by. Use `-` prefix for descending order.", "required": false, "schema": { "type": "string", "enum": [ "balance", "-balance" ], "default": "-balance", "example": "balance" } }, "utxoFilterChainGIDs": { "name": "chain_gid", "in": "query", "description": "Filter UTXOs by blockchain identifiers (CAIP-2 format). If not specified, returns all bip122 chains.", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/ChainGID" } }, "example": [ "bip122:000000000019d6689c085ae165831e93" ] }, "sortBitcoinUTXOs": { "name": "sort_by", "in": "query", "description": "Field to sort results by. Use `-` prefix for descending order.", "required": false, "schema": { "type": "string", "enum": [ "hash", "-hash", "amount", "-amount", "block_number", "-block_number" ], "default": "-block_number", "example": "-amount" } }, "sortTokens": { "name": "sort_by", "in": "query", "description": "Field to sort results by. Use `-` prefix for descending order.", "required": false, "schema": { "type": "string", "enum": [ "gid", "-gid", "address", "-address", "decimals", "-decimals", "name", "-name", "symbol", "-symbol" ], "default": "symbol", "example": "symbol" } }, "tokensFilterSearch": { "name": "search", "in": "query", "description": "Filter tokens by address, symbol, or name (partial match, case-insensitive).", "required": false, "schema": { "type": "string", "maxLength": 32, "example": "USDT" } }, "tokensFilterChainGIDs": { "name": "chain_gid", "in": "query", "description": "Filter tokens by blockchain identifiers (CAIP-2 format).", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/ChainGID" } }, "example": [ "eip155:1" ] }, "tokensFilterTagIDs": { "name": "tag_id", "in": "query", "description": "Filter tokens by tag identifier (UUID). Repeat the parameter to pass\nmultiple values; tokens tagged with any of them are returned (OR semantics).\n", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/UUID" } }, "example": [ "0199ce7e-d9e7-7c01-9c2a-9d0010eaa1cc" ] }, "assetPath": { "name": "asset_path", "in": "path", "description": "Asset type identifier in CAIP-19 format (asset_namespace:asset_reference).", "required": true, "schema": { "$ref": "#/components/schemas/AssetPath" } }, "activityFilterAddresses": { "name": "address", "in": "query", "description": "Filter activity by addresses. If not specified, includes all tracked addresses.", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/AddressValue" } }, "example": [ "0x742d35cc6634c0532925a3b8d1e1d78d8E15e5c4" ] }, "activityFilterAssetGIDs": { "name": "asset_gid", "in": "query", "description": "Filter activity by asset identifier (CAIP-19 format).", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/AssetGID" } }, "example": [ "eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7" ] }, "activityFilterChainGIDs": { "name": "chain_gid", "in": "query", "description": "Filter activity by blockchain identifier (CAIP-2 format).", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/ChainGID" } }, "example": [ "eip155:1" ] }, "activityFilterHashes": { "name": "hash", "in": "query", "description": "Filter activity by transaction hash.", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/TransactionHash" } }, "example": [ "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" ] }, "activityFilterDirection": { "name": "direction", "in": "query", "description": "Filter activity by movement direction relative to the address.\n- `in`: only positive deltas (incoming assets)\n- `out`: only negative deltas (outgoing assets)\n\nIf not specified, both directions are returned.\n", "required": false, "schema": { "type": "string", "enum": [ "in", "out" ] }, "example": "in" }, "activityFilterDateFrom": { "name": "date_from", "in": "query", "description": "Filter activity starting from this date (inclusive, RFC 3339).", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2024-01-01T00:00:00Z" }, "activityFilterDateTo": { "name": "date_to", "in": "query", "description": "Filter activity up to this date (inclusive, RFC 3339).", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2024-12-31T23:59:59Z" }, "sortActivity": { "name": "sort_by", "in": "query", "description": "Field to sort results by. Use `-` prefix for descending order.", "required": false, "schema": { "type": "string", "enum": [ "address", "-address", "asset_gid", "-asset_gid", "hash", "-hash", "created_at", "-created_at", "delta", "-delta" ], "default": "-created_at", "example": "created_at" } }, "balanceFilterAddresses": { "name": "address", "in": "query", "description": "Filter balances by addresses. If not specified, includes all tracked addresses.", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/AddressValue" } }, "example": [ "0x742d35cc6634c0532925a3b8d1e1d78d8E15e5c4" ] }, "balanceFilterAssetGIDs": { "name": "asset_gid", "in": "query", "description": "Filter balances by specific assets (CAIP-19 format). If not specified, returns all assets.", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/AssetGID" } }, "example": [ "eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7" ] }, "balanceFilterChainGIDs": { "name": "chain_gid", "in": "query", "description": "Filter balances by blockchain identifiers (CAIP-2 format). If not specified, returns all blockchains.", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/ChainGID" } }, "example": [ "eip155:1" ] }, "transactionFilterChainGIDs": { "name": "chain_gid", "in": "query", "description": "Filter transactions by blockchain identifier (CAIP-2 format).", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/ChainGID" } }, "example": [ "eip155:1" ] }, "transactionFilterHashes": { "name": "hash", "in": "query", "description": "Filter transactions by transaction hash.", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/TransactionHash" } }, "example": [ "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" ] }, "transactionFilterBlockNumbers": { "name": "block_number", "in": "query", "description": "Filter transactions by block number.", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/BlockNumber" } }, "example": [ 18500000 ] }, "transactionFilterIsSuccess": { "name": "is_success", "in": "query", "description": "Filter transactions by execution status.", "required": false, "schema": { "type": "boolean" }, "example": true }, "transactionFilterIsConfirmed": { "name": "is_confirmed", "in": "query", "description": "Filter transactions by confirmation status.", "required": false, "schema": { "type": "boolean" }, "example": true }, "transactionFilterAddresses": { "name": "address", "in": "query", "description": "Filter transactions by the addresses they touch. Repeat the parameter to\npass multiple values; transactions touching any of them are returned (OR\nsemantics). Combined with `tag_id` as a union.\n", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/AddressValue" } }, "example": [ "0x8521E8b15eCEF4D4269Fded3E6694225E096959E" ] }, "transactionFilterTagIDs": { "name": "tag_id", "in": "query", "description": "Filter transactions by address tag identifier (UUID). Repeat the parameter\nto pass multiple values; transactions touching an address with any of these\ntags are returned (OR semantics). Combined with `address` as a union.\n", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/UUID" } }, "example": [ "0199ce7e-d9e7-7c01-9c2a-9d0010eaa1cc" ] }, "sortTransactions": { "name": "sort_by", "in": "query", "description": "Field to sort results by. Use `-` prefix for descending order.", "required": false, "schema": { "type": "string", "enum": [ "hash", "-hash", "block_number", "-block_number", "is_success", "-is_success", "confirmed_at", "-confirmed_at", "created_at", "-created_at" ], "default": "-created_at", "example": "confirmed_at" } }, "hash": { "name": "hash", "in": "path", "description": "Transaction hash identifier.", "required": true, "schema": { "$ref": "#/components/schemas/TransactionHash" }, "example": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" }, "invoicesFilterStatuses": { "name": "status", "in": "query", "description": "Filter invoices by status.", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceStatus" } }, "example": [ "pending" ] }, "sortInvoices": { "name": "sort_by", "in": "query", "description": "Field to sort results by. Use `-` prefix for descending order.", "required": false, "schema": { "type": "string", "enum": [ "created_at", "-created_at", "updated_at", "-updated_at", "expires_at", "-expires_at", "status", "-status" ], "default": "-created_at", "example": "created_at" } }, "invoiceID": { "name": "invoice_id", "in": "path", "description": "Unique identifier (UUID) of the invoice.", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, "channelsFilterKind": { "name": "kind", "in": "query", "required": false, "description": "Filter by delivery type (`telegram` or `webhook`).", "schema": { "$ref": "#/components/schemas/ChannelKind" }, "example": "webhook" }, "channelsFilterSearch": { "name": "search", "in": "query", "description": "Filter channels by name (partial match, case-insensitive).", "required": false, "schema": { "type": "string", "maxLength": 32 }, "example": "production" }, "sortChannels": { "name": "sort_by", "in": "query", "description": "Field to sort results by. Use `-` prefix for descending order.", "required": false, "schema": { "type": "string", "enum": [ "name", "-name", "kind", "-kind", "created_at", "-created_at", "updated_at", "-updated_at" ], "default": "-created_at", "example": "created_at" } }, "channelID": { "name": "channel_id", "in": "path", "description": "Unique identifier (UUID) of the channel.", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, "channelLogsFilterEventType": { "name": "event_type", "in": "query", "required": false, "description": "Filter delivery logs by subscription event type.\n\n- `transaction_detected` — A new transaction involving a tracked address appears on-chain.\n- `transaction_confirmed` — A previously detected transaction reaches the required number of confirmations.\n", "schema": { "$ref": "#/components/schemas/SubscriptionEventType" }, "example": "transaction_detected" }, "channelLogsFilterIsSuccess": { "name": "is_success", "in": "query", "required": false, "description": "Filter delivery logs by success status.\n\n- `true` — Returns only successful deliveries (2xx status code).\n- `false` — Returns only failed deliveries.\n- Omit parameter — Returns all deliveries.\n", "schema": { "type": "boolean" }, "example": false }, "sortChannelLogs": { "name": "sort_by", "in": "query", "description": "Field to sort results by. Use `-` prefix for descending order.", "required": false, "schema": { "type": "string", "enum": [ "created_at", "-created_at" ], "default": "-created_at", "example": "created_at" } }, "subscriptionsFilterChannelID": { "name": "channel_id", "in": "query", "required": false, "description": "Filter by channel ID (UUID).", "schema": { "$ref": "#/components/schemas/UUID" } }, "subscriptionsFilterEventType": { "name": "event_type", "in": "query", "required": false, "description": "Filter by event type.", "schema": { "$ref": "#/components/schemas/SubscriptionEventType" } }, "subscriptionsFilterEnabled": { "name": "enabled", "in": "query", "required": false, "description": "Filter by enabled status.", "schema": { "type": "boolean" } }, "subscriptionsFilterSearch": { "name": "search", "in": "query", "description": "Filter subscriptions by name (partial match, case-insensitive).", "required": false, "schema": { "type": "string", "maxLength": 64 }, "example": "transaction" }, "sortSubscriptions": { "name": "sort_by", "in": "query", "description": "Field to sort results by. Use `-` prefix for descending order.", "required": false, "schema": { "type": "string", "enum": [ "name", "-name", "event_type", "-event_type", "created_at", "-created_at", "updated_at", "-updated_at" ], "default": "-created_at", "example": "created_at" } }, "subscriptionID": { "name": "subscription_id", "in": "path", "description": "Unique identifier (UUID) of the subscription.", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, "sortTokenTags": { "name": "sort_by", "in": "query", "description": "Field to sort results by. Use `-` prefix for descending order.", "required": false, "schema": { "type": "string", "enum": [ "name", "-name", "created_at", "-created_at", "updated_at", "-updated_at" ], "default": "-created_at", "example": "created_at" } }, "tokenTagsFilterSearch": { "name": "search", "in": "query", "description": "Filter token tags by name (partial match, case-insensitive).", "required": false, "schema": { "type": "string", "maxLength": 32 }, "example": "Stablecoins" }, "tokenTagID": { "name": "token_tag_id", "in": "path", "description": "Unique identifier (UUID) of the token tag.", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } }, "sortAddressTags": { "name": "sort_by", "in": "query", "description": "Field to sort results by. Use `-` prefix for descending order.", "required": false, "schema": { "type": "string", "enum": [ "name", "-name", "created_at", "-created_at", "updated_at", "-updated_at" ], "default": "-created_at", "example": "created_at" } }, "addressTagsFilterSearch": { "name": "search", "in": "query", "description": "Filter address tags by name (partial match, case-insensitive).", "required": false, "schema": { "type": "string", "maxLength": 32 }, "example": "Hot Wallets" }, "addressTagID": { "name": "address_tag_id", "in": "path", "description": "Unique identifier (UUID) of the address tag.", "required": true, "schema": { "$ref": "#/components/schemas/UUID" } } }, "schemas": { "ChainFamily": { "description": "Chain family that identifies blockchain ecosystems united by common protocol or account model.", "enum": [ "evm", "bitcoin", "solana", "tron" ], "x-enumDescriptions": { "evm": "Ethereum Virtual Machine-based blockchains (Ethereum, BSC, Polygon, Arbitrum, etc.).", "bitcoin": "Bitcoin and Bitcoin-compatible networks.", "solana": "Solana blockchain ecosystem.", "tron": "Tron blockchain ecosystem." }, "example": "evm", "type": "string" }, "ProblemType": { "type": "string", "format": "uri", "description": "A URI that identifies the error type.\nOpen it in a browser to read about this category of error.\n", "example": "https://docs.vilna.io/apis/problems/internal-error" }, "ProblemTitle": { "type": "string", "description": "A short summary of the error type.\nUse `detail` for information specific to this occurrence.\n", "example": "Bad Request" }, "ProblemStatus": { "type": "integer", "description": "The HTTP status code for this error.\nMatches the status code of the HTTP response.\n", "example": 400 }, "ProblemDetail": { "type": "string", "description": "A human-readable explanation of what went wrong in this specific case.\nMay be localized.\n", "example": "The address is already assigned to another invoice" }, "ProblemInstance": { "type": "string", "description": "A URI that identifies this specific error occurrence.\nInclude this value when contacting support.\n", "example": "/errors?id=XXXXXX-xxxxx" }, "ProblemCode": { "type": "string", "description": "Stable machine-readable error code (`{domain}.{reason}`) for programmatic error handling. Unlike the HTTP `status` or free-form `detail`, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to `unspecified` when the server has not assigned a specific code.\n", "default": "unspecified", "example": "resource.not_found" }, "Problem": { "type": "object", "description": "Error response following [RFC 7807](https://tools.ietf.org/rfc/rfc7807.txt). Served with `Content-Type: application/problem+json`. All error responses use this format; branch on `code` for programmatic handling and surface `detail` to end users.\n", "required": [ "type", "title", "status", "code" ], "properties": { "type": { "$ref": "#/components/schemas/ProblemType" }, "title": { "$ref": "#/components/schemas/ProblemTitle" }, "status": { "$ref": "#/components/schemas/ProblemStatus" }, "detail": { "$ref": "#/components/schemas/ProblemDetail" }, "instance": { "$ref": "#/components/schemas/ProblemInstance" }, "code": { "$ref": "#/components/schemas/ProblemCode" } } }, "ChainGID": { "type": "string", "description": "Blockchain identifier in [CAIP-2](https://chainagnostic.org/CAIPs/caip-2) format.\n\nFormat: `{namespace}:{reference}`\n- **namespace**: Ecosystem identifier (3-8 chars, lowercase)\n- **reference**: Blockchain identifier within namespace (1-32 chars)\n\n**Examples**:\n- `eip155:1` — Ethereum mainnet\n- `eip155:56` — BNB Smart Chain mainnet\n- `eip155:137` — Polygon mainnet\n- `bip122:000000000019d6689c085ae165831e93` — Bitcoin mainnet\n- `tron:mainnet` — Tron mainnet\n", "pattern": "^[a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32}$", "example": "eip155:1" }, "MinConfirmations": { "type": "integer", "format": "uint8", "minimum": 1, "maximum": 100, "description": "Required number of block confirmations for a transaction to be considered finalized.", "example": 12 }, "Blockchain": { "description": "Blockchain details.", "properties": { "gid": { "$ref": "#/components/schemas/ChainGID" }, "image_url": { "description": "Blockchain logo URL.", "format": "uri", "type": "string" }, "name": { "description": "Blockchain name identifier (for example, `ethereum`).", "type": "string", "minLength": 1, "maxLength": 32 }, "short_name": { "description": "Short blockchain identifier (for example, `eth`).", "type": "string", "minLength": 1, "maxLength": 32 }, "min_confirmations": { "$ref": "#/components/schemas/MinConfirmations" } }, "required": [ "gid", "name", "short_name", "image_url", "min_confirmations" ], "type": "object", "example": { "gid": "eip155:1", "name": "ethereum", "short_name": "eth", "image_url": "https://raw.githubusercontent.com/vilna-io/icons/refs/heads/main/chains/ethereum.svg", "min_confirmations": 12 } }, "PaginationMeta": { "type": "object", "description": "Pagination metadata returned on every list response. `page` and `limit` echo the values used to build this page (defaults are applied when the request omits them). `total` and `total_pages` reflect the full result set after any filters are applied.\n", "properties": { "limit": { "description": "Page size used to build this response.", "type": "integer", "format": "uint", "minimum": 1 }, "page": { "description": "Index of the page returned, starting at 1.", "type": "integer", "format": "uint", "minimum": 1 }, "total": { "description": "Total number of items matching the request across all pages.", "type": "integer", "format": "uint", "minimum": 0 }, "total_pages": { "description": "Total number of pages available at the current `limit`.", "type": "integer", "format": "uint", "minimum": 0 } }, "required": [ "total", "page", "limit", "total_pages" ], "example": { "limit": 20, "page": 1, "total": 42, "total_pages": 3 } }, "InvalidRequestProblem": { "type": "object", "description": "Problem details for invalid request errors (400 Bad Request).\n\nExtends base Problem with field-specific validation error details\nfollowing [RFC 7807](https://tools.ietf.org/rfc/rfc7807.txt).\n", "required": [ "type", "title", "status", "code" ], "properties": { "type": { "$ref": "#/components/schemas/ProblemType", "example": "https://docs.vilna.io/apis/problems/invalid-request" }, "title": { "$ref": "#/components/schemas/ProblemTitle", "example": "Invalid Request" }, "status": { "$ref": "#/components/schemas/ProblemStatus", "example": 400 }, "detail": { "$ref": "#/components/schemas/ProblemDetail", "example": "Validation error" }, "instance": { "$ref": "#/components/schemas/ProblemInstance" }, "code": { "$ref": "#/components/schemas/ProblemCode", "example": "blockchain.name_too_long" }, "fields": { "type": "array", "description": "List of invalid fields in the request", "items": { "type": "object", "required": [ "name", "reason" ], "properties": { "name": { "type": "string", "description": "The name of the invalid field", "example": "meta" }, "reason": { "type": "string", "description": "Why this field is invalid", "example": "Exceeded maximum data size — must not exceed 1000 characters" } } } } } }, "UnauthorizedProblem": { "type": "object", "description": "Standard problem response when authentication is missing or invalid,\nfollowing [RFC 7807](https://tools.ietf.org/rfc/rfc7807.txt).\n", "required": [ "type", "title", "status", "code" ], "properties": { "type": { "$ref": "#/components/schemas/ProblemType", "example": "https://docs.vilna.io/apis/problems/unauthorized" }, "title": { "$ref": "#/components/schemas/ProblemTitle", "example": "Unauthorized" }, "status": { "$ref": "#/components/schemas/ProblemStatus", "example": 401 }, "detail": { "$ref": "#/components/schemas/ProblemDetail", "example": "Missing or invalid authentication credentials" }, "instance": { "$ref": "#/components/schemas/ProblemInstance" }, "code": { "$ref": "#/components/schemas/ProblemCode", "example": "auth.unauthorized" } } }, "ForbiddenProblem": { "type": "object", "description": "Standard problem response when the authenticated user lacks permission\nto access the requested resource, following [RFC 7807](https://tools.ietf.org/rfc/rfc7807.txt).\n", "required": [ "type", "title", "status", "code" ], "properties": { "type": { "$ref": "#/components/schemas/ProblemType", "example": "https://docs.vilna.io/apis/problems/forbidden" }, "title": { "$ref": "#/components/schemas/ProblemTitle", "example": "Forbidden" }, "status": { "$ref": "#/components/schemas/ProblemStatus", "example": 403 }, "detail": { "$ref": "#/components/schemas/ProblemDetail", "example": "You do not have permission to perform this action" }, "instance": { "$ref": "#/components/schemas/ProblemInstance" }, "code": { "$ref": "#/components/schemas/ProblemCode", "example": "chain.not_allowed" } } }, "NotFoundProblem": { "type": "object", "description": "Problem details for not found errors (404 Not Found).\n\nStandard problem response when requested resource does not exist\nfollowing [RFC 7807](https://tools.ietf.org/rfc/rfc7807.txt).\n", "required": [ "type", "title", "status", "code" ], "properties": { "type": { "$ref": "#/components/schemas/ProblemType", "example": "https://docs.vilna.io/apis/problems/not-found" }, "title": { "$ref": "#/components/schemas/ProblemTitle", "example": "Not Found" }, "status": { "$ref": "#/components/schemas/ProblemStatus", "example": 404 }, "detail": { "$ref": "#/components/schemas/ProblemDetail", "example": "The requested resource was not found" }, "instance": { "$ref": "#/components/schemas/ProblemInstance" }, "code": { "$ref": "#/components/schemas/ProblemCode", "example": "blockchain.not_found" } } }, "UUID": { "type": "string", "format": "uuid", "description": "Unique identifier (UUID v4).", "example": "550e8400-e29b-41d4-a716-446655440000" }, "PublicKeyValue": { "description": "BIP32/SLIP-0132 extended public key in Base58Check format.\n", "type": "string", "pattern": "^(xpub|ypub|zpub|tpub|vpub|upub)[1-9A-HJ-NP-Za-km-z]{100,108}$", "examples": [ "xpub6EFxzN6ZgMCZ1PxeRigmAhm2UBGzXtZNgznCEaWuEt9efBpJwAXFA4ZckBdR1pdMQ1pBgsey7ebjToZ5gYXveftB3zwoQ8NvEkimvyaz34i", "ypub6ZtCaoXpd9GqsJMiFThRchS8RXiyRBD3WxyoZhhnKF9n198VSV8U38TPrrhMenYSXZGU4N8Q5J1XYEjc4JKr8Dj1BtvhCjNTRxPimrfCN4T", "zpub6svdUH71uTR9YXumEJroNo51GfHdASMmzKFafeBr51yEzf4gj4cPBafQDjk18AGTZSfhXi8uMuuZKpSdmzHjZDTDCVK3KjVYj1NKUTFfCkk", "tpub6EFxzN6ZgMCZ1PxeRigmAhm2UBGzXtZNgznCEaWuEt9efBpJwAXFA4ZckBdR1pdMQ1pBgsey7ebjToZ5gYXveftB3zwoQ8NvEkimvyaz34i" ] }, "PublicKeyLabel": { "description": "User-friendly label for the public key.", "maxLength": 32, "minLength": 1, "type": "string", "example": "Main Bitcoin Wallet" }, "PublicKeyDerivationPath": { "description": "HD derivation path in BIP-44 format. Supports both account-level (`m/purpose'/coin_type'/account'`)\nand change-level (`m/purpose'/coin_type'/account'/change`) paths.\n\nAccount-level paths (depth-3) represent HD wallet accounts and cannot derive addresses directly —\nuse the children endpoint to create change-level child keys first.\n", "pattern": "^m/(44|49|84|86)'/\\d+'/\\d+'(/\\d+)?$", "type": "string", "examples": [ "m/44'/0'/0'/0", "m/44'/60'/0'/0", "m/44'/137'/0'/0", "m/49'/0'/0'/0", "m/84'/0'/0'", "m/84'/0'/0'/0", "m/86'/0'/0'/0" ] }, "PublicKey": { "type": "object", "description": "HD public key used to derive child addresses.\n", "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "value": { "$ref": "#/components/schemas/PublicKeyValue" }, "label": { "$ref": "#/components/schemas/PublicKeyLabel" }, "derivation_path": { "$ref": "#/components/schemas/PublicKeyDerivationPath" }, "children": { "description": "Child keys derived from this account-level key. Present only for account-level keys (depth-3).\nEach child represents an external (change=0) or internal (change=1) chain.\n", "type": "array", "items": { "$ref": "#/components/schemas/PublicKey" } }, "created_at": { "$ref": "#/components/schemas/CreatedAt" }, "updated_at": { "$ref": "#/components/schemas/UpdatedAt" } }, "required": [ "id", "value", "label", "derivation_path", "created_at", "updated_at" ], "example": { "id": "550e8400-e29b-41d4-a716-446655440000", "value": "xpub6EFxzN6ZgMCZ1PxeRigmAhm2UBGzXtZNgznCEaWuEt9efBpJwAXFA4ZckBdR1pdMQ1pBgsey7ebjToZ5gYXveftB3zwoQ8NvEkimvyaz34i", "label": "Main Bitcoin Wallet", "derivation_path": "m/84'/0'/0'", "children": [ { "id": "660e8400-e29b-41d4-a716-446655440001", "value": "xpub6F7C1ZtQ411zykk6KTEoQMqfNdxiSA4uxAwAoqFanijnAavqQvVmh5zZCH6Swhdbzt2HuMRLx4chEVRZu9ic4Cnkkq5AsQcmjeMASk6FLqf", "label": "external", "derivation_path": "m/84'/0'/0'/0", "created_at": "2025-01-15T12:00:00Z", "updated_at": "2025-01-15T12:00:00Z" } ], "created_at": "2025-01-15T12:00:00Z", "updated_at": "2025-01-15T12:00:00Z" } }, "CreatedAt": { "description": "Timestamp when the resource was created.", "format": "date-time", "type": "string", "example": "2024-01-15T10:30:00Z" }, "UpdatedAt": { "description": "Timestamp when the resource was last updated.", "format": "date-time", "type": "string", "example": "2024-01-15T10:30:00Z" }, "PreconditionProblem": { "type": "object", "description": "Problem details for precondition failed errors (422 Unprocessable Entity).\n\nStandard problem response when request cannot be processed due to failed\nbusiness rule validation following [RFC 7807](https://tools.ietf.org/rfc/rfc7807.txt).\n", "required": [ "type", "title", "status", "code" ], "properties": { "type": { "$ref": "#/components/schemas/ProblemType", "example": "https://docs.vilna.io/apis/problems/precondition-failed" }, "title": { "$ref": "#/components/schemas/ProblemTitle", "example": "Precondition Failed" }, "status": { "$ref": "#/components/schemas/ProblemStatus", "example": 422 }, "detail": { "$ref": "#/components/schemas/ProblemDetail", "example": "The request cannot be processed due to failed business rule validation" }, "instance": { "$ref": "#/components/schemas/ProblemInstance" }, "code": { "$ref": "#/components/schemas/ProblemCode", "example": "simulation.failed" }, "fields": { "type": "array", "description": "List of fields that failed precondition validation", "items": { "type": "object", "required": [ "name", "reason" ], "properties": { "name": { "type": "string", "description": "The name of the field that failed validation", "example": "status" }, "reason": { "type": "string", "description": "Why the precondition failed for this field", "example": "Cannot transition from archived to active state" } } } } } }, "PublicKeyChildChange": { "description": "BIP-44 change index for child key derivation.\n`0` = external chain (receiving addresses), `1` = internal chain (change addresses).\n", "type": "integer", "enum": [ 0, 1 ], "x-enumDescriptions": { "0": "External chain (receiving addresses)", "1": "Internal chain (change addresses)" }, "example": 0 }, "AddressFormat": { "description": "Blockchain address format that determines how the address should be interpreted and validated.", "enum": [ "evm", "solana", "tron", "p2pkh", "p2sh", "p2wpkh", "p2wsh", "p2tr", "p2pkh-testnet", "p2sh-testnet", "p2wpkh-testnet", "p2wsh-testnet", "p2tr-testnet" ], "x-enumDescriptions": { "evm": "EVM-compatible address (Ethereum, BSC, Polygon, Arbitrum). Format: 0x + 40 hex chars. Normalized to EIP-55 checksum on import.", "solana": "Solana address. Format: Base58 encoded, 32-44 characters.", "tron": "Tron address. Format: Base58 encoded, starts with T.", "p2pkh": "Pay-to-Public-Key-Hash (Legacy). Starts with 1.", "p2sh": "Pay-to-Script-Hash. Starts with 3.", "p2wpkh": "Pay-to-Witness-Public-Key-Hash (Native SegWit). Starts with bc1q, 42 characters.", "p2wsh": "Pay-to-Witness-Script-Hash (Native SegWit). Starts with bc1q, 62 characters.", "p2tr": "Pay-to-Taproot (BIP-341). Starts with bc1p, 62 characters.", "p2pkh-testnet": "Pay-to-Public-Key-Hash (Legacy testnet). Starts with m or n.", "p2sh-testnet": "Pay-to-Script-Hash (testnet). Starts with 2.", "p2wpkh-testnet": "Pay-to-Witness-Public-Key-Hash (Native SegWit testnet). Starts with tb1q, 42 characters.", "p2wsh-testnet": "Pay-to-Witness-Script-Hash (Native SegWit testnet). Starts with tb1q, 62 characters.", "p2tr-testnet": "Pay-to-Taproot (BIP-341 testnet). Starts with tb1p, 62 characters." }, "example": "p2wpkh", "type": "string" }, "AddressValue": { "description": "Blockchain address in its native format.\n\n**Format by network**:\n- **EVM**: `0x` + 40 hex chars (normalized to [EIP-55](https://eips.ethereum.org/EIPS/eip-55) checksum on import)\n- **Bitcoin**: P2PKH (1...), P2SH (3...), P2WPKH (bc1...)\n- **Solana**: Base58, 32-44 chars\n- **Tron**: Base58, starts with `T`\n", "maxLength": 128, "minLength": 1, "type": "string", "pattern": "^[a-zA-Z0-9]+$", "example": "0x8521E8b15eCEF4D4269Fded3E6694225E096959E" }, "AddressLabel": { "description": "User-friendly label for the address.", "maxLength": 32, "type": "string", "example": "user_deposit_wallet" }, "AddressKind": { "description": "Kind of address.", "enum": [ "hd", "external" ], "x-enumDescriptions": { "hd": "HD (Hierarchical Deterministic) address derived from an extended public key.", "external": "External address imported directly without derivation." }, "example": "hd", "type": "string" }, "AddressMeta": { "type": "object", "description": "Optional key-value pairs attached to the address for tracking user associations,\nsource information, or custom application data.\nTotal size of all keys and values combined must not exceed 1000 characters.\n", "additionalProperties": { "type": "string" }, "example": { "user_id": "12345", "source": "exchange", "category": "trading" } }, "Address": { "type": "object", "description": "Blockchain address that can be monitored for transactions.", "properties": { "value": { "$ref": "#/components/schemas/AddressValue" }, "format": { "$ref": "#/components/schemas/AddressFormat" }, "label": { "$ref": "#/components/schemas/AddressLabel" }, "kind": { "$ref": "#/components/schemas/AddressKind" }, "meta": { "$ref": "#/components/schemas/AddressMeta" }, "tag_ids": { "type": "array", "description": "IDs of the address tags assigned to this address. The full tag for each ID is included in `references.address_tags`.", "items": { "$ref": "#/components/schemas/UUID" } }, "created_at": { "$ref": "#/components/schemas/CreatedAt" }, "updated_at": { "$ref": "#/components/schemas/UpdatedAt" } }, "required": [ "value", "format", "kind", "tag_ids", "created_at", "updated_at" ], "example": { "value": "0x8521E8b15eCEF4D4269Fded3E6694225E096959E", "format": "evm", "label": "cold_wallet", "kind": "external", "tag_ids": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ], "meta": { "source": "binance", "type": "withdrawal" }, "created_at": "2025-07-03T14:20:00Z", "updated_at": "2025-07-03T14:20:00Z" } }, "HDAddress": { "allOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "hd" ] }, "public_key_id": { "$ref": "#/components/schemas/UUID", "description": "ID of the public key used to derive this HD address." }, "derivation_index": { "type": "integer", "format": "uint32", "minimum": 0, "description": "Index used for address derivation from the public key.", "example": 0 } }, "required": [ "kind", "public_key_id", "derivation_index" ] } ], "description": "HD address derived from a public key using [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki)/[BIP44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki)/[BIP49](https://github.com/bitcoin/bips/blob/master/bip-0049.mediawiki)/[BIP84](https://github.com/bitcoin/bips/blob/master/bip-0084.mediawiki) standards.\n\nAddress type depends on BIP standard:\n- BIP44: Legacy P2PKH\n- BIP49: SegWit P2SH-P2WPKH\n- BIP84: Native SegWit P2WPKH\n", "example": { "value": "bc1q8faxe8g4u2v67qfwf9d8xhyl5tkkkphvet6r08", "format": "p2wpkh", "label": "user_45_deposit", "kind": "hd", "public_key_id": "123e4567-e89b-12d3-a456-426614174000", "derivation_index": 0, "tag_ids": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ], "meta": { "user_id": "45", "purpose": "deposit" }, "created_at": "2025-07-03T12:45:00Z", "updated_at": "2025-07-03T13:15:22Z" } }, "AddressTagName": { "type": "string", "description": "Display name for the address tag.", "minLength": 1, "maxLength": 32, "example": "Hot Wallets" }, "AddressTag": { "type": "object", "description": "A named collection of addresses within a project.", "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "name": { "$ref": "#/components/schemas/AddressTagName" }, "created_at": { "$ref": "#/components/schemas/CreatedAt" }, "updated_at": { "$ref": "#/components/schemas/UpdatedAt" } }, "required": [ "id", "name", "created_at", "updated_at" ] }, "AddressReferences": { "type": "object", "description": "Related objects included in the response, keyed by ID.", "properties": { "public_keys": { "type": "object", "description": "Map of public keys indexed by their UUID ID.", "propertyNames": { "$ref": "#/components/schemas/UUID" }, "additionalProperties": { "$ref": "#/components/schemas/PublicKey" } }, "address_tags": { "type": "object", "description": "Map of address tags indexed by their UUID ID.", "propertyNames": { "$ref": "#/components/schemas/UUID" }, "additionalProperties": { "$ref": "#/components/schemas/AddressTag" } } }, "required": [ "public_keys", "address_tags" ], "example": { "public_keys": {}, "address_tags": {} } }, "ChainFamilyForGeneration": { "description": "Chain family for HD address generation. Solana is not supported for HD address generation from public keys.\n", "enum": [ "evm", "bitcoin", "tron" ], "x-enumDescriptions": { "evm": "Ethereum Virtual Machine-based blockchains (Ethereum, BSC, Polygon, Arbitrum, etc.).", "bitcoin": "Bitcoin and Bitcoin-compatible networks.", "tron": "Tron blockchain ecosystem." }, "example": "evm", "type": "string" }, "ExternalAddress": { "allOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "external" ] } }, "required": [ "kind" ] } ], "description": "External address imported for tracking.\nNot derived from a public key, used for watching external wallets.\n", "example": { "value": "0xCa79F73628E5D46Cc2c0F6CcD3a3F934d3cE66B7", "format": "evm", "label": "cold_wallet", "kind": "external", "tag_ids": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ], "meta": { "source": "binance", "type": "withdrawal" }, "created_at": "2025-07-03T14:20:00Z", "updated_at": "2025-07-03T14:20:00Z" } }, "AddressUnion": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/HDAddress" } ], "type": "object", "properties": { "kind": { "type": "string", "enum": [ "hd" ] } }, "required": [ "kind" ] }, { "allOf": [ { "$ref": "#/components/schemas/ExternalAddress" } ], "type": "object", "properties": { "kind": { "type": "string", "enum": [ "external" ] } }, "required": [ "kind" ] } ], "discriminator": { "propertyName": "kind", "mapping": { "hd": "#/components/schemas/HDAddress", "external": "#/components/schemas/ExternalAddress" } } }, "ConflictProblem": { "type": "object", "description": "Problem details for conflict errors (409 Conflict).\n\nStandard problem response when request conflicts with current server state\nfollowing [RFC 7807](https://tools.ietf.org/rfc/rfc7807.txt).\n", "required": [ "type", "title", "status", "code" ], "properties": { "type": { "$ref": "#/components/schemas/ProblemType", "example": "https://docs.vilna.io/apis/problems/conflict" }, "title": { "$ref": "#/components/schemas/ProblemTitle", "example": "Conflict" }, "status": { "$ref": "#/components/schemas/ProblemStatus", "example": 409 }, "detail": { "$ref": "#/components/schemas/ProblemDetail", "example": "Resource already exists with the same identifier" }, "instance": { "$ref": "#/components/schemas/ProblemInstance" }, "code": { "$ref": "#/components/schemas/ProblemCode", "example": "invoice.address_occupied" } } }, "ResolveAddressFormat": { "description": "Address format for resolving an address from a public key. Restricted subset of AddressFormat — excludes p2wsh/p2wsh-testnet (script-based formats that cannot be derived from a single public key).\n", "type": "string", "enum": [ "evm", "tron", "solana", "p2pkh", "p2sh", "p2wpkh", "p2pkh-testnet", "p2sh-testnet", "p2wpkh-testnet" ], "x-enumDescriptions": { "evm": "EVM-compatible address (Ethereum, BSC, Polygon, Arbitrum). Input: hex secp256k1 public key. Output normalized to EIP-55 checksum.", "tron": "Tron address. Input: hex secp256k1 public key.", "solana": "Solana address. Input: base58 ed25519 public key.", "p2pkh": "Pay-to-Public-Key-Hash (Legacy). Input: hex secp256k1 public key.", "p2sh": "Pay-to-Script-Hash (Nested SegWit). Input: hex secp256k1 public key.", "p2wpkh": "Pay-to-Witness-Public-Key-Hash (Native SegWit). Input: hex secp256k1 public key.", "p2pkh-testnet": "Pay-to-Public-Key-Hash (Legacy testnet). Input: hex secp256k1 public key.", "p2sh-testnet": "Pay-to-Script-Hash (testnet). Input: hex secp256k1 public key.", "p2wpkh-testnet": "Pay-to-Witness-Public-Key-Hash (Native SegWit testnet). Input: hex secp256k1 public key." }, "example": "evm" }, "AssetGID": { "description": "Global asset identifier in [CAIP-19](https://chainagnostic.org/CAIPs/caip-19) format.\n\nFormat: `{chain_gid}/{asset_path}`\n\n**Examples**:\n- `eip155:1/slip44:60` — ETH on Ethereum\n- `eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7` — USDT on Ethereum\n- `eip155:56/bep20:0x55d398326f99059fF775485246999027B3197955` — USDT on BNB Smart Chain\n- `tron:0x2b6653dc/trc20:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` — USDT on Tron\n- `eip155:137/erc20:0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174` — USDC on Polygon\n", "pattern": "^[-a-zA-Z0-9]{1,32}:[-a-zA-Z0-9]{1,64}/[-a-zA-Z0-9]{1,64}:[-a-zA-Z0-9]{1,128}$", "type": "string", "example": "eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7" }, "AmountInBaseUnits": { "type": "string", "pattern": "^[0-9]+$", "description": "Amount in the smallest asset unit.", "examples": [ "1000000000000000000", "1000000000", "500000", "1" ] }, "AmountFormatted": { "type": "string", "description": "Human-readable amount.", "examples": [ "1.0", "1000.5", "0.001", "42.123456" ] }, "Amount": { "type": "object", "description": "Asset amount in base units, plus a human-readable value when we know\nthe token's decimals.\n", "properties": { "base": { "$ref": "#/components/schemas/AmountInBaseUnits" }, "formatted": { "$ref": "#/components/schemas/AmountFormatted" } }, "required": [ "base" ], "example": { "base": "1000000000", "formatted": "1.0" } }, "BalanceItem": { "type": "object", "description": "Current balance of a specific asset held by an address.\n", "properties": { "address": { "$ref": "#/components/schemas/AddressValue" }, "asset_gid": { "$ref": "#/components/schemas/AssetGID" }, "amount": { "$ref": "#/components/schemas/Amount" } }, "required": [ "address", "asset_gid", "amount" ], "example": { "address": "0x742d35cc6634c0532925a3b8d1e1d78d8E15e5c4", "asset_gid": "eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7", "amount": { "base": "1000000", "formatted": "1.0" } } }, "TokenDecimals": { "description": "Number of decimal places for the token (e.g., 6 for USDT, 18 for ETH).", "maximum": 18, "minimum": 0, "type": "integer", "examples": [ 18, 6, 8, 0 ] }, "TokenName": { "description": "Full token name (e.g., \"Tether USD\", \"Ethereum\", \"Binance Coin\").", "type": "string", "minLength": 1, "maxLength": 32, "examples": [ "Tether USD", "Ethereum", "Binance Coin", "USD Coin" ] }, "TokenSymbol": { "description": "Token symbol (e.g., \"USDT\", \"ETH\", \"BNB\").", "type": "string", "minLength": 1, "maxLength": 8, "examples": [ "USDT", "ETH", "BNB", "USDC" ] }, "Token": { "title": "Token", "type": "object", "description": "Fungible blockchain asset metadata.\n", "properties": { "gid": { "$ref": "#/components/schemas/AssetGID" }, "decimals": { "$ref": "#/components/schemas/TokenDecimals" }, "name": { "$ref": "#/components/schemas/TokenName" }, "symbol": { "$ref": "#/components/schemas/TokenSymbol" } }, "required": [ "gid", "decimals", "name", "symbol" ], "example": { "gid": "eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7", "symbol": "USDT", "name": "Tether USD", "decimals": 6 } }, "BalanceReferences": { "type": "object", "description": "Related objects included in the response, keyed by ID.", "properties": { "tokens": { "type": "object", "description": "Map of tokens indexed by their CAIP-19 Asset GID.", "propertyNames": { "$ref": "#/components/schemas/AssetGID" }, "additionalProperties": { "$ref": "#/components/schemas/Token" } }, "blockchains": { "type": "object", "description": "Map of blockchains indexed by their CAIP-2 Chain GID.", "propertyNames": { "$ref": "#/components/schemas/ChainGID" }, "additionalProperties": { "$ref": "#/components/schemas/Blockchain" } }, "addresses": { "type": "object", "description": "Map of tracked addresses to labels. Presence in this map means the address is tracked; value is label or `null`.", "propertyNames": { "$ref": "#/components/schemas/AddressValue" }, "additionalProperties": { "oneOf": [ { "$ref": "#/components/schemas/AddressLabel" }, { "type": "null" } ] } } } }, "TransactionHash": { "type": "string", "description": "Transaction hash identifier on the blockchain.", "example": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" }, "BlockNumber": { "type": "integer", "format": "uint64", "minimum": 0, "description": "Block number/height on the blockchain.", "example": 18500000 }, "BitcoinUTXOItem": { "type": "object", "description": "Unspent Bitcoin output held by an address.", "properties": { "chain_gid": { "$ref": "#/components/schemas/ChainGID" }, "address": { "$ref": "#/components/schemas/AddressValue" }, "hash": { "$ref": "#/components/schemas/TransactionHash" }, "vout_index": { "type": "integer", "format": "uint32", "minimum": 0, "description": "Output index within the transaction.", "example": 0 }, "amount": { "$ref": "#/components/schemas/Amount" }, "script_pubkey_hex": { "type": "string", "description": "Hex-encoded locking script of the address.", "pattern": "^[0-9a-f]+$", "example": "0014751e76e8199196d454941c45d1b3a323f1433bd6" }, "block_number": { "$ref": "#/components/schemas/BlockNumber" } }, "required": [ "chain_gid", "address", "hash", "vout_index", "amount", "script_pubkey_hex", "block_number" ] }, "BitcoinUTXOReferences": { "type": "object", "description": "Related objects included in the response, keyed by ID.", "properties": { "blockchains": { "type": "object", "description": "Map of blockchains indexed by their CAIP-2 Chain GID.", "propertyNames": { "$ref": "#/components/schemas/ChainGID" }, "additionalProperties": { "$ref": "#/components/schemas/Blockchain" } } }, "required": [ "blockchains" ] }, "AssetPath": { "type": "string", "description": "Asset identifier in [CAIP-19](https://chainagnostic.org/CAIPs/caip-19) format.\n\nFormat: `{namespace}:{reference}`\n- **namespace**: Asset type (3-8 chars, lowercase)\n- **reference**: Asset-specific identifier (1-128 chars)\n\n**Examples**:\n- `slip44:60` — Ethereum native token\n- `erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F` — DAI token\n- `erc721:0x06012c8cf97BEaD5deAe237070F9587f8E7A266d` — CryptoKitties NFT\n- `trc20:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` — USDT on Tron\n- `bep20:0x55d398326f99059fF775485246999027B3197955` — USDT on BNB Smart Chain\n", "pattern": "^[a-z0-9]{3,8}:[-.%a-zA-Z0-9]{1,128}$", "example": "erc20:0x6B175474E89094C44Da98b954EedeAC495271d0F" }, "ActivityDirection": { "type": "string", "description": "Direction of the asset movement relative to the tracked address.", "enum": [ "in", "out" ], "x-enumDescriptions": { "in": "Balance increased (received assets).", "out": "Balance decreased (sent assets or paid fees)." }, "examples": [ "in", "out" ] }, "DeltaInBaseUnits": { "type": "string", "pattern": "^-?[0-9]+$", "description": "Signed amount in the smallest asset unit.", "examples": [ "1000000000000000000", "-1000000000", "500000", "-1" ] }, "DeltaFormatted": { "type": "string", "description": "Human-readable signed amount.", "examples": [ "+1.0", "-1000.5", "+0.001", "-42.123456" ] }, "Delta": { "type": "object", "description": "Signed balance change in base units, plus a human-readable value\nwhen we know the token's decimals.\n", "properties": { "base": { "$ref": "#/components/schemas/DeltaInBaseUnits" }, "formatted": { "$ref": "#/components/schemas/DeltaFormatted" } }, "required": [ "base" ], "examples": [ { "base": "1000000000000000000", "formatted": "+1.0" }, { "base": "-500000000", "formatted": "-0.5" } ] }, "ActivityItem": { "type": "object", "description": "Asset balance change for an address caused by a transaction.\n", "properties": { "chain_gid": { "$ref": "#/components/schemas/ChainGID" }, "hash": { "$ref": "#/components/schemas/TransactionHash" }, "address": { "$ref": "#/components/schemas/AddressValue" }, "asset_gid": { "$ref": "#/components/schemas/AssetGID" }, "direction": { "$ref": "#/components/schemas/ActivityDirection" }, "delta": { "$ref": "#/components/schemas/Delta" }, "created_at": { "$ref": "#/components/schemas/CreatedAt" } }, "required": [ "chain_gid", "hash", "address", "asset_gid", "direction", "delta", "created_at" ], "example": { "chain_gid": "eip155:1", "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "address": "0x742d35cc6634c0532925a3b8d1e1d78d8E15e5c4", "asset_gid": "eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7", "direction": "out", "delta": { "base": "-1000000", "formatted": "-1.0" }, "created_at": "2024-01-15T10:30:00Z" } }, "ActivityReferences": { "type": "object", "description": "Related objects included in the response, keyed by ID.", "properties": { "tokens": { "type": "object", "description": "Map of tokens indexed by their CAIP-19 Asset GID.", "propertyNames": { "$ref": "#/components/schemas/AssetGID" }, "additionalProperties": { "$ref": "#/components/schemas/Token" } }, "blockchains": { "type": "object", "description": "Map of blockchains indexed by their CAIP-2 Chain GID.", "propertyNames": { "$ref": "#/components/schemas/ChainGID" }, "additionalProperties": { "$ref": "#/components/schemas/Blockchain" } }, "addresses": { "type": "object", "description": "Map of tracked addresses to labels. Presence in this map means the address is tracked; value is label or `null`.", "propertyNames": { "$ref": "#/components/schemas/AddressValue" }, "additionalProperties": { "oneOf": [ { "$ref": "#/components/schemas/AddressLabel" }, { "type": "null" } ] } } } }, "TransactionSummary": { "type": "object", "description": "Core transaction metadata.\n", "properties": { "chain_gid": { "$ref": "#/components/schemas/ChainGID" }, "hash": { "$ref": "#/components/schemas/TransactionHash" }, "block_number": { "$ref": "#/components/schemas/BlockNumber" }, "is_success": { "type": "boolean", "description": "Transaction execution status." }, "confirmed_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the transaction reached required confirmations. Null if the transaction is not yet confirmed." }, "created_at": { "$ref": "#/components/schemas/CreatedAt" } }, "required": [ "chain_gid", "hash", "block_number", "is_success", "confirmed_at", "created_at" ], "example": { "chain_gid": "eip155:1", "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "block_number": 18500000, "is_success": true, "confirmed_at": null, "created_at": "2024-01-15T10:30:00Z" } }, "TransactionReferences": { "type": "object", "description": "Related objects included in the response, keyed by ID.", "properties": { "tokens": { "type": "object", "description": "Map of tokens indexed by their CAIP-19 Asset GID.", "propertyNames": { "$ref": "#/components/schemas/AssetGID" }, "additionalProperties": { "$ref": "#/components/schemas/Token" } }, "blockchains": { "type": "object", "description": "Map of blockchains indexed by their CAIP-2 Chain GID.", "propertyNames": { "$ref": "#/components/schemas/ChainGID" }, "additionalProperties": { "$ref": "#/components/schemas/Blockchain" } }, "addresses": { "type": "object", "description": "Map of tracked addresses to labels. Presence in this map means the address is tracked; value is label or `null`.", "propertyNames": { "$ref": "#/components/schemas/AddressValue" }, "additionalProperties": { "oneOf": [ { "$ref": "#/components/schemas/AddressLabel" }, { "type": "null" } ] } } } }, "EventKind": { "type": "string", "description": "Type of canonical event.", "enum": [ "transfer", "utxo_transfer", "fee", "approval", "call", "contract_create" ], "x-enumDescriptions": { "transfer": "Asset transfer between addresses.", "utxo_transfer": "UTXO-based transfer with full input/output visibility (Bitcoin, Litecoin).", "fee": "Transaction fee paid to the network.", "approval": "Token spending approval granted to a third-party address.", "call": "Smart contract function call.", "contract_create": "New smart contract deployment." }, "examples": [ "transfer", "fee", "approval" ] }, "TransferDataSource": { "type": "string", "description": "Source type of the transfer.", "enum": [ "native", "contract", "internal" ], "x-enumDescriptions": { "native": "Native coin transfer (e.g. ETH, BTC, SOL).", "contract": "Token transfer via smart contract event (e.g. ERC-20 Transfer).", "internal": "Internal transaction (e.g. EVM internal call with value)." }, "examples": [ "native", "contract", "internal" ] }, "TransferEventData": { "type": "object", "description": "Asset transfer event data.", "properties": { "kind": { "type": "string", "enum": [ "transfer" ] }, "asset_gid": { "$ref": "#/components/schemas/AssetGID" }, "from": { "$ref": "#/components/schemas/AddressValue", "description": "Sender address." }, "to": { "$ref": "#/components/schemas/AddressValue", "description": "Recipient address." }, "amount": { "$ref": "#/components/schemas/Amount" }, "token_id": { "type": "string", "description": "Token identifier for NFTs (ERC-721/ERC-1155)." }, "source": { "$ref": "#/components/schemas/TransferDataSource" } }, "required": [ "kind", "asset_gid", "from", "to", "amount", "source" ], "example": { "kind": "transfer", "asset_gid": "eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7", "from": "0x742d35cc6634c0532925a3b8d1e1d78d8E15e5c4", "to": "0x95212290dd7278aa3ddd389cc1e1d165cc4bafe5", "amount": { "base": "1000000", "formatted": "1.0" }, "source": "contract" } }, "UTXOEntry": { "type": "object", "description": "A single input or output in a UTXO transaction.", "properties": { "address": { "$ref": "#/components/schemas/AddressValue", "description": "Bitcoin address (P2PKH, P2SH, P2WPKH, P2WSH, P2TR)." }, "amount": { "$ref": "#/components/schemas/Amount", "description": "For inputs: the prevout value (amount the address contributed to the transaction pool).\nFor outputs: the value sent to this address.\n" }, "index": { "type": "integer", "description": "Position in the transaction (vin index for inputs, vout index for outputs).", "minimum": 0 } }, "required": [ "address", "amount", "index" ], "example": { "address": "bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4", "amount": { "base": "50000", "formatted": "0.0005" }, "index": 0 } }, "UTXOTransferEventData": { "type": "object", "description": "UTXO-based transfer event data (Bitcoin, Litecoin, etc.).\nCaptures all transaction inputs (funding sources) and outputs (destinations).\nUnlike `TransferEventData`, there is no 1:1 sender→recipient mapping —\nall inputs pool into a shared sum from which outputs are drawn.\n", "properties": { "kind": { "type": "string", "enum": [ "utxo_transfer" ] }, "asset_gid": { "$ref": "#/components/schemas/AssetGID" }, "inputs": { "type": "array", "description": "All transaction inputs (funding sources with prevout data).", "items": { "$ref": "#/components/schemas/UTXOEntry" } }, "outputs": { "type": "array", "description": "All transaction outputs (destinations).", "items": { "$ref": "#/components/schemas/UTXOEntry" } }, "fee": { "$ref": "#/components/schemas/Amount", "description": "Transaction fee (sum of inputs minus sum of outputs)." } }, "required": [ "kind", "asset_gid", "inputs", "outputs", "fee" ], "example": { "kind": "utxo_transfer", "asset_gid": "bip122:000000000019d6689c085ae165831e93/slip44:0", "inputs": [ { "address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq", "amount": { "base": "50000", "formatted": "0.0005" }, "index": 0 }, { "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa", "amount": { "base": "30000", "formatted": "0.0003" }, "index": 1 } ], "outputs": [ { "address": "bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4", "amount": { "base": "70000", "formatted": "0.0007" }, "index": 0 }, { "address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq", "amount": { "base": "8000", "formatted": "0.00008" }, "index": 1 } ], "fee": { "base": "2000", "formatted": "0.00002" } } }, "FeeEventData": { "type": "object", "description": "Network fee payment event data.", "properties": { "kind": { "type": "string", "enum": [ "fee" ] }, "asset_gid": { "$ref": "#/components/schemas/AssetGID" }, "payer": { "$ref": "#/components/schemas/AddressValue", "description": "Address that paid the fee." }, "amount": { "$ref": "#/components/schemas/Amount" } }, "required": [ "kind", "asset_gid", "payer", "amount" ], "example": { "kind": "fee", "asset_gid": "eip155:1/slip44:60", "payer": "0x742d35cc6634c0532925a3b8d1e1d78d8E15e5c4", "amount": { "base": "21000000000000000", "formatted": "0.021" } } }, "ApprovalEventData": { "type": "object", "description": "Token allowance/permission update event data.", "properties": { "kind": { "type": "string", "enum": [ "approval" ] }, "asset_gid": { "$ref": "#/components/schemas/AssetGID" }, "owner": { "$ref": "#/components/schemas/AddressValue", "description": "Token owner address." }, "spender": { "$ref": "#/components/schemas/AddressValue", "description": "Address granted spending permission." }, "amount": { "$ref": "#/components/schemas/Amount" }, "token_id": { "type": "string", "description": "Token identifier for NFT approvals (ERC-721/ERC-1155)." } }, "required": [ "kind", "asset_gid", "owner", "spender", "amount" ], "example": { "kind": "approval", "asset_gid": "eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7", "owner": "0x742d35cc6634c0532925a3b8d1e1d78d8E15e5c4", "spender": "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984", "amount": { "base": "1000000", "formatted": "1.0" } } }, "CallEventData": { "type": "object", "description": "Unclassified contract interaction event data.", "properties": { "kind": { "type": "string", "enum": [ "call" ] }, "caller": { "$ref": "#/components/schemas/AddressValue", "description": "Address that initiated the call." }, "target": { "$ref": "#/components/schemas/AddressValue", "description": "Called contract address." } }, "required": [ "kind", "caller", "target" ], "example": { "kind": "call", "caller": "0x742d35cc6634c0532925a3b8d1e1d78d8E15e5c4", "target": "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984" } }, "ContractCreateEventData": { "type": "object", "description": "Contract creation/deployment event data.", "properties": { "kind": { "type": "string", "enum": [ "contract_create" ] }, "creator": { "$ref": "#/components/schemas/AddressValue", "description": "Address that deployed the contract." }, "created_address": { "$ref": "#/components/schemas/AddressValue", "description": "Deployed contract address." } }, "required": [ "kind", "creator", "created_address" ], "example": { "kind": "contract_create", "creator": "0x742d35cc6634c0532925a3b8d1e1d78d8E15e5c4", "created_address": "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984" } }, "Event": { "type": "object", "description": "Canonical blockchain event within a transaction.\nEach event has a `kind` (transfer, utxo_transfer, fee, approval, call, contract_create)\nand a corresponding data payload. Identified by `sequence` within the transaction, not by ID.\n", "properties": { "hash": { "$ref": "#/components/schemas/TransactionHash" }, "sequence": { "type": "integer", "description": "Event position within the transaction (0-based).", "minimum": 0 }, "kind": { "$ref": "#/components/schemas/EventKind" }, "data": { "oneOf": [ { "$ref": "#/components/schemas/TransferEventData" }, { "$ref": "#/components/schemas/UTXOTransferEventData" }, { "$ref": "#/components/schemas/FeeEventData" }, { "$ref": "#/components/schemas/ApprovalEventData" }, { "$ref": "#/components/schemas/CallEventData" }, { "$ref": "#/components/schemas/ContractCreateEventData" } ], "discriminator": { "propertyName": "kind", "mapping": { "transfer": "#/components/schemas/TransferEventData", "utxo_transfer": "#/components/schemas/UTXOTransferEventData", "fee": "#/components/schemas/FeeEventData", "approval": "#/components/schemas/ApprovalEventData", "call": "#/components/schemas/CallEventData", "contract_create": "#/components/schemas/ContractCreateEventData" } } } }, "required": [ "hash", "sequence", "kind", "data" ], "example": { "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "sequence": 0, "kind": "transfer", "data": { "kind": "transfer", "asset_gid": "eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7", "from": "0x742d35cc6634c0532925a3b8d1e1d78d8E15e5c4", "to": "0x95212290dd7278aa3ddd389cc1e1d165cc4bafe5", "amount": { "base": "1000000", "formatted": "1.0" }, "source": "contract" } } }, "Transaction": { "type": "object", "description": "Transaction details with canonical events and balance changes.\n", "allOf": [ { "$ref": "#/components/schemas/TransactionSummary" }, { "type": "object", "properties": { "events": { "type": "array", "description": "Canonical events ordered by sequence.", "items": { "$ref": "#/components/schemas/Event" } }, "activity": { "type": "array", "description": "Balance changes for tracked addresses.\n", "items": { "$ref": "#/components/schemas/ActivityItem" } } }, "required": [ "events", "activity" ] } ], "example": { "chain_gid": "eip155:1", "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "block_number": 18500000, "is_success": true, "confirmed_at": null, "created_at": "2024-01-15T10:30:00Z", "events": [ { "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "sequence": 0, "kind": "transfer", "data": { "kind": "transfer", "asset_gid": "eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7", "from": "0x742d35cc6634c0532925a3b8d1e1d78d8E15e5c4", "to": "0x95212290dd7278aa3ddd389cc1e1d165cc4bafe5", "amount": { "base": "1000000", "formatted": "1.0" }, "source": "contract" } }, { "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "sequence": 1, "kind": "fee", "data": { "kind": "fee", "asset_gid": "eip155:1/slip44:60", "payer": "0x742d35cc6634c0532925a3b8d1e1d78d8E15e5c4", "amount": { "base": "21000000000000000", "formatted": "0.021" } } } ], "activity": [ { "chain_gid": "eip155:1", "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "address": "0x742d35cc6634c0532925a3b8d1e1d78d8E15e5c4", "asset_gid": "eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7", "direction": "out", "delta": { "base": "-1000000", "formatted": "-1.0" }, "created_at": "2024-01-15T10:30:00Z" }, { "chain_gid": "eip155:1", "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "address": "0x742d35cc6634c0532925a3b8d1e1d78d8E15e5c4", "asset_gid": "eip155:1/slip44:60", "direction": "out", "delta": { "base": "-21000000000000000", "formatted": "-0.021" }, "created_at": "2024-01-15T10:30:00Z" } ] } }, "SimulationError": { "type": "object", "description": "Error details for a failed simulation.\n", "properties": { "code": { "type": "integer", "description": "Error code from the EVM execution.", "example": -32000 }, "message": { "type": "string", "description": "Human-readable error message.", "example": "execution reverted" }, "data": { "type": "string", "description": "Raw revert data (hex-encoded) for detailed error decoding.", "example": "0x08c379a00000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000001a4e6f7420656e6f75676820746f6b656e2062616c616e636500000000000000" } }, "required": [ "code", "message" ], "example": { "code": -32000, "message": "execution reverted", "data": "0x" } }, "SimulatedTransaction": { "type": "object", "description": "Predicted result of a simulated transaction.\n", "allOf": [ { "$ref": "#/components/schemas/TransactionSummary" }, { "type": "object", "properties": { "events": { "type": "array", "description": "Canonical events that would be emitted, ordered by sequence.", "items": { "$ref": "#/components/schemas/Event" } }, "activity": { "type": "array", "description": "Predicted balance changes for involved addresses.\n", "items": { "$ref": "#/components/schemas/ActivityItem" } }, "error": { "$ref": "#/components/schemas/SimulationError" } }, "required": [ "events", "activity" ] } ], "example": { "chain_gid": "eip155:1", "hash": "0x5ab3bd0e9411c0537ae0d4d277e2b88951ac0e4eef1e4ed1434b2e6b6ae677f7", "block_number": 24331622, "is_success": true, "confirmed_at": null, "created_at": "2025-01-15T10:30:00Z", "events": [ { "hash": "0x5ab3bd0e9411c0537ae0d4d277e2b88951ac0e4eef1e4ed1434b2e6b6ae677f7", "sequence": 0, "kind": "transfer", "data": { "kind": "transfer", "asset_gid": "eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7", "from": "0x974caa59e49682cda0ad2bbe82983419a2ecc400", "to": "0xd0930a8fc56fd94038250bb93dbac0e13da4eb99", "amount": { "base": "1000000", "formatted": "1.0" }, "source": "contract" } }, { "hash": "0x5ab3bd0e9411c0537ae0d4d277e2b88951ac0e4eef1e4ed1434b2e6b6ae677f7", "sequence": 1, "kind": "fee", "data": { "kind": "fee", "asset_gid": "eip155:1/slip44:60", "payer": "0x974caa59e49682cda0ad2bbe82983419a2ecc400", "amount": { "base": "1100877000000000", "formatted": "0.001100877" } } } ], "activity": [ { "chain_gid": "eip155:1", "hash": "0x5ab3bd0e9411c0537ae0d4d277e2b88951ac0e4eef1e4ed1434b2e6b6ae677f7", "address": "0x974caa59e49682cda0ad2bbe82983419a2ecc400", "asset_gid": "eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7", "direction": "out", "delta": { "base": "-1000000", "formatted": "-1.0" }, "created_at": "2025-01-15T10:30:00Z" }, { "chain_gid": "eip155:1", "hash": "0x5ab3bd0e9411c0537ae0d4d277e2b88951ac0e4eef1e4ed1434b2e6b6ae677f7", "address": "0xd0930a8fc56fd94038250bb93dbac0e13da4eb99", "asset_gid": "eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7", "direction": "in", "delta": { "base": "1000000", "formatted": "1.0" }, "created_at": "2025-01-15T10:30:00Z" }, { "chain_gid": "eip155:1", "hash": "0x5ab3bd0e9411c0537ae0d4d277e2b88951ac0e4eef1e4ed1434b2e6b6ae677f7", "address": "0x974caa59e49682cda0ad2bbe82983419a2ecc400", "asset_gid": "eip155:1/slip44:60", "direction": "out", "delta": { "base": "-1100877000000000", "formatted": "-0.001100877" }, "created_at": "2025-01-15T10:30:00Z" } ] } }, "InvoiceStatus": { "type": "string", "description": "Current status of the invoice.", "enum": [ "pending", "underpaid", "paid", "confirmed", "overpaid", "cancelled", "expired" ], "x-enumDescriptions": { "pending": "Waiting for payment, no transactions received.", "underpaid": "Partial payment received, amount below required.", "paid": "Full amount received, waiting for block confirmations.", "confirmed": "Payment confirmed with sufficient block confirmations.", "overpaid": "Received more than the requested amount.", "cancelled": "Cancelled by the merchant.", "expired": "Invoice has passed its payment deadline without receiving full payment." }, "example": "pending" }, "InvoiceSummary": { "type": "object", "description": "Compact invoice representation for list endpoints.\nUse GET /invoices/{invoice_id} for full details including status logs and transactions.\n", "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "address": { "$ref": "#/components/schemas/AddressValue" }, "asset_gid": { "$ref": "#/components/schemas/AssetGID" }, "amount": { "$ref": "#/components/schemas/AmountInBaseUnits" }, "received_amount": { "$ref": "#/components/schemas/AmountInBaseUnits" }, "status": { "$ref": "#/components/schemas/InvoiceStatus" }, "expires_at": { "type": "string", "format": "date-time", "description": "Deadline for payment.", "example": "2024-01-15T13:00:00Z" }, "metadata": { "type": "object", "description": "Optional key-value pairs for storing additional information about the invoice.", "additionalProperties": { "type": "string" }, "example": { "order_id": "1234", "customer": "john@example.com" } }, "created_at": { "$ref": "#/components/schemas/CreatedAt" }, "updated_at": { "$ref": "#/components/schemas/UpdatedAt" } }, "required": [ "id", "address", "asset_gid", "amount", "received_amount", "status", "expires_at", "metadata", "created_at", "updated_at" ], "example": { "id": "550e8400-e29b-41d4-a716-446655440000", "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18", "asset_gid": "eip155:56/bep20:0x55d398326f99059fF775485246999027B3197955", "amount": "42500000", "received_amount": "0", "status": "pending", "expires_at": "2024-01-15T13:00:00Z", "metadata": { "order_id": "1234" }, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z" } }, "InvoiceReferences": { "type": "object", "description": "Related objects included in the response, keyed by ID.", "properties": { "tokens": { "type": "object", "description": "Map of tokens indexed by their CAIP-19 Asset GID.", "propertyNames": { "$ref": "#/components/schemas/AssetGID" }, "additionalProperties": { "$ref": "#/components/schemas/Token" } }, "blockchains": { "type": "object", "description": "Map of blockchains indexed by their CAIP-2 Chain GID.", "propertyNames": { "$ref": "#/components/schemas/ChainGID" }, "additionalProperties": { "$ref": "#/components/schemas/Blockchain" } } }, "required": [ "tokens", "blockchains" ], "example": { "tokens": {}, "blockchains": {} } }, "InvoiceStatusLog": { "type": "object", "description": "A single status transition in the invoice lifecycle with optional comment.", "properties": { "status": { "$ref": "#/components/schemas/InvoiceStatus" }, "comment": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional comment explaining the status change (e.g. cancellation reason).", "example": "Cancelled by merchant" }, "changed_at": { "type": "string", "format": "date-time", "description": "When the status transition occurred.", "example": "2024-01-15T12:05:00Z" } }, "required": [ "status", "comment", "changed_at" ], "example": { "status": "cancelled", "comment": "Cancelled by merchant", "changed_at": "2024-01-15T12:05:00Z" } }, "InvoiceDeposit": { "type": "object", "description": "Individual token deposit received within a transaction.", "properties": { "asset_gid": { "$ref": "#/components/schemas/AssetGID" }, "amount": { "description": "Deposit amount in base units (smallest token denomination). Use the token metadata\nfrom the `references.tokens` map to format the value for display.\nIf the token is not in `references.tokens`, it is not tracked by the project.\n", "$ref": "#/components/schemas/AmountInBaseUnits" }, "is_matched": { "type": "boolean", "description": "Whether this deposit's token matches the invoice's expected token.", "example": true } }, "required": [ "asset_gid", "amount", "is_matched" ], "example": { "asset_gid": "eip155:56/bep20:0x55d398326f99059fF775485246999027B3197955", "amount": "42500000", "is_matched": true } }, "InvoiceTransaction": { "type": "object", "description": "Blockchain transaction detected on the invoice address.\nContains one or more deposits — individual token movements within this transaction.\nA failed transaction (is_success=false) is visible but does not count toward payment.\n", "properties": { "hash": { "$ref": "#/components/schemas/TransactionHash" }, "block_number": { "$ref": "#/components/schemas/BlockNumber" }, "is_success": { "type": "boolean", "description": "Whether the transaction executed successfully on-chain.", "example": true }, "detected_at": { "type": "string", "format": "date-time", "description": "When the transaction was first seen.", "example": "2024-01-15T12:05:00Z" }, "confirmed_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the transaction reached required confirmations. Null if not yet confirmed.", "example": "2024-01-15T12:15:00Z" }, "deposits": { "type": "array", "description": "Individual token deposits received within this transaction.", "items": { "$ref": "#/components/schemas/InvoiceDeposit" } } }, "required": [ "hash", "block_number", "is_success", "detected_at", "confirmed_at", "deposits" ], "example": { "hash": "0xabc123def456789012345678901234567890123456789012345678901234abcd", "block_number": 12345678, "is_success": true, "detected_at": "2024-01-15T12:05:00Z", "confirmed_at": "2024-01-15T12:15:00Z", "deposits": [ { "asset_gid": "eip155:56/bep20:0x55d398326f99059fF775485246999027B3197955", "amount": "42500000", "is_matched": true } ] } }, "Invoice": { "type": "object", "description": "Payment invoice. A request for crypto payment to a specific address for a specific token amount.\nThe invoice UUID is the access token — anyone with the UUID can view the invoice.\n", "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "address": { "$ref": "#/components/schemas/AddressValue" }, "asset_gid": { "$ref": "#/components/schemas/AssetGID" }, "amount": { "$ref": "#/components/schemas/AmountInBaseUnits" }, "received_amount": { "$ref": "#/components/schemas/AmountInBaseUnits" }, "status": { "$ref": "#/components/schemas/InvoiceStatus" }, "expires_at": { "type": "string", "format": "date-time", "description": "Deadline for payment.", "example": "2024-01-15T13:00:00Z" }, "metadata": { "type": "object", "description": "Optional key-value pairs for storing additional information about the invoice.", "additionalProperties": { "type": "string" }, "example": { "order_id": "1234", "customer": "john@example.com" } }, "created_at": { "$ref": "#/components/schemas/CreatedAt" }, "updated_at": { "$ref": "#/components/schemas/UpdatedAt" }, "status_logs": { "type": "array", "description": "Chronological log of invoice status transitions with optional comments.", "items": { "$ref": "#/components/schemas/InvoiceStatusLog" } }, "transactions": { "type": "array", "description": "Transactions detected on the invoice address since creation.", "items": { "$ref": "#/components/schemas/InvoiceTransaction" } } }, "required": [ "id", "address", "asset_gid", "amount", "received_amount", "status", "expires_at", "metadata", "created_at", "updated_at", "status_logs", "transactions" ], "example": { "id": "550e8400-e29b-41d4-a716-446655440000", "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18", "asset_gid": "eip155:56/bep20:0x55d398326f99059fF775485246999027B3197955", "amount": "42500000", "received_amount": "0", "status": "pending", "expires_at": "2024-01-15T13:00:00Z", "metadata": { "order_id": "1234" }, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z", "status_logs": [ { "status": "pending", "comment": null, "changed_at": "2024-01-15T10:30:00Z" } ], "transactions": [] } }, "PublicInvoiceStatusLog": { "type": "object", "description": "A single status transition in the invoice lifecycle.", "properties": { "status": { "$ref": "#/components/schemas/InvoiceStatus" }, "changed_at": { "type": "string", "format": "date-time", "description": "When the status transition occurred.", "example": "2024-01-15T12:05:00Z" } }, "required": [ "status", "changed_at" ], "example": { "status": "pending", "changed_at": "2024-01-15T12:00:00Z" } }, "PublicInvoice": { "type": "object", "description": "Public-facing invoice view for payers. Contains only information necessary\nfor payment — no internal IDs, no merchant notes, no metadata.\n", "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "status": { "$ref": "#/components/schemas/InvoiceStatus" }, "amount": { "$ref": "#/components/schemas/Amount" }, "received_amount": { "$ref": "#/components/schemas/Amount" }, "address": { "$ref": "#/components/schemas/AddressValue" }, "asset_gid": { "$ref": "#/components/schemas/AssetGID" }, "expires_at": { "type": "string", "format": "date-time", "description": "Payment deadline.", "example": "2024-01-15T13:00:00Z" }, "created_at": { "$ref": "#/components/schemas/CreatedAt" }, "status_logs": { "type": "array", "description": "Chronological log of invoice status transitions.", "items": { "$ref": "#/components/schemas/PublicInvoiceStatusLog" } }, "transactions": { "type": "array", "description": "Transactions detected on the invoice address since creation.", "items": { "$ref": "#/components/schemas/InvoiceTransaction" } } }, "required": [ "id", "status", "amount", "received_amount", "address", "asset_gid", "expires_at", "created_at", "status_logs", "transactions" ], "example": { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "pending", "amount": { "base": "42500000", "formatted": "42.5" }, "received_amount": { "base": "0", "formatted": "0" }, "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18", "asset_gid": "eip155:56/bep20:0x55d398326f99059fF775485246999027B3197955", "expires_at": "2024-01-15T13:00:00Z", "created_at": "2024-01-15T12:00:00Z", "status_logs": [ { "status": "pending", "changed_at": "2024-01-15T12:00:00Z" } ], "transactions": [] } }, "ChannelKind": { "type": "string", "description": "Type of notification delivery channel.", "enum": [ "telegram", "webhook" ], "x-enumDescriptions": { "telegram": "Telegram bot message delivery to chats or direct messages.", "webhook": "HTTP POST callbacks to external endpoints." }, "example": "webhook" }, "ChannelName": { "type": "string", "description": "Display name for the notification channel.", "minLength": 1, "maxLength": 32, "example": "Production Alerts Webhook" }, "ChannelSummary": { "type": "object", "description": "Notification channel summary for list responses.\n", "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "kind": { "$ref": "#/components/schemas/ChannelKind" }, "name": { "$ref": "#/components/schemas/ChannelName" }, "created_at": { "$ref": "#/components/schemas/CreatedAt" } }, "required": [ "id", "kind", "name", "created_at" ], "example": { "id": "550e8400-e29b-41d4-a716-446655440000", "kind": "webhook", "name": "Production Alerts Webhook", "created_at": "2024-01-15T10:30:00Z" } }, "TelegramBotToken": { "type": "string", "description": "Telegram Bot API token from @BotFather. Format: `{bot_id}:{auth_token}`.\n\nAccepted on write (create, or update to rotate the token). On read the\nvalue is masked (see `TelegramBotTokenMasked`).\n", "pattern": "^\\d{7,12}:[A-Za-z0-9_-]{35}$", "examples": [ "123456789:ABCDEFGHIJKLMNOPQRSTUVWXYZ123456789" ] }, "TelegramChatID": { "type": "integer", "format": "int64", "description": "Telegram chat ID where notifications are sent.\nPositive for private chats, negative for groups, `-100...` prefix for channels.\nUse the Telegram Bot API `getUpdates` method to find your chat ID.\n", "examples": [ -1001234567890, 123456789, -987654321 ] }, "Language": { "type": "string", "description": "Language code for localization.", "enum": [ "ru", "en" ], "x-enumDescriptions": { "ru": "Russian.", "en": "English." }, "example": "en" }, "TelegramThreadID": { "type": "integer", "format": "int32", "description": "Unique identifier for the target message thread (topic) of a forum.\n\nUsed for forum supergroups and private chats of bots with forum topic mode enabled only.\nDefault value is 0 (no specific thread).\n", "default": 0, "example": 0 }, "CreateTelegramChannelConfig": { "type": "object", "description": "Telegram channel configuration for channel creation. The `bot_token` is\nrequired in plaintext; after that it's only ever returned masked.\n", "properties": { "kind": { "type": "string", "enum": [ "telegram" ], "description": "Configuration type discriminator." }, "bot_token": { "$ref": "#/components/schemas/TelegramBotToken" }, "chat_id": { "$ref": "#/components/schemas/TelegramChatID" }, "language": { "$ref": "#/components/schemas/Language" }, "thread_id": { "$ref": "#/components/schemas/TelegramThreadID" } }, "required": [ "kind", "bot_token", "chat_id", "language", "thread_id" ], "example": { "kind": "telegram", "bot_token": "123456789:ABCDEFGHIJKLMNOPQRSTUVWXYZ123456789", "chat_id": -1001234567890, "language": "en", "thread_id": 0 } }, "WebhookURL": { "type": "string", "format": "uri", "description": "HTTP/HTTPS endpoint that accepts POST requests with JSON payloads.\nUse headers (not query params) for authentication.\n", "examples": [ "https://api.example.com/webhooks/notifications", "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX", "https://discord.com/api/webhooks/123456789012345678/abcdefghijklmnopqrstuvwxyz123456789" ] }, "WebhookHeaders": { "type": "object", "description": "Optional HTTP headers to include with webhook requests.\n\nReturned verbatim on read, not masked. Don't put credentials here:\nreceivers verify a webhook by its signing secret (the HMAC\n`X-Webhook-Signature` header), not by a header you set. On update, omit\n`headers` to keep the stored set, send an object to replace it, or `{}`\nto clear them.\n", "additionalProperties": { "type": "string" }, "example": { "Content-Type": "application/json", "X-Tenant-Id": "acme" } }, "WebhookChannelConfig": { "type": "object", "description": "Webhook notification channel configuration.\n\nSends HTTP POST requests with JSON payloads to the configured URL.\nOptional `headers` are returned verbatim (see `WebhookHeaders`).\n", "properties": { "kind": { "type": "string", "enum": [ "webhook" ], "description": "Configuration type discriminator." }, "url": { "$ref": "#/components/schemas/WebhookURL" }, "headers": { "$ref": "#/components/schemas/WebhookHeaders" } }, "required": [ "kind", "url" ], "example": { "kind": "webhook", "url": "https://api.example.com/webhooks/notifications", "headers": { "Content-Type": "application/json", "X-Tenant-Id": "acme" } } }, "CreateChannelConfig": { "type": "object", "description": "Channel-specific configuration for channel creation. The Telegram\n`bot_token` is required in plaintext; after that it's only ever returned\nmasked.\n", "discriminator": { "propertyName": "kind", "mapping": { "telegram": "#/components/schemas/CreateTelegramChannelConfig", "webhook": "#/components/schemas/WebhookChannelConfig" } }, "oneOf": [ { "$ref": "#/components/schemas/CreateTelegramChannelConfig" }, { "$ref": "#/components/schemas/WebhookChannelConfig" } ] }, "TelegramBotTokenMasked": { "type": "string", "description": "Masked Telegram bot token returned in responses. The `bot_id` prefix is\npreserved for identification; the secret `auth_token` portion is hidden,\nshowing only its last 4 characters: `{bot_id}:••••`.\n\nTo keep the stored token on update, omit `bot_token` from the request.\nTo rotate it, send a new plaintext token (see `TelegramBotToken`).\n", "examples": [ "123456789:••••6789" ] }, "TelegramChannelConfig": { "type": "object", "description": "Telegram notification channel configuration as returned in responses.\n\n`bot_token` is masked (see `TelegramBotTokenMasked`); all other fields are\nreturned verbatim.\n", "properties": { "kind": { "type": "string", "enum": [ "telegram" ], "description": "Configuration type discriminator." }, "bot_token": { "$ref": "#/components/schemas/TelegramBotTokenMasked" }, "chat_id": { "$ref": "#/components/schemas/TelegramChatID" }, "language": { "$ref": "#/components/schemas/Language" }, "thread_id": { "$ref": "#/components/schemas/TelegramThreadID" } }, "required": [ "kind", "bot_token", "chat_id", "language", "thread_id" ], "example": { "kind": "telegram", "bot_token": "123456789:••••6789", "chat_id": -1001234567890, "language": "en", "thread_id": 0 } }, "ChannelConfig": { "type": "object", "description": "Channel-specific configuration as returned in responses. Schema depends\non `kind`: `telegram` (bot_token + chat_id) or `webhook` (url + headers).\nThe Telegram `bot_token` is masked; webhook headers are returned verbatim.\n", "discriminator": { "propertyName": "kind", "mapping": { "telegram": "#/components/schemas/TelegramChannelConfig", "webhook": "#/components/schemas/WebhookChannelConfig" } }, "oneOf": [ { "$ref": "#/components/schemas/TelegramChannelConfig" }, { "$ref": "#/components/schemas/WebhookChannelConfig" } ] }, "Channel": { "type": "object", "description": "Notification delivery channel.\n", "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "kind": { "$ref": "#/components/schemas/ChannelKind" }, "name": { "$ref": "#/components/schemas/ChannelName" }, "config": { "$ref": "#/components/schemas/ChannelConfig" }, "created_at": { "$ref": "#/components/schemas/CreatedAt" }, "updated_at": { "$ref": "#/components/schemas/UpdatedAt" } }, "required": [ "id", "kind", "name", "config", "created_at", "updated_at" ], "example": { "id": "550e8400-e29b-41d4-a716-446655440001", "kind": "telegram", "name": "Production Alerts", "config": { "kind": "telegram", "bot_token": "123456789:••••6789", "chat_id": -1001234567890, "language": "en", "thread_id": 0 }, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z" } }, "RawWebhookSecret": { "type": "string", "minLength": 42, "maxLength": 42, "pattern": "^vilna_whsec_[A-Za-z0-9]{30}$", "description": "The full webhook signing secret, 42 characters: `vilna_whsec_{body}`\nwhere `{body}` is 30 base62 characters. Used as the HMAC-SHA256 key\nfor the `X-Webhook-Signature` header on outgoing webhook deliveries.\n**Returned only at channel creation and on rotation; store it\nsecurely.** The server does not store the plaintext and cannot return\nit again; lost secrets must be rotated.\n", "example": "vilna_whsec_a3K9pQ2mB5N8rT1xY7cZ4dH6eJ0fLm" }, "UpdateTelegramChannelConfig": { "type": "object", "description": "Telegram channel configuration for channel update (partial). Omit\n`bot_token` to keep the stored token; send a new plaintext value to\nrotate it.\n", "properties": { "kind": { "type": "string", "enum": [ "telegram" ], "description": "Configuration type discriminator." }, "bot_token": { "$ref": "#/components/schemas/TelegramBotToken" }, "chat_id": { "$ref": "#/components/schemas/TelegramChatID" }, "language": { "$ref": "#/components/schemas/Language" }, "thread_id": { "$ref": "#/components/schemas/TelegramThreadID" } }, "required": [ "kind", "chat_id", "language", "thread_id" ], "example": { "kind": "telegram", "chat_id": -1001234567890, "language": "en", "thread_id": 0 } }, "UpdateChannelConfig": { "type": "object", "description": "Channel-specific configuration for channel update (partial). Omit the\nTelegram `bot_token` to keep the stored token; send a new value to rotate\nit. Webhook `headers` may be omitted (keep), replaced, or cleared (`{}`).\n", "discriminator": { "propertyName": "kind", "mapping": { "telegram": "#/components/schemas/UpdateTelegramChannelConfig", "webhook": "#/components/schemas/WebhookChannelConfig" } }, "oneOf": [ { "$ref": "#/components/schemas/UpdateTelegramChannelConfig" }, { "$ref": "#/components/schemas/WebhookChannelConfig" } ] }, "SubscriptionEventType": { "type": "string", "description": "Event type that a subscription listens to.", "enum": [ "transaction_detected", "transaction_confirmed" ], "x-enumDescriptions": { "transaction_detected": "A new transaction involving a tracked address appears on-chain.", "transaction_confirmed": "A previously detected transaction reaches the required number of confirmations." }, "example": "transaction_detected" }, "TransactionDetectedMeta": { "type": "object", "description": "Delivery context for `transaction_detected` events.", "properties": { "kind": { "type": "string", "enum": [ "transaction_detected" ], "description": "Metadata type discriminator." }, "tx_hash": { "type": "string", "description": "Hash of the detected transaction.", "example": "0xabc123..." }, "chain_id": { "type": "string", "description": "CAIP-2 chain identifier.", "example": "eip155:1" } }, "required": [ "kind", "tx_hash", "chain_id" ] }, "TransactionConfirmedMeta": { "type": "object", "description": "Delivery context for `transaction_confirmed` events.", "properties": { "kind": { "type": "string", "enum": [ "transaction_confirmed" ], "description": "Metadata type discriminator." }, "tx_hash": { "type": "string", "description": "Hash of the confirmed transaction.", "example": "0xabc123..." }, "chain_id": { "type": "string", "description": "CAIP-2 chain identifier.", "example": "eip155:1" } }, "required": [ "kind", "tx_hash", "chain_id" ] }, "ChannelLogMeta": { "type": "object", "description": "Event-specific delivery metadata. Actual schema depends on `kind`.", "discriminator": { "propertyName": "kind", "mapping": { "transaction_detected": "#/components/schemas/TransactionDetectedMeta", "transaction_confirmed": "#/components/schemas/TransactionConfirmedMeta" } }, "oneOf": [ { "$ref": "#/components/schemas/TransactionDetectedMeta" }, { "$ref": "#/components/schemas/TransactionConfirmedMeta" } ] }, "ChannelLog": { "type": "object", "description": "Immutable delivery log entry for a notification channel.\n", "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "channel_id": { "$ref": "#/components/schemas/UUID" }, "event_type": { "$ref": "#/components/schemas/SubscriptionEventType" }, "status_code": { "type": "integer", "description": "HTTP status code returned by the delivery endpoint. `0` indicates a network error.", "example": 200 }, "is_success": { "type": "boolean", "description": "Whether the delivery was successful (2xx status code)." }, "is_test": { "type": "boolean", "description": "Whether this log entry was produced by a test delivery." }, "error": { "type": "string", "description": "Error message if the delivery failed." }, "duration_ms": { "type": "integer", "description": "Delivery duration in milliseconds.", "example": 142 }, "meta": { "$ref": "#/components/schemas/ChannelLogMeta" }, "created_at": { "$ref": "#/components/schemas/CreatedAt" } }, "required": [ "id", "channel_id", "event_type", "status_code", "is_test", "is_success", "duration_ms", "created_at" ], "example": { "id": "550e8400-e29b-41d4-a716-446655440010", "channel_id": "550e8400-e29b-41d4-a716-446655440001", "event_type": "transaction_detected", "is_test": false, "status_code": 200, "is_success": true, "duration_ms": 142, "meta": { "kind": "transaction_detected", "tx_hash": "0xabc123...", "chain_id": "eip155:1" }, "created_at": "2024-01-15T10:30:00Z" } }, "WebhookSecretMask": { "type": "string", "minLength": 20, "maxLength": 20, "description": "Masked form of a webhook signing secret: the `vilna_whsec_` prefix,\nfour obfuscation bullets, and the last 4 characters of the random\nbody. Safe to display in UIs for identifying a secret without\nexposing it (\"is the right secret stored on my side?\").\n", "example": "vilna_whsec_••••2gW9" }, "WebhookSecret": { "type": "object", "description": "A webhook signing secret in masked form. The plaintext value is only\nreturned at issuance (channel creation or rotation); subsequent reads\nexpose just the mask.\n", "required": [ "mask", "created_at" ], "properties": { "mask": { "$ref": "#/components/schemas/WebhookSecretMask" }, "created_at": { "$ref": "#/components/schemas/CreatedAt" }, "expires_at": { "type": "string", "format": "date-time", "description": "The moment after which this secret will no longer sign new\noutgoing webhooks. Set only when this secret occupies the\n`previous` slot.\n" } } }, "SubscriptionName": { "type": "string", "description": "Display name for the notification subscription.", "minLength": 1, "maxLength": 64, "example": "Transaction Alerts" }, "Subscription": { "type": "object", "description": "Notification subscription that binds a channel to an event type.\n", "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "channel_id": { "$ref": "#/components/schemas/UUID" }, "event_type": { "$ref": "#/components/schemas/SubscriptionEventType" }, "name": { "$ref": "#/components/schemas/SubscriptionName" }, "enabled": { "type": "boolean", "description": "Whether this subscription is active." }, "created_at": { "$ref": "#/components/schemas/CreatedAt" }, "updated_at": { "$ref": "#/components/schemas/UpdatedAt" } }, "required": [ "id", "channel_id", "event_type", "name", "enabled", "created_at", "updated_at" ], "example": { "id": "550e8400-e29b-41d4-a716-446655440010", "channel_id": "550e8400-e29b-41d4-a716-446655440001", "event_type": "transaction_detected", "name": "Transaction Detected", "enabled": true, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z" } }, "SubscriptionReferences": { "type": "object", "description": "Related objects included in the response, keyed by ID.", "properties": { "channels": { "type": "object", "description": "Map of notification channels indexed by their UUID ID.", "propertyNames": { "$ref": "#/components/schemas/UUID" }, "additionalProperties": { "$ref": "#/components/schemas/ChannelSummary" } } } }, "TokenTagName": { "type": "string", "description": "Display name for the token tag.", "minLength": 1, "maxLength": 32, "example": "Stablecoins" }, "TokenTag": { "type": "object", "description": "A named collection of tokens within a project.", "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "name": { "$ref": "#/components/schemas/TokenTagName" }, "created_at": { "$ref": "#/components/schemas/CreatedAt" }, "updated_at": { "$ref": "#/components/schemas/UpdatedAt" } }, "required": [ "id", "name", "created_at", "updated_at" ] }, "VersionInfo": { "type": "object", "description": "API version information.", "properties": { "version": { "description": "API version (semantic versioning).", "type": "string" } }, "required": [ "version" ], "example": { "version": "1.0.0" }, "examples": [ { "version": "1.0.0" }, { "version": "1.2.3" }, { "version": "2.0.0-beta.1" }, { "version": "1.5.2-rc.1" } ] } }, "responses": { "problem": { "description": "Unexpected error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "blockchains_list_response": { "description": "Paginated list of supported blockchains.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Blockchain" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "items", "meta" ] } } } }, "invalid_request_problem": { "description": "Bad request (e.g., missing or invalid fields).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/InvalidRequestProblem" }, "examples": { "field_too_long": { "summary": "A field exceeds its maximum length", "value": { "type": "https://docs.vilna.io/apis/problems/invalid-request", "title": "Invalid Request", "status": 400, "code": "blockchain.name_too_long", "detail": "blockchain name too long", "instance": "/traces/0199ce7e-d9e7-7c01-9c2a-9d0010eaa1cc", "fields": [ { "name": "name", "reason": "must not exceed 64 characters" } ] } }, "invalid_address": { "summary": "An address value is malformed", "value": { "type": "https://docs.vilna.io/apis/problems/invalid-request", "title": "Invalid Request", "status": 400, "code": "address.invalid", "detail": "invalid address", "instance": "/traces/0199ce80-1a2b-7c01-9c2a-9d0010eaa200" } }, "invalid_pagination": { "summary": "A pagination argument is out of range", "value": { "type": "https://docs.vilna.io/apis/problems/invalid-request", "title": "Invalid Request", "status": 400, "code": "pagination.invalid_argument", "detail": "invalid pagination arguments", "instance": "/traces/0199ce80-4c5d-7c01-9c2a-9d0010eaa201" } } } } } }, "unauthorized_problem": { "description": "Missing or invalid authentication credentials.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/UnauthorizedProblem" }, "examples": { "missing_api_key": { "summary": "No valid API key was supplied", "value": { "type": "https://docs.vilna.io/apis/problems/unauthorized", "title": "Unauthorized", "status": 401, "code": "auth.unauthorized", "detail": "missing or invalid API key", "instance": "/traces/0199ce84-1a2b-7c01-9c2a-9d0010eaa240" } } } } } }, "forbidden_problem": { "description": "Insufficient permissions.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ForbiddenProblem" }, "examples": { "insufficient_permissions": { "summary": "The API key lacks the required permission", "value": { "type": "https://docs.vilna.io/apis/problems/forbidden", "title": "Forbidden", "status": 403, "code": "unspecified", "detail": "Your credentials are valid but don't include the permission this operation needs. Check the API key permissions in the dashboard. Permissions are set when the key is created and can't be edited later. To change them, create a new key.", "instance": "/forbidden?method=createInvoice" } } } } } }, "blockchain_response": { "description": "Blockchain details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Blockchain" } }, "required": [ "item" ] } } } }, "not_found_problem": { "description": "Requested resource does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/NotFoundProblem" }, "examples": { "address_not_found": { "summary": "The address does not exist in this project", "value": { "type": "https://docs.vilna.io/apis/problems/not-found", "title": "Not Found", "status": 404, "code": "address.not_found", "detail": "address not found", "instance": "/traces/0199ce81-7a8b-7c01-9c2a-9d0010eaa210" } }, "invoice_not_found": { "summary": "The invoice does not exist in this project", "value": { "type": "https://docs.vilna.io/apis/problems/not-found", "title": "Not Found", "status": 404, "code": "invoice.not_found", "detail": "invoice not found", "instance": "/traces/0199ce81-9c0d-7c01-9c2a-9d0010eaa211" } } } } } }, "public_keys_list_response": { "description": "Paginated list of public keys.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "List of public keys.", "items": { "$ref": "#/components/schemas/PublicKey" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "items", "meta" ] } } } }, "create_public_key_response": { "description": "Created public key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/PublicKey" } }, "required": [ "item" ] } } } }, "precondition_problem": { "description": "Request preconditions were not met.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PreconditionProblem" }, "examples": { "invoice_not_cancellable": { "summary": "The invoice cannot be cancelled in its current status", "value": { "type": "https://docs.vilna.io/apis/problems/precondition", "title": "Precondition Failed", "status": 422, "code": "invoice.not_cancellable", "detail": "invoice cannot be cancelled in current status", "instance": "/traces/0199ce83-1a2b-7c01-9c2a-9d0010eaa230" } }, "hd_count_exceeds_limit": { "summary": "The requested HD address count exceeds the allowed limit", "value": { "type": "https://docs.vilna.io/apis/problems/precondition", "title": "Precondition Failed", "status": 422, "code": "address.hd_count_exceeds_limit", "detail": "HD address count exceeds limit", "instance": "/traces/0199ce83-4c5d-7c01-9c2a-9d0010eaa231" } } } } } }, "public_key_response": { "description": "Public key details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/PublicKey" } }, "required": [ "item" ] } } } }, "no_content_response": { "description": "Successful operation with no response body." }, "update_public_key_response": { "description": "Updated public key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/PublicKey" } }, "required": [ "item" ] } } } }, "create_public_key_child_response": { "description": "Created child public key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/PublicKey" } }, "required": [ "item" ] } } } }, "hd_addresses_list_response": { "description": "List of addresses derived from the public key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "List of HD addresses derived from public keys.", "items": { "$ref": "#/components/schemas/HDAddress" } }, "references": { "$ref": "#/components/schemas/AddressReferences" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "items", "references", "meta" ] } } } }, "generate_addresses_response": { "description": "Generated addresses.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "Generated address values.", "items": { "$ref": "#/components/schemas/AddressValue" } }, "count": { "type": "integer", "description": "Number of addresses generated.", "minimum": 0 } }, "required": [ "items", "count" ] } } } }, "hd_address_response": { "description": "Created HD address.", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/HDAddress" }, "references": { "$ref": "#/components/schemas/AddressReferences" } }, "required": [ "item", "references" ] } } } }, "addresses_list_response": { "description": "List of addresses.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "List of addresses.", "items": { "$ref": "#/components/schemas/AddressUnion" } }, "references": { "$ref": "#/components/schemas/AddressReferences" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "items", "references", "meta" ] } } } }, "external_address_response": { "description": "Created external address.", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/ExternalAddress" }, "references": { "$ref": "#/components/schemas/AddressReferences" } }, "required": [ "item", "references" ] } } } }, "conflict_problem": { "description": "Request conflicts with the current resource state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ConflictProblem" }, "examples": { "address_occupied": { "summary": "The address already has an active invoice", "value": { "type": "https://docs.vilna.io/apis/problems/conflict", "title": "Conflict", "status": 409, "code": "invoice.address_occupied", "detail": "address already has an active invoice with different parameters", "instance": "/traces/0199ce82-2a3b-7c01-9c2a-9d0010eaa220" } }, "address_in_use": { "summary": "The address cannot be deleted while in use", "value": { "type": "https://docs.vilna.io/apis/problems/conflict", "title": "Conflict", "status": 409, "code": "address.in_use", "detail": "address has an active invoice and cannot be deleted", "instance": "/traces/0199ce82-4c5d-7c01-9c2a-9d0010eaa221" } } } } } }, "address_response": { "description": "Address details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/AddressUnion" }, "references": { "$ref": "#/components/schemas/AddressReferences" } }, "required": [ "item", "references" ] } } } }, "address_balances_response": { "description": "Active asset balances for the address.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "List of address balances.", "items": { "$ref": "#/components/schemas/BalanceItem" } }, "references": { "$ref": "#/components/schemas/BalanceReferences" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "items", "references", "meta" ] } } } }, "address_utxos_response": { "description": "Unspent Bitcoin outputs held by the address.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "List of unspent outputs.", "items": { "$ref": "#/components/schemas/BitcoinUTXOItem" } }, "references": { "$ref": "#/components/schemas/BitcoinUTXOReferences" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "items", "references", "meta" ] } } } }, "tokens_list_response": { "description": "List of tokens.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "Tokens managed by the service.", "items": { "$ref": "#/components/schemas/Token" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "items", "meta" ] } } } }, "token_response": { "description": "Token details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Token" } }, "required": [ "item" ] } } } }, "activity_list_response": { "description": "Paginated list of asset movements.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "List of asset movement records.", "items": { "$ref": "#/components/schemas/ActivityItem" } }, "references": { "$ref": "#/components/schemas/ActivityReferences" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "items", "references", "meta" ] } } } }, "balances_list_response": { "description": "Paginated list of current balances.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "Current balances for addresses and assets.", "items": { "$ref": "#/components/schemas/BalanceItem" } }, "references": { "$ref": "#/components/schemas/BalanceReferences" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "items", "references", "meta" ] } } } }, "transactions_list_response": { "description": "Paginated list of transactions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "List of blockchain transactions.", "items": { "$ref": "#/components/schemas/TransactionSummary" } }, "references": { "$ref": "#/components/schemas/TransactionReferences" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "items", "references", "meta" ] } } } }, "transaction_details_response": { "description": "Transaction details with events and balance changes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Transaction" }, "references": { "$ref": "#/components/schemas/TransactionReferences" } }, "required": [ "item", "references" ] } } } }, "simulate_evm_response": { "description": "EVM simulation result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "List of simulated transaction results, one per input call in submission order.", "items": { "$ref": "#/components/schemas/SimulatedTransaction" } }, "references": { "$ref": "#/components/schemas/TransactionReferences" } }, "required": [ "items", "references" ] } } } }, "invoices_list_response": { "description": "List of invoices with pagination.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceSummary" } }, "references": { "$ref": "#/components/schemas/InvoiceReferences" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "items", "references", "meta" ] } } } }, "invoice_response": { "description": "Invoice details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Invoice" }, "references": { "$ref": "#/components/schemas/InvoiceReferences" } }, "required": [ "item", "references" ] }, "examples": { "pending_invoice": { "summary": "Just created, awaiting payment", "value": { "item": { "id": "550e8400-e29b-41d4-a716-446655440000", "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18", "asset_gid": "eip155:56/bep20:0x55d398326f99059fF775485246999027B3197955", "amount": "42500000", "received_amount": "0", "status": "pending", "expires_at": "2024-01-15T13:00:00Z", "metadata": { "order_id": "1234" }, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z", "status_logs": [ { "status": "pending", "comment": null, "changed_at": "2024-01-15T10:30:00Z" } ], "transactions": [] }, "references": { "tokens": {}, "blockchains": {} } } }, "confirmed_invoice": { "summary": "Paid in full and confirmed on-chain", "value": { "item": { "id": "550e8400-e29b-41d4-a716-446655440000", "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18", "asset_gid": "eip155:56/bep20:0x55d398326f99059fF775485246999027B3197955", "amount": "42500000", "received_amount": "42500000", "status": "confirmed", "expires_at": "2024-01-15T13:00:00Z", "metadata": { "order_id": "1234" }, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T12:15:00Z", "status_logs": [ { "status": "pending", "comment": null, "changed_at": "2024-01-15T10:30:00Z" }, { "status": "paid", "comment": null, "changed_at": "2024-01-15T12:05:00Z" }, { "status": "confirmed", "comment": null, "changed_at": "2024-01-15T12:15:00Z" } ], "transactions": [ { "hash": "0xabc123def456789012345678901234567890123456789012345678901234abcd", "block_number": 12345678, "is_success": true, "detected_at": "2024-01-15T12:05:00Z", "confirmed_at": "2024-01-15T12:15:00Z", "deposits": [ { "asset_gid": "eip155:56/bep20:0x55d398326f99059fF775485246999027B3197955", "amount": "42500000", "is_matched": true } ] } ] }, "references": { "tokens": {}, "blockchains": {} } } } } } } }, "public_invoice_response": { "description": "Public invoice details for payers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/PublicInvoice" }, "references": { "$ref": "#/components/schemas/InvoiceReferences" } }, "required": [ "item", "references" ] } } } }, "channels_list_response": { "description": "List of channels with pagination.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelSummary" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "items", "meta" ] } } } }, "channel_created_response": { "description": "Channel created, or matched by `pid` (idempotent).", "content": { "application/json": { "schema": { "type": "object", "required": [ "item" ], "properties": { "item": { "$ref": "#/components/schemas/Channel" }, "webhook_secret": { "$ref": "#/components/schemas/RawWebhookSecret", "description": "Plaintext signing secret for the new channel. Present only\nwhen `kind=webhook` and the channel was newly created.\nIdempotent retries that match an existing channel do not\nreturn the secret; the existing one is preserved and can\nonly be re-issued via rotation.\n" } } } } } }, "channel_response": { "description": "Notification channel details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Channel" } }, "required": [ "item" ] } } } }, "test_channel_response": { "description": "Log entry ID for this test delivery. Use the channel logs endpoint to check the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "log_id": { "allOf": [ { "$ref": "#/components/schemas/UUID" }, { "description": "ID of the log entry created for this test delivery. Use it to look up delivery status and details in channel logs." } ] } }, "required": [ "log_id" ], "example": { "log_id": "550e8400-e29b-41d4-a716-446655440010" } } } } }, "channel_logs_list_response": { "description": "List of channel delivery logs with pagination.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelLog" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "items", "meta" ] } } } }, "channel_webhook_secrets_response": { "description": "Webhook signing secrets for the channel.", "content": { "application/json": { "schema": { "type": "object", "required": [ "current" ], "properties": { "current": { "$ref": "#/components/schemas/WebhookSecret", "description": "Signing secret used for all new outgoing webhooks." }, "previous": { "$ref": "#/components/schemas/WebhookSecret", "description": "Previous secret retained during the 24-hour rotation overlap.\nAbsent outside a rotation window.\n" } } } } } }, "rotate_channel_webhook_secret_response": { "description": "Updated webhook signing secrets after rotation, including the new plaintext.", "content": { "application/json": { "schema": { "type": "object", "required": [ "current", "secret" ], "properties": { "current": { "$ref": "#/components/schemas/WebhookSecret", "description": "The newly issued signing secret, now used for all new outgoing webhooks." }, "previous": { "$ref": "#/components/schemas/WebhookSecret", "description": "The secret that was just demoted to the `previous` slot,\nretained for the 24-hour overlap. Absent when this rotation\nissued the channel's first secret.\n" }, "secret": { "$ref": "#/components/schemas/RawWebhookSecret", "description": "Plaintext form of the new `current` secret. **Store it\nimmediately in your secrets manager; if lost, rotate again.**\n" } } } } } }, "subscriptions_list_response": { "description": "List of subscriptions with pagination.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Subscription" } }, "references": { "$ref": "#/components/schemas/SubscriptionReferences" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "items", "references", "meta" ] } } } }, "subscription_response": { "description": "Notification subscription details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Subscription" }, "references": { "$ref": "#/components/schemas/SubscriptionReferences" } }, "required": [ "item", "references" ] } } } }, "token_tags_list_response": { "description": "List of token tags with pagination.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TokenTag" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "items", "meta" ] } } } }, "token_tag_response": { "description": "Token tag details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/TokenTag" } }, "required": [ "item" ] } } } }, "address_tags_list_response": { "description": "List of address tags with pagination.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AddressTag" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "items", "meta" ] } } } }, "address_tag_response": { "description": "Address tag details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/AddressTag" } }, "required": [ "item" ] } } } }, "version_response": { "description": "Service version info.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionInfo" } } } } }, "requestBodies": { "create_public_key_request": { "content": { "application/json": { "schema": { "properties": { "derivation_path": { "$ref": "#/components/schemas/PublicKeyDerivationPath" }, "label": { "$ref": "#/components/schemas/PublicKeyLabel" }, "value": { "$ref": "#/components/schemas/PublicKeyValue" } }, "required": [ "value", "label", "derivation_path" ], "type": "object" }, "examples": { "xpub_example": { "summary": "BIP44 public key", "value": { "derivation_path": "m/44'/0'/0'/0", "label": "My Legacy Wallet", "value": "xpub6F7C1ZtQ411zykk6KTEoQMqfNdxiSA4uxAwAoqFanijnAavqQvVmh5zZCH6Swhdbzt2HuMRLx4chEVRZu9ic4Cnkkq5AsQcmjeMASk6FLqf" } }, "ypub_example": { "summary": "BIP49 public key", "value": { "derivation_path": "m/49'/0'/0'/0", "label": "My SegWit Wallet", "value": "ypub6ZtCaoXpd9GqsJMiFThRchS8RXiyRBD3WxyoZhhnKF9n198VSV8U38TPrrhMenYSXZGU4N8Q5J1XYEjc4JKr8Dj1BtvhCjNTRxPimrfCN4T" } }, "zpub_example": { "summary": "BIP84 public key", "value": { "derivation_path": "m/84'/0'/0'/0", "label": "My Native SegWit Wallet", "value": "zpub6svdUH71uTR9YXumEJroNo51GfHdASMmzKFafeBr51yEzf4gj4cPBafQDjk18AGTZSfhXi8uMuuZKpSdmzHjZDTDCVK3KjVYj1NKUTFfCkk" } }, "taproot_example": { "summary": "BIP86 public key (Taproot)", "value": { "derivation_path": "m/86'/0'/0'/0", "label": "My Taproot Wallet", "value": "xpub6DiEBECiexRBYEYhTgzmGn7UaGvG7yEPMgNgdib3iwHHJd7HPSnfniQ2mBamKVBLWYPbM7MqCVBHiTnFuLwNrZCbk2eY8N7hT4vV89XSJfH" } } } } }, "description": "Public key creation payload.", "required": true }, "update_public_key_request": { "content": { "application/json": { "schema": { "properties": { "label": { "$ref": "#/components/schemas/PublicKeyLabel" } }, "type": "object" } } }, "description": "Public key update payload.", "required": true }, "create_public_key_child_request": { "content": { "application/json": { "schema": { "properties": { "change": { "$ref": "#/components/schemas/PublicKeyChildChange" }, "label": { "$ref": "#/components/schemas/PublicKeyLabel" } }, "required": [ "change", "label" ], "type": "object" }, "examples": { "external_child": { "summary": "External chain (receiving addresses)", "value": { "change": 0, "label": "BTC Receiving" } }, "internal_child": { "summary": "Internal chain (change addresses)", "value": { "change": 1, "label": "BTC Change" } } } } }, "description": "Create a child key from an account-level public key.\nThe server derives the child extended public key — no cryptography needed on the client side.\n", "required": true }, "generate_hd_addresses_request": { "content": { "application/json": { "schema": { "type": "object", "properties": { "range": { "description": "Address index range.", "type": "object", "properties": { "startIndex": { "description": "Start index (inclusive).", "type": "integer", "minimum": 0, "example": 100 }, "count": { "description": "Number of addresses.", "type": "integer", "minimum": 1, "maximum": 10000, "example": 50 } }, "required": [ "startIndex", "count" ] }, "chainFamily": { "$ref": "#/components/schemas/ChainFamilyForGeneration" } }, "required": [ "range", "chainFamily" ] } } }, "description": "HD address generation payload.", "required": true }, "generate_next_hd_address_request": { "description": "Next HD address generation payload.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chainFamily": { "$ref": "#/components/schemas/ChainFamilyForGeneration" }, "label": { "$ref": "#/components/schemas/AddressLabel" }, "meta": { "$ref": "#/components/schemas/AddressMeta" } }, "required": [ "chainFamily" ], "example": { "chainFamily": "evm", "meta": { "user_id": "100", "type": "deposit" } } } } } }, "create_external_address_request": { "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/AddressValue", "description": "Blockchain address to import for tracking." }, "chainFamily": { "$ref": "#/components/schemas/ChainFamily" }, "label": { "$ref": "#/components/schemas/AddressLabel" }, "meta": { "$ref": "#/components/schemas/AddressMeta" } }, "required": [ "value", "chainFamily" ] } } }, "description": "External address payload.", "required": true }, "resolve_external_address_request": { "content": { "application/json": { "schema": { "type": "object", "properties": { "publicKey": { "type": "string", "description": "Raw public key. Hex-encoded for secp256k1 chains (EVM, Tron, Bitcoin), base58-encoded for ed25519 chains (Solana). Compressed (33 bytes) and uncompressed (65 bytes) secp256k1 keys are both accepted. 0x prefix is optional for hex keys.\n", "example": "02c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5" }, "addressFormat": { "$ref": "#/components/schemas/ResolveAddressFormat" }, "label": { "$ref": "#/components/schemas/AddressLabel" }, "meta": { "$ref": "#/components/schemas/AddressMeta" } }, "required": [ "publicKey", "addressFormat" ] } } }, "description": "Create an external address from a raw public key.", "required": true }, "update_address_request": { "content": { "application/json": { "schema": { "properties": { "label": { "$ref": "#/components/schemas/AddressLabel" }, "meta": { "$ref": "#/components/schemas/AddressMeta" } }, "type": "object" } } }, "description": "Address metadata payload.", "required": true }, "simulate_evm_request": { "content": { "application/json": { "schema": { "type": "object", "properties": { "validation": { "type": "boolean", "description": "When true, the simulation checks sender balance, nonce sequence, and\nfee consistency the same way a real submission would. When false\n(default), missing parameters are filled with permissive defaults\nand balance is not checked.\n", "default": false }, "block_state_calls": { "type": "array", "description": "Blocks to simulate.", "items": { "type": "object", "properties": { "calls": { "type": "array", "description": "Calls in this block.", "items": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Sender address.", "example": "0x974caa59e49682cda0ad2bbe82983419a2ecc400" }, "to": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Recipient address.", "example": "0xd0930a8fc56fd94038250bb93dbac0e13da4eb99" }, "value": { "type": "string", "pattern": "^(0x[a-fA-F0-9]+|[0-9]+)$", "description": "Transfer value in wei (decimal or 0x hex).", "example": "10000000000000000", "default": "0" }, "data": { "type": "string", "pattern": "^0x[a-fA-F0-9]*$", "description": "Call data (hex).", "example": "0xa9059cbb000000000000000000000000d0930a8fc56fd94038250bb93dbac0e13da4eb99000000000000000000000000000000000000000000000000000000003b9aca00", "default": "0x" }, "nonce": { "type": "string", "pattern": "^(0x[a-fA-F0-9]+|[0-9]+)$", "description": "Sender nonce (decimal or 0x hex). If omitted, the current nonce is used.", "example": "1" }, "gas": { "type": "string", "pattern": "^(0x[a-fA-F0-9]+|[0-9]+)$", "description": "Gas limit (decimal or 0x hex). If omitted, no limit is enforced.", "example": "21000" }, "gas_price": { "type": "string", "pattern": "^(0x[a-fA-F0-9]+|[0-9]+)$", "description": "Gas price in wei (decimal or 0x hex). Legacy transactions only. Mutually exclusive with max_fee_per_gas / max_priority_fee_per_gas.", "example": "1000000000" }, "max_fee_per_gas": { "type": "string", "pattern": "^(0x[a-fA-F0-9]+|[0-9]+)$", "description": "Max fee per gas in wei (decimal or 0x hex). EIP-1559 only. Mutually exclusive with gas_price.", "example": "2000000000" }, "max_priority_fee_per_gas": { "type": "string", "pattern": "^(0x[a-fA-F0-9]+|[0-9]+)$", "description": "Priority fee (tip) per gas in wei (decimal or 0x hex). EIP-1559 only. Mutually exclusive with gas_price.", "example": "1000000000" } }, "required": [ "from", "to" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "calls" ], "additionalProperties": false }, "minItems": 1 } }, "required": [ "block_state_calls" ], "additionalProperties": false }, "examples": { "multi_transaction_simulation": { "summary": "Multi-call simulation", "value": { "block_state_calls": [ { "calls": [ { "from": "0x974caa59e49682cda0ad2bbe82983419a2ecc400", "to": "0xd0930a8fc56fd94038250bb93dbac0e13da4eb99", "value": "10000000000000000", "data": "0x" }, { "from": "0x974caa59e49682cda0ad2bbe82983419a2ecc400", "to": "0xdAC17F958D2ee523a2206206994597C13D831ec7", "value": "0", "data": "0x095ea7b3000000000000000000000000d0930a8fc56fd94038250bb93dbac0e13da4eb99000000000000000000000000000000000000000000000000000000003b9aca00" }, { "from": "0x974caa59e49682cda0ad2bbe82983419a2ecc400", "to": "0xdAC17F958D2ee523a2206206994597C13D831ec7", "value": "0", "data": "0xa9059cbb000000000000000000000000d0930a8fc56fd94038250bb93dbac0e13da4eb99000000000000000000000000000000000000000000000000000000003b9aca00" } ] } ] } }, "simple_transfer": { "summary": "Native transfer", "value": { "block_state_calls": [ { "calls": [ { "from": "0x974caa59e49682cda0ad2bbe82983419a2ecc400", "to": "0xd0930a8fc56fd94038250bb93dbac0e13da4eb99", "value": "1000000000000000000", "data": "0x" } ] } ] } }, "strict_validation": { "summary": "Pre-send validation with EIP-1559 fees", "value": { "validation": true, "block_state_calls": [ { "calls": [ { "from": "0x974caa59e49682cda0ad2bbe82983419a2ecc400", "to": "0xdAC17F958D2ee523a2206206994597C13D831ec7", "value": "0", "data": "0xa9059cbb000000000000000000000000d0930a8fc56fd94038250bb93dbac0e13da4eb99000000000000000000000000000000000000000000000000000000003b9aca00", "nonce": "1", "gas": "60000", "max_fee_per_gas": "2000000000", "max_priority_fee_per_gas": "1000000000" } ] } ] } } } } }, "description": "EVM simulation payload.", "required": true }, "create_invoice_request": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Invoice creation payload.", "properties": { "address": { "$ref": "#/components/schemas/AddressValue" }, "asset_gid": { "$ref": "#/components/schemas/AssetGID" }, "amount": { "$ref": "#/components/schemas/AmountInBaseUnits" }, "expires_at": { "type": "string", "format": "date-time", "description": "Payment deadline. Must be in the future.", "example": "2024-01-15T13:00:00Z" }, "metadata": { "type": "object", "description": "Optional key-value pairs for storing additional information about the invoice.", "additionalProperties": { "type": "string" }, "example": { "order_id": "1234" } } }, "required": [ "address", "asset_gid", "amount", "expires_at" ], "additionalProperties": false }, "examples": { "create_usdt_invoice": { "summary": "USDT invoice on BNB Smart Chain", "value": { "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18", "asset_gid": "eip155:56/bep20:0x55d398326f99059fF775485246999027B3197955", "amount": "42500000", "expires_at": "2024-01-15T13:00:00Z", "metadata": { "order_id": "1234" } } } } } } }, "cancel_invoice_request": { "required": false, "description": "Optional cancellation details.", "content": { "application/json": { "schema": { "type": "object", "description": "Optional payload for invoice cancellation.", "properties": { "comment": { "type": "string", "description": "Optional reason for cancellation. Max 64 characters.", "maxLength": 64, "example": "Cancelled by merchant" } }, "additionalProperties": false }, "examples": { "with_comment": { "summary": "Cancel with reason", "value": { "comment": "Cancelled by merchant" } }, "without_comment": { "summary": "Cancel without reason", "value": {} } } } } }, "create_channel_request": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Notification channel creation payload.", "properties": { "name": { "$ref": "#/components/schemas/ChannelName" }, "config": { "$ref": "#/components/schemas/CreateChannelConfig" } }, "required": [ "name", "config" ], "additionalProperties": false }, "examples": { "create_telegram_channel": { "summary": "Telegram channel", "value": { "name": "Production Alerts", "config": { "kind": "telegram", "bot_token": "987654321:ABCDEFGHIJKLMNOPQRSTUVWXYZ123456789", "chat_id": -1001234567890, "language": "en", "thread_id": 0 } } }, "create_webhook_channel": { "summary": "Webhook channel", "value": { "name": "Alert Webhook", "config": { "kind": "webhook", "url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX", "headers": { "Content-Type": "application/json", "X-Tenant-Id": "acme" } } } } } } } }, "update_channel_config_request": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Notification channel update payload.", "properties": { "name": { "$ref": "#/components/schemas/ChannelName" }, "config": { "$ref": "#/components/schemas/UpdateChannelConfig" } }, "minProperties": 1, "additionalProperties": false }, "examples": { "update_telegram_keep_token": { "summary": "Telegram update, keep stored bot_token", "value": { "name": "Updated Production Alerts", "config": { "kind": "telegram", "chat_id": -1001234567891, "language": "ru", "thread_id": 42 } } }, "update_telegram_rotate_token": { "summary": "Telegram update, rotate bot_token", "value": { "config": { "kind": "telegram", "bot_token": "123456789:ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghi", "chat_id": -1001234567890, "language": "en", "thread_id": 0 } } }, "update_webhook_keep_headers": { "summary": "Webhook update, keep stored headers", "value": { "name": "Updated Alert Webhook", "config": { "kind": "webhook", "url": "https://hooks.slack.com/services/T11111111/B11111111/YYYYYYYYYYYYYYYYYYYYYYYY" } } }, "update_webhook_replace_headers": { "summary": "Webhook update, replace headers", "value": { "config": { "kind": "webhook", "url": "https://hooks.slack.com/services/T11111111/B11111111/YYYYYYYYYYYYYYYYYYYYYYYY", "headers": { "Content-Type": "application/json", "X-Tenant-Id": "acme" } } } }, "update_webhook_clear_headers": { "summary": "Webhook update, clear all headers", "value": { "config": { "kind": "webhook", "url": "https://hooks.slack.com/services/T11111111/B11111111/YYYYYYYYYYYYYYYYYYYYYYYY", "headers": {} } } }, "update_name_only": { "summary": "Name-only update", "value": { "name": "New Channel Name" } } } } } }, "test_channel_request": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Channel test payload.", "properties": { "event_type": { "$ref": "#/components/schemas/SubscriptionEventType" } }, "required": [ "event_type" ], "additionalProperties": false }, "examples": { "transaction_detected_test": { "summary": "Transaction detected test message", "value": { "event_type": "transaction_detected" } } } } } }, "create_subscription_request": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Notification subscription creation payload.", "properties": { "channel_id": { "$ref": "#/components/schemas/UUID" }, "event_type": { "$ref": "#/components/schemas/SubscriptionEventType" }, "name": { "$ref": "#/components/schemas/SubscriptionName" } }, "required": [ "channel_id", "event_type", "name" ], "additionalProperties": false }, "examples": { "create_transaction_detected_subscription": { "summary": "Transaction detected subscription", "value": { "channel_id": "550e8400-e29b-41d4-a716-446655440001", "event_type": "transaction_detected", "name": "Transaction Detected" } } } } } }, "update_subscription_request": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Notification subscription update payload.", "properties": { "name": { "$ref": "#/components/schemas/SubscriptionName" }, "enabled": { "type": "boolean", "description": "Whether this subscription is active." } }, "minProperties": 1, "additionalProperties": false }, "examples": { "update_name_only": { "summary": "Name-only update", "value": { "name": "New Subscription Name" } }, "disable_subscription": { "summary": "Disable subscription", "value": { "enabled": false } } } } } }, "create_token_tag_request": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Token tag creation payload.", "properties": { "name": { "$ref": "#/components/schemas/TokenTagName" } }, "required": [ "name" ], "additionalProperties": false } } } }, "update_token_tag_request": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Token tag update payload.", "properties": { "name": { "$ref": "#/components/schemas/TokenTagName" } }, "additionalProperties": false } } } }, "add_token_tag_assets_request": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Add tokens to a tag by asset GID.", "properties": { "asset_gids": { "type": "array", "description": "List of CAIP-19 asset GIDs to add.", "items": { "$ref": "#/components/schemas/AssetGID" }, "minItems": 1 } }, "required": [ "asset_gids" ], "additionalProperties": false } } } }, "remove_token_tag_assets_request": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Remove tokens from a tag by asset GID.", "properties": { "asset_gids": { "type": "array", "description": "List of CAIP-19 asset GIDs to remove.", "items": { "$ref": "#/components/schemas/AssetGID" }, "minItems": 1 } }, "required": [ "asset_gids" ], "additionalProperties": false } } } }, "create_address_tag_request": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Address tag creation payload.", "properties": { "name": { "$ref": "#/components/schemas/AddressTagName" } }, "required": [ "name" ], "additionalProperties": false } } } }, "update_address_tag_request": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Address tag update payload.", "properties": { "name": { "$ref": "#/components/schemas/AddressTagName" } }, "required": [ "name" ], "additionalProperties": false } } } }, "add_address_tag_addresses_request": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Add addresses to a tag by address value.", "properties": { "addresses": { "type": "array", "description": "List of address values to add.", "items": { "$ref": "#/components/schemas/AddressValue" }, "minItems": 1 } }, "required": [ "addresses" ], "additionalProperties": false } } } }, "remove_address_tag_addresses_request": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Remove addresses from a tag by address value.", "properties": { "addresses": { "type": "array", "description": "List of address values to remove.", "items": { "$ref": "#/components/schemas/AddressValue" }, "minItems": 1 } }, "required": [ "addresses" ], "additionalProperties": false } } } } } }, "x-keywords": { "includes": [ "blockchain api", "crypto api", "web3 api", "blockchain data api", "wallet monitoring api", "multichain", "pagination", "rate limiting", "error handling" ], "excludes": [ "management api", "workspace management", "api key management", "team management" ] }, "x-tagGroups": [ { "name": "Activity & Balances", "tags": [ "activity", "balance" ] }, { "name": "Address Operations", "tags": [ "address", "address_tag", "public_key" ] }, { "name": "Transactions", "tags": [ "transaction" ] }, { "name": "Payments", "tags": [ "invoice" ] }, { "name": "Monitoring", "tags": [ "channel", "subscription" ] }, { "name": "Blockchain Data", "tags": [ "blockchain", "token", "token_tag" ] }, { "name": "Developer Tools", "tags": [ "simulate", "version" ] } ] }