Skip to main content
Glama

mcp-server

by io.github.realopengroup
OverviewDiscussionsAdmin

link_wallet_xpub

DestructiveIdempotent

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.7/5.0
Behavior5/5

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

Annotations flag destructiveHint=true/openWorldHint=true/idempotentHint=true, and the description goes well beyond that by explaining the verified-vs-pending binding states, that nothing counts toward Proof of Funds until verification, the automatic rescan that follows linking, the binding-failure error case, and hard safety rules about private keys and seed phrases. This is unusually rich behavioral disclosure for a mutation tool.

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

Conciseness3/5

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

The most decision-critical facts (chain restriction, verb, effect) are front-loaded, and ALL-CAPS headings give structure. But the description is very long, with wallet-export instructions and multisig guidance that arguably belong in get_faq/get_snippets siblings, and several clauses restate the same behavior, so it is dense rather than tight.

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?

For a tool with rich annotations, a full input schema and an existing output schema (xpub_scan results), the description covers the remaining gaps: supported chains, unlink behavior, pending verification lifecycle, binding-failure recovery, and the multisig exception. An agent has everything needed to call it correctly.

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

Parameters4/5

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

Schema coverage is 100%, so the schema already documents all three parameters; however, the description adds real meaning beyond it, including the multisig output-descriptor/Unchained-config alternative for xpub, the warning that a lone Ypub/Zpub is one cosigner, and that unlink reverts balance to the verified address.

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?

States a specific verb (link/remove) and resource (extended public key / xpub) and immediately scopes supported chains (BTC, Zcash transparent, Dogecoin) plus the effect on balance and Proof of Funds. It is clearly distinguishable from siblings like add_wallet and verify_wallet_signature, which address wallet creation and signature verification rather than key linking.

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?

Explicit trigger conditions are given: use when a verified BTC wallet shows less than expected, when get_wallet_summary or refresh_wallet_balance returns full_wallet_hint, or when the user mentions a hardware/HD wallet. It also names the sequencing (offer right after add_wallet) and the conditions under which to use unlink or supply a multisig descriptor instead of a single xpub.

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