Build (but never sign or broadcast) a multi-clause VeChainThor transaction. Each clause is { name, method, args, valueWei?, comment?, address? }; for erc20 / erc721 an explicit address is mandatory. Returns the array of { to, value, data, comment? } clauses ready to be passed to VeWorld, the dApp Kit or vechain-kit for signing. By default every clause is simulated via Thor multicall first (using a generic signer): reverts are surfaced in simulation.results so the agent can fix the request before asking the user to sign. The server NEVER holds private keys and NEVER broadcasts.

Execute one or more read-only contract calls (view / pure methods) in a single multicall round-trip. Each clause is { name, method, args, address? } where name is a registry contract from listKnownContracts. Pass address only to override the registry default or when calling erc20 / erc721 on an arbitrary token. Returns one result per clause with success, the decoded primary value and the full decoded array. bigint values are stringified. Use this instead of one call per round-trip whenever you need multiple values.

Decode an event emitted by a contract on Thor network

Get account details from Thor network

Retrieve total unique VeChain accounts by timeframe via /api/v1/accounts/totals. Provide timeFrame (DAY, WEEK, MONTH, YEAR) to get per-interval totals; omit timeFrame to get cumulative ALL. Supports pagination.

List official apps from VeChain App Hub. Supports filtering by category, tag, VeWorld support and free-text search. Always return app URL when available.

Fetch B3TR actions for a VeBetterDAO app via /api/v1/b3tr/actions/apps/{appId}. Requires appId (if coming from app-hub from name or description, use veBetterDaoId).

Get B3TR actions for a user and the impacts of those actions via /api/v1/b3tr/actions/users/{wallet}. Optionally filter by appId and time range.

Get APP overview for a specific app listed on veBetterDao via /api/v1/b3tr/actions/apps/{appId}/overview. Returns total B3TR rewards, number of rewarded actions, sustainability impact totals, global rankings for a specific app. appId must be the veBetterDaoId (32-byte hex, e.g. 0x2fc30c...). If the user gives an app name like "Mugshot", call getAppHubApps first to resolve the veBetterDaoId — never pass an app name directly here. Optionally filter by roundId OR date (yyyy-MM-dd UTC), but not both — they are mutually exclusive.

Get user B3TR action leaderboard for a given app via /api/v1/b3tr/actions/leaderboards/apps/{appId}. Optionally filter by roundId or date; sort by totalRewardAmount or actionsRewarded; supports cursor pagination.

Get app B3TR action leaderboard via /api/v1/b3tr/actions/leaderboards/apps. Optionally filter by roundId OR date (yyyy-MM-dd UTC) but not both — they are mutually exclusive. Sort by totalRewardAmount or actionsRewarded; supports cursor pagination.

Get global B3TR action overview via /api/v1/b3tr/actions/global/overview. Optionally filter by roundId OR date (yyyy-MM-dd UTC), but not both — they are mutually exclusive.

Get on-chain voting comments/reasons for a specific B3TR proposal via /api/v1/b3tr/proposals/{proposalId}/comments. Shows comments from users who actually voted on-chain with their voting power and weight. NOTE: This shows on-chain voter comments. For broader community discussion, extract the Discourse forum link from the proposal's IPFS description. If getDiscourseTopic is available, use it to fetch the full forum thread; if not available (optional feature), provide the forum URL for manual viewing. Forum discussions often have more detailed debate and sentiment from the wider community before/during voting. Supports filtering by support type (FOR, AGAINST, ABSTAIN).

Get B3TR proposal results via /api/v2/b3tr/proposals/results. IMPORTANT: If user provides a specific proposal ID, pass it as the proposalId parameter to query directly for that single proposal - DO NOT fetch all proposals and filter! Returns proposals with voting results and IPFS description CIDs. WORKFLOW: 1) Use this tool with proposalId parameter if specific proposal requested, or browse all proposals if general query, 2) Use getIPFSContent with the description CID to get full proposal details, 3) Extract Discourse forum link from description (format: vechain.discourse.group/t/topic-name/TOPIC_ID), 4) If getDiscourseTopic is available, use it with the topic ID to fetch community discussion; if not available (optional feature), provide the forum URL for manual viewing, 5) Use getB3TRProposalComments to get on-chain voting comments. This gives complete view: proposal data + forum discussion (via API or URL) + on-chain voter comments.

