Release v0.26.0

Origin-SHA: ba6c08327287ef3e140b9681456d8aac33e1b07f

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

Author: CodySearsOS

AGENTS.md

@@ -33,7 +33,7 @@ pnpm run type-check  # TypeScript type checking
 | `src/lib/handler/` | `createToolHandler` — Web Request/Response handler factory |
 | `src/lib/middleware/` | Gating middleware (predicate gate, x402, x402 facilitators, well-known endpoint) |
 | `src/lib/wallet/` | Re-exports from `@opensea/wallet-adapters` (adapters, types, and viem bridge) |
-| `src/lib/client/` | Authenticated HTTP clients: EIP-3009 auth, x402 payment, external signer, paid authenticated fetch |
+| `src/lib/client/` | Authenticated HTTP clients: EIP-3009 auth, SIWE auth, x402 payment, external signer, paid authenticated fetch |
 | `src/lib/usage/` | Usage reporters — report tool invocations / x402 settlements to the OpenSea usage endpoint, plus EIP-3009 zero-value auth helpers |
 | `src/lib/adapters/` | Framework adapters (Vercel, Cloudflare, Express) |
 | `src/lib/utils.ts` | Shared utilities used across `lib/` |

CHANGELOG.md

@@ -1,5 +1,16 @@
 # @opensea/tool-sdk
 
