diff --git a/packages/react/README.md b/packages/react/README.md
index 0d6babe..2f805f6 100644
--- a/packages/react/README.md
+++ b/packages/react/README.md
@@ -1,30 +1,73 @@
-# React + TypeScript + Vite
+<p align="center">
+  <img src="../docs/public/icon.png" alt="Fedimint Logo" width="300" />
+  <!-- Removes the border below the header tag -->
+  <div id="toc"><ul align="center" style="list-style: none;"><summary>
+    <h1><b>@fedimint/react</b></h1>
+    <p>Helpful React hooks for building with the Fedimint Web SDK.</p>
+  </summary></ul></div>
 
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+# @fedimint/react
 
-Currently, two official plugins are available:
+## Install
 
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react/README.md) uses [Babel](https://babeljs.io/) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+```bash
+pnpm install @fedimint/core-web @fedimint/react
+```
 
-## Expanding the ESLint configuration
+## Usage
 
-If you are developing a production application, we recommend updating the configuration to enable type aware lint rules:
+```tsx
+import { FedimintWalletProvider, setupFedimintWallet } from '@fedimint/react'
 
-- Configure the top-level `parserOptions` property like this:
+setupFedimintWallet({
+  lazy: false,
+  debug: true,
+})
 
-```js
-export default {
-  // other rules...
-  parserOptions: {
-    ecmaVersion: 'latest',
-    sourceType: 'module',
-    project: ['./tsconfig.json', './tsconfig.node.json'],
-    tsconfigRootDir: __dirname,
-  },
-}
-```
+// Wrap your app in the FedimintWalletProvider
+<FedimintWalletProvider>
+  <App />
+</FedimintWalletProvider>
+
+
+// App.tsx
+
+
+// Balance
+
+import { useBalance } from '@fedimint/react'
+
+const balance = useBalance()
+
+// Wallet
 
-- Replace `plugin:@typescript-eslint/recommended` to `plugin:@typescript-eslint/recommended-type-checked` or `plugin:@typescript-eslint/strict-type-checked`
-- Optionally add `plugin:@typescript-eslint/stylistic-type-checked`
-- Install [eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react) and add `plugin:react/recommended` & `plugin:react/jsx-runtime` to the `extends` list
+import { useOpenWallet } from '@fedimint/react'
+
+const {
+  walletStatus, // 'open' | 'closed' | 'connecting' | 'failed'
+  openWallet, // () => Promise<boolean> - Returns true if wallet was opened successfully.
+  joinFederation, // () => Promise<boolean> - Returns true if joined federation successfully.
+} = useOpenWallet()
+
+// Receive Lightning
+
+import { useReceiveLightning } from '@fedimint/react'
+
+const {
+  generateInvoice, // (amount: number) => Promise<void>
+  bolt11, // string
+  invoiceStatus, // 'pending' | 'confirmed' | 'failed'
+  error, // Error | undefined
+} = useReceiveLightning()
+
+// Send Lightning
+
+import { useSendLightning } from '@fedimint/react'
+
+const {
+  payInvoice, // (bolt11: string) => Promise<void>
+  paymentStatus, // 'pending' | 'confirmed' | 'failed'
+  paymentError, // Error | undefined
+} = useSendLightning()
+
+```
diff --git a/packages/react/src/components/HooksDemo.tsx b/packages/react/src/components/HooksDemo.tsx
index 695d3c4..4c2ece3 100644
--- a/packages/react/src/components/HooksDemo.tsx
+++ b/packages/react/src/components/HooksDemo.tsx
@@ -10,12 +10,20 @@ const TEST_FEDERATION_INVITE =
   'fed11qgqzc2nhwden5te0vejkg6tdd9h8gepwvejkg6tdd9h8garhduhx6at5d9h8jmn9wshxxmmd9uqqzgxg6s3evnr6m9zdxr6hxkdkukexpcs3mn7mj3g5pc5dfh63l4tj6g9zk4er'
 
 function HooksDemo() {
+  const [bolt11Input, setBolt11Input] = useState<string>()
+
+  // Balance
   const balance = useBalance()
+
+  // Wallet
   const { walletStatus, openWallet, joinFederation } = useOpenWallet()
-  const [bolt11Input, setBolt11Input] = useState<string>()
   const isOpen = walletStatus === 'open'
+
+  // Receive Lightning
   const { generateInvoice, bolt11, invoiceStatus, error } =
     useReceiveLightning()
+
+  // Send Lightning
   const { payInvoice, payment, paymentStatus, paymentError } =
     useSendLightning()
 
@@ -45,12 +53,14 @@ function HooksDemo() {
             </button>
           </div>
         </div>
+
         <div className="section">
           <div className="row">
             <b>useBalance</b>
             <p>{balance ? `${balance / 1000} sats` : 'no balance'}</p>
           </div>
         </div>
+
         <div className="section">
           <b>useLightningInvoice()</b>
           <div className="row">
diff --git a/packages/react/src/main.tsx b/packages/react/src/main.tsx
index db393a6..c82fa27 100644
--- a/packages/react/src/main.tsx
+++ b/packages/react/src/main.tsx
@@ -4,6 +4,7 @@ import App from './App.tsx'
 import './index.css'
 import { FedimintWalletProvider, setupFedimintWallet } from '../lib/contexts'
 
+// Setup singleton client
 setupFedimintWallet({
   lazy: false,
   debug: true,
@@ -11,6 +12,8 @@ setupFedimintWallet({
 
 ReactDOM.createRoot(document.getElementById('root')!).render(
   <React.StrictMode>
+    {/* Wrap the app in the FedimintWalletProvider */}
+
     <FedimintWalletProvider>
       <App />
     </FedimintWalletProvider>