@coinbase/cdp-core 0.0.123 → 0.0.125

package/README.md

@@ -33,6 +33,66 @@ in CDP Portal, and click Add origin to include your local app
 2. Enter the origin of your locally running app - e.g., `http://localhost:3000`
 3. Click Add origin again to save your changes
 
+### React Native Storage
+
+On React Native, the SDK stores state through `@react-native-async-storage/async-storage` by
+default. AsyncStorage is an optional peer dependency of `@coinbase/cdp-core`. Apps that use a
+different store supply an adapter with `configurePlatformServices`. Configure it at startup, after
+importing `@coinbase/cdp-core` and before calling `initialize`.
+
+`configurePlatformServices` replaces only the services you pass. Every other service keeps its
+React Native default. Platform storage holds the pending OAuth flow ID, backs OAuth flow
+validation, holds the embedded wallet store, and mirrors the refresh token on platforms without
+secure storage. `getItemWithOutcome` is optional on a custom adapter. The SDK derives it from
+`getItem` when you omit it.
+
+The pending OAuth flow ID is CSRF state. Its store must be private to the app and must not be
+writable by another origin or app.
+
+An app without `@react-native-async-storage/async-storage` very likely also lacks
+`expo-secure-store`, which the SDK uses for the refresh token on native. Such an app must install
+`expo-secure-store` or also pass `secureStorage` to `configurePlatformServices`. Without secure
+storage, the app can sign in and then be signed out on the next token refresh.
+
+For example, create `cdp-storage.ts` with an [MMKV](https://github.com/mrousavy/react-native-mmkv)
+adapter. `createMMKV` is the `react-native-mmkv` v4 API; v2 and v3 used `new MMKV()`.
+
+```ts lines
+import { configurePlatformServices, type PlatformStorageOverride } from "@coinbase/cdp-core";
+import { createMMKV } from "react-native-mmkv";
+
+const mmkv = createMMKV({ id: "cdp" });
+
+export const mmkvStorage: PlatformStorageOverride = {
+  async getItem(key) {
+    return mmkv.getString(key) ?? null;
+  },
+  async setItem(key, value) {
+    mmkv.set(key, value);
+  },
+  async removeItem(key) {
+    mmkv.remove(key);
+  },
+  async clear() {
+    mmkv.clearAll();
+  },
+};
+
+configurePlatformServices({ storage: mmkvStorage });
+```
+
+The SDK never calls `clear()` itself. `clearAll()` is safe here because
+`createMMKV({ id: "cdp" })` dedicates the instance to CDP. An adapter over a shared instance must
+scope `clear` to CDP keys.
+
+Import that file for its side effect from your app entry point, ahead of the code that calls
+`initialize`:
+
+```ts lines
+import "./cdp-storage";
+import "expo-router/entry";
+```
+
 ### Initialize the SDK
 
 Before calling any methods in the SDK, you must first initialize it:
@@ -1293,48 +1353,36 @@ console.log("Solana Private Key:", privateKey);
 
 ### X402 Payment Protocol Support
 
-The SDK includes built-in support for the X402 payment protocol, which enables HTTP requests with micropayments. This allows accessing paid APIs and services that require payment for each request.
+The SDK includes built-in support for the x402 (v2) payment protocol, which enables HTTP requests with micropayments. This allows accessing paid APIs and services that require payment for each request.
+
+By default, `fetchWithX402` registers the `exact`, `upto` (usage-based billing), and `authCapture` (escrow-style holds) schemes on Base mainnet for an EVM account, and `exact`/`upto` on Solana mainnet for a Solana account — see [Advanced Configuration](#advanced-configuration) to opt out of a scheme.
 
 #### Installation
 
-Ensure you have separately installed the `x402-fetch` package:
+Ensure you have separately installed the `@x402/*` packages:
 
 ```bash
-npm install x402-fetch
+npm install @x402/core @x402/evm @x402/svm @x402/fetch
 ```
 
 #### Basic Usage
 
-The `fetchWithX402` function provides a wrapped fetch API that automatically handles X402 payment requests:
+The `fetchWithX402` function provides a wrapped fetch API that automatically handles x402 payment requests:
 
 ```typescript lines
 import { fetchWithX402, getCurrentUser } from "@coinbase/cdp-core";
 
 // The user must be authenticated first
-const user = await getCurrentUser();
+await getCurrentUser();
 
-// Create a fetch function with X402 payment handling
 const { fetchWithPayment } = fetchWithX402();
-
-// Make a request to an X402-protected resource
-try {
-  const response = await fetchWithPayment("https://api.example.com/paid-endpoint", {
-    method: "GET",
-    headers: {
-      "Content-Type": "application/json"
-    }
-  });
-  
-  const data = await response.json();
-  console.log("Paid API response:", data);
-} catch (error) {
-  console.error("X402 payment failed:", error);
-}
+const response = await fetchWithPayment("https://api.example.com/paid-endpoint");
+const data = await response.json();
 ```
 
 #### Advanced Configuration
 
-You can customize the X402 behavior with options:
+You can customize the x402 behavior with options:
 
 ```typescript lines
 // Use a specific address for payments (instead of the user's default)
@@ -1344,18 +1392,40 @@ const { fetchWithPayment } = fetchWithX402({
 
 // Use a custom fetch implementation
 const customFetch = (url, options) => {
-  console.log("Making request to:", url);
-  return fetch(url, options);
+  return fetch(url, { ...options, cache: "no-store" });
 };
 
 const { fetchWithPayment } = fetchWithX402({
   fetch: customFetch
 });
+
+// Also register Base Sepolia (e.g. for local testing) and disable authCapture.
+const { fetchWithPayment: fetchWithTestnet } = fetchWithX402({
+  rpcUrls: { "eip155:84532": "https://sepolia.base.org" },
+  schemes: { authCapture: false },
+});
+```
+
+**Options:**
+
+| Option     | Description                                                                                                                                                                                    |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `address`  | The address of the account to use for payments. Defaults to the signed-in user's smart account, then EOA, then Solana account.                                                                |
+| `fetch`    | A custom `fetch` implementation to wrap.                                                                                                                                                       |
+| `rpcUrls`  | CAIP-2 network id → RPC URL overrides, e.g. `{ "eip155:84532": "https://sepolia.base.org" }`. Also registers schemes on any additional `eip155:*`/`solana:*` network supplied here, on top of the Base mainnet + Solana mainnet baseline. |
+| `policies` | `PaymentPolicy`s registered on the underlying `x402Client`, e.g. to cap spend or restrict networks/assets.                                                                                     |
+| `schemes`  | Opt-in/out per payment scheme: `exact`, `upto`, and `authCapture` all default to `true`. `authCapture` only applies to EVM (Base).           |
+
+`fetchWithX402` also returns the underlying `x402Client` as a promise, for advanced use (e.g. registering additional schemes or policies at runtime):
+
+```typescript lines
+const { client } = fetchWithX402();
+const x402Client = await client;
 ```
 
 #### How It Works
 
-1. When you make a request to an X402-protected resource, the server responds with a `402 Payment Required` status
+1. When you make a request to an x402-protected resource, the server responds with a `402 Payment Required` status
 2. The wrapped fetch function automatically:
    - Extracts payment details from the server's response
    - Creates and signs a payment transaction using the user's wallet
@@ -1371,12 +1441,12 @@ const user = await getCurrentUser();
 console.log("Using account:", user.evmSmartAccountObjects?.[0] || user.evmAccountObjects?.[0]);
 
 // This will automatically use the appropriate account type
-const { fetchWithPayment } = await fetchWithX402();
+const { fetchWithPayment } = fetchWithX402();
 ```
 
 #### Solana Support
 
-Solana is supported out of the box with `fetchWithX402`. If your end user has both an EVM and Solana account, the EVM account will be used by default. You can pass a Solana address to `fetchWithX402` to use the Solana account instead.
+Solana is supported out of the box with `fetchWithX402` — the `exact` and `upto` schemes are registered on Solana mainnet by default. If your end user has both an EVM and Solana account, the EVM account will be used by default. You can pass a Solana address to `fetchWithX402` to use the Solana account instead.
 
 ```typescript lines
 const user = await getCurrentUser();