web3_subscribe

Instructions

Implementation Reference

• src/index.ts:2237-2306 (registration)

  Registration of the web3_subscribe tool on the MCP server. Handles the x402 USDC payment flow on Base for subscribing to Build or Pro tiers. First call (without payment_signature) returns 402 with payment details; second call with the signed x402 payload completes the subscription.

  server.registerTool(
    "web3_subscribe",
    {
      description:
        "Subscribe to a paid tier (build or pro) using x402 USDC payment on Base.\n\n" +
        "TWO-STEP FLOW:\n" +
        "Step 1: Call with just tier (omit payment_signature) → returns 402 with payment details " +
        "(amount in micro-USDC, pay_to treasury address, network, asset_address).\n" +
        "Step 2: Sign a USDC EIP-3009 transferWithAuthorization, build the x402 v2 payment payload, " +
        "base64-encode it, and call again with payment_signature.\n\n" +
        "PAYMENT PAYLOAD FORMAT (x402 v2):\n" +
        "The payment_signature must be a base64-encoded JSON string with this exact structure:\n" +
        '{\n  "x402Version": 2,\n' +
        '  "payload": {\n' +
        '    "signature": "0x<130+ hex chars — EIP-712 signature>",\n' +
        '    "authorization": {\n' +
        '      "from": "0x<your wallet address>",\n' +
        '      "to": "0x<pay_to address from step 1>",\n' +
        '      "value": "<amount from step 1, as string e.g. \'49000000\'>",\n' +
        '      "validAfter": "0",\n' +
        '      "validBefore": "<unix timestamp ~1hr from now, as string>",\n' +
        '      "nonce": "0x<64 hex chars — 32 random bytes>"\n' +
        "    }\n  }\n}\n\n" +
        "EIP-712 SIGNING:\n" +
        "Domain: { name: 'USD Coin', version: '2', chainId: 8453, verifyingContract: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' }\n" +
        "Type: TransferWithAuthorization(address from, address to, uint256 value, uint256 validAfter, uint256 validBefore, bytes32 nonce)\n" +
        "Sign the typed data, then hex-encode the 65-byte signature with 0x prefix.\n\n" +
        "IMPORTANT: All values inside authorization (value, validAfter, validBefore) must be STRINGS, not numbers.",
      inputSchema: {
        tier: z.enum(["build", "pro"]).describe("Subscription tier: 'build' ($49/mo) or 'pro' ($199/mo)"),
        payment_signature: z.string().optional().describe(
          "Base64-encoded x402 v2 payment payload JSON. " +
          "Omit on first call to get pricing (402 response). " +
          "On second call, provide base64(JSON) where JSON has: " +
          '{ "x402Version": 2, "payload": { "signature": "0x...", "authorization": { "from", "to", "value", "validAfter", "validBefore", "nonce" } } }. ' +
          "See tool description for full format."
        ),
      },
      outputSchema: ObjectOutputSchema,
      annotations: AUTH_TOOL_ANNOTATIONS,
    },
    async (params: any) => {
      try {
        const headers: Record<string, string> = { "Content-Type": "application/json" };
        if (params.payment_signature) {
          headers["payment-signature"] = params.payment_signature;
        }
        const response = await fetch("https://api.0xarchive.io/v1/web3/subscribe", {
          method: "POST",
          headers,
          body: JSON.stringify({ tier: params.tier }),
        });
        const data = await response.json();
        if (response.status === 402) {
          // Expected first-step response with pricing info
          return formatResponse(data);
        }
        if (!response.ok) {
          return {
            content: [{ type: "text" as const, text: `Error: ${data.error || "Subscribe failed"}` }],
            isError: true,
          };
        }
        return formatResponse(data);
      } catch (err) {
        const error = err instanceof OxArchiveError ? err : new OxArchiveError(String(err), 500);
        return formatError(error);
      }
    }
  );

• src/index.ts:2265-2276 (schema)

  Input schema for web3_subscribe: requires a 'tier' enum (build/pro) and an optional 'payment_signature' string for the x402 v2 payload.

  inputSchema: {
    tier: z.enum(["build", "pro"]).describe("Subscription tier: 'build' ($49/mo) or 'pro' ($199/mo)"),
    payment_signature: z.string().optional().describe(
      "Base64-encoded x402 v2 payment payload JSON. " +
      "Omit on first call to get pricing (402 response). " +
      "On second call, provide base64(JSON) where JSON has: " +
      '{ "x402Version": 2, "payload": { "signature": "0x...", "authorization": { "from", "to", "value", "validAfter", "validBefore", "nonce" } } }. ' +
      "See tool description for full format."
    ),
  },
  outputSchema: ObjectOutputSchema,
  annotations: AUTH_TOOL_ANNOTATIONS,

• src/index.ts:2278-2306 (handler)

  Handler function for web3_subscribe. Makes a POST request to the 0xArchive subscribe API endpoint with the tier. If payment_signature is provided, it's sent as a header. Handles 402 response for first-step pricing and errors.

    async (params: any) => {
      try {
        const headers: Record<string, string> = { "Content-Type": "application/json" };
        if (params.payment_signature) {
          headers["payment-signature"] = params.payment_signature;
        }
        const response = await fetch("https://api.0xarchive.io/v1/web3/subscribe", {
          method: "POST",
          headers,
          body: JSON.stringify({ tier: params.tier }),
        });
        const data = await response.json();
        if (response.status === 402) {
          // Expected first-step response with pricing info
          return formatResponse(data);
        }
        if (!response.ok) {
          return {
            content: [{ type: "text" as const, text: `Error: ${data.error || "Subscribe failed"}` }],
            isError: true,
          };
        }
        return formatResponse(data);
      } catch (err) {
        const error = err instanceof OxArchiveError ? err : new OxArchiveError(String(err), 500);
        return formatError(error);
      }
    }
  );