Integrate Topaz ID

Topaz ID is a global wallet — an email/Google login backed by a self-custodial embedded wallet on BNB Chain, living at id.topazdex.com. Users already have a Topaz ID account; your app lets them reuse it. There is no seed phrase and no browser extension, and the user is always the signer.

@topazdex/id-connectis a thin, open-source wrapper that bakes in Topaz ID’s app id, chain, branding, and public-profile helpers — so you integrate in a few lines instead of wiring @privy-io/cross-app-connect by hand.

• npm: @topazdex/id-connect
• Package source: github.com/topazdex/topaz-id-connect
• Live demo: topaz-id-demo.vercel.app
• Demo source (Next.js): github.com/topazdex/topaz-id-connect-demo

Topaz ID is built on Privy’s global-wallet (cross-app) feature. Your app is the requester; Topaz ID is the provider.

• The package references Topaz ID’s public Privy app id for you. You do not create your own Privy app or pass an app id.
• You don’t even need a Privy account — the connector talks to Topaz ID directly.
• Every signature and transaction opens an isolated Topaz ID consent window. Approval happens on our domain, with our keys, under the user’s control.
• Once connected, the wallet behaves like any EIP-1193 wallet — you use standard wagmi.

• Onboard users with just an email — no wallet friction.
• Reach the Topaz ecosystem of DEX, AI Wallet, and Privacy users.
• Self-custodial by default — the user is always the signer.
• Standard EVM wallet interface on BNB Chain.

1. User clicks connect and picks “Topaz ID” in your wallet list.
2. A Topaz ID window opens; they sign in with their existing account.
3. Your app receives their Topaz ID wallet address.
4. Each transaction or signature is approved in a Topaz ID consent popup.

One package plus the standard wagmi stack. You need no Privy app id of your own.

# Topaz ID is a Privy global wallet — your app references ours.
# You do NOT need your own Privy app or app id.
yarn add @topazdex/id-connect @privy-io/cross-app-connect wagmi viem \
  @rainbow-me/rainbowkit @tanstack/react-query

@privy-io/cross-app-connect pins viem@2.52.0 — match it to avoid peer-dependency warnings.

topazIdWallet() and TOPAZ_ID_CHAIN come ready to use — no app id, icon, or chain config needed.

import { topazIdWallet, TOPAZ_ID_CHAIN } from "@topazdex/id-connect/rainbow-kit";
import { connectorsForWallets } from "@rainbow-me/rainbowkit";
import { createConfig, http } from "wagmi";

// Topaz ID's app id, name, icon, and chain are baked into the package —
// nothing to configure. List it first; add your other wallets alongside.
const connectors = connectorsForWallets(
  [{ groupName: "Sign in", wallets: [topazIdWallet()] }],
  { appName: "Your App", projectId: "<walletconnect-project-id>" },
);

export const wagmiConfig = createConfig({
  chains: [TOPAZ_ID_CHAIN],                 // BNB Chain (id 56)
  transports: { [TOPAZ_ID_CHAIN.id]: http() },
  connectors,
  ssr: true,
});

import "@rainbow-me/rainbowkit/styles.css";
import { WagmiProvider } from "wagmi";
import { RainbowKitProvider } from "@rainbow-me/rainbowkit";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { wagmiConfig } from "./wagmi";

const queryClient = new QueryClient();

export function Providers({ children }) {
  return (
    <WagmiProvider config={wagmiConfig}>
      <QueryClientProvider client={queryClient}>
        <RainbowKitProvider>{children}</RainbowKitProvider>
      </QueryClientProvider>
    </WagmiProvider>
  );
}

import { ConnectButton } from "@rainbow-me/rainbowkit";

// "Topaz ID" now appears in the wallet picker. Selecting it opens a
// Topaz ID consent window where the user signs in with email or Google —
// no new wallet is created.
export function Header() {
  return <ConnectButton />;
}

Topaz ID is a normal EIP-1193 wallet — read the address and send transactions with plain wagmi hooks. Don’t reach for @privy-io/react-authsigning hooks; they are embedded-wallet-only and won’t route through Topaz ID.

import { useAccount, useSendTransaction } from "wagmi";
import { parseEther } from "viem";

