@orangecheck/wallet-adapter

Full reference: ochk.io/docs/sdk/wallet-adapter — auto-generated from the TypeScript source on every release. Hand-written prose below is the high-level overview; the docs site is the source of truth for every export, type, and signature.

Normalize browser Bitcoin wallets behind a single sign(message) API.

UniSat, Xverse, Leather, OKX, Phantom — every wallet exposes a different signing API. This package hides that behind one shape:

const sign = getSigner('unisat', { address });
const signature = await sign(message);

Pairs cleanly with <OcChallengeButton sign={sign} /> from @orangecheck/react, or with the lower-level primitives.

yarn add @orangecheck/wallet-adapter

React components are under a subpath to keep the core library zero-dep:

import { detectWallets, getSigner } from '@orangecheck/wallet-adapter';
import { OcWalletButton } from '@orangecheck/wallet-adapter/react';

detectWallets()

Return every supported wallet with a detected flag.

import { detectWallets } from '@orangecheck/wallet-adapter';

detectWallets();
// [
//   { id: 'unisat',  name: 'UniSat',  detected: true,  installUrl: '...' },
//   { id: 'xverse',  name: 'Xverse',  detected: false, installUrl: '...' },
//   { id: 'leather', name: 'Leather', detected: false, installUrl: '...' },
//   { id: 'manual',  name: 'Paste signature (Sparrow / Core / hardware)',
//     detected: true, isManual: true }
// ]

Use to render install prompts for missing wallets and "sign with" buttons for installed ones.

getSigner(id, { address })

Return a SignFn bound to a particular wallet.

import { getSigner } from '@orangecheck/wallet-adapter';

const sign = getSigner('unisat', { address: userBtcAddress });
const signature = await sign(canonicalMessage);

For the manual wallet (Sparrow, Bitcoin Core, a hardware wallet), pass onManualSign: it receives the message, shows it however your UI does, and resolves with the pasted signature.

const sign = getSigner('manual', {
    address: userBtcAddress,
    onManualSign: (message) => openPasteDialog(message), // resolves with the paste
});

Without onManualSign, manual falls back to window.prompt with a one-time console warning; that fallback is deprecated and will be removed. Outside a browser it throws ManualSignUnavailable (code: 'E_MANUAL_SIGN_UNAVAILABLE'). <OcWalletButton /> renders its own paste panel and needs neither.

SignFn is (message: string) => Promise<string>. Throws when the wallet isn't available or the user cancels, and throws WrongAccountError (code: 'E_WRONG_ACCOUNT') when the signature is not by address — some wallets sign with their active account whatever address is asked for. verifyBip322({ address, message, signature }) resolves to whether a signature obtained elsewhere passes the same check (BIP-322 or legacy BIP-137, base64 or hex); assertSignedBy({ address, message, signature }) throws WrongAccountError instead.

Telling a person what failed

A wallet's own error text is not for people ("User rejected the request", a bare { code: 4001 }). walletFailureText(err) gives one sentence for each cause, the same on every site:

| walletFailure(err) | Thrown as | walletFailureText(err) | | --- | --- | --- | | rejected | WalletRejectedError (E_USER_REJECTED) | The request was declined in your wallet. Sign again when you are ready. | | wrong-account | WrongAccountError (E_WRONG_ACCOUNT) | That signature is not from the address shown. Switch your wallet to that address, then sign again. | | not-found | WalletNotFoundError (E_WALLET_NOT_FOUND) | That wallet is not in this browser. Install it, or choose another wallet. | | timed-out | a TimeoutError | Your wallet did not answer. Open it to finish the request, then try again. | | other | anything else | Your wallet did not sign. Try again. |

Pass { paste: true } where the page also offers to paste a signature, and the sentence offers it too. getSigner always throws an Error, keeping the wallet's code, so OcWalletButton's onError can be handed straight to it:

<OcWalletButton address={address} message={message} onSigned={finish}
  onError={(err) => setError(walletFailureText(err, { paste: true }))} />

