mcp-server

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

Name	Required	Description
`xpub`	No	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.
`unlink`	No	Set true to remove a previously linked extended key; the balance then reverts to the verified address (plus transfer-proven addresses).
`wallet_id`	Yes	Internal wallet UUID of the verified Bitcoin, Zcash or Dogecoin wallet, from get_wallet_summary. Do NOT show this ID to the user.

Output Schema

Name	Required	Description
`assets`	No
`status`	Yes	linked \| pending_verification \| unlinked
`address`	No
`binding`	No	active (bound to a proven address) \| pending (activates when the wallet is verified)
`message`	No
`total_usd`	No
`wallet_id`	No
`xpub_scan`	No	Scan summary: total_btc, total_usd, funded_address_count, addresses_scanned, truncated, scanned_at
`blockchain`	No
`bound_path`	No	chain/index of the verified address within the account, e.g. 0/3
`script_type`	No	Address type the key derives: p2wpkh (bc1q), p2tr (bc1p), p2sh-p2wpkh (3…), p2pkh (1…)

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedOct 26, 2026

removedInput schema / additionalProperties
```
Removed value: -false
```
changedOutput schema / properties / assets / items / additionalProperties
```
Previous value: -trueNew value: +{}
```

changedOutput schema / properties / xpub_scan / anyOf

Previous value: -[
-  {
-    "additionalProperties": true,
-    "properties": {},
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": {},
+    "properties": {},
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

Changed1 schema field changedSep 15, 2026

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."

Changed2 schema fields changedSep 6, 2026

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."

Changed2 schema fields changedSep 5, 2026

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"

Changed1 schema field changedSep 5, 2026

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."

AddedSep 4, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Beyond annotations, the description discloses verified vs pending binding behavior, automatic activation after verification, what happens on binding failure, that future refreshes rescan automatically, and that unlink reverts balance to the verified address. It also includes strong safety guidance about never accepting private keys or seed phrases and explains the privacy tradeoff of sharing an xpub.

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 front-loaded with scope, purpose, and usage triggers before moving into wallet-specific export instructions and safety notes. It is long but information-dense; a minor trim of wallet-by-wallet export details could improve it, but little is wasted.

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 complex, stateful wallet-linking tool, the description covers the full operational picture: supported coins, verified and pending states, multisig handling, unlink behavior, safety constraints, and user-facing export locations. An output schema exists, so return-value details are appropriately left to it.

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?

Schema description coverage is 100%, so the schema already documents xpub formats, multisig descriptors, unlink behavior, and wallet_id. The description adds useful context about pending vs verified wallet states, but most parameter-specific meaning is already present in the schema, making 3 the appropriate baseline.

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 states a specific verb and resource: link or remove the extended PUBLIC key of a verified Bitcoin, Zcash, or Dogecoin wallet. It clearly distinguishes this from adding a single wallet address by explaining that every receive/change address in the account counts toward balance and Proof of Funds.

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 explicit triggers: use when a verified BTC wallet shows less than expected, when get_wallet_summary or refresh_wallet_balance returns full_wallet_hint, when the user mentions a hardware or HD wallet, and right after add_wallet for relevant users. It also names alternatives and special cases, including unlink and multisig descriptor handling.

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

All mcp-server tools Inspect

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.