chore: add TrustConnect SDK

README.md

@@ -20,6 +20,14 @@ Programmatic access to Trust Wallet's multichain infrastructure — balance quer
 
 ## Build on Trust Wallet
 
+### [TrustConnect SDK](trustconnect/trustconnect.md)
+The free, open-source wallet connection SDK for every chain. Connect dApps to Trust Wallet across EVM, Solana, and Bitcoin with a modular React hooks API and fully customizable UI.
+
+- [Quickstart](trustconnect/quickstart.md)
+- [EVM (EIP-155)](trustconnect/evm.md)
+- [Solana](trustconnect/solana.md)
+- [Bitcoin (BIP-122)](trustconnect/bitcoin.md)
+
 ### [Developing for Trust Wallet](develop-for-trust/develop-for-trust.md)
 An introduction to web3 development with Trust Wallet. Covers the Provider API, WalletConnect, deep linking, and the browser extension.
 

SUMMARY.md

@@ -6,6 +6,13 @@
   - [CLI Reference](agent-sdk/cli-reference.md)
   - [Authentication](agent-sdk/authentication.md)
   - [Key Management](agent-sdk/key-management.md)
+- [TrustConnect SDK](trustconnect/trustconnect.md)
+  - [Quickstart](trustconnect/quickstart.md)
+  - [Modal & Connection Management](trustconnect/modal-and-connections.md)
+  - [EVM (EIP-155)](trustconnect/evm.md)
+  - [Solana](trustconnect/solana.md)
+  - [Bitcoin (BIP-122)](trustconnect/bitcoin.md)
+  - [Theming & Customization](trustconnect/theming.md)
 - [MCP Servers](mcp/mcp.md)
   - [Docs MCP](mcp/docs-mcp.md)
   - [API Gateway MCP](mcp/api-gateway.md)

trustconnect/bitcoin.md

@@ -0,0 +1,142 @@
+# Bitcoin (BIP-122)
+
+TrustConnect provides React hooks for Bitcoin wallet interactions using the BIP-122 CAIP namespace.
+
+## Installation
+
+```bash
+pnpm add @trustwallet/connect-bip122-react
+```
+
+## Setup
+
+Configure Bitcoin using `createBIP122`:
+
+```tsx
+import { createBIP122, mainnet as bip122Mainnet } from '@trustwallet/connect-bip122-react'
+
+const bip122 = createBIP122({
+    chain: bip122Mainnet,
+})
+```
+
+Then add it to the `namespaces` array in your `TrustConnectProvider` configuration. See [Quickstart](quickstart.md) for the full setup.
+
+## Sign messages
+
+### useSignMessage
+
+Sign a message with the connected Bitcoin wallet. Supports both ECDSA and BIP-322 signing protocols:
+
+```tsx
+import { useSignMessage } from '@trustwallet/connect-bip122-react'
+import { useConnection } from '@trustwallet/connect-react'
+
+function BitcoinSignMessage() {
+    const { isConnected } = useConnection({ namespaceId: 'bip122' })
+
+    const {
+        mutate: sign,
+        data: signature,
+        isPending,
+        isSuccess,
+        error,
+    } = useSignMessage()
+
+    const handleSign = () => {
+        if (!isConnected) return
+        sign({
+            message: 'Hello from TrustConnect SDK!',
+            protocol: 'ecdsa', // or 'bip322'
+        })
+    }
+
+    return (
+        <div>
+            <button onClick={handleSign} disabled={isPending || !isConnected}>
+                {isPending ? 'Signing...' : 'Sign Message'}
+            </button>
+            {isSuccess && signature && (
+                <div>
+                    <p>Message signed!</p>
+                    <code>{signature.signature}</code>
+                </div>
+            )}
+            {error && <p>Error: {error.message}</p>}
+        </div>
+    )
+}
+```
+
+## Sign PSBTs
+
+### useSignPsbt
+
+Sign a Partially Signed Bitcoin Transaction (PSBT):
+
+```tsx
+import { useSignPsbt } from '@trustwallet/connect-bip122-react'
+
+function BitcoinSignPsbt() {
+    const { mutate: signPsbt, isPending } = useSignPsbt({})
+
+    const handleSignPsbt = () => {
+        signPsbt({
+            psbt: 'cHNidP8BA...', // Base64 encoded PSBT
+            signInputs: [
+                { index: 0, sighashType: 1 },
+            ],
+            finalize: false,
+        })
+    }
+
+    return (
+        <button onClick={handleSignPsbt} disabled={isPending}>
+            {isPending ? 'Signing...' : 'Sign PSBT'}
+        </button>
+    )
+}
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `psbt` | `string` | Base64-encoded PSBT |
+| `signInputs` | `array` | Array of input objects with `index`, optional `address`, `publicKey`, and `sighashType` |
+| `finalize` | `boolean` | Whether the wallet should finalize and broadcast the PSBT |
+
+## Send transfers
+
+### useSendTransfer
+
+Send a simple BTC transfer:
+
+```tsx
+import { useSendTransfer } from '@trustwallet/connect-bip122-react'
+
+function BitcoinTransfer() {
+    const { mutateAsync: sendTransfer, isPending } = useSendTransfer({})
+
+    const handleTransfer = async () => {
+        try {
+            const result = await sendTransfer({
+                toAddress: 'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh',
+                satoshis: 10000,
+            })
+            console.log('Transaction ID:', result.txid)
+        } catch (error) {
+            console.error('Transfer failed:', error)
+        }
+    }
+
+    return (
+        <button onClick={handleTransfer} disabled={isPending}>
+            {isPending ? 'Sending...' : 'Send BTC'}
+        </button>
+    )
+}
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `toAddress` | `string` | Destination Bitcoin address |
+| `satoshis` | `number` | Amount in satoshis |

