Release v0.3.1

Origin-SHA: aab183ad42e10a44f34d71f4ecd1ef027be8d8c8

Co-authored-by: Ryan Ghods <ryan@ryanio.com>

Author: CodySearsOS

AGENTS.md

@@ -26,6 +26,7 @@ pnpm run type-check  # TypeScript type checking
 | `src/adapters/fireblocks.ts` | Fireblocks enterprise MPC custody adapter |
 | `src/adapters/private-key.ts` | Raw private key adapter (dev/testing) |
 | `src/factory.ts` | `createWalletFromEnv()` — auto-detection from env vars |
+| `src/util/eip712.ts` | EIP-712 typed data hashing utilities used by adapters for `signTypedData` |
 | `src/bridges/viem.ts` | Bridge: WalletAdapter → viem WalletClient |
 | `src/bridges/ethers.ts` | Bridge: WalletAdapter → ethers.js Signer |
 | `src/__tests__/` | Vitest test suite |

CHANGELOG.md

@@ -1,5 +1,11 @@
 # @opensea/wallet-adapters
 
+## 0.3.1
+
+### Patch Changes
+
+- c982513: Make `RPC_URL` optional for signing-only workflows. The factory and the private-key adapter no longer require `RPC_URL` when an adapter is only used to sign (not broadcast) transactions, so a key configured purely for signing no longer fails to initialize. A read provider is created lazily and only when a chain operation actually needs one.
+
 ## 0.3.0
 
 ### Minor Changes

README.md

@@ -2,6 +2,17 @@
 
 Provider-agnostic wallet adapters for signing and sending transactions across managed and local backends.
 
