Release v0.16.0

CodySearsOS · CodySearsOS · commit 85447ac4de66 · 2026-06-08T17:23:54.000Z
Origin-SHA: 0e840532ebf4153daeb68d1cca7cee3e15dc2205
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,15 @@
 # @opensea/tool-sdk
 
+## 0.16.0
+
+### Minor Changes
+
+- Add `paidPredicateGate`, a combined gate that resolves identity verification (predicate) and x402 payment in a single 402 round trip.
+
+  Tools using `paidPredicateGate` need only 2 requests (a 402 advertising the real payment amount, then a 200) instead of 3 (predicate 402, then x402 402, then 200). The caller's `X-Payment` signature for the payment amount simultaneously proves identity, via the recovered `from` address, and authorizes the transfer. The onchain predicate is checked before the facilitator settles payment: if access is denied, the gate returns a 403 and no funds move.
+
+  New exports: `paidPredicateGate` and `PaidPredicateGateConfig`.
+
 ## 0.15.0
 
 ### Minor Changes
diff --git a/README.md b/README.md
@@ -842,6 +842,27 @@ const data = await res.json()
 
 Gate your tool using the onchain access predicate system. When `operatorAddress` is configured, `predicateGate` uses a unified 402 challenge flow: it returns `PaymentRequirements` with `maxAmountRequired: "0"`, the caller signs a zero-value `X-Payment`, and the middleware recovers the caller's address via `ecrecover`. Access is then delegated to `IToolRegistry.tryHasAccess` — it works with ERC721OwnerPredicate, ERC1155OwnerPredicate, SubscriptionPredicate, ERC20BalancePredicate, CompositePredicate, or any future predicate automatically.
 
+#### Combined predicate + payment (`paidPredicateGate`)
+
+For tools that require **both** predicate access and x402 payment, use `paidPredicateGate` to resolve identity and payment in a single 402 round trip (2 requests instead of 3):
+
+```typescript
+import { paidPredicateGate } from "@opensea/tool-sdk"
+import { mainnet } from "viem/chains"
+
+gates: [
+  paidPredicateGate({
+    toolId: 1n,
+    operatorAddress: "0xYOUR_WALLET",
+    amountUsdc: "0.05",
+    chain: mainnet,
+    rpcUrl: "https://ethereum-rpc.publicnode.com",
+  }),
+]
+```
+
+The gate advertises the real payment amount in the 402 challenge. The caller's `X-Payment` signature proves identity (`from`) AND authorizes payment in one step. The predicate is verified before payment settles — if access is denied, no funds move.
+
 See [docs/predicate-gating-guide.md](docs/predicate-gating-guide.md) for the full setup walkthrough.
 
 ## Usage Reporting