Get a users overview for a specific app on veBetterDao via /api/v1/b3tr/actions/users/{wallet}/app/{appId}/overview. Returns total B3TR rewards, number of rewarded actions, sustainability impact totals, global rankings for a specific app. appId must be the veBetterDaoId (32-byte hex). If the user gives an app name, call getAppHubApps first to resolve the veBetterDaoId. Optionally filter by roundId OR date (yyyy-MM-dd UTC), but not both — they are mutually exclusive.

Get daily action summaries for a specific user within a date range via /api/v1/b3tr/actions/users/{wallet}/daily-summaries. Returns total B3TR rewards, number of rewarded actions, sustainability impact totals for each day. Dates must be UTC in yyyy-MM-dd.

Get the B3TR action overview for a specific wallet via /api/v1/b3tr/actions/users/{wallet}/overview. Returns total B3TR rewards, number of rewarded actions, sustainability impact totals, global rankings, and unique X-App interactions. Optionally filter by roundId OR date (yyyy-MM-dd UTC), but not both — they are mutually exclusive.

Get leaderboard of users' B3TR actions via /api/v1/b3tr/actions/leaderboards/users. Optionally filter by roundId OR date (yyyy-MM-dd UTC) but not both — they are mutually exclusive. Sort by totalRewardAmount or actionsRewarded; supports cursor pagination.

Get block details from Thor network

Return the ABI of a contract registered in the server, with optional filters to keep the payload small. Always prefer the most specific filters: pass methodNames: ["balanceOf", "transfer"] to get just those fragments, or stateMutability: "view" to list read-only methods. When called with no filters on a large ABI the server returns only the list of function names and asks you to refine the query (the full ABI would be tens of KB). Use the returned fragments directly in callContract / buildContractTransaction together with the same name.

Query VeWorld Indexer /api/v1/transactions/contract for transactions interacting with a contract address. Supports pagination.

Get the current VeBetterDAO round ID by querying the X Allocation Voting smart contract directly. Rounds are time periods for voting cycles and reward distribution. Use this round ID to filter other queries (e.g., getB3TRGlobalOverview, getB3TRAppOverview) to see data for the current active round. Returns real-time on-chain value.

Query VeWorld Indexer /api/v1/transactions/delegated for transactions delegated by a given delegator address. Supports pagination.

Get all available categories from the VeBetterDAO Discourse forum. OPTIONAL FEATURE: Requires Discourse MCP server running separately. If not available, suggest visiting https://vechain.discourse.group/categories to browse categories.

Get the latest topics from the VeBetterDAO Discourse forum. Returns standard page size by default. OPTIONAL FEATURE: Requires Discourse MCP server running separately. If not available, suggest visiting https://vechain.discourse.group directly. Useful for browsing what the community is currently discussing, finding new proposal discussions, or monitoring general sentiment.

Get a specific post from the VeBetterDAO Discourse forum by post ID. Useful for reading specific replies or comments in detail. OPTIONAL FEATURE: Requires Discourse MCP server running separately.

Get detailed information about a specific Discourse forum topic, including posts and replies. Returns 5 posts by default. OPTIONAL FEATURE: Requires Discourse MCP server running separately. CRITICAL FOR B3TR PROPOSALS: Proposal descriptions (fetched via getIPFSContent) often contain Discourse forum links in the format vechain.discourse.group/t/topic-name/TOPIC_ID. If this tool is not available, provide the direct forum URL for manual viewing. Example: from URL "https://vechain.discourse.group/t/vebetterdao-proposal-auto-voting/559" extract topicId: 559.

Get cumulative block usage statistics (gas, tx counts, clauses, base fee) over a timestamp range via /api/v1/explorer/block-usage. Query: startTimestamp, endTimestamp (Unix seconds, inclusive). Returns cumulative counters at sampled points; compute deltas client-side.

List fungible token contract addresses for a wallet via Indexer. Use with getTokenRegistry for metadata. Endpoint: /api/v1/transfers/fungible-tokens-contracts.