+## 0.26.0
+
+### Minor Changes
+
+- 1699f42: **BREAKING**: Unify `predicateGate` to use the standard 402 + X-Payment (EIP-3009) auth flow only.
+
+  - `PredicateGateConfig.operatorAddress` is now **required** (was optional)
+  - `Authorization: EIP-3009 <token>` header is no longer accepted: use the X-Payment header via the 402 challenge flow
+  - `Authorization: SIWE <msg>.<sig>` header is no longer accepted (was already deprecated)
+  - CLI `dry-run-predicate-gate` now requires `--operator-address` and asserts a 402 response
+
 ## 0.25.0
 
 ### Minor Changes

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensea/tool-sdk",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "type": "module",
   "description": "SDK and CLI for building ERC-8257 compliant AI agent tools",
   "repository": {

skill/SKILL.md

@@ -350,7 +350,7 @@ const account = await createBankrAccount("your-bankr-api-key")
 |------|---------|--------|
 | 200 | Success | Parse the JSON body per the manifest's `outputs` schema |
 | 400 | Invalid input | Fix request body to match the manifest's `inputs` schema |
-| 401 | Missing/invalid auth (no `operatorAddress`) | Sign an EIP-3009 zero-value authorization and include `Authorization: EIP-3009 <token>` (legacy) |
+| 401 | Invalid or expired X-Payment signature | Re-sign a fresh zero-value EIP-3009 authorization and retry with the `X-Payment` header |
 | 402 | Payment / identity required | The challenge is in `body.accepts[0]` (x402 v1) or the `PAYMENT-REQUIRED` response header (v2). For predicate gates (amount `"0"`), sign a zero-value authorization; for x402 paywalls, sign the requested amount. Send it back in `X-PAYMENT` (v1) or `PAYMENT-SIGNATURE` (v2) — `pay`/`paidFetch` choose the right header automatically. |
 | 403 | Access denied | Inspect `body.predicate` to discover what's needed; acquire the required token/subscription |
 | 405 | Method not allowed | Use the verb the tool expects. `pay` auto-retries as GET when an unspecified-method POST probe returns 404/405; otherwise pass `--method <verb>`. |

skill/references/predicate-gating.md

@@ -38,7 +38,6 @@ Agent                        Tool Server                   ToolRegistry (onchain
 8. If access is denied: return 403 with predicate address for self-diagnosis
 9. If predicate misbehaved: return 502
 
-> **Backward compatibility:** The gate still accepts `Authorization: EIP-3009 <base64url(json)>` and deprecated `Authorization: SIWE <token>` headers. However, the 402 + `X-Payment` flow is preferred for new integrations because it mirrors the x402 pattern and lets the client discover the correct `to` address from the challenge.
 
 ## Build a predicate-gated tool (server side)
 
@@ -74,6 +73,7 @@ export const toolHandler = createToolHandler({
   gates: [
     predicateGate({
       toolId: 1n,  // your onchain tool ID from registration
+      operatorAddress: "0xYOUR_OPERATOR_ADDRESS",  // receives the zero-value authorization
       // chain: base,
       // rpcUrl: "https://mainnet.base.org",
     }),

src/__tests__/auth.test.ts

@@ -220,7 +220,7 @@ describe("auth command", () => {
 
 function stubBankrFetch() {
   return vi.fn(async (url: string, init?: RequestInit) => {
-    if (typeof url === "string" && url.includes("/wallet/info")) {
+    if (typeof url === "string" && url.includes("/wallet/me")) {
       return new Response(JSON.stringify({ address: BANKR_ADDRESS }), {
         status: 200,
       })
@@ -258,8 +258,8 @@ describe("auth command with --bankr-key", () => {
       "{}",
     ])
 
-    // Should have called /wallet/info first
-    expect(fetchMock.mock.calls[0][0]).toContain("/wallet/info")
+    // Should have called /wallet/me first
+    expect(fetchMock.mock.calls[0][0]).toContain("/wallet/me")
 
     // Should print the Bankr address
     const output = logSpy.mock.calls.map(c => c.join(" ")).join("\n")
@@ -287,8 +287,8 @@ describe("auth command with --bankr-key", () => {
       "{}",
     ])
 
-    // Bankr path: first call should be /wallet/info
-    expect(fetchMock.mock.calls[0][0]).toContain("/wallet/info")
+    // Bankr path: first call should be /wallet/me
+    expect(fetchMock.mock.calls[0][0]).toContain("/wallet/me")
 
     logSpy.mockRestore()
   })

src/__tests__/delegation-gate.test.ts

@@ -8,6 +8,8 @@ const HOLDER_ADDRESS =
   "0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984" as `0x${string}`
 const TEST_PREDICATE =
   "0xpredicatepredicatepredicatepredicatepredi" as `0x${string}`
+const TEST_OPERATOR =
+  "0x5ECA0441311643608a8c9Ab8B250f695Dd32E2a8" as `0x${string}`
 
 const mockTryHasAccess = vi.fn(async () => ({ ok: true, granted: true }))
 const mockGetToolConfig = vi.fn(async () => ({
@@ -31,24 +33,12 @@ vi.mock("viem", async importOriginal => {
   return {
     ...actual,
     createPublicClient: () => ({
-      verifySiweMessage: vi.fn().mockResolvedValue(true),
       readContract: mockReadContract,
     }),
+    recoverTypedDataAddress: () => Promise.resolve(AGENT_ADDRESS),
   }
 })
 
-vi.mock("viem/siwe", () => ({
-  parseSiweMessage: vi.fn().mockReturnValue({
-    address: AGENT_ADDRESS,
-    domain: "example.com",
-    uri: "https://example.com",
-    version: "1",
-    chainId: 8453,
-    nonce: "testnonce",
-    issuedAt: new Date(),
-  }),
-}))
-
 beforeEach(() => {
   mockTryHasAccess.mockReset()
   mockTryHasAccess.mockResolvedValue({ ok: true, granted: true })
@@ -60,19 +50,33 @@ afterEach(() => {
   vi.clearAllMocks()
 })
 
-function makeAuthHeader(): string {
-  const siweB64 = btoa("mock-siwe-message")
-    .replace(/\+/g, "-")
-    .replace(/\//g, "_")
-    .replace(/=/g, "")
-  return `SIWE ${siweB64}.0xmocksignature`
+function makeXPaymentHeader(overrides: Record<string, unknown> = {}): string {
+  const authorization = {
+    from: AGENT_ADDRESS,
+    to: TEST_OPERATOR,
+    value: "0",
+    validAfter: "0",
+    validBefore: String(Math.floor(Date.now() / 1000) + 300),
+    nonce: "0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
+    ...overrides,
+  }
+  const payload = {
+    x402Version: 1,
+    scheme: "exact",
+    network: "base",
+    payload: {
+      signature: "0xabcd",
+      authorization,
+    },
+  }
+  return Buffer.from(JSON.stringify(payload)).toString("base64")
 }
 
 function makeRequest(headers?: Record<string, string>): Request {
   return new Request("https://example.com/api", {
     method: "POST",
     headers: {
-      Authorization: makeAuthHeader(),
+      "X-Payment": makeXPaymentHeader(),
       ...headers,
     },
   })
@@ -83,7 +87,10 @@ describe("predicateGate with delegate.xyz delegation", () => {
     const { predicateGate } = await import(
       "../lib/middleware/predicate-gate.js"
     )
-    const gate = predicateGate({ toolId: TEST_TOOL_ID })
+    const gate = predicateGate({
+      toolId: TEST_TOOL_ID,
+      operatorAddress: TEST_OPERATOR,
+    })
     const ctx: Partial<ToolContext> = { gates: {} }
 
     const response = await gate.check(
@@ -118,7 +125,10 @@ describe("predicateGate with delegate.xyz delegation", () => {
     const { predicateGate } = await import(
       "../lib/middleware/predicate-gate.js"
     )
-    const gate = predicateGate({ toolId: TEST_TOOL_ID })
+    const gate = predicateGate({
+      toolId: TEST_TOOL_ID,
+      operatorAddress: TEST_OPERATOR,
+    })
     const ctx: Partial<ToolContext> = { gates: {} }
 
     const response = await gate.check(
@@ -136,7 +146,10 @@ describe("predicateGate with delegate.xyz delegation", () => {
     const { predicateGate } = await import(
       "../lib/middleware/predicate-gate.js"
     )
-    const gate = predicateGate({ toolId: TEST_TOOL_ID })
+    const gate = predicateGate({
+      toolId: TEST_TOOL_ID,
+      operatorAddress: TEST_OPERATOR,
+    })
     const ctx: Partial<ToolContext> = { gates: {} }
 
     const response = await gate.check(
@@ -155,7 +168,10 @@ describe("predicateGate with delegate.xyz delegation", () => {
     const { predicateGate } = await import(
       "../lib/middleware/predicate-gate.js"
     )
-    const gate = predicateGate({ toolId: TEST_TOOL_ID })
+    const gate = predicateGate({
+      toolId: TEST_TOOL_ID,
+      operatorAddress: TEST_OPERATOR,
+    })
     const ctx: Partial<ToolContext> = { gates: {} }
 
     const response = await gate.check(
@@ -174,7 +190,10 @@ describe("predicateGate with delegate.xyz delegation", () => {
     const { predicateGate } = await import(
       "../lib/middleware/predicate-gate.js"
     )
-    const gate = predicateGate({ toolId: TEST_TOOL_ID })
+    const gate = predicateGate({
+      toolId: TEST_TOOL_ID,
+      operatorAddress: TEST_OPERATOR,
+    })
     const ctx: Partial<ToolContext> = { gates: {} }
 
     const response = await gate.check(
@@ -196,9 +215,11 @@ describe("predicateGate with delegate.xyz delegation", () => {
     const { predicateGate } = await import(
       "../lib/middleware/predicate-gate.js"
     )
-    const gate = predicateGate({ toolId: TEST_TOOL_ID })
+    const gate = predicateGate({
+      toolId: TEST_TOOL_ID,
+      operatorAddress: TEST_OPERATOR,
+    })
 
-    // Override parseSiweMessage to return AGENT_ADDRESS as caller for this test
     mockTryHasAccess.mockResolvedValue({ ok: true, granted: true })
 
     const ctx: Partial<ToolContext> = { gates: {} }
@@ -218,6 +239,7 @@ describe("predicateGate with delegate.xyz delegation", () => {
     )
     const gate = predicateGate({
       toolId: TEST_TOOL_ID,
+      operatorAddress: TEST_OPERATOR,
       delegateRegistryAddress: customAddress,
     })
     const ctx: Partial<ToolContext> = { gates: {} }

src/__tests__/external-signer.test.ts

@@ -218,9 +218,9 @@ describe("external signer + authenticatedFetch round-trip", () => {
 const BANKR_ADDRESS = "0x8b8e1C20E0630De8C60f0e0D5C3e9C7c20F0c20e"
 
 describe("createBankrAccount", () => {
-  it("fetches address from /wallet/info and creates a signing account", async () => {
+  it("fetches address from /wallet/me and creates a signing account", async () => {
     const fetchMock = vi.fn(async (url: string, _init?: RequestInit) => {
-      if (url.includes("/wallet/info")) {
+      if (url.includes("/wallet/me")) {
         return new Response(JSON.stringify({ address: BANKR_ADDRESS }), {
           status: 200,
         })
@@ -241,9 +241,9 @@ describe("createBankrAccount", () => {
     const sig = await account.signMessage!({ message: "hello" })
     expect(sig).toBe("0xdeadbeef")
 
-    // Verify /wallet/info was called with API key header
+    // Verify /wallet/me was called with API key header
     const infoCall = fetchMock.mock.calls[0]
-    expect(infoCall[0]).toContain("/wallet/info")
+    expect(infoCall[0]).toContain("/wallet/me")
     expect(infoCall[1]?.headers).toEqual(
       expect.objectContaining({ "X-API-Key": "test-api-key" }),
     )
@@ -256,22 +256,22 @@ describe("createBankrAccount", () => {
     expect(signBody.message).toBe("hello")
   })
 
-  it("throws when /wallet/info returns an error", async () => {
+  it("throws when /wallet/me returns an error", async () => {
     vi.stubGlobal(
       "fetch",
       vi.fn(async () => new Response("Unauthorized", { status: 401 })),
     )
 
     await expect(createBankrAccount("bad-key")).rejects.toThrow(
-      "Bankr /wallet/info failed (401)",
+      "Bankr /wallet/me failed (401)",
     )
   })
 
   it("throws when /wallet/sign returns an error", async () => {
     vi.stubGlobal(
       "fetch",
       vi.fn(async (url: string) => {
-        if (typeof url === "string" && url.includes("/wallet/info")) {
+        if (typeof url === "string" && url.includes("/wallet/me")) {
           return new Response(JSON.stringify({ address: BANKR_ADDRESS }), {
             status: 200,
           })