diff --git a/docs/predicate-gating-guide.md b/docs/predicate-gating-guide.md
@@ -327,57 +327,60 @@ The holder can revoke the delegation at any time by visiting [delegate.xyz](http
 
 ## Combining predicate gating with x402 payment
 
-You can stack both gates to require **identity verification and per-call payment**:
+Use `paidPredicateGate` to require **identity verification and per-call payment** in a single 402 round trip (2 requests total instead of 3):
 
 ```typescript
 import {
   createToolHandler,
   defineManifest,
-  payaiX402Gate,
-  predicateGate,
-  x402UsdcPricing,
+  paidPredicateGate,
 } from "@opensea/tool-sdk"
+import { mainnet } from "viem/chains"
 
 export const manifest = defineManifest({
   // ...
-  pricing: x402UsdcPricing({
-    recipient: "0xYourPayoutAddress",
-    amountUsdc: "0.01",
-  }),
+  pricing: { model: "pay_per_call", amount: "0.01", currency: "USDC" },
 })
 
 const handler = createToolHandler({
   manifest,
   inputSchema,
   outputSchema,
   gates: [
-    predicateGate({ toolId: 1n }),
-    payaiX402Gate({
-      recipient: "0xYourPayoutAddress",
+    paidPredicateGate({
+      toolId: 1n,
+      operatorAddress: "0xYourPayoutAddress",
       amountUsdc: "0.01",
+      chain: mainnet,
+      rpcUrl: "https://ethereum-rpc.publicnode.com",
     }),
   ],
   handler: async (input, ctx) => {
-    // ctx.callerAddress — verified wallet (set by predicate gate)
+    // ctx.callerAddress — verified wallet (recovered from X-Payment)
     // ctx.gates.predicate.granted === true
     // ctx.gates.x402.paid === true
     return { result: "access granted and payment received" }
   },
 })
 ```
 
-### Middleware ordering
+### How `paidPredicateGate` works
 
-Gates run in array order (see `src/lib/handler/index.ts`). Put `predicateGate` **first**:
+The combined gate issues a single 402 with the **real payment amount** (not zero). The caller's `X-Payment` signature simultaneously:
+- Proves identity (the recovered `from` address)
+- Authorizes the USDC transfer (via the facilitator)
 
-1. **Predicate gate** runs first — returns 402 with zero-value `PaymentRequirements`. The client signs a zero-value `X-Payment` and retries. Once verified, the predicate gate establishes `ctx.callerAddress`. Returns `403` if the predicate denies access.
-2. **x402 gate** runs second — returns 402 with real payment `PaymentRequirements`. The client signs a real `X-Payment` and retries. Returns `402` if no payment is provided.
+The gate runs these checks in order:
+1. Verify the EIP-712 signature and recover the caller's address
+2. Check the onchain predicate (`tryHasAccess`) — returns 403 if denied
+3. Verify the payment with the facilitator — returns 402 if invalid
+4. After the handler succeeds: settle the payment via the facilitator
 
-The client handles multiple 402 challenges in a retry loop — `paidAuthenticatedFetch` does this automatically.
+This ordering ensures **no funds move** if the predicate denies access.
 
 ### Client requirements
 
-`paidAuthenticatedFetch` handles the multi-402 flow automatically: it sends a bare request, then on each 402 reads `PaymentRequirements`, signs an `X-Payment`, and retries. No separate `Authorization` header is needed.
+`paidAuthenticatedFetch` handles the 402 challenge automatically. Since `paidPredicateGate` issues only one 402, the client signs once and the call completes:
 
 ```typescript
 import { paidAuthenticatedFetch } from "@opensea/tool-sdk"
@@ -387,6 +390,18 @@ const response = await paidAuthenticatedFetch(toolUrl, {
   method: "POST",
   headers: { "Content-Type": "application/json" },
   body: JSON.stringify({ query: "hello" }),
-  maxAmount: "100000",  // safety cap for the x402 payment
+  maxAmount: "100000",  // safety cap: 0.10 USDC
+  allowedRecipients: ["0xYourPayoutAddress"],
 })
 ```
+
+### Legacy: separate gates (3 requests)
+
+For backward compatibility, you can still chain `predicateGate` + x402 gate as separate middleware. The client handles both 402s in a retry loop. However, `paidPredicateGate` is preferred for new tools.
+
+```typescript
+gates: [
+  predicateGate({ toolId: 1n, operatorAddress: "0x..." }),
+  payaiX402Gate({ recipient: "0x...", amountUsdc: "0.01" }),
+]
+```
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@opensea/tool-sdk",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "type": "module",
   "description": "SDK and CLI for building ERC-8257 compliant AI agent tools",
   "repository": {
diff --git a/skill/SKILL.md b/skill/SKILL.md
@@ -528,11 +528,11 @@ PRIVATE_KEY=0x... RPC_URL=https://mainnet.base.org \
   --body '{"query": "hello"}'
 ```
 
-### Example F: NFT-gated + paid tool (both gates)
+### Example F: NFT-gated + paid tool (combined gate, single round trip)
 
 ```bash
-# Server: add both predicateGate and paywall.gate (see references/predicate-gating.md)
-# Call via CLI:
+# Server: use paidPredicateGate (see references/predicate-gating.md)
+# Single 402: identity proof + payment in one X-Payment signature
 PRIVATE_KEY=0x... RPC_URL=https://mainnet.base.org \
   npx @opensea/tool-sdk pay --auth \
   https://my-tool.vercel.app/api \
diff --git a/skill/references/predicate-gating.md b/skill/references/predicate-gating.md
@@ -169,24 +169,45 @@ const [requirements, logic] = await client.readContract({
 
 ## Combined gates (predicate + x402)
 
-Tools can require both identity verification and x402 payment. The server runs gates sequentially: predicate first (identity via zero-value `X-Payment`), then x402 (real payment via `X-Payment`). The client handles multiple 402 challenges in a retry loop.
+Tools that require both identity verification (predicate) and x402 payment should use `paidPredicateGate` — a single gate that resolves both in **one 402 round trip** instead of two.
 
-### Server side
+### Flow (2 requests instead of 3)
+
+```
+Agent                        Tool Server                   ToolRegistry + Facilitator
+  |--- POST /api ------------->|                                |
+  |    (no auth headers)       |                                |
+  |                            |  (no X-Payment → 402)          |
+  |<-- 402 + PaymentReqs ------|                                |
+  |    {payTo: operator,       |                                |
+  |     maxAmountRequired: "$"}|                                |
+  |                            |                                |
+  |--- POST /api ------------->|                                |
+  |    X-Payment(to=op, val=$) |                                |
+  |                            |  (verify X-Payment signature)  |
+  |                            |  (recover signer = from)       |
+  |                            |--- tryHasAccess(toolId, from)->|
+  |                            |<-- granted=true ---------------|
+  |                            |--- /verify (facilitator) ----->|
+  |                            |<-- isValid=true ---------------|
+  |                            |  (execute handler)             |
+  |<-- 200 + result -----------|                                |
+  |                            |--- /settle (facilitator) ----->|  (post-response)
+```
+
+The caller's real-value `X-Payment` signature simultaneously proves identity (`from` = caller) AND authorizes payment. The predicate is checked BEFORE the facilitator settles — if the caller doesn't meet the access requirement, a 403 is returned and no funds move.
+
+### Server side: `paidPredicateGate`
 
 ```typescript
 import {
   createToolHandler,
-  defineToolPaywall,
-  predicateGate,
+  paidPredicateGate,
   defineManifest,
 } from "@opensea/tool-sdk"
+import { mainnet } from "viem/chains"
 import { z } from "zod/v4"
 
-const paywall = defineToolPaywall({
-  recipient: "0xYOUR_WALLET",
-  amountUsdc: "0.05",
-})
-
 export const toolHandler = createToolHandler({
   manifest: defineManifest({
     name: "Premium Gated Tool",
@@ -195,7 +216,7 @@ export const toolHandler = createToolHandler({
     creatorAddress: "0xYOUR_WALLET",
     inputs: { type: "object", properties: { query: { type: "string" } }, required: ["query"] },
     outputs: { type: "object", properties: { result: { type: "string" } } },
-    pricing: paywall.pricing,
+    pricing: { model: "pay_per_call", amount: "0.05", currency: "USDC" },
     access: {
       logic: "OR",
       requirements: [{
@@ -208,16 +229,23 @@ export const toolHandler = createToolHandler({
   inputSchema: z.object({ query: z.string() }),
   outputSchema: z.object({ result: z.string() }),
   gates: [
-    predicateGate({ toolId: 1n }),  // checked first
-    paywall.gate,                   // checked second
+    paidPredicateGate({
+      toolId: 1n,
+      operatorAddress: "0xYOUR_WALLET",
+      amountUsdc: "0.05",
+      chain: mainnet,       // chain where the registry lives
+      rpcUrl: "https://ethereum-rpc.publicnode.com",
+      // network: "base",   // payment network (default: base)
+      // facilitator: "payai",  // or "cdp"
+    }),
   ],
   handler: async (input) => ({ result: input.query }),
 })
 ```
 
 ### Client side: `paidAuthenticatedFetch`
 
-`paidAuthenticatedFetch` handles multiple 402 challenges automatically: it sends a bare request, then on each 402 it reads the `PaymentRequirements`, signs an `X-Payment`, and retries. For a combined predicate + x402 tool, the first 402 is the predicate's zero-value challenge and the second is the x402 real payment.
+`paidAuthenticatedFetch` handles the 402 challenge automatically. For a `paidPredicateGate` tool, only one 402 is issued (with the real amount), so the client signs once and the call completes.
 
 ```typescript
 import { paidAuthenticatedFetch, createWalletFromEnv, walletAdapterToClient } from "@opensea/tool-sdk"
@@ -227,20 +255,32 @@ const adapter = createWalletFromEnv()
 const client = await walletAdapterToClient(adapter, base)
 
 const res = await paidAuthenticatedFetch("https://my-tool.example.com/api", {
-  account: client.account,   // for X-Payment signing (identity + payment)
-  signer: adapter,           // for x402 payment signing (can differ from account)
+  account: client.account,
+  signer: adapter,
   method: "POST",
   headers: { "Content-Type": "application/json" },
   body: JSON.stringify({ query: "hello" }),
   maxAmount: "100000",       // safety cap: 0.10 USDC
+  allowedRecipients: ["0xYOUR_WALLET"],
 })
 ```
 
-### Via CLI (auto-detect both gates)
+### Via CLI (auto-detect)
 
 ```bash
 PRIVATE_KEY=0x... RPC_URL=https://mainnet.base.org \
   npx @opensea/tool-sdk smoke \
   --endpoint https://my-tool.example.com/api \
   --expect 200
 ```
+
+### Legacy: separate gates (3 requests)
+
+For backward compatibility, tools can still chain `predicateGate` + `paywall.gate` as separate gates. The client handles both 402 challenges in a retry loop. However, `paidPredicateGate` is preferred for new tools since it eliminates one round trip.
+
+```typescript
+gates: [
+  predicateGate({ toolId: 1n, operatorAddress: "0x..." }),
+  paywall.gate,
+]
+```
diff --git a/src/__tests__/paid-predicate-gate.test.ts b/src/__tests__/paid-predicate-gate.test.ts
diff --git a/src/index.ts b/src/index.ts
diff --git a/src/lib/middleware/predicate-gate.ts b/src/lib/middleware/predicate-gate.ts

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@opensea/tool-sdk",`
`3`		`- "version": "0.15.0",`
	`3`	`+ "version": "0.16.0",`
`4`	`4`	`"type": "module",`
`5`	`5`	`"description": "SDK and CLI for building ERC-8257 compliant AI agent tools",`
`6`	`6`	`"repository": {`