Check if a wallet address owns a Galaxy Member (GM) NFT and get its details. Uses hybrid approach: 1) Indexer to quickly check IF user has GM NFT (cached, fast), 2) Smart contract to get precise level/tier details. Galaxy Member NFTs provide special governance rights and benefits in VeBetterDAO. Returns whether the address holds a GM NFT, token ID(s), and level/tier.

Retrieve transaction history for a VeChain address with filtering support.

IMPORTANT: Pass ARRAYS of event names to fetch multiple event types in ONE call - this is much more efficient than separate calls.

Available Event Types:

STARGATE STAKING (Current - Post-Hayabusa):

• STARGATE_STAKE: User stakes VET and mints Stargate NFT

• STARGATE_UNSTAKE: User unstakes VET and burns NFT

• STARGATE_DELEGATE_REQUEST: User requests to delegate NFT to validator

• STARGATE_DELEGATE_ACTIVE: Delegation becomes active with validator

• STARGATE_DELEGATE_EXIT_REQUEST: User requests to exit delegation

• STARGATE_DELEGATION_EXITED: Delegation fully exited, can unstake

• STARGATE_DELEGATION_EXITED_VALIDATOR: Validator-side exit event

• STARGATE_DELEGATE_REQUEST_CANCELLED: Delegation request cancelled before activation

• STARGATE_CLAIM_REWARDS: User claims VTHO staking rewards

• STARGATE_BOOST: User boosts NFT maturity with VTHO payment

• STARGATE_MANAGER_ADDED: User adds manager address to control NFT

• STARGATE_MANAGER_REMOVED: Manager address removed from NFT

STARGATE LEGACY (Pre-Hayabusa - Historical only):

• STARGATE_DELEGATE_LEGACY: Old delegation system

• STARGATE_CLAIM_REWARDS_BASE_LEGACY: Old base rewards

• STARGATE_CLAIM_REWARDS_DELEGATE_LEGACY: Old delegation rewards

• STARGATE_UNDELEGATE_LEGACY: Old undelegation

TRANSFERS:

• TRANSFER_VET: Native VET token transfers

• TRANSFER_FT: Fungible token (VIP-180) transfers - includes VTHO, other tokens

• TRANSFER_NFT: NFT (VIP-181/VIP-721) transfers

• TRANSFER_SF: Semi-fungible token transfers

SWAPS (DEX Activity):

• SWAP_VET_TO_FT: Swapping VET for tokens

• SWAP_FT_TO_VET: Swapping tokens for VET

• SWAP_FT_TO_FT: Token-to-token swaps

VEBETTERDAO (B3TR Ecosystem):

• B3TR_SWAP_VOT3_TO_B3TR: Converting VOT3 governance token to B3TR

• B3TR_SWAP_B3TR_TO_VOT3: Converting B3TR to VOT3

• B3TR_PROPOSAL_SUPPORT: Supporting a proposal with B3TR

• B3TR_PROPOSAL_VOTE: Voting on governance proposal

• B3TR_PROPOSAL_WITHDRAW: Withdrawing a B3TR proposal

• B3TR_XALLOCATION_VOTE: Voting on X-Allocation distribution

• B3TR_CLAIM_REWARD: Claiming B3TR ecosystem rewards

• B3TR_UPGRADE_GM: Upgrading governance model

• B3TR_ACTION: General B3TR ecosystem action

GOVERNANCE:

• VEVOTE_VOTE_CAST: Vote cast in VeVote governance system

OTHER:

• NFT_SALE: NFT marketplace sale transaction

• UNKNOWN_TX: Unclassified transaction type

Common Query Patterns:

Complete Stargate history: ["STARGATE_STAKE", "STARGATE_UNSTAKE", "STARGATE_DELEGATE_REQUEST", "STARGATE_DELEGATE_ACTIVE", "STARGATE_DELEGATE_EXIT_REQUEST", "STARGATE_DELEGATION_EXITED", "STARGATE_CLAIM_REWARDS", "STARGATE_BOOST", "STARGATE_MANAGER_ADDED", "STARGATE_MANAGER_REMOVED"]

All asset transfers: ["TRANSFER_VET", "TRANSFER_FT", "TRANSFER_NFT", "TRANSFER_SF"]