<OcWalletButton /> (React)

Pre-built wallet picker that detects installed wallets, lets the user pick one, and calls onSigned with the signature.

import { OcWalletButton } from '@orangecheck/wallet-adapter/react';

<OcWalletButton
    address={userBtcAddress}
    message={challenge.message}
    onSigned={(sig, walletId) => {
        console.log(`${walletId} returned`, sig);
        postVerify({ signature: sig });
    }}
    onError={(err) => console.error(err)}
/>;

Props:

| Prop | Type | Notes | | -------------------- | ------------------------- | ---------------------------------------------------------------- | | address | string | Required by some wallets (Xverse, Leather). | | message | string | Canonical message to sign (e.g. from /api/challenge). | | onSigned | (sig, walletId) => void | Success callback. | | onError | (err, walletId) => void | Failure callback. | | hideUninstalled | boolean | Default false — uninstalled wallets render as install prompts. | | heading | ReactNode | Header text. Default "Sign with your wallet". | | className, style | | Pass-through for the root container. |

Appearance

OcWalletPicker and OcWalletButton read --oc-wallet-* CSS variables for font, case, tracking, scale, weight, radii, row height, surface, the ready dot, the paste field's size and the decorative marks. @orangecheck/app-design ≥ 1.1.0 sets them; set none and the components keep the family's monospace look. Every variable and its fallback is listed in src/appearance.ts and the 0.6.0 CHANGELOG entry.

Full example — signed-challenge auth with wallet picker

import { useState } from 'react';
import { OcWalletButton } from '@orangecheck/wallet-adapter/react';

export function SignIn({ address }: { address: string }) {
  const [step, setStep] = useState<'idle' | 'ready' | 'done'>('idle');
  const [message, setMessage] = useState('');
  const [proven, setProven] = useState('');

  async function issueChallenge() {
    const r = await fetch(`/api/challenge?addr=${address}`);
    const { message } = await r.json();
    setMessage(message);
    setStep('ready');
  }

  async function handleSigned(signature: string) {
    const r = await fetch('/api/challenge', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ message, signature }),
    });
    const body = await r.json();
    if (body.ok) {
      setProven(body.address);
      setStep('done');
    }
  }

  if (step === 'idle') return <button onClick={issueChallenge}>Start sign-in</button>;
  if (step === 'ready') {
    return <OcWalletButton address={address} message={message} onSigned={handleSigned} />;
  }
  return <p>Signed in as {proven}</p>;
}

Wallet details (for the curious)

| Wallet | Global | BIP-322 style | | ------------ | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | UniSat | window.unisat.signMessage(msg, 'bip322-simple') | Simple | | Xverse | window.BitcoinProvider.request('signMessage', { address, message, protocol: 'BIP322' }) | Full | | Leather | window.LeatherProvider.request('signMessage', { message, paymentType: 'p2tr' }) | Full | | Manual | The caller's onManualSign (deprecated fallback: window.prompt) | Caller's wallet produces the signature out-of-band |

The shims are duck-typed — we check shape, not just presence of globals, so spoofing wrappers don't produce false positives.

Alby is not listed. webln.signMessage signs with a Lightning node key, not a Bitcoin address, so no signature it makes verifies as BIP-322. getSigner('alby') refuses without prompting. Offer the paste option so people on hardware wallets (Sparrow, Bitcoin Core, Ledger) can still sign.

Security note on detection: XverseProviders used to pass if it was any truthy value. As of 0.1.1 we require a callable BitcoinProvider.request function so a bookmarklet or unrelated extension setting window.XverseProviders = {} won't register as Xverse.

UniSat fallback: earlier versions silently fell back from bip322-simple to the legacy ECDSA signMessage on any error. That produced signatures segwit/taproot verifiers couldn't accept. As of 0.1.1 we only sign BIP-322 — if the wallet throws, the error propagates so the caller can suggest switching wallets or using paste mode.

License

MIT.