+ )
+}
+```
+
+### useEIP155Mutation
+
+Use `useEIP155Mutation` for any Viem wallet action not covered by the higher-level hooks:
+
+```tsx
+import { useEIP155Mutation } from '@trustwallet/connect-eip155-react'
+import { switchChain } from 'viem/actions'
+import { mainnet } from 'viem/chains'
+
+function CustomAction() {
+ const { mutateAsync, isPending } = useEIP155Mutation({
+ chain: mainnet,
+ action: switchChain,
+ })
+
+ return (
+
+ )
+}
+```
diff --git a/trustconnect/modal-and-connections.md b/trustconnect/modal-and-connections.md
new file mode 100644
index 0000000..13f8293
--- /dev/null
+++ b/trustconnect/modal-and-connections.md
@@ -0,0 +1,95 @@
+# Modal & Connection Management
+
+TrustConnect provides React hooks for controlling the wallet connection modal and reading connection state across all supported chains.
+
+## Modal control
+
+### useTrustModal
+
+Use `useTrustModal` to open and control the connection modal:
+
+```tsx
+import { useTrustModal } from '@trustwallet/connect-react'
+
+function ConnectButton() {
+ const { open } = useTrustModal()
+
+ return (
+ <>
+ {/* Open wallet selection */}
+
+
+ {/* Prompt the user to connect to a specific namespace */}
+
+
+ )
+}
+```
+
+The `open` function accepts an optional parameter to target a specific namespace:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `type` | `'namespace'` | Specifies that the modal should filter by namespace |
+| `namespaceId` | `string` | The CAIP-2 namespace to filter wallets by (`'eip155'`, `'solana'`, `'bip122'`) |
+
+## Connection state
+
+### useConnections
+
+Use `useConnections` to read all active connections across every namespace:
+
+```tsx
+import { useConnections } from '@trustwallet/connect-react'
+
+function AllConnections() {
+ const { connections } = useConnections()
+
+ return (
+
+ {connections.map((conn) => (
+
+ {conn.wallet?.name} — {conn.address}
+
+ ))}
+
+ )
+}
+```
+
+### useConnection
+
+Use `useConnection` to read the connection for a single namespace:
+
+```tsx
+import { useConnection } from '@trustwallet/connect-react'
+
+function WalletInfo() {
+ const { isConnected, address, wallet, chain, status } = useConnection({
+ namespaceId: 'eip155',
+ })
+
+ if (!isConnected) return
Not connected
+
+ return (
+
+
Wallet: {wallet?.name}
+
Address: {address}
+
Chain: {chain?.reference}
+
Status: {status}
+
+ )
+}
+```
+
+**Returned properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `isConnected` | `boolean` | Whether a wallet is connected for this namespace |
+| `address` | `string \| undefined` | The connected wallet address |
+| `wallet` | `object \| undefined` | Wallet metadata (name, icon, etc.) |
+| `chain` | `object \| undefined` | The active chain for this connection |
+| `status` | `string` | Connection status |
diff --git a/trustconnect/quickstart.md b/trustconnect/quickstart.md
new file mode 100644
index 0000000..a9197d5
--- /dev/null
+++ b/trustconnect/quickstart.md
@@ -0,0 +1,113 @@
+# Quickstart
+
+Get from zero to a working wallet connection in your React app.
+
+## Step 1 — Install packages
+
+Install the core package, at least one network package, and WalletConnect:
+
+```bash
+pnpm add @trustwallet/connect-react \
+ @trustwallet/connect-eip155-react \
+ @trustwallet/connect-walletconnect
+```
+
+EIP-155 requires these peer dependencies:
+
+```bash
+pnpm add @tanstack/react-query viem
+```
+
+> **Other chains?** Add `@trustwallet/connect-solana-react` for Solana or `@trustwallet/connect-bip122-react` for Bitcoin. See [Solana](solana.md) and [Bitcoin](bitcoin.md) for details.
+
+## Step 2 — Configure the provider
+
+Wrap your app with `TrustConnectProvider` and configure the namespaces and services:
+
+```tsx
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { mainnet, polygon } from 'viem/chains'
+import { createEIP155 } from '@trustwallet/connect-eip155-react'
+import { createWalletConnect } from '@trustwallet/connect-walletconnect'
+import { TrustConnectProvider } from '@trustwallet/connect-react'
+
+const queryClient = new QueryClient()
+const projectId = import.meta.env.VITE_WALLETCONNECT_ID
+
+const eip155 = createEIP155({
+ chains: [mainnet, polygon],
+})
+
+const walletConnect = createWalletConnect({
+ projectId,
+ metadata: {
+ name: 'My dApp',
+ url: 'https://example.com',
+ description: 'My awesome dApp',
+ icons: ['https://example.com/icon.png'],
+ },
+})
+
+function App() {
+ return (
+
+
+
+
+
+ )
+}
+```
+
+> **WalletConnect project ID** — get yours at [cloud.walletconnect.com](https://cloud.walletconnect.com/).
+
+## Step 3 — Open the connection modal
+
+Use the `useTrustModal` hook to open the wallet selection modal:
+
+```tsx
+import { useTrustModal } from '@trustwallet/connect-react'
+
+function ConnectButton() {
+ const { open } = useTrustModal()
+
+ return
+}
+```
+
+## Step 4 — Read connection state
+
+Use `useConnection` to check if a wallet is connected and read its details:
+
+```tsx
+import { useConnection } from '@trustwallet/connect-react'
+
+function WalletInfo() {
+ const { isConnected, address, wallet, chain } = useConnection({
+ namespaceId: 'eip155',
+ })
+
+ if (!isConnected) return
Not connected
+
+ return (
+
+
Wallet: {wallet?.name}
+
Address: {address}
+
Chain: {chain?.reference}
+
+ )
+}
+```
+
+## Next steps
+
+- [Modal & Connection Management](modal-and-connections.md) — fine-grained modal and connection control
+- [EVM (EIP-155)](evm.md) — sign messages, write contracts, and send transactions
+- [Solana](solana.md) — Solana wallet interactions
+- [Bitcoin (BIP-122)](bitcoin.md) — Bitcoin wallet interactions
+- [Theming & Customization](theming.md) — match the modal to your brand
diff --git a/trustconnect/solana.md b/trustconnect/solana.md
new file mode 100644
index 0000000..0117591
--- /dev/null
+++ b/trustconnect/solana.md
@@ -0,0 +1,119 @@
+# Solana
+
+TrustConnect provides React hooks for Solana wallet interactions.
+
+## Installation
+
+```bash
+pnpm add @trustwallet/connect-solana-react
+```
+
+## Setup
+
+Configure Solana using `createSolana`:
+
+```tsx
+import { createSolana, mainnet as solanaMainnet } from '@trustwallet/connect-solana-react'
+
+const solana = createSolana({
+ chain: solanaMainnet,
+})
+```
+
+Then add it to the `namespaces` array in your `TrustConnectProvider` configuration. See [Quickstart](quickstart.md) for the full setup.
+
+## Sign messages
+
+### useSignMessage
+
+Sign an arbitrary message with the connected Solana wallet:
+
+```tsx
+import { useSignMessage } from '@trustwallet/connect-solana-react'
+import { useConnection } from '@trustwallet/connect-react'
+import bs58 from 'bs58'
+
+function SolanaSignMessage() {
+ const { isConnected } = useConnection({ namespaceId: 'solana' })
+ const { mutate, data, isPending, isSuccess, error } = useSignMessage()
+
+ const handleSign = () => {
+ if (!isConnected) return
+ mutate({ message: 'Hello Solana!' })
+ }
+
+ // Signature is returned as Uint8Array
+ const signatureBase58 = data ? bs58.encode(data.signature) : null
+
+ return (
+
+
+ {isSuccess && signatureBase58 && (
+
+
Message signed successfully!
+ {signatureBase58}
+
+ )}
+ {error &&
Error: {error.message}
}
+
+ )
+}
+```
+
+## Send transactions
+
+### useSignSendTransaction
+
+Sign and broadcast a Solana transaction:
+
+```tsx
+import { useSignSendTransaction } from '@trustwallet/connect-solana-react'
+import { Transaction, SystemProgram, PublicKey } from '@solana/web3.js'
+
+function SolanaSendTransaction() {
+ const { mutateAsync, isPending } = useSignSendTransaction()
+
+ const handleSend = async () => {
+ try {
+ const tx = new Transaction().add(
+ SystemProgram.transfer({
+ fromPubkey: new PublicKey('...'),
+ toPubkey: new PublicKey('...'),
+ lamports: 1000000, // 0.001 SOL
+ })
+ )
+
+ const serialized = tx.serialize({ requireAllSignatures: false })
+ const result = await mutateAsync({
+ transaction: serialized,
+ options: {
+ skipPreflight: false,
+ preflightCommitment: 'confirmed',
+ },
+ })
+
+ console.log('Transaction signature:', result.signature)
+ } catch (error) {
+ console.error('Transaction failed:', error)
+ }
+ }
+
+ return (
+
+ )
+}
+```
+
+#### Transaction options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `skipPreflight` | `boolean` | Disable transaction verification at the RPC |
+| `preflightCommitment` | `'processed' \| 'confirmed' \| 'finalized'` | Commitment level for preflight |
+| `commitment` | `'processed' \| 'confirmed' \| 'finalized'` | If provided, confirm the transaction after sending |
+| `maxRetries` | `number` | Maximum number of times to retry sending the transaction |
+| `minContextSlot` | `number` | Minimum slot to include the transaction |
diff --git a/trustconnect/theming.md b/trustconnect/theming.md
new file mode 100644
index 0000000..e2cc13f
--- /dev/null
+++ b/trustconnect/theming.md
@@ -0,0 +1,74 @@
+# Theming & Customization
+
+TrustConnect's modal UI can be customized at two levels: theme configuration for quick color scheme changes, or full component ejection for complete control over every element.
+
+## Theme configuration
+
+Set the theme via the `theme` prop on `TrustConnectProvider`:
+
+```tsx
+
+ {children}
+
+```
+
+| Value | Description |
+|-------|-------------|
+| `'auto'` | Follows the user's system preference (default) |
+| `'light'` | Light theme |
+| `'dark'` | Dark theme |
+
+### Programmatic theme control
+
+Use the `useTheme` hook to read and change the theme at runtime:
+
+```tsx
+import { useTheme } from '@trustwallet/connect-react'
+
+function ThemeToggle() {
+ const { theme, resolvedTheme, setTheme, toggleTheme } = useTheme()
+
+ return (
+
+
Current: {resolvedTheme}
+
+
+
+
+
+ )
+}
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `theme` | `string` | The configured theme value (`'auto'`, `'light'`, or `'dark'`) |
+| `resolvedTheme` | `string` | The actual active theme after resolving `'auto'` (`'light'` or `'dark'`) |
+| `setTheme` | `function` | Set the theme to `'auto'`, `'light'`, or `'dark'` |
+| `toggleTheme` | `function` | Toggle between light and dark themes |
+
+## Full UI customization
+
+For complete control over every UI element, eject the TrustConnect components into your project:
+
+```bash
+npx @trustwallet/connect-react add
+```
+
+You can specify a custom output path:
+
+```bash
+npx @trustwallet/connect-react add --path ./src/components/trust
+```
+
+This copies the React components and their styles into your project so you can customize everything locally. The CLI also installs two additional dependencies automatically:
+
+- `@trustwallet/connect-ui-logic` — headless state logic used by the UI components
+- `cuer` — QR code rendering
+
+After ejecting, import `TrustConnectProvider` and other hooks directly from your local TrustConnect components folder instead of `@trustwallet/connect-react`.
+
+> **Note:** After ejecting, you are responsible for maintaining the components. Updates to the SDK's built-in UI will not automatically apply to ejected components.
diff --git a/trustconnect/trustconnect.md b/trustconnect/trustconnect.md
new file mode 100644
index 0000000..fa19007
--- /dev/null
+++ b/trustconnect/trustconnect.md
@@ -0,0 +1,58 @@
+# TrustConnect SDK
+
+The free, open-source wallet connection SDK for every chain, built by Trust Wallet. TrustConnect is a [CAIP](https://chainagnostic.org/)-compliant, multi-chain SDK that connects your dApp to Trust Wallet and other wallets across EVM, Solana, and Bitcoin — with a React hooks API and fully customizable UI.
+
+## Install
+
+Install the core React package:
+
+```bash
+pnpm add @trustwallet/connect-react
+```
+
+Then add the network-specific packages for the chains you need:
+
+```bash
+# EVM chains (Ethereum, Polygon, etc.)
+pnpm add @trustwallet/connect-eip155-react
+
+# Solana
+pnpm add @trustwallet/connect-solana-react
+
+# Bitcoin
+pnpm add @trustwallet/connect-bip122-react
+```
+
+For WalletConnect support (mobile and QR code connections):
+
+```bash
+pnpm add @trustwallet/connect-walletconnect
+```
+
+EIP-155 peer dependencies (if not already installed):
+
+```bash
+pnpm add @tanstack/react-query viem
+```
+
+## Get started
+
+- [Quickstart](quickstart.md) — install, configure, and connect your first wallet
+- [Modal & Connection Management](modal-and-connections.md) — control the connection modal and read wallet state
+- [EVM (EIP-155)](evm.md) — sign messages, send transactions, and call contracts on Ethereum and EVM chains
+- [Solana](solana.md) — sign messages and send transactions on Solana
+- [Bitcoin (BIP-122)](bitcoin.md) — sign messages, PSBTs, and send transfers on Bitcoin
+- [Theming & Customization](theming.md) — customize the UI theme or eject the full component set
+
+## Key features
+
+- **100% free, always** — no usage fees, no freemium tiers, no paywalls
+- **Native multi-chain support** — EVM, Solana, and Bitcoin in a single, modular SDK
+- **Fully customizable UI** — override any style to match your design system, or eject the entire component set for full control
+- **Apache 2.0 licensed** — fork it, extend it, own it. No vendor lock-in
+- **Lightweight by design** — minimal dependencies, small bundle size, internally audited
+- **CAIP-compliant** — built on [Chain Agnostic](https://chainagnostic.org/) standards for consistent multi-chain addressing
+
+## License
+
+TrustConnect SDK is available under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).