Trading activity: ["SWAP_VET_TO_FT", "SWAP_FT_TO_VET", "SWAP_FT_TO_FT"]

Filters:

• eventName: Single string OR array (ALWAYS prefer arrays for related events)

• searchBy: 'to' | 'from' | 'origin' | 'gasPayer' - filter by address role

• contractAddress: Filter by specific contract interactions

• after/before: Unix timestamps in SECONDS (NOT milliseconds). Example: 2025-08-03 00:00 UTC = 1754179200, 2025-08-04 00:00 UTC = 1754265600

• Pagination: page, size, cursor, direction (ASC/DESC)

Returns paginated array of events with full transaction details.

Fetch content from IPFS using the VeChain gateway proxy (api.gateway-proxy.vechain.org). Provide an IPFS Content Identifier (CID) to retrieve the associated data. Commonly used to fetch B3TR proposal descriptions. IMPORTANT: Proposal descriptions often contain Discourse forum links (vechain.discourse.group/t/topic-name/TOPIC_ID or discourse.vebetterdao.org/t/topic-name/TOPIC_ID). After fetching IPFS content, search for these links and extract them. If getDiscourseTopic is available, use it with the topic ID. If not available (optional feature), provide the full forum URL for manual viewing to see community discussion and sentiment.

Get all NFT contract addresses for a given owner using VeWorld Indexer. Endpoint: /api/v1/nfts/contracts. Accepts address and pagination (page/size/direction or cursor).

Get all NFTs owned by an address using VeWorld Indexer. Endpoint: /api/v1/nfts. Accepts address, optional contractAddress, and pagination (page/size/direction or cursor).

Time‑series of total Stargate NFT holders by period (DAY, WEEK, MONTH, YEAR, ALL). Each element corresponds to an interval at the selected granularity.

Running-total time series of total NFT holders in Stargate, optionally filtered by NFT level. Endpoint: /api/v1/stargate/nft-holders/historic/{range}.

Get the total number of Stargate NFTs and breakdown by level via /api/v1/stargate/nft-holders. Returns an object with block metadata, total, and byLevel.

Overview of rewards earned by a Stargate NFT delegation to a validator over time. Not the same as “claimed” (claimable only at end of cycle). Supports periodType (CYCLE, DAY, WEEK, MONTH, YEAR, ALL), optional validator, and pagination.

Fetch Stargate NFT information (VET staked, rewards, level, delegation status, validator id, etc.) via /api/v1/stargate/tokens. Supports filtering by owner, manager, or tokenId; supports pagination (page, size, direction).

Get total VET staked in Stargate at latest or at a specific block via /api/v1/stargate/total-vet-staked. Returns block metadata, total, and byLevel breakdown.

Running-total time series of total VET staked in Stargate, optionally filtered by NFT level. Endpoint: /api/v1/stargate/total-vet-staked/historic/{range}.

Fetch the total VTHO that Stargate users have actually claimed from rewards generated by delegations. Returns a numeric value encoded as a JSON string. Optional: blockNumber for historical snapshots; rewardsType can filter by LEGACY (pre‑Hayabusa) or DELEGATED (post‑Hayabusa).

Get total VTHO claimed by a given account via /api/v1/stargate/total-vtho-claimed/{account}. Optional rewardsType filter: LEGACY (pre‑Hayabusa bootstrap) or DELEGATION (post‑Hayabusa delegated) if not provided, all rewards ever claimed are included.

Get total VTHO claimed by a given account and token via /api/v1/stargate/total-vtho-claimed/{account}/{tokenId}. Optional rewardsType filter: LEGACY (pre‑Hayabusa bootstrap) or DELEGATION (post‑Hayabusa delegated).

Running-total time series of total VTHO claimed across Stargate. Endpoint: /api/v1/stargate/total-vtho-claimed/historic/{range}.

Fetch the total VTHO generated by Stargate delegations from validators’ block rewards (aggregate produced, whether or not claimed). Returns a numeric value encoded as a JSON string. Optional: blockNumber for historical snapshots.

Running-total time series of total VTHO generated across Stargate. Endpoint: /api/v1/stargate/total-vtho-generated/historic/{range}.

