{"id":48593999,"url":"https://github.com/fran-dv/bch-connect-monorepo","last_synced_at":"2026-04-08T20:55:13.383Z","repository":{"id":317468639,"uuid":"1064212065","full_name":"fran-dv/bch-connect-monorepo","owner":"fran-dv","description":"Seamlessly connect Bitcoin Cash wallets to your react dApp.","archived":false,"fork":false,"pushed_at":"2026-01-30T17:47:35.000Z","size":1460,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-08T20:55:10.284Z","etag":null,"topics":["bitcoincash","dapp","library","react","typescript","web3"],"latest_commit_sha":null,"homepage":"https://bch-connect-example.netlify.app/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fran-dv.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-25T17:46:50.000Z","updated_at":"2026-01-30T17:48:20.000Z","dependencies_parsed_at":"2025-10-01T04:25:55.117Z","dependency_job_id":"8412be52-ceff-4839-ad88-cb6a88713dd3","html_url":"https://github.com/fran-dv/bch-connect-monorepo","commit_stats":null,"previous_names":["fran-dv/bch-connect","fran-dv/bch-connect-monorepo"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/fran-dv/bch-connect-monorepo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fran-dv%2Fbch-connect-monorepo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fran-dv%2Fbch-connect-monorepo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fran-dv%2Fbch-connect-monorepo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fran-dv%2Fbch-connect-monorepo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fran-dv","download_url":"https://codeload.github.com/fran-dv/bch-connect-monorepo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fran-dv%2Fbch-connect-monorepo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31573788,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bitcoincash","dapp","library","react","typescript","web3"],"created_at":"2026-04-08T20:55:12.181Z","updated_at":"2026-04-08T20:55:13.364Z","avatar_url":"https://github.com/fran-dv.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BCH Connect\n\n[![npm version](https://img.shields.io/npm/v/bch-connect.svg?style=flat-square)](https://www.npmjs.com/package/bch-connect)\n[![License](https://img.shields.io/github/license/fran-dv/bch-connect?style=flat-square)](./LICENSE)\n\nA React library to seamlessly integrate Bitcoin Cash wallet connections in your dApps. 🚀\n\n**_🚧 Actively working on online docs..._**\n\n## Table of contents\n\n- [⚡ Getting started](#getting-started)\n- [💡 Example](#example)\n- [🧩 API reference](#api-reference)\n- [🧑‍💻 Local development](#local-development)\n- [🤝 Contribute](#contribute)\n\n## \u003ca name=\"getting-started\"\u003e\u003c/a\u003e ⚡ Getting started\n\n### Quick Start\n\nThe easiest way to build a BCH dApp is using our scaffolding tool. It sets up **React + Vite** or **Next.js** with TypeScript and BCH Connect pre-configured and ready to use.\n\nJust run:\n\n```bash\nbun create bch-dapp\n# Or use your preferred package manager.\n```\n\n### Manual installation\n\nIf you already have a project and want to add **bch-connect**, follow these steps:\n\n**1. Install the package:**\n\n```bash\nnpm install bch-connect\n```\n\nOr replace `npm` with your preferred package manager.\n\n**2. Set up your configuration**\n\nYou'll need a Reown project ID. Get it from [Reown dashboard](https://dashboard.reown.com). Then, in your `main.tsx`, `App`, or in a specific `config.ts` file:\n\n```tsx\nimport { createConfig } from \"bch-connect\";\n\nexport const config = createConfig({\n  projectId: \"your-reown-project-id\", // Get it from https://dashboard.reown.com\n  network: \"testnet\", // or \"mainnet\"\n  metadata: {\n    name: \"Your dApp name\",\n    description: \"Your dApp description\",\n    url: \"https://your-dapp.com\",\n    icons: [\"https://placehold.co/600x400?text=YourDApp\"],\n  },\n  debug: true,\n});\n```\n\n**3. Wrap your app with the provider**\n\nIn your `main.tsx` or `App`:\n\n```tsx\n// App.tsx\nimport { config } from \"./your-config-file\";\nimport { BCHConnectProvider } from \"bch-connect\";\n\nfunction App() {\n  return (\n    \u003cBCHConnectProvider config={config}\u003e\n      \u003cRestOfYourApp /\u003e\n    \u003c/BCHConnectProvider\u003e\n  );\n}\n```\n\n**4. Start using it!**\n\n```tsx\nimport { useWallet } from \"bch-connect\";\n\nconst ConnectButton = () =\u003e {\n  const { connect } = useWallet();\n\n  return \u003cbutton onClick={connect}\u003eConnect Wallet\u003c/button\u003e;\n};\n```\n\n## \u003ca name=\"example\"\u003e\u003c/a\u003e 💡 Example\n\nVisit the example [**live demo here**](https://bch-connect-example.netlify.app/).\n\nBelow are some code snippets from the example app. To view the full code or run it locally, check the [simple-transaction example](examples/simple-transaction/) folder in this repository.\n\n### Connect button:\n\n```tsx\n// other imports...\nimport { useWallet } from \"bch-connect\";\n\n// styles and UI code are omitted here\nexport const ConnectButton: React.FC\u003c\n  ButtonHTMLAttributes\u003cHTMLButtonElement\u003e\n\u003e = (props: ButtonHTMLAttributes\u003cHTMLButtonElement\u003e) =\u003e {\n  const { connect, isConnected, address, disconnect } = useWallet();\n\n  const handleWalletConnect = () =\u003e {\n    if (isConnected) return;\n    connect();\n  };\n  const handleWalletDisconnect = () =\u003e {\n    disconnect();\n  };\n\n  return (\n    \u003cdiv\u003e\n      \u003cbutton {...props} onClick={handleWalletConnect}\u003e\n        {isConnected \u0026\u0026 address ? (\n          \u003cAddress address={address} /\u003e\n        ) : (\n          \"Connect Wallet\"\n        )}\n      \u003c/button\u003e\n\n      {isConnected \u0026\u0026 (\n        \u003cbutton onClick={handleWalletDisconnect}\u003e\n          \u003cExitIcon /\u003e\n        \u003c/button\u003e\n      )}\n    \u003c/div\u003e\n  );\n};\n\nexport default ConnectButton;\n```\n\n### Sending a transaction using bch-connect and cashscript SDK, with recipient and amount entered through a form:\n\n```tsx\n// other imports...\nimport { useSignTransaction, useWallet } from \"bch-connect\";\n\nexport const Example: React.FC = () =\u003e {\n  // bch-connect hooks\n  const { address, tokenAddress, isConnected } = useWallet();\n  const { signTransaction } = useSignTransaction();\n  // -----------------\n\n  // other hooks from the example app\n  const { showSuccess, showError, showMessage } = useUserMessages();\n  const { provider } = useNetworkProviderStore(); // Cashscript's NetworkProvider\n  const { balance, error: balanceError } = useBalance({ address });\n  const [isLoading, setIsLoading] = useState(false);\n\n  const proposeTransactionToWallet = async (values: TransferFormValues) =\u003e {\n    if (!isConnected || !address || !provider) return;\n\n    setIsLoading(true);\n\n    // helper function to create a transaction object\n    const wcTransactionObj = await getSimpleTransaction({\n      provider,\n      sender: address,\n      amount: values.satoshis,\n      recipient: values.recipient,\n    });\n\n    showMessage(\"Please sign the transaction in your wallet...\");\n\n    // Request signature of the generated transaction to the wallet\n    try {\n      const response = await signTransaction({ txRequest: wcTransactionObj });\n\n      // Defensive checking for malformed response received from wallet\n      if (!response) {\n        showMessage(\n          \"Transaction status couldn’t be tracked. Please check your wallet to see if it was sent or rejected.\",\n        );\n        return;\n      }\n\n      showSuccess(\n        `Tx signed successfully. Hash: ${response.signedTransactionHash}`,\n      );\n    } catch (error) {\n      const errorMsg = (error as Error).message;\n      showError(\"Failed to sign transaction: \" + errorMsg);\n    } finally {\n      setIsLoading(false);\n    }\n  };\n\n  // Below, TransferCard has the form, which call proposeTransactionToWallet on submit\n  // and WalletInfoCard just shows addresses and balance\n  return (\n    \u003csection\u003e\n      \u003cTransferCard\n        isConnected={isConnected}\n        onFormSubmit={proposeTransactionToWallet}\n        balance={balance}\n        isLoading={isLoading}\n      /\u003e\n      \u003cWalletInfoCard\n        isConnected={isConnected}\n        address={address}\n        tokenAddress={tokenAddress}\n        balance={balance}\n        balanceError={balanceError}\n      /\u003e\n    \u003c/section\u003e\n  );\n};\n\nexport default Example;\n```\n\n## \u003ca name=\"api-reference\"\u003e\u003c/a\u003e 🧩 API Reference\n\n### `createConfig(options: Configuration): CreatedConfig`\n\nCreates the configuration object required by `BCHConnectProvider`, applying defaults for you.\n\n**Parameters:**\n\n- `options`: `Configuration` object.\n\n```ts\nexport interface Configuration {\n  projectId: string;\n  network: NETWORK_INDEX | keyof typeof NETWORK_INDEX; // \"mainnet\" | \"testnet\" | \"regtest\"\n  metadata: {\n    name: string;\n    description: string;\n    url: string;\n    icons: string[];\n  };\n  sessionType?: SessionType;\n  modal?: Modal | ModalFactory; // defaults to bchConnectModal()\n  supportLegacyClient?: boolean; // defaults to true. It ensures working with required namespaces\n  debug?: boolean; // defaults to false\n}\n```\n\n**Returns:**\n\n- `CreatedConfig` – branded configuration to pass to the provider.\n\n### `bchConnectModal(config?: BCHConnectModalConfig): Modal`\n\n[bch-connect-modal](/packages/bch-connect-modal/) factory function. Default modal adapter used when you don’t pass a `modal` to `createConfig`. Wraps the `bch-connect-modal` package and accepts the same configuration (with `sessionType` defaulting to `\"Wallet Connect V2\"`).\n\n**Parameters:**\n\n- `config` (optional): `BCHConnectModalConfig`\n\n```ts\ninterface BCHConnectModalConfig {\n  sessionType: SessionType; // \"Wallet Connect V2\"\n  wallets?: {\n    id: string;\n    name: string;\n    iconUrl: string;\n    links: {\n      fallback: string;\n      native?: string;\n      universal?: string;\n      web?: string;\n    };\n  }[]; // optional curated wallet list\n  theme?: \"light\" | \"dark\" | \"system\"; // modal theme\n}\n```\n\n**Returns:**\n\n- `Modal` – object with `open({ uri })` and `close()` methods used internally by BCH Connect.\n\n### `reownModal(options): ModalFactory`\n\nFactory to use Reown AppKit’s modal. Pass the returned function as `modal` in `createConfig`. Accepts all `createAppKit` options except `projectId`, `metadata`, `manualWCControl`, and `networks` (BCH Connect injects those for you).\n\n**Parameters:**\n\n- `options`: `Omit\u003cCreateAppKit, \"projectId\" | \"metadata\" | \"manualWCControl\" | \"networks\"\u003e`\n\n**Returns:**\n\n- `ModalFactory` – async factory that BCH Connect will call with `{ projectId, network, sessionType }` to build the modal.\n\n### `\u003cBCHConnectProvider config={config}\u003e`\n\nProvides the React context for BCH Connect, enabling wallet connections throughout your app.\nThis should wrap your root component (e.g. `App.tsx`).\n\n**Props:**\n\n- `config`: `CreatedConfig` – the object returned by [`createConfig`](#createconfigoptions-configuration-createdconfig).\n- `children`: `React.ReactNode` – your application components.\n\n### `useWallet()`\n\nReact hook to access the current wallet connection state and perform connect/disconnect actions.\nMust be used within a [`\u003cBCHConnectProvider\u003e`](#bchconnectprovider-configconfig) context.\n\n**Returns:**\n\n- `address` – the currently connected wallet address. It is automatically refetched when an `addressesChanged` event is emitted by the wallet.\n- `tokenAddress` – the [CashTokens](https://cashtokens.org/) aware address of the wallet, derived from `address`. It is automatically refetched when `address` changes.\n- `session` – the active WalletConnect session (`SessionTypes.Struct`) or `null` when disconnected.\n- `isConnected` – boolean indicating whether a wallet is currently connected.\n- `connect()` – initiates a wallet connection.\n- `disconnect()` – disconnects the current wallet session.\n- `refetchAddresses()` – programmatically refetches `address`, updating both `address` and `tokenAddress` states.\n- `areAddressesLoading` – boolean indicating whether the addresses are currently being loaded.\n- `addressError` – error object if an error occurred while fetching the address.\n- `tokenAddressError` – error object if an error occurred while converting address to token address.\n- `connectError` – error object if an error occurred while connecting to a wallet.\n- `disconnectError` – error object if an error occurred while disconnecting from a wallet.\n- `isError` – boolean indicating whether an error occurred.\n\n```ts\ninterface UseWalletReturnType {\n  address: string | null;\n  tokenAddress: string | null;\n  areAddressesLoading: boolean;\n  addressError: Error | null;\n  tokenAddressError: Error | null;\n  isConnected: boolean;\n  session: SessionTypes.Struct | null;\n  connectError: Error | null;\n  disconnectError: Error | null;\n  isError: boolean;\n  connect: () =\u003e Promise\u003cvoid\u003e;\n  disconnect: () =\u003e Promise\u003cvoid\u003e;\n  refetchAddresses: () =\u003e Promise\u003cvoid\u003e;\n}\n```\n\n### `useSignTransaction()`\n\nReact hook to sign Bitcoin Cash transactions with the connected wallet.\nIt works within [`\u003cBCHConnectProvider\u003e`](#bchconnectprovider-configconfig) context and when a wallet session is active.\n\n**Returns:**\n\n```ts\ninterface UseSignTransactionReturnType {\n  signTransaction: (\n    options: SignTransactionOpts,\n  ) =\u003e Promise\u003cWcSignTransactionResponse | null\u003e;\n}\n\ninterface SignTransactionOpts {\n  txRequest: WcSignTransactionRequest;\n  requestExpirySeconds?: number; // defaults to 300 seconds\n}\n```\n\n`WcSignTransactionRequest` and `WcSignTransactionResponse` are interfaces from [`@bch-wc2/interfaces`](https://github.com/mainnet-pat/bch-wc2) package, which are also re-exported by `bch-connect` for convenience.\n\n**`signTransaction` parameters:**\n\n- `options.txRequest`: `WcSignTransactionRequest`\n- `options.requestExpirySeconds`: optional expiration for the WalletConnect request in seconds (defaults to 300).\n\n```ts\ninterface WcSignTransactionRequest {\n  transaction: Transaction | string;\n  sourceOutputs: WcSourceOutput[];\n  broadcast?: boolean;\n  userPrompt?: string;\n}\n```\n\nYou’ll commonly pass a `WcTransactionObject` from `cashscript` as the parameter to this function, which is fully compatible. This is shown in the [simple-transaction example](/examples/simple-transaction)\n\n**`signTransaction` returns:**\n\n- `Promise\u003cWcSignTransactionResponse | null\u003e` – resolves with the signed transaction response. Returns `null` when the wallet returns an invalid empty-object response, allowing you to show a neutral “status unknown” message. Throws if the WalletConnect client/session is missing or the wallet rejects/returns an error.\n  It should be used within a try / catch block.\n\n```ts\ninterface WcSignTransactionResponse {\n  signedTransaction: string;\n  signedTransactionHash: string;\n}\n```\n\n### `useSignMessage()`\n\nReact hook to sign arbitrary messages with the connected wallet.\nIt works when your app is wrapped with `\u003cBCHConnectProvider\u003e` and when a wallet session is active.\n\n**Returns:**\n\n```ts\ninterface UseSignMessageReturnType {\n  signMessage: (\n    options: WcSignMessageRequest,\n  ) =\u003e Promise\u003cWcSignMessageResponse | undefined\u003e;\n}\n```\n\n`WcSignMessageRequest` and `WcSignMessageResponse` are interfaces from [`@bch-wc2/interfaces`](https://github.com/mainnet-pat/bch-wc2), which are also re-exported by `bch-connect` for convenience.\n\n**`signMessage` parameters:**\n\n- `options`: `WcSignMessageRequest`\n\n```ts\ninterface WcSignMessageRequest {\n  message: string;\n  userPrompt?: string;\n}\n```\n\n**`signMessage` returns:**\n\n- `Promise\u003cWcSignMessageResponse | undefined\u003e` – resolves with the message signature as a string. Throws if the WalletConnect client/session is missing or the wallet rejects/returns an error.\n  It should be used within a try / catch block.\n\n```ts\ntype WcSignMessageResponse = string;\n```\n\n## \u003ca name=\"local-development\"\u003e\u003c/a\u003e 🧑‍💻 Local Development (for contributors)\n\nThis is a Bun-powered monorepo (`packages/*`, `examples/*`, `docs`). After cloning, install everything once from the root:\n\n```bash\ngit clone https://github.com/fran-dv/bch-connect-monorepo.git\ncd bch-connect-monorepo\nbun install\n```\n\n### Library (`packages/bch-connect`)\n\nDevelopment (tsup watch writes to `dist/`):\n\n```bash\ncd packages/bch-connect\nbun dev\n```\n\nTests and tooling:\n\n```bash\nbun test            # or: bun test:coverage\nbun run lint\nbun run format\n```\n\n### Modal (`packages/bch-connect-modal`)\n\nPlayground (watch + serve `src/index.html` with the built global bundle):\n\n```bash\ncd packages/bch-connect-modal\nbun run dev:playground  # serves at http://localhost:4173\n```\n\nThe playground needs manual reload on the browser to see changes.\n\nBundle without serving:\n\n```bash\nbun dev            # watch build\nbun run build      # without minification\nbun run build:prod # with minification\n```\n\nTests:\n\n```bash\nbun test\nbun test:coverage\n```\n\n### Example app (`examples/simple-transaction`)\n\nRun the demo:\n\n```bash\ncd examples/simple-transaction\nbun dev\n```\n\nBuild and preview:\n\n```bash\nbun run build\nbun run preview\n```\n\n### Docs site (`docs`)\n\nPreview locally (Next.js):\n\n```bash\ncd docs\nbun run dev\n```\n\nProduction build and type/MDX checks:\n\n```bash\nbun run build\nbun run types:check\n```\n\n## \u003ca name=\"contribute\"\u003e\u003c/a\u003e 🤝 Contribute\n\nThis project is open source and contributions are more than welcome!\n\nLicensed under MIT – feel free to copy, modify, and use the code in your own projects.\n\n---\n\nBuilt with 💚 by [fran-dv](https://github.com/fran-dv)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffran-dv%2Fbch-connect-monorepo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffran-dv%2Fbch-connect-monorepo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffran-dv%2Fbch-connect-monorepo/lists"}