Skip to main content

Import a view-only wallet

A view-only wallet lets you derive addresses and check balances without the ability to sign transactions. This is useful for:

  • Monitoring wallets without exposing private keys
  • Building read-only dashboards
  • Address verification workflows

ChainGate supports two types of view-only wallets:

Import from xpub​

An xpub (extended public key) allows deriving multiple public addresses (like an HD wallet) but cannot sign transactions:

import { importWallet } from 'chaingate'

const wallet = importWallet({ xpub: 'xpub6CUGRUonZSQ4TWtTMmzXdrXDtypWKiKrhko4egpiMZbpiaQL2jkwSB1icqYh2cfDfVxdx4df189oLKnC5fSwqPfgyP3hooxujYzAu3fDVmz' })

Using the xpub wallet​

import { importWallet, ChainGate } from 'chaingate'

const wallet = importWallet({ xpub: 'xpub6CUGRUo...' })
const cg = new ChainGate({ apiKey: 'your-api-key' })

const bitcoin = cg.connect(cg.networks.bitcoin, wallet)

// Derive multiple addresses
const address0 = await bitcoin.address()             // m/0/0
const address1 = await bitcoin.address({ index: 1 }) // m/0/1
const address2 = await bitcoin.address({ index: 2 }) // m/0/2

// Check balances
const { confirmed } = await bitcoin.addressBalance()
console.log('Balance:', confirmed.base().toString(), confirmed.symbol)
Cannot sign

Attempting to call transfer() or signAndBroadcast() on a view-only wallet will throw an UnsupportedOperationError.

Import from public key​

A public key wallet can derive a single address for any supported network:

import { importWallet } from 'chaingate'

// Compressed public key (33 bytes / 66 hex chars)
const wallet = importWallet({ publicKey: '02a1633cafcc01ebfb6d78e39f687a1f0995c62fc95f51ead10a02ee0be551b5dc' })

// Or as Uint8Array
const wallet2 = importWallet({ publicKey: new Uint8Array([0x02, 0xa1, /* ... */]) })

Using the public key wallet​

const cg = new ChainGate({ apiKey: 'your-api-key' })
const ethereum = cg.connect(cg.networks.ethereum, wallet)

const address = await ethereum.address()
const { confirmed } = await ethereum.addressBalance()
Single address only

Public key wallets do not support derivation — only index: 0 is valid. For monitoring multiple addresses, use an xpub wallet instead.

Checking wallet capabilities​

Use the supports() type guard to check if a wallet can sign:

import { supports } from 'chaingate'

if (supports(wallet, 'viewonly')) {
  console.log('This is a view-only wallet — cannot sign transactions')
}

if (supports(wallet, 'signingwallet')) {
  console.log('This wallet can sign transactions')
}

if (supports(wallet, 'hdwallet')) {
  console.log('This wallet supports multiple address derivation')
}

Key points​

  • xpub: Derives multiple addresses. Cannot sign. Useful for monitoring HD wallets.
  • public key: Derives a single address. Cannot sign. Useful for verifying or monitoring a specific address.
  • No private material: View-only wallets never contain private keys, seeds, or phrases.
  • Synchronous: Import is instantaneous — no API key or async call needed.
  • Same connector API: Use address(), addressBalance(), and addressHistory() just like any other wallet.