diff --git a/README.md b/README.md
index 735f519..856f19c 100644
--- a/README.md
+++ b/README.md
@@ -44,7 +44,7 @@ npm install @oceanprotocol/react
 
 ## 🏄 Usage
 
-First, wrap your App with the `Web3Provider` and the `OceanProvider`.
+First, wrap your whole app with the `Web3Provider` and the `OceanProvider`.
 
 ### Providers
 
@@ -54,7 +54,8 @@ import { Web3Provider, OceanProvider, Config } from '@oceanprotocol/react'
 
 const config: Config = {
   nodeUri: '',
-  aquariusUri: ''
+  aquariusUri: '',
+  ...
 }
 
 export default function MyApp({
@@ -75,14 +76,7 @@ export default function MyApp({
 }
 ```
 
-The `OceanProvider` requires a Web3 instance to be passed as prop so you can replace the builtin `Web3Provider` with whatever library which returns a Web3 instance. To get you started, we added a basic `Web3Provider` which assumes an injected provider (like MetaMask), and will ask for user permissions automatically on first mount.
-
-We suggest you replace this provider with a more complete solution, since there are many UX considerations not handled in that basic provider, like activate only on user intent, listen for account & network changes, display connection instructions and errors, etc.
-
-Some great solutions we liked to work with:
-
-- [web3-react](https://github.com/NoahZinsmeister/web3-react)
-- [web3modal](https://github.com/web3modal/web3modal)
+The `OceanProvider` requires a Web3 instance to be passed as prop so you can replace the basic [`Web3Provider`](src/providers/Web3Provider) with whatever component/library/provider returning a Web3 instance.
 
 ### Hooks
 
diff --git a/src/providers/OceanProvider/README.md b/src/providers/OceanProvider/README.md
index e69de29..788df92 100644
--- a/src/providers/OceanProvider/README.md
+++ b/src/providers/OceanProvider/README.md
@@ -0,0 +1,86 @@
+# `OceanProvider`
+
+The `OceanProvider` maintains a connection to the Ocean Protocol network in multiple steps:
+
+1. On mount, connect to Aquarius instance right away so any asset metadata can be retrieved before, and independent of any Web3 connections.
+2. Once Web3 becomes available, a connection to all Ocean Protocol network components is established.
+3. Once Ocean becomes available, spits out some info about it.
+
+Also provides a `useOcean` helper hook to access its context values from any component.
+
+## Usage
+
+Wrap your whole app with the `OceanProvider`:
+
+```tsx
+import React, { ReactNode } from 'react'
+import { OceanProvider, Config } from '@oceanprotocol/react'
+
+const config: Config = {
+  nodeUri: '',
+  aquariusUri: '',
+  ...
+}
+
+export default function MyApp({
+  children
+}: {
+  children: ReactNode
+}): ReactNode {
+  const web3 = await getWeb3()
+
+  return (
+    <OceanProvider config={config} web3={web3}>
+        <h1>My App</h1>
+        {children}
+    </OceanProvider>
+  )
+}
+```
+
+The `OceanProvider` requires a Web3 instance to be passed as prop so you can either handle this with your own `getWeb3()`, or use the basic [`Web3Provider`](../Web3Provider):
+
+```tsx
+import React, { ReactNode } from 'react'
+import { Web3Provider, OceanProvider, Config } from '@oceanprotocol/react'
+
+const config: Config = {
+  nodeUri: '',
+  aquariusUri: '',
+  ...
+}
+
+export default function MyApp({
+  children
+}: {
+  children: ReactNode
+}): ReactNode {
+  return (
+    <Web3Provider>
+      {({ web3 }) => (
+        <OceanProvider config={config} web3={web3}>
+          <h1>My App</h1>
+          {children}
+        </OceanProvider>
+      )}
+    </Web3Provider>
+  )
+}
+```
+
+You can then access the provider context values with the `useOcean` hook:
+
+```tsx
+import { useOcean } from '@oceanprotocol/react'
+
+function MyComponent() {
+  const { ocean, account } = useOcean()
+
+  return (
+    <ul>
+      <li>Ocean available: {`${Boolean(ocean)}`}</li>
+      <li>Account: {account}</li>
+    </ul>
+  )
+}
+```
diff --git a/src/providers/Web3Provider/README.md b/src/providers/Web3Provider/README.md
index e69de29..48c9c62 100644
--- a/src/providers/Web3Provider/README.md
+++ b/src/providers/Web3Provider/README.md
@@ -0,0 +1,54 @@
+# `Web3Provider`
+
+To get you started, we added this basic `Web3Provider` which assumes an injected provider (like MetaMask), and will ask for user permissions automatically on first mount.
+
+Also provides a `useWeb3` helper hook to access its context values from any component.
+
+We suggest you replace this provider with a more complete solution, since there are many UX considerations not handled in that basic provider, like activate only on user intent, listen for account & network changes, display connection instructions and errors, etc.
+
+Some great solutions we liked to work with:
+
+- [web3-react](https://github.com/NoahZinsmeister/web3-react)
+- [web3modal](https://github.com/web3modal/web3modal)
+
+## Usage
+
+Wrap your whole app with the `Web3Provider`:
+
+```tsx
+import { Web3Provider } from '@oceanprotocol/react'
+
+function MyApp() {
+  return (
+    <Web3Provider>
+      {({ web3, chainId, account, balance, enable }) => (
+        <ul>
+          <li>Web3 available: {`${Boolean(web3)}`}</li>
+          <li>Chain ID: {chainId}</li>
+          <li>Account: {account}</li>
+          <li>Balance: {balance}</li>
+        </ul>
+      )}
+    </Web3Provider>
+  )
+}
+```
+
+You can then access the provider context values with the `useWeb3` hook:
+
+```tsx
+import { useWeb3 } from '@oceanprotocol/react'
+
+function MyComponent() {
+  const { web3, chainId, account, balance, enable } = useWeb3()
+
+  return (
+    <ul>
+      <li>Web3 available: {`${Boolean(web3)}`}</li>
+      <li>Chain ID: {chainId}</li>
+      <li>Account: {account}</li>
+      <li>Balance: {balance}</li>
+    </ul>
+  )
+}
+```