Skip to main content
Glama

mcp-server

by io.github.realopengroup
OverviewDiscussionsAdmin

link_wallet_xpub

Idempotent

BITCOIN, ZCASH (transparent) AND DOGECOIN ONLY. Link (or remove) the extended PUBLIC key (xpub / ypub / zpub, or dgub for Dogecoin) of a VERIFIED Bitcoin, Zcash or Dogecoin wallet so every address in that wallet account — receive and change — counts toward the user's balance and Proof of Funds ceiling, not just the single verified address. Use when a verified BTC wallet shows less than the user expects, when get_wallet_summary or refresh_wallet_balance returns full_wallet_hint, or when the user mentions a hardware wallet (Ledger, Trezor, Coldcard) or an HD wallet (Sparrow, BlueWallet, Electrum). The wallet can be verified OR not yet verified. Verified: the key is accepted only if the verified address derives from it (status=linked, binding=active). Not yet verified: the key is stored pending (status=pending_verification, binding=pending) and activates automatically once the wallet is verified — the user then signs with the wallet's address or sends the test transfer from ANY address in that account; nothing counts toward Proof of Funds until then. Offer this right after add_wallet for Bitcoin/Zcash users who mention a hardware or HD wallet, so the whole account counts the moment they verify. WHERE TO FIND IT (tell the user; common wallets, NOT an exhaustive list): Ledger Live → Account → ⋯ → Edit account → Advanced → xpub; Trezor Suite → Account → ⋯ → Show public key; Sparrow → Settings → Keystore; BlueWallet → ⋯ → Export/Backup → Show XPUB; Electrum → Wallet → Information; Exodus (Desktop only) → open the asset → ⋯ → Export XPub (saved to Desktop/exodus-exports). Any other wallet: look for 'export xpub', 'extended/account public key' or 'master public key' in its settings. Ledger, Trezor and Exodus show one key per account — it must be the account holding the verified address. Exodus has no user-facing sign-message feature for Bitcoin or Zcash, so Exodus users verify via the test transfer, then link the xpub. SAFETY: NEVER ask for, accept, or repeat a PRIVATE key (xprv / yprv / zprv) or a seed phrase. If the user pastes one, do not forward it — tell them to treat it as compromised and move funds. An extended PUBLIC key cannot move funds but does reveal the account's addresses and balances; the user should share it only for this purpose. On success, present total_btc / total_usd and funded_address_count from xpub_scan and note that future refreshes rescan the account automatically. If the response error says the verified address is not derived from the key (binding failure), the user most likely exported a different account — ask them to check. Pass unlink: true to remove a previously linked key. MULTISIG (Bitcoin only): a multisig wallet (Sparrow/Nunchuk/Unchained/Casa-style k-of-n) has no single xpub — pass its output descriptor or Unchained wallet config instead; RealOpen derives every receive/change address of the multisig account. Multisig addresses cannot sign messages, so the wallet is verified by the test transfer (verify_wallet_transfer) and the descriptor binds to that transfer's input address; it can be attached before verification (pending) exactly like an xpub.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
xpubNoThe extended PUBLIC key exactly as exported by the wallet (starts with xpub, ypub, zpub or dgub; ~111 characters) — OR, for a Bitcoin MULTISIG wallet, its full output descriptor (e.g. wsh(sortedmulti(2,[fp/48h/0h/0h/2h]xpub…/<0;1>/*,…)) — Sparrow: Settings → Export → Output Descriptor; Nunchuk: Export → BSMS) or the Unchained/Caravan wallet configuration JSON. A lone Ypub/Zpub is one cosigner and is NOT enough. Omit when unlink is true. NEVER pass anything containing xprv/yprv/zprv/Yprv/Zprv/dgpv.
unlinkNoSet true to remove a previously linked extended key; the balance then reverts to the verified address (plus transfer-proven addresses).
wallet_idYesInternal wallet UUID of the verified Bitcoin, Zcash or Dogecoin wallet, from get_wallet_summary. Do NOT show this ID to the user.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
assetsNo
statusYeslinked | pending_verification | unlinked
addressNo
bindingNoactive (bound to a proven address) | pending (activates when the wallet is verified)
messageNo
total_usdNo
wallet_idNo
xpub_scanNoScan summary: total_btc, total_usd, funded_address_count, addresses_scanned, truncated, scanned_at
blockchainNo
bound_pathNochain/index of the verified address within the account, e.g. 0/3
script_typeNoAddress type the key derives: p2wpkh (bc1q), p2tr (bc1p), p2sh-p2wpkh (3…), p2pkh (1…)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / xpub / description
      Previous value: -"The extended PUBLIC key exactly as exported by the wallet (starts with xpub, ypub, zpub or dgub; ~111 characters). Omit when unlink is true. NEVER pass a key starting with xprv/yprv/zprv/dgpv."New value: +"The extended PUBLIC key exactly as exported by the wallet (starts with xpub, ypub, zpub or dgub; ~111 characters) — OR, for a Bitcoin MULTISIG wallet, its full output descriptor (e.g. wsh(sortedmulti(2,[fp/48h/0h/0h/2h]xpub…/<0;1>/*,…)) — Sparrow: Settings → Export → Output Descriptor; Nunchuk: Export → BSMS) or the Unchained/Caravan wallet configuration JSON. A lone Ypub/Zpub is one cosigner and is NOT enough. Omit when unlink is true. NEVER pass anything containing xprv/yprv/zprv/Yprv/Zprv/dgpv."
  2. Changed2 schema fields changed
    • changedInput schema / properties / wallet_id / description
      Previous value: -"Internal wallet UUID of the verified Bitcoin or Zcash wallet, from get_wallet_summary. Do NOT show this ID to the user."New value: +"Internal wallet UUID of the verified Bitcoin, Zcash or Dogecoin wallet, from get_wallet_summary. Do NOT show this ID to the user."
    • changedInput schema / properties / xpub / description
      Previous value: -"The extended PUBLIC key exactly as exported by the wallet (starts with xpub, ypub or zpub; ~111 characters). Omit when unlink is true. NEVER pass a key starting with xprv/yprv/zprv."New value: +"The extended PUBLIC key exactly as exported by the wallet (starts with xpub, ypub, zpub or dgub; ~111 characters). Omit when unlink is true. NEVER pass a key starting with xprv/yprv/zprv/dgpv."
  3. Changed2 schema fields changed
    • addedOutput schema / properties / binding
      Added value: +{
+  "description": "active (bound to a proven address) | pending (activates when the wallet is verified)",
+  "type": [
+    "string",
+    "null"
+  ]
+}
    • changedOutput schema / properties / status / description
      Previous value: -"linked | unlinked"New value: +"linked | pending_verification | unlinked"
  4. Changed1 schema field changed
    • changedInput schema / properties / wallet_id / description
      Previous value: -"Internal wallet UUID of the verified Bitcoin wallet, from get_wallet_summary. Do NOT show this ID to the user."New value: +"Internal wallet UUID of the verified Bitcoin or Zcash wallet, from get_wallet_summary. Do NOT show this ID to the user."
  5. Added

TDQS

A4.9/5.0
Behavior5/5

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

Annotations only indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false, which are minimal. The description goes far beyond by detailing verification statuses (linked vs pending_verification), the automatic activation upon wallet verification, the safety rule never to accept private keys, the success output (total_btc, total_usd, funded_address_count), and the binding-failure error meaning. It also explains multisig behavior. This fully discloses the tool's behavior.

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 description is extremely long but well-structured: it front-loads the core purpose and conditions, then provides verification details, wallet-specific instructions, safety warnings, success handling, and multisig notes. Every sentence carries operational information, but the length could be trimmed without losing critical guidance. It is appropriately sized for the complexity but not concise; it earns a 4.

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

Completeness5/5

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

Given the tool's complexity (multiple currencies, verification states, multisig, safety), the description is complete. It explains the output format (total_btc, total_usd, funded_address_count) and common error handling (binding failure). It also covers the 'where to find' for common wallets, which is essential for an agent. Nothing an agent needs to invoke correctly is missing.

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

Parameters5/5

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

Although the schema already describes all three parameters at 100% coverage, the description adds crucial semantics: it clarifies the xpub prefixes (xpub, ypub, zpub, dgub), specifies the multisig alternative (output descriptor or Unchained config), explains when to omit xpub (when unlink=true), and explicitly warns never to pass private keys. It also clarifies wallet_id is an internal UUID not to be shown. This adds significant value beyond the schema.

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 scoping (BITCOIN, ZCASH transparent, DOGECOIN ONLY) and a precise verb+resource: 'Link (or remove) the extended PUBLIC key' so that all addresses count toward balance and Proof of Funds. It clearly distinguishes the tool from siblings like add_wallet and refresh_wallet_balance by stating exactly when it applies (hardware/HD wallets, full_wallet_hint).

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?

The description explicitly states when to use it: when a verified wallet shows less than expected, when get_wallet_summary or refresh_wallet_balance returns full_wallet_hint, or when the user mentions hardware/HD wallets. It also instructs to offer it right after add_wallet for relevant users, and explains when to use unlink: true. This is explicit and action-guiding.

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
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources