Skip to content

feat(express): add API endpoint to verify private key matches wallet#9345

Draft
bitgo-ai-agent-dev[bot] wants to merge 1 commit into
masterfrom
WCI-1139-verify-private-key-matches-wallet
Draft

feat(express): add API endpoint to verify private key matches wallet#9345
bitgo-ai-agent-dev[bot] wants to merge 1 commit into
masterfrom
WCI-1139-verify-private-key-matches-wallet

Conversation

@bitgo-ai-agent-dev

Copy link
Copy Markdown

What

  • Add POST /api/v2/{coin}/wallet/{id}/verifyPrivateKey endpoint to BitGo Express
  • The endpoint accepts either a plaintext private key (prv) or an encrypted private key (encryptedPrv + walletPassphrase)
  • Fetches the wallet's user keychain from BitGo automatically when publicKey is not provided (uses commonKeychain for TSS wallets, pub for standard wallets)
  • Delegates cryptographic verification to coin.assertIsValidKey, which handles both standard (onchain) and TSS wallet key types
  • Returns { valid: true } on success; returns 400 for missing required params; propagates errors for key mismatches

Why

  • Users need a way to verify that a private key they hold actually corresponds to a specific wallet's user keychain, without having to sign a transaction
  • This is useful for key auditing, recovery workflows, and onboarding validation where operators want to confirm they have the correct key before committing to a transaction

Test plan

  • 24 unit tests passing covering codec validation, route definition, successful verification, automatic public key fetching, TSS key type, encryptedPrv flow, and all error cases (missing prv, missing walletPassphrase, key mismatch, wallet not found)
  • Manually test with a real BTC wallet using POST /api/v2/tbtc/wallet/:id/verifyPrivateKey with valid and invalid keys

Ticket: WCI-1139

Add POST /api/v2/{coin}/wallet/{id}/verifyPrivateKey endpoint to
BitGo Express. The endpoint accepts either a plaintext private key
(prv) or an encrypted private key (encryptedPrv + walletPassphrase)
and verifies that it matches the wallet's user keychain by calling
coin.assertIsValidKey. When no publicKey is provided the user
keychain's pub (or commonKeychain for TSS wallets) is fetched from
BitGo automatically.

Ticket: WCI-1139

Co-Authored-By: Claude <noreply@anthropic.com>
Session-Id: b17db9f7-ab01-4cc9-ba52-3b1fb87cb276
Task-Id: 77daf7cf-15f3-4405-9967-bd3c8150be94
@bitgo-ai-agent-dev
bitgo-ai-agent-dev Bot force-pushed the WCI-1139-verify-private-key-matches-wallet branch from c4ab408 to 888bdee Compare July 24, 2026 06:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

0 participants