Skip to main content
Glama

mcp-server

by io.github.realopengroup

refresh_wallet_balance

Idempotent

Re-fetch on-chain asset balances for an existing wallet and update the stored record. Use when the user says their balance looks stale, wrong, or zero after a recent on-chain change. Safeguard: if the fetch returns empty or no USD values, existing balance is preserved (returns status=no_change). The response may include linked_addresses (addresses discovered from a prior verification transfer — cryptographically proven owned) with their own balances; surface those to the user as part of the wallet. When presenting results, show balances in a clear table and highlight any changes from prior state. ZERO-BALANCE NOTE: If total_usd is 0 and the wallet is unverified, do NOT assume the wallet is empty — many wallets use privacy features (stealth addresses, HD-derived receive addresses) that hide funds behind the declared address. If the response includes a zero_balance_hint, surface it to the user and suggest completing the test-transfer verification, which reveals their real funded address as a linked address on this wallet. BITCOIN FULL-WALLET NOTE: for Bitcoin the response may include xpub_linked (true when the user has linked their wallet's extended public key — the balance then covers every derived address, and xpub_scan summarises the scan) or full_wallet_hint (a verified BTC wallet with no xpub yet). When full_wallet_hint is present and the user thinks the balance is low, relay the hint and offer link_wallet_xpub. ZCASH: transparent_only_hint means only transparent (t1…) balances count — shielded ZEC is invisible and must be moved to a t-address first.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
wallet_idYesInternal wallet UUID from a prior get_wallet_summary or add_wallet response. Do NOT show this ID to the user or ask them for it — look it up from the address they mentioned.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
assetsNoPer-asset balances on the wallet
statusYesrefreshed | no_change
addressNo
messageNo
total_usdNo
wallet_idNo
xpub_scanNoBitcoin only: summary of the last extended-key scan (script_type, total_btc, total_usd, funded_address_count, scanned_at)
blockchainNo
xpub_linkedNoBitcoin only: true when an extended public key is linked and the balance covers every derived address
full_wallet_hintNoBitcoin/Zcash: present for verified wallets with no extended key linked — how to count the full wallet via link_wallet_xpub
linked_addressesNoAdditional addresses proven owned via a prior verification transfer
zero_balance_hintNoSurfaced when balance is 0 and the wallet is unverified — explains stealth/HD addressing
transparent_only_hintNoZcash only: only transparent (t1…) balances are verified and counted; shielded ZEC must be moved to a t-address first

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. Changed2 schema fields changed
    • changedOutput schema / properties / full_wallet_hint / description
      Previous value: -"Bitcoin only: present for verified wallets with no extended key linked — how to count the full wallet via link_wallet_xpub"New value: +"Bitcoin/Zcash: present for verified wallets with no extended key linked — how to count the full wallet via link_wallet_xpub"
    • addedOutput schema / properties / transparent_only_hint
      Added value: +{
+  "description": "Zcash only: only transparent (t1…) balances are verified and counted; shielded ZEC must be moved to a t-address first",
+  "type": [
+    "string",
+    "null"
+  ]
+}
  2. Changed3 schema fields changed
    • addedOutput schema / properties / full_wallet_hint
      Added value: +{
+  "description": "Bitcoin only: present for verified wallets with no extended key linked — how to count the full wallet via link_wallet_xpub",
+  "type": [
+    "string",
+    "null"
+  ]
+}
    • addedOutput schema / properties / xpub_linked
      Added value: +{
+  "description": "Bitcoin only: true when an extended public key is linked and the balance covers every derived address",
+  "type": "boolean"
+}
    • addedOutput schema / properties / xpub_scan
      Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": true,
+      "properties": {},
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Bitcoin only: summary of the last extended-key scan (script_type, total_btc, total_usd, funded_address_count, scanned_at)"
+}
  3. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "address": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "assets": {
+      "description": "Per-asset balances on the wallet",
+      "items": {
+        "additionalProperties": true,
+        "properties": {},
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "blockchain": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "linked_addresses": {
+      "description": "Additional addresses proven owned via a prior verification transfer",
+      "items": {
+        "additionalProperties": true,
+        "properties": {},
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "message": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "status": {
+      "description": "refreshed | no_change",
+      "type": "string"
+    },
+    "total_usd": {
+      "type": [
+        "number",
+        "null"
+      ]
+    },
+    "wallet_id": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "zero_balance_hint": {
+      "description": "Surfaced when balance is 0 and the wallet is unverified — explains stealth/HD addressing",
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "required": [
+    "status"
+  ],
+  "type": "object"
+}
  4. Added

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description goes far beyond the annotations: it discloses that empty or no-USD fetches preserve the existing balance and return status=no_change, explains linked_addresses as cryptographically proven owned, warns against assuming zero-balance wallets are empty, and explains consolidation_hint behavior. This is consistent with annotations; readOnlyHint=false aligns with 'update the stored record.'

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose and trigger are front-loaded, and the long caveats are clearly labeled as notes. However, the zero-balance warning is repeated across the ZERO-BALANCE, BITCOIN, and ZCASH notes, and the description appears to end mid-sentence at the Zcash note, so it is somewhat longer and less tidy than ideal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the trigger, mutation semantics, preservation behavior, linked addresses, presentation requirements, and multiple zero-balance edge cases. The output schema handles return-shape details. The main gap is that the text appears truncated at the Zcash note, leaving that final instruction incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already fully documents wallet_id, including that it is an internal UUID from get_wallet_summary or add_wallet and should not be shown to the user. With 100% schema description coverage, the description adds no additional parameter-level semantics, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Re-fetch on-chain asset balances for an existing wallet and update the stored record.' It clearly distinguishes this tool from siblings like get_wallet_summary or refresh_wallet_verification by centering on balance refresh and update semantics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit trigger: 'Use when the user says their balance looks stale, wrong, or zero after a recent on-chain change.' It also provides conditional guidance for empty results, zero-balance hints, BTC consolidation hints, and Zcash re-fetch/linking suggestions, which tells an agent how to behave in key edge cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All mcp-server toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.4/5.0
Disambiguation4/5

Most tools have clearly distinct purposes (wallet management, verification, knowledge lookup, marketing, account status), but there is minor overlap between add_wallet and refresh_wallet_verification (both generate verification challenges) and between get_started and get_account_status (both touch on next-step resolution). Descriptions clarify the differences, so confusion is unlikely.

Naming Consistency5/5

All tool names follow a consistent verb_noun snake_case pattern (e.g., add_wallet, get_wallet_summary, verify_wallet_transfer), with only 'logout' as a single verb, which is still consistent with the imperative style. No mixed conventions or cryptic names.

Tool Count4/5

The server exposes 20 tools, which is on the heavier side of the typical range but appropriate for the broad domain (wallet operations, verification, KYC, knowledge base, marketing assets, referral tracking). Each tool has a distinct role, so the count feels justified rather than bloated.

Completeness5/5

The surface covers the full lifecycle for crypto-to-real-estate transactions: wallet management (add, remove, refresh, verify), identity verification, proof-of-funds generation, knowledge tools (fees, coverage, supported crypto, how-it-works), marketing (snippets, assets, referral), and account navigation (get_started, logout). No obvious gaps that would leave an agent stuck.

Resources