updatePaymentInstruction

Modify existing payment instructions for USDC transactions on Base networks by updating recipient addresses, amounts, descriptions, and network settings.

Instructions

Update an existing x402 payment instruction. Currently supports USDC (6 decimals) on Base/Base Sepolia only.

Input Schema

TableJSON Schema

Name	Required	Description
`id`	Yes	The unique identifier of the payment instruction to update
`name`	No	Updated name
`pay_to`	No	Updated wallet address (0x...) to receive USDC payments
`amount_usdc`	No	Updated price in USD as a string (e.g., '0.01' for 1 cent, '1.50' for $1.50)
`network`	No	Updated blockchain network
`description`	No	Updated description

Implementation Reference

src/index.ts:1141-1192 (handler)

The handler function that executes the updatePaymentInstruction tool logic. It constructs a PATCH request to the Pinata API to update payment instructions, converting USD amounts to USDC smallest units (6 decimals) and building the payload conditionally based on provided parameters.

async ({ id, name, pay_to, amount_usdc, network, description }) => {
  try {
    const url = `https://api.pinata.cloud/v3/x402/payment_instructions/${id}`;

    // USDC contract addresses
    const USDC_ADDRESSES: Record<string, string> = {
      "base": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "base-sepolia": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
    };

    const payload: {
      name?: string;
      payment_requirements?: Array<{
        asset: string;
        pay_to: string;
        network: string;
        amount: string;
      }>;
      description?: string;
    } = {};

    if (name) payload.name = name;
    if (pay_to && amount_usdc && network) {
      // Convert USD amount to USDC smallest unit (6 decimals)
      const amountInSmallestUnit = Math.round(parseFloat(amount_usdc) * 1_000_000).toString();
      payload.payment_requirements = [{
        asset: USDC_ADDRESSES[network],
        pay_to,
        network,
        amount: amountInSmallestUnit,
      }];
    }
    if (description) payload.description = description;

    const response = await fetch(url, {
      method: "PATCH",
      headers: getHeaders(),
      body: JSON.stringify(payload),
    });

    if (!response.ok) {
      throw new Error(
        `Failed to update payment instruction: ${response.status} ${response.statusText}`
      );
    }

    const data = await response.json();
    return successResponse(data);
  } catch (error) {
    return errorResponse(error);
  }
}

src/index.ts:1122-1139 (schema)

The zod schema defining the input parameters for updatePaymentInstruction tool. It includes optional fields for id (required), name, pay_to, amount_usdc, network (enum: 'base' | 'base-sepolia'), and description.

{
  id: z
    .string()
    .describe("The unique identifier of the payment instruction to update"),
  name: z.string().optional().describe("Updated name"),
  pay_to: z
    .string()
    .optional()
    .describe("Updated wallet address (0x...) to receive USDC payments"),
  amount_usdc: z
    .string()
    .optional()
    .describe("Updated price in USD as a string (e.g., '0.01' for 1 cent, '1.50' for $1.50)"),
  network: z
    .enum(["base", "base-sepolia"])
    .optional()
    .describe("Updated blockchain network"),
  description: z.string().optional().describe("Updated description"),

src/index.ts:1119-1193 (registration)

The complete tool registration using server.tool() which registers the updatePaymentInstruction tool with its name, description, schema, and handler function.

server.tool(
  "updatePaymentInstruction",
  "Update an existing x402 payment instruction. Currently supports USDC (6 decimals) on Base/Base Sepolia only.",
  {
    id: z
      .string()
      .describe("The unique identifier of the payment instruction to update"),
    name: z.string().optional().describe("Updated name"),
    pay_to: z
      .string()
      .optional()
      .describe("Updated wallet address (0x...) to receive USDC payments"),
    amount_usdc: z
      .string()
      .optional()
      .describe("Updated price in USD as a string (e.g., '0.01' for 1 cent, '1.50' for $1.50)"),
    network: z
      .enum(["base", "base-sepolia"])
      .optional()
      .describe("Updated blockchain network"),
    description: z.string().optional().describe("Updated description"),
  },
  async ({ id, name, pay_to, amount_usdc, network, description }) => {
    try {
      const url = `https://api.pinata.cloud/v3/x402/payment_instructions/${id}`;

      // USDC contract addresses
      const USDC_ADDRESSES: Record<string, string> = {
        "base": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "base-sepolia": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      };

      const payload: {
        name?: string;
        payment_requirements?: Array<{
          asset: string;
          pay_to: string;
          network: string;
          amount: string;
        }>;
        description?: string;
      } = {};

      if (name) payload.name = name;
      if (pay_to && amount_usdc && network) {
        // Convert USD amount to USDC smallest unit (6 decimals)
        const amountInSmallestUnit = Math.round(parseFloat(amount_usdc) * 1_000_000).toString();
        payload.payment_requirements = [{
          asset: USDC_ADDRESSES[network],
          pay_to,
          network,
          amount: amountInSmallestUnit,
        }];
      }
      if (description) payload.description = description;

      const response = await fetch(url, {
        method: "PATCH",
        headers: getHeaders(),
        body: JSON.stringify(payload),
      });

      if (!response.ok) {
        throw new Error(
          `Failed to update payment instruction: ${response.status} ${response.statusText}`
        );
      }

      const data = await response.json();
      return successResponse(data);
    } catch (error) {
      return errorResponse(error);
    }
  }
);

Pinata MCP