Release v0.24.0

Origin-SHA: 9bb7ce5927eeac55b8286a3035ee6d0182cc7478

Author: CodySearsOS

CHANGELOG.md

@@ -1,5 +1,11 @@
 # @opensea/tool-sdk
 
+## 0.24.0
+
+### Minor Changes
+
+- c23aa96: Add support for the `upto` x402 payment scheme, which allows variable pricing (charge up to `amountPerCall`, with the actual charge potentially less). `createX402Client` now accepts a signer and registers both `ExactEip3009Scheme` and `UptoEip3009Scheme` internally, letting `@x402/core` route to the correct scheme based on the challenge's `scheme` field. The `pay` CLI, `paidFetch`, and `paidAuthenticatedFetch` route to the appropriate scheme automatically, so callers no longer need to know which scheme to instantiate.
+
 ## 0.23.1
 
 ### Patch Changes

package.json

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

src/__tests__/pay.test.ts

@@ -149,6 +149,64 @@ describe("pay command", () => {
     logSpy.mockRestore()
   })
 
+  it("uses upto scheme when challenge specifies scheme: upto", async () => {
+    const uptoRequirements = { ...PAYMENT_REQUIREMENTS, scheme: "upto" }
+    const calls: { url: string; headers: Record<string, string> }[] = []
+
+    const fetchMock = vi.fn(async (url: string, init?: RequestInit) => {
+      const headers = Object.fromEntries(
+        new Headers(init?.headers).entries(),
+      ) as Record<string, string>
+      calls.push({ url: url as string, headers })
+
+      if (!headers["x-payment"]) {
+        return new Response(
+          JSON.stringify({
+            x402Version: 1,
+            error: "Payment required",
+            accepts: [uptoRequirements],
+          }),
+          { status: 402 },
+        )
+      }
+
+      return new Response(
+        JSON.stringify({ result: "success", txHash: "0xabc" }),
+        { status: 200 },
+      )
+    })
+
+    vi.stubGlobal("fetch", fetchMock)
+
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {})
+    process.env.PRIVATE_KEY = PRIVATE_KEY
+    process.env.RPC_URL = "http://localhost:8545"
+
+    const { payCommand } = await import("../cli/commands/pay.js")
+
+    await payCommand.parseAsync([
+      "node",
+      "pay",
+      "https://tool.example.com/api",
+      "--body",
+      '{"query":"test"}',
+    ])
+
+    expect(fetchMock).toHaveBeenCalledTimes(2)
+
+    const paymentPayload = JSON.parse(
+      Buffer.from(calls[1].headers["x-payment"], "base64").toString("utf-8"),
+    )
+    expect(paymentPayload.x402Version).toBe(1)
+    expect(paymentPayload.scheme).toBe("upto")
+    expect(paymentPayload.payload.signature).toBeDefined()
+    expect(paymentPayload.payload.authorization.to).toBe(
+      PAYMENT_REQUIREMENTS.payTo,
+    )
+
+    logSpy.mockRestore()
+  })
+
   it("falls back to GET when an unspecified-method POST probe 404s", async () => {
     const calls: { method?: string }[] = []
     const fetchMock = vi.fn(async (_url: string, init?: RequestInit) => {

src/__tests__/x402-scheme.test.ts

@@ -1,11 +1,15 @@
 import type { WalletAdapter } from "@opensea/wallet-adapters"
 import { generatePrivateKey, privateKeyToAccount } from "viem/accounts"
 import { describe, expect, it } from "vitest"
-import type { PaymentRequirements } from "../lib/client/x402-payment.js"
+import {
+  createX402Client,
+  type PaymentRequirements,
+} from "../lib/client/x402-payment.js"
 import {
   ExactEip3009Scheme,
   signEip3009Authorization,
   toX402PaymentRequired,
+  UptoEip3009Scheme,
 } from "../lib/client/x402-scheme.js"
 
 const signer = privateKeyToAccount(generatePrivateKey())
@@ -182,6 +186,96 @@ describe("signEip3009Authorization", () => {
   })
 })
 
+describe("UptoEip3009Scheme", () => {
+  it("creates a v1 payload with upto scheme identifier", async () => {
+    const scheme = new UptoEip3009Scheme(signer)
+    const result = await scheme.createPaymentPayload(1, {
+      scheme: "upto",
+      network: "eip155:8453",
+      asset: baseRequirements.asset,
+      amount: "10000",
+      payTo: baseRequirements.payTo,
+      maxTimeoutSeconds: 600,
+      extra: {},
+    })
+
+    const payload = result.payload as {
+      signature: string
+      authorization: Record<string, string>
+    }
+    expect(result.x402Version).toBe(1)
+    expect((result as Record<string, unknown>).scheme).toBe("upto")
+    expect((result as Record<string, unknown>).network).toBe("eip155:8453")
+    expect(payload.signature).toMatch(/^0x[0-9a-f]+$/i)
+    expect(payload.authorization.from).toBe(signer.address)
+    expect(payload.authorization.to).toBe(baseRequirements.payTo)
+    expect(payload.authorization.value).toBe("10000")
+  })
+
+  it("creates a v2 payload without scheme/network fields", async () => {
+    const scheme = new UptoEip3009Scheme(signer)
+    const result = await scheme.createPaymentPayload(2, {
+      scheme: "upto",
+      network: "eip155:8453",
+      asset: baseRequirements.asset,
+      amount: "10000",
+      payTo: baseRequirements.payTo,
+      maxTimeoutSeconds: 600,
+      extra: {},
+    })
+
+    expect(result.x402Version).toBe(2)
+    expect((result as Record<string, unknown>).scheme).toBeUndefined()
+    expect((result as Record<string, unknown>).network).toBeUndefined()
+    expect(result.payload.signature).toMatch(/^0x[0-9a-f]+$/i)
+  })
+
+  it("has scheme property set to upto", () => {
+    const scheme = new UptoEip3009Scheme(signer)
+    expect(scheme.scheme).toBe("upto")
+  })
+})
+
+describe("createX402Client", () => {
+  const v2Requirements: PaymentRequirements = {
+    ...baseRequirements,
+    network: "eip155:8453",
+  }
+
+  it("routes to exact scheme for exact requirements", async () => {
+    const client = createX402Client(signer, "eip155:8453", 2)
+    const paymentRequired = toX402PaymentRequired({
+      requirements: { ...v2Requirements, scheme: "exact" },
+      x402Version: 2,
+      raw: { scheme: "exact", network: "eip155:8453", amount: "10000" },
+    })
+    const result = await client.createPaymentPayload(paymentRequired)
+    expect(result.payload.signature).toMatch(/^0x[0-9a-f]+$/i)
+  })
+
+  it("routes to upto scheme for upto requirements", async () => {
+    const client = createX402Client(signer, "eip155:8453", 2)
+    const paymentRequired = toX402PaymentRequired({
+      requirements: { ...v2Requirements, scheme: "upto" },
+      x402Version: 2,
+      raw: { scheme: "upto", network: "eip155:8453", amount: "10000" },
+    })
+    const result = await client.createPaymentPayload(paymentRequired)
+    expect(result.payload.signature).toMatch(/^0x[0-9a-f]+$/i)
+  })
+
+  it("registers both schemes for v1", async () => {
+    const client = createX402Client(signer, "base", 1)
+    const paymentRequired = toX402PaymentRequired({
+      requirements: { ...baseRequirements, scheme: "upto" },
+      x402Version: 1,
+      raw: { scheme: "upto", network: "base", amount: "10000" },
+    })
+    const result = await client.createPaymentPayload(paymentRequired)
+    expect(result.payload.signature).toMatch(/^0x[0-9a-f]+$/i)
+  })
+})
+
 describe("toX402PaymentRequired", () => {
   it("builds a PaymentRequired with correct fields", () => {
     const result = toX402PaymentRequired({

src/cli/commands/pay.ts

@@ -9,10 +9,7 @@ import {
   extractSettlementTxHash,
   validatePaymentRequirements,
 } from "../../lib/client/x402-payment.js"
-import {
-  ExactEip3009Scheme,
-  toX402PaymentRequired,
-} from "../../lib/client/x402-scheme.js"
+import { toX402PaymentRequired } from "../../lib/client/x402-scheme.js"
 import { reportCallerX402Usage } from "../../lib/usage/caller-reporter.js"
 import {
   createWalletForProvider,
@@ -352,8 +349,7 @@ async function runPaymentOnly(
 
   console.log(pc.cyan("\nSigning EIP-3009 transferWithAuthorization..."))
 
-  const scheme = new ExactEip3009Scheme(adapter)
-  const client = createX402Client(scheme, requirements.network, x402Version)
+  const client = createX402Client(adapter, requirements.network, x402Version)
   const { x402HTTPClient } = await import("@x402/core/client")
   const httpClient = new x402HTTPClient(client)
 

src/lib/client/paid-authenticated-fetch.ts

@@ -10,7 +10,7 @@ import {
   type PaymentRequirements,
   rejectServerErrorAfterPayment,
 } from "./x402-payment.js"
-import { ExactEip3009Scheme, toX402PaymentRequired } from "./x402-scheme.js"
+import { toX402PaymentRequired } from "./x402-scheme.js"
 
 export interface PaidAuthenticatedFetchOptions extends RequestInit {
   account: Account
@@ -95,8 +95,7 @@ export async function paidAuthenticatedFetch(
       allowedAssets,
     })
 
-    const scheme = new ExactEip3009Scheme(paymentSigner)
-    const client = createX402Client(scheme, requirements.network, x402Version)
+    const client = createX402Client(paymentSigner, requirements.network, x402Version)
     const httpClient = new x402HTTPClient(client)
 
     const paymentRequired = toX402PaymentRequired({

src/lib/client/x402-payment.ts

@@ -12,6 +12,7 @@ import {
   ExactEip3009Scheme,
   signEip3009Authorization,
   toX402PaymentRequired,
+  UptoEip3009Scheme,
 } from "./x402-scheme.js"
 
 const REJECTED_ADDRESSES = new Set([
@@ -240,8 +241,7 @@ export async function paidFetch(
     allowedAssets,
   })
 
-  const scheme = new ExactEip3009Scheme(signer)
-  const client = createX402Client(scheme, requirements.network, x402Version)
+  const client = createX402Client(signer, requirements.network, x402Version)
   const httpClient = new x402HTTPClient(client)
 
   const paymentRequired = toX402PaymentRequired({
@@ -403,19 +403,24 @@ export function validatePaymentRequirements(
 }
 
 /**
- * Create an x402Client with an {@link ExactEip3009Scheme} registered for the
- * given network and protocol version.
+ * Create an x402Client with both exact and upto EIP-3009 schemes registered
+ * for the specified network and protocol version. The x402Client routes to
+ * the correct scheme based on the challenge's `scheme` field.
  */
 export function createX402Client(
-  scheme: ExactEip3009Scheme,
+  signer: WalletAdapter | Account,
   network: string,
   x402Version: number,
 ): x402Client {
+  const exact = new ExactEip3009Scheme(signer)
+  const upto = new UptoEip3009Scheme(signer)
   const client = new x402Client()
   if (x402Version >= 2) {
-    client.register(network as `${string}:${string}`, scheme)
+    client.register(network as `${string}:${string}`, exact)
+    client.register(network as `${string}:${string}`, upto)
   } else {
-    client.registerV1(network, scheme)
+    client.registerV1(network, exact)
+    client.registerV1(network, upto)
   }
   return client
 }

src/lib/client/x402-scheme.ts

@@ -48,6 +48,44 @@ export class ExactEip3009Scheme implements SchemeNetworkClient {
   }
 }
 
+/**
+ * x402 "upto" scheme — ceiling-price variant of EIP-3009. The caller
+ * authorizes up to `amount` but the facilitator may settle for less based
+ * on the tool's response. Signing logic is identical to exact; only the
+ * scheme identifier differs so the facilitator knows to apply variable
+ * pricing.
+ */
+export class UptoEip3009Scheme implements SchemeNetworkClient {
+  readonly scheme = "upto"
+
+  constructor(private readonly signer: WalletAdapter | Account) {}
+
+  async createPaymentPayload(
+    x402Version: number,
+    paymentRequirements: X402PaymentRequirements,
+    _context?: PaymentPayloadContext,
+  ): Promise<PaymentPayloadResult> {
+    const payload = await signEip3009Authorization(this.signer, {
+      network: paymentRequirements.network,
+      payTo: paymentRequirements.payTo,
+      asset: paymentRequirements.asset,
+      amount: paymentRequirements.amount,
+      extra: paymentRequirements.extra,
+    })
+
+    if (x402Version === 1) {
+      return {
+        x402Version,
+        scheme: paymentRequirements.scheme,
+        network: paymentRequirements.network,
+        payload,
+      } as PaymentPayloadResult
+    }
+
+    return { x402Version, payload }
+  }
+}
+
 /**
  * Core EIP-3009 TransferWithAuthorization signing logic shared by
  * {@link ExactEip3009Scheme} and the standalone {@link signX402Payment}.