// Topaz ID behaves as a normal EIP-1193 wallet — use plain wagmi,
// never @privy-io/react-auth signing hooks.
const { address, isConnected } = useAccount(); // the user's Topaz ID address

const { sendTransactionAsync } = useSendTransaction();
await sendTransactionAsync({
  to: recipient,
  value: parseEther("0.01"),
  chainId: 56, // BNB Chain
});
// A Topaz ID popup asks the user to approve every signature and transaction.

Topaz ID owns each wallet’s name, handle, and avatar. The package ships helpers and a React Query hook so you can render a real identity instead of a bare address.

import { displayNameForWallet, avatarForWallet } from "@topazdex/id-connect";
import { useTopazIdProfile } from "@topazdex/id-connect/react";

// React Query hook — public, CORS-open, no auth. (For non-React apps,
// use fetchTopazIdProfile() from the root entry instead.)
const { data: profile } = useTopazIdProfile(address);

// @handle → name → 0x1234…abcd, with safe fallbacks.
const label = displayNameForWallet(profile ?? null, address);
const avatar = avatarForWallet(profile ?? null, "/default-avatar.png");

A complete Next.js (App Router) example — RainbowKit picker with Topaz ID on top, profile display, and signing — is live at topaz-id-demo.vercel.app. Run it locally:

git clone https://github.com/topazdex/topaz-id-connect-demo
cd topaz-id-connect-demo
yarn install
cp .env.local.example .env.local   # add a WalletConnect project id
yarn dev

topazIdConnector() is a first-class wagmi connector. Drop it into any wagmi config (or wrap it for ConnectKit) without RainbowKit.

import { topazIdConnector, TOPAZ_ID_CHAIN } from "@topazdex/id-connect/rainbow-kit";
import { createConfig, http } from "wagmi";

// First-class wagmi connector — no RainbowKit required.
export const wagmiConfig = createConfig({
  chains: [TOPAZ_ID_CHAIN],
  transports: { [TOPAZ_ID_CHAIN.id]: http() },
  connectors: [topazIdConnector()],
  ssr: true,
});

If your app is itself a Privy app, you can add Topaz ID as a cross-app login method instead of a wagmi connector. List it in loginMethods and call loginWithCrossAppAccount from useCrossAppAccounts. The package exports TOPAZ_ID_APP_ID so you never hardcode it.

import { useCrossAppAccounts, usePrivy } from "@privy-io/react-auth";
import { TOPAZ_ID_APP_ID } from "@topazdex/id-connect";

// In your PrivyProvider config, list Topaz ID as a login method:
//   loginMethods: ["email", "wallet", `privy:${TOPAZ_ID_APP_ID}`]
const { user } = usePrivy();
const { loginWithCrossAppAccount } = useCrossAppAccounts();

await loginWithCrossAppAccount({ appId: TOPAZ_ID_APP_ID });

const topaz = user?.linkedAccounts.find(
  (a) => a.type === "cross_app" && a.providerApp.id === TOPAZ_ID_APP_ID,
);
const address = topaz?.embeddedWallets[0]?.address;

v1 targets BNB Chain (chain id 56). Supported assets include BNB, USDT, USDC, USD1, TOPAZ, WBNB, BTCB, ETH, and CAKE.

Label the wallet Topaz ID in your picker, paired with the Topaz logo on a dark surface and the gold accent (#E8C47C). Don’t imply custody or automated execution beyond what the user approves in the Topaz ID consent window.

• The user signs and approves every transaction in Topaz ID.
• Never request or store private keys — you never see them.
• Validate recipient addresses and chain before submitting.
• Show transaction details before the user confirms.

Apps that accept Topaz ID can be featured in the in-app launcher so users can discover and open them directly. To request a listing, send the following to the team:

• App name, one-line description, and production URL.
• A square logo (SVG or 512×512 PNG, transparent background).
• Confirmation that you integrate Topaz ID as a login or wallet option.
• A support contact for listing and security questions.

Listings are reviewed for a working Topaz ID integration and basic security hygiene before they go live.

Open an issue on GitHub, reach the team at topazdex.com/docs, or on X.