Getting Started

Get a dApp-to-wallet connection running in under 5 minutes.

Install the SDK

bash 
# Clone the repo and link locally (SDK not yet published to npm)
git clone https://github.com/atshelchin/walletpair.git
cd walletpair/walletpair-sdk
npm install && npm link

The SDK is not yet published to npm. Link it locally from the monorepo for now.

Start a Relay

You need a relay server to route messages between peers. Use the public relay at wss://relay.walletpair.org/v1 for development, or self-host your own.

dApp Side

Create a DAppSession, generate a pairing URI, and display it as a QR code for the wallet to scan.

dapp.ts 
import { DAppSession, WebSocketTransport } from 'walletpair-sdk';

const transport = new WebSocketTransport('wss://relay.walletpair.org/v1');
const session = new DAppSession({
  transport,
  meta: {
    name: 'My dApp',
    description: 'Example dApp',
    url: 'https://dapp.example',
    icon: 'https://dapp.example/icon.png',
  },
  methods: ['wallet_getAccounts', 'wallet_sendTransaction', 'wallet_signMessage'],
  chains: ['eip155:1', 'eip155:137'],
});

// Create pairing - display the URI as a QR code
const uri = await session.createPairing();

session.on('sessionFingerprint', (fingerprint) => {
  console.log('Session fingerprint (verify matches wallet):', fingerprint);
});

session.on('phase', async (phase) => {
  if (phase !== 'connected') return;
  const result = await session.request('wallet_getAccounts');
  console.log('Accounts:', result);
});

Wallet Side

Create a WalletSession, scan the QR code, verify the session fingerprint, and handle incoming requests.

wallet.ts 
import { WalletSession, WebSocketTransport } from 'walletpair-sdk';

const transport = new WebSocketTransport('wss://relay.walletpair.org/v1');
const session = new WalletSession({
  transport,
  capabilities: {
    methods: ['wallet_getAccounts', 'wallet_sendTransaction', 'wallet_signMessage'],
    events: ['accountsChanged', 'chainChanged'],
    chains: ['eip155:1', 'eip155:137'],
  },
  meta: {
    name: 'My Wallet',
    description: 'Example wallet',
    url: 'https://wallet.example',
    icon: 'https://wallet.example/icon.png',
  },
});

// Parse the scanned QR code and join
await session.prepareJoin(pairingUri);
console.log('Session fingerprint:', session.sessionFingerprint);
await session.confirmJoin();

session.on('request', async (req) => {
  // Review and respond to requests
  await session.approve(req.id, { accounts: ['0x...'] });
});

Verify the Fingerprint

Both the dApp and wallet derive a 4-digit session fingerprint from the handshake transcript. Users should visually confirm these match to prevent man-in-the-middle attacks.

Next Steps