trustconnect/evm.md

@@ -0,0 +1,201 @@
+# EVM (EIP-155)
+
+TrustConnect provides React hooks for interacting with Ethereum and EVM-compatible chains. The EIP-155 package is built on top of [Viem](https://viem.sh) and uses Viem actions for read and write operations.
+
+## Installation
+
+```bash
+pnpm add @trustwallet/connect-eip155-react
+```
+
+Peer dependencies:
+
+```bash
+pnpm add @tanstack/react-query viem
+```
+
+## Setup
+
+Configure EVM chains using `createEIP155`:
+
+```tsx
+import { mainnet, polygon } from 'viem/chains'
+import { createEIP155 } from '@trustwallet/connect-eip155-react'
+
+const eip155 = createEIP155({
+    chains: [mainnet, polygon],
+})
+```
+
+### Custom RPC URLs
+
+You can configure custom RPC endpoints per chain. Since Viem doesn't follow CAIP-2, use `formatChainId` to convert chain IDs:
+
+```tsx
+import { mainnet } from 'viem/chains'
+import { formatChainId, createEIP155 } from '@trustwallet/connect-eip155-react'
+
+const caipMainnetId = formatChainId(mainnet.id)
+
+const eip155 = createEIP155({
+    chains: [mainnet],
+    rpcUrls: {
+        [caipMainnetId]: ['https://rpc-node.com'],
+    },
+})
+```
+
+## Read operations
+
+### useEIP155Query
+
+Use `useEIP155Query` for read-only operations with any Viem public action:
+
+```tsx
+import { useEIP155Query } from '@trustwallet/connect-eip155-react'
+import { getBalance } from 'viem/actions'
+import { mainnet } from 'viem/chains'
+import { useConnection } from '@trustwallet/connect-react'
+
+function Balance() {
+    const { address, isConnected } = useConnection({ namespaceId: 'eip155' })
+
+    const { data } = useEIP155Query({
+        chain: mainnet,
+        action: getBalance,
+        request: { address },
+        queryOptions: {
+            enabled: isConnected,
+            queryKey: [address],
+        },
+    })
+
+    return <p>Balance: {data?.toString()}</p>
+}
+```
+
+> **Important:** Always pass `queryOptions.enabled: isConnected` to prevent the query from running before a wallet is connected. Without this, the query will fail with a "Transport is undefined" error because no RPC client exists yet.
+
+## Write operations
+
+### useSignMessage
+
+Sign messages with the connected EVM wallet:
+
+```tsx
+import { useSignMessage } from '@trustwallet/connect-eip155-react'
+import { useConnection } from '@trustwallet/connect-react'
+
+function SignMessage() {
+    const { isConnected } = useConnection({ namespaceId: 'eip155' })
+    const { mutate: sign, data, isPending, isSuccess, isError, error } = useSignMessage()
+
+    return (
+        <div>
+            <button onClick={() => sign({ message: 'Hello World' })} disabled={!isConnected || isPending}>
+                Sign Message
+            </button>
+            {isPending && <p>Signing...</p>}
+            {isSuccess && <p>Signature: {data}</p>}
+            {isError && <p>Error: {error?.message}</p>}
+        </div>
+    )
+}
+```
+
+### useWriteContract
+
+Call smart contract functions that modify state. This hook handles chain switching automatically and waits for transaction confirmation via [`waitForTransactionReceipt`](https://viem.sh/docs/actions/public/waitForTransactionReceipt).
+
+> **Note:** You can disable automatic chain switching by setting `autoSwitchChain` to `false`.
+
+```tsx
+import { useWriteContract } from '@trustwallet/connect-eip155-react'
+import { mainnet } from 'viem/chains'
+import { parseEther } from 'viem'
+
+function WriteContract() {
+    const { mutate, hash, receipt, isLoading, isConfirming, isConfirmed } = useWriteContract()
+
+    const handleWrite = () => {
+        mutate({
+            chain: mainnet,
+            address: '0x...',
+            abi: [...],
+            functionName: 'transfer',
+            args: ['0x...', parseEther('0.01')],
+        })
+    }
+
+    return (
+        <div>
+            <button onClick={handleWrite} disabled={isLoading}>
+                {isLoading ? 'Sending...' : 'Send'}
+            </button>
+            {hash && <p>Hash: {hash}</p>}
+            {isConfirming && <p>Waiting for confirmation...</p>}
+            {isConfirmed && receipt && <p>Confirmed in block {receipt.blockNumber}</p>}
+        </div>
+    )
+}
+```
+
+### useSendTransaction
+
+Send native token transfers. Like `useWriteContract`, this hook handles chain switching and waits for confirmation automatically.
+
+```tsx
+import { useSendTransaction } from '@trustwallet/connect-eip155-react'
+import { mainnet } from 'viem/chains'
+import { parseEther } from 'viem'
+
+function SendTransaction() {
+    const { mutateAsync, isPending, hash, receipt, isConfirming, isConfirmed } = useSendTransaction()
+
+    const handleSend = async () => {
+        try {
+            await mutateAsync({
+                chain: mainnet,
+                to: '0x...',
+                value: parseEther('0.01'),
+            })
+        } catch (error) {
+            console.error('Failed:', error)
+        }
+    }
+
+    return (
+        <div>
+            <button onClick={handleSend} disabled={isPending}>
+                {isPending ? 'Sending...' : 'Send 0.01 ETH'}
+            </button>
+            {hash && <p>Hash: {hash}</p>}
+            {isConfirming && <p>Waiting for confirmation...</p>}
+            {isConfirmed && receipt && <p>Confirmed in block {receipt.blockNumber}</p>}
+        </div>
+    )
+}
+```
+
+### 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 (
+        <button onClick={() => mutateAsync({ id: mainnet.id })} disabled={isPending}>
+            {isPending ? 'Switching...' : 'Switch Chain'}
+        </button>
+    )
+}
+```