Time‑series of VET delegated to validators via Stargate by period (DAY, WEEK, MONTH, YEAR, ALL). Useful for tracking delegation flows over time.

Time‑series of VET staked (locked via Stargate) by period (DAY, WEEK, MONTH, YEAR, ALL). Each element is the total amount staked during that interval.

Time‑series of VTHO that users actually claimed from Stargate rewards by period (DAY, WEEK, MONTH, YEAR, ALL). Values represent the claimed subset of generated rewards per interval. Only take into account rewaerds that were claimed post hayabusa.

Time‑series of VTHO generated from validators’ block rewards by period (DAY, WEEK, MONTH, YEAR, ALL). Each element represents the amount generated during that interval; use it to chart production over time.

Get the balance of any VIP-180/ERC-20 token for a wallet address by querying the smart contract directly. Returns the raw balance (smallest unit), formatted balance (human-readable), decimals, and token metadata (symbol, name) if available. Requires the token contract address.

Get the current price of VET, VTHO, or B3TR in a given fiat currency using the on-chain VeChain Energy Oracle.

Fetch the VeChain token registry curated list for the current network (VECHAIN_NETWORK=mainnet|testnet). Use this to identify official tokens, metadata (decimals, symbol, website), and bridge provenance. Supports optional filtering by symbol or contract address.

Get transaction details from Thor network

Get a single decoded transaction (with events) by ID from VeWorld Indexer. Endpoint: /api/v1/transactions/{txId}.

Query VeWorld Indexer /api/v1/transactions. Provide either 'origin' or 'delegator' address with optional time filters and pagination. Returns decoded events.

Query VeWorld Indexer /api/v1/transfers/forBlock for all transfers in a block. Required 'blockNumber'. Optional 'tokenAddress' to scope to a specific VIP‑180/721 contract and pagination. Use for 'transfers in block' or 'block activity'.

Query VeWorld Indexer /api/v1/transfers/from for outgoing transfers. Required 'address' (sender, accepts BOTH VNS names like roisin.vet AND 0x hex addresses). Optional 'tokenAddress' (accepts token symbol like VET, VTHO, B3TR OR 0x hex address) to scope to a specific VIP‑180/ERC-20 contract and pagination. Use for 'outgoing transfers' or 'payments from wallet'. NOTE: This is a directional filter of getTransfersOfAccount - prefer using getTransfersOfAccount unless you specifically need only outgoing transfers.

Query transfer events using VeWorld Indexer /api/v1/transfers. Provide either 'address' (wallet, accepts BOTH VNS names like roisin.vet AND 0x hex addresses) or 'tokenAddress' (accepts token symbol like VET, VTHO, B3TR OR 0x hex address) plus optional pagination. Returns enriched transfers with VNS names and token symbols when available. Use for 'wallet transfers', 'token movements', or 'activity for contract/wallet'.

Query VeWorld Indexer /api/v1/transfers/to for incoming transfers. Required 'address' (recipient, accepts BOTH VNS names like roisin.vet AND 0x hex addresses). Optional 'tokenAddress' (accepts token symbol like VET, VTHO, B3TR OR 0x hex address) to scope to a specific VIP‑180/ERC-20 contract and pagination. Use for 'incoming transfers' or 'receipts to wallet'. NOTE: This is a directional filter of getTransfersOfAccount - prefer using getTransfersOfAccount unless you specifically need only incoming transfers.

Fetch VTHO rewards per block via /api/v1/validators/blocks. Returns blockReward (base), priorityReward (mempool priority fees), total, and the split into delegatorRewards and validatorRewards. Filter by blockNumber, validator, and status. Use status=VALIDATED for produced blocks or status=MISSED for blocks the validator missed. Supports pagination and sort direction.

Retrieve delegation records via /api/v1/validators/delegations. Filter by validator, tokenId, and one or more statuses. Supports pagination and sort direction. Get information on delegations to a validator and the Stargate NFTs that are delegated to the validator

Calculate percentage of missed blocks for a validator in a block range via /api/v1/validators/blocks/missed/{validator}. Provide startBlock (inclusive) and endBlock (inclusive). Returns a percentage (0..100).