+## Why wallet-adapters?
+
+`@opensea/wallet-adapters` is the shared wallet layer used across the OpenSea developer toolchain. Every package that needs to sign transactions depends on the same `WalletAdapter` interface:
+
+- [`@opensea/sdk`](https://github.com/ProjectOpenSea/opensea-js) — TypeScript SDK for buying, selling, and managing NFTs
+- [`@opensea/cli`](https://github.com/ProjectOpenSea/opensea-cli) — command-line interface for the OpenSea API
+- [`@opensea/tool-sdk`](https://github.com/ProjectOpenSea/tool-sdk) — SDK for building ERC-8257 AI agent tools
+- [`opensea-skill`](https://github.com/ProjectOpenSea/opensea-skill) — modular AI agent skills for Claude, Devin, and other assistants
+
+By implementing the `WalletAdapter` interface once, a new wallet provider automatically works everywhere — the CLI, the SDK, AI agent tool execution, and any future package that depends on this library.
+
 ## Features
 
 - **Provider-agnostic interface** — unified `WalletAdapter` abstraction with capabilities declaration
@@ -151,6 +162,33 @@ wallet.onResponse = (method, result, durationMs) => {
 }
 ```
 
+## Adding a New Provider
+
+To add a wallet provider, implement the `WalletAdapter` interface:
+
+```ts
+import type { WalletAdapter, WalletCapabilities } from "@opensea/wallet-adapters"
+
+export class MyProviderAdapter implements WalletAdapter {
+  readonly name = "my-provider"
+  readonly capabilities: WalletCapabilities = {
+    signMessage: true,
+    signTypedData: true,
+    managedGas: true,
+    managedNonce: true,
+  }
+
+  async getAddress(): Promise<string> { /* ... */ }
+  async sendTransaction(tx) { /* ... */ }
+  async signMessage(request) { /* ... */ }
+  async signTypedData(request) { /* ... */ }
+
+  static fromEnv(): MyProviderAdapter { /* ... */ }
+}
+```
+
+Then register it in the `createWalletFromEnv()` factory in `src/factory.ts` so the CLI and tool-sdk auto-detect it from environment variables.
+
 ## License
 
 MIT

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensea/wallet-adapters",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "description": "Provider-agnostic wallet adapters for signing and sending transactions across managed and local backends",
   "license": "MIT",

src/__tests__/adapters.test.ts

@@ -150,14 +150,25 @@ describe("PrivateKeyAdapter", () => {
     )
   })
 
-  it("fromEnv throws when RPC_URL is missing", () => {
+  it("fromEnv succeeds without RPC_URL (signing-only mode)", () => {
     process.env.PRIVATE_KEY = TEST_PRIVATE_KEY
-    expect(() => PrivateKeyAdapter.fromEnv()).toThrow(
-      "RPC_URL environment variable is required",
-    )
+    const adapter = PrivateKeyAdapter.fromEnv()
+    expect(adapter.getRpcUrl()).toBeUndefined()
     delete process.env.PRIVATE_KEY
   })
 
+  it("sendTransaction throws when RPC_URL is not configured", async () => {
+    const adapter = new PrivateKeyAdapter({ privateKey: TEST_PRIVATE_KEY })
+    await expect(
+      adapter.sendTransaction({
+        to: "0x0000000000000000000000000000000000000001",
+        data: "0x",
+        value: "0",
+        chainId: 1,
+      }),
+    ).rejects.toThrow("RPC_URL is required for sending transactions")
+  })
+
   it("signMessage produces a valid 65-byte signature", async () => {
     const adapter = new PrivateKeyAdapter({
       privateKey: TEST_PRIVATE_KEY,

src/adapters/private-key.ts

@@ -8,9 +8,10 @@
  *
  * Required environment variables:
  *   PRIVATE_KEY — Hex-encoded private key (with or without 0x prefix)
- *   RPC_URL    — JSON-RPC endpoint for broadcasting and gas estimation
  *
  * Optional:
+ *   RPC_URL        — JSON-RPC endpoint for broadcasting and gas estimation
+ *                    (required only when sending transactions)
  *   WALLET_ADDRESS — Pre-computed address (skips derivation)
  */
 
@@ -30,7 +31,7 @@ import { bytesToHex, hexToBytes, rlpEncodeEip1559Tx } from "./turnkey.js"
 
 export interface PrivateKeyConfig {
   privateKey: string
-  rpcUrl: string
+  rpcUrl?: string
   address?: string
 }
 
@@ -59,9 +60,6 @@ export class PrivateKeyAdapter implements WalletAdapter {
     if (!privateKey) {
       throw new Error("PRIVATE_KEY environment variable is required")
     }
-    if (!rpcUrl) {
-      throw new Error("RPC_URL environment variable is required")
-    }
 
     const clean = privateKey.startsWith("0x") ? privateKey.slice(2) : privateKey
     if (!/^[0-9a-fA-F]{64}$/.test(clean)) {
@@ -77,7 +75,7 @@ export class PrivateKeyAdapter implements WalletAdapter {
     })
   }
 
-  getRpcUrl(): string {
+  getRpcUrl(): string | undefined {
     return this.config.rpcUrl
   }
 
@@ -99,7 +97,12 @@ export class PrivateKeyAdapter implements WalletAdapter {
     const startTime = Date.now()
 
     const from = await this.getAddress()
-    const { rpcUrl } = this.config
+    const rpcUrl = this.config.rpcUrl
+    if (!rpcUrl) {
+      throw new Error(
+        "RPC_URL is required for sending transactions. Set the RPC_URL environment variable or pass --rpc-url.",
+      )
+    }
 
     let nonce: bigint
     let gasLimit: bigint

src/factory.ts

@@ -42,7 +42,7 @@ export function createWalletFromEnv(): WalletAdapter {
       "  • Fireblocks: FIREBLOCKS_API_KEY, FIREBLOCKS_API_SECRET, FIREBLOCKS_VAULT_ID\n" +
       "  • Turnkey: TURNKEY_API_PUBLIC_KEY, TURNKEY_API_PRIVATE_KEY, TURNKEY_ORGANIZATION_ID, TURNKEY_WALLET_ADDRESS, TURNKEY_RPC_URL\n" +
       "  • Bankr: BANKR_API_KEY\n" +
-      "  • PrivateKey: PRIVATE_KEY, RPC_URL",
+      "  • PrivateKey: PRIVATE_KEY (optionally RPC_URL for sending transactions)",
   )
 }
 

src/types/index.ts

@@ -131,7 +131,7 @@ export interface WalletAdapter {
   getWalletInfo?(): Promise<WalletInfo>
 
   /** Optional RPC URL for read operations (gas estimation, nonce, etc.) */
-  getRpcUrl?(): string
+  getRpcUrl?(): string | undefined
 
   /** Optional hook called before each adapter request (for metrics/logging) */
   onRequest?: (method: string, params: unknown) => void