Fetch validator metadata (name, location, description, website, logo) for the current network. Data source: validator-hub. Supports optional filtering by address.

Retrieve validator statistics via /api/v1/validators for Stargate NFT delegation decisions and validator performance. IMPORTANT: Look at all no status filter when getting validators when getting nft yields, when getting current validator not nft yields look at status=ACTIVE

KEY METRICS:

• nftYieldsIfDelegatedNextCycle: Projected APY (%) for each Stargate NFT level in the next cycle if delegated to this validator (use this for delegation decisions)

• nftYields: Current-cycle APY (%) for each Stargate NFT level already delegated to this validator

• blockProbability: Validator's chance of producing blocks (higher = more rewards)

• percentageOffline: Validator uptime reliability (lower = better)

• delegatorTvl: Total USD value delegated by Stargate NFTs (higher = more competition)

FILTERS:

• validatorId: Filter by specific validator address

• endorser: Filter by endorser address

• status: NONE, QUEUED, ACTIVE, EXITED, EXITING - only filter by ACTIVE for currently operating validators and all when getting nft yields

SORTING (sortBy parameter):

• For NFT delegation: Use 'nft:' (e.g., 'nft:Dawn', 'nft:Thunder') to sort by APY IMPORTANT: When sorting by NFT yield, filter by status=ACTIVE or include QUEUED validators

• Other options: validatorTvl, totalTvl, blockProbability, delegatorTvl

PAGINATION: Supports page, size, cursor, and direction (ASC/DESC)

VALIDATOR RECOMMENDATION GUIDELINES:

1. Primary metric: nftYieldsIfDelegatedNextCycle[level] - this is APY percentage, NOT absolute VTHO

2. Sort by the user's NFT level (e.g., sortBy='nft:Dawn' for Dawn NFTs)

3. Filter to status=ACTIVE for currently operating validators

4. Consider percentageOffline as secondary factor (reject if >30%)

5. Present top 3-5 options with APY clearly labeled as percentage

List VeBetterDAO xApps directly from the on-chain X2EarnApps registry. For each app returns: id, on-chain name, owner (teamWalletAddress), createdAtTimestamp, roles (admin, moderators, creators, rewardDistributors), endorsement status (isEndorsed, endorsementScore vs threshold, isUnendorsed/grace period, isBlacklisted, isEligibleNow), whether the app is active in the current XAllocationVoting round, and IPFS metadata (description, website, logo, banner, social links, categories, distribution_strategy). Supports filtering to a single appId, to apps active in the current round, and by category (array of category ids, case-insensitive, OR semantics — sourced from IPFS metadata). Uses the VeChain SDK multicall for efficiency.

Query legacy VeVote (Stakeholder and Steering Committee Governance contracts) historic proposals from /api/v1/vevote/historic-proposals. By default excludes test proposals (testProposals=false). Supports filtering by proposalId or legacy contractAddress and pagination.

Fetch aggregated voting results per support from /api/v1/vevote/proposal/results. Optional filters: proposalId, support; supports pagination.

List the contracts the MCP server can talk to via the generic callContract and buildContractTransaction tools. For each entry returns the registry name (use this in clause.name), the on-chain addresses for mainnet and testnet, how many read / write / event fragments the ABI exposes, and whether an explicit address is required. The full ABI is NOT included to keep the context small — fetch it with getContractAbi when needed. Available categories: vebetterdao (B3TR, VOT3, governance, X2EarnApps, …), stargate (Stargate, StargateNFT, StargateDelegation, NodeManagement) and standard (erc20, erc721).

Search the VeBetterDAO Discourse forum (vechain.discourse.group) for topics, discussions, and community posts. Returns 10 results by default. OPTIONAL FEATURE: Requires Discourse MCP server running separately: npx -y @discourse/mcp@latest --transport http --site https://vechain.discourse.group. If not available, propose manually visiting forum links found in proposal descriptions. USE CASE: If a proposal's IPFS description doesn't contain a direct Discourse link, search by proposal ID or title to find related forum discussions.

Search the Stargate documentation

Search the VeBetterDao documentation

Search the VeChain documentation

Search the VeChain Kit documentation

Search the VeVote documentation