Skip to main content
Create a new payment instruction for x402 monetization

​
Usage

import { PinataSDK } from "pinata";

const pinata = new PinataSDK({
  pinataJwt: process.env.PINATA_JWT!,
  pinataGateway: "example-gateway.mypinata.cloud",
});

const instruction = await pinata.x402.createPaymentInstruction({
  name: "Premium Content Access",
  payment_requirements: [
    {
      asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC on Base
      pay_to: "0x1234567890abcdef1234567890abcdef12345678",
      network: "base",
      amount: "10000", // $0.01 in USDC (6 decimals)
    },
  ],
});

​
Returns

type PaymentInstructionResponse = {
  data: PaymentInstruction;
};

type PaymentInstruction = {
  id: string;
  version: number;
  payment_requirements: PaymentRequirement[];
  name: string;
  description?: string;
  created_at: string;
};

type PaymentRequirement = {
  asset: string;
  pay_to: string;
  network: "base" | "base-sepolia" | "eip155:8453" | "eip155:84532";
  amount: string;
  description?: string;
};

​
Parameters

​
name (required)

  • Type: string
The name for the payment instruction 
const instruction = await pinata.x402.createPaymentInstruction({
  name: "Premium Content Access",
  payment_requirements: [
    {
      asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC on Base
      pay_to: "0x1234567890abcdef1234567890abcdef12345678",
      network: "base",
      amount: "10000", // $0.01 in USDC (6 decimals)
    },
  ],
});

​
payment_requirements (required)

  • Type: PaymentRequirement[]
An array of payment requirements. Each requirement specifies the asset, recipient address, network, and amount required for access. 
const instruction = await pinata.x402.createPaymentInstruction({
  name: "Premium Content Access",
  payment_requirements: [
    {
      asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC on Base
      pay_to: "0x1234567890abcdef1234567890abcdef12345678",
      network: "base",
      amount: "10000", // $0.01 in USDC (6 decimals)
    },
  ],
});

​
PaymentRequirement Properties

PropertyTypeRequiredDescription
assetstringYesThe USDC token contract address for the network
pay_tostringYesThe wallet address to receive payments
network"base" | "base-sepolia" | "eip155:8453" | "eip155:84532"YesThe blockchain network
amountstringYesThe maximum amount required for access
descriptionstringNoOptional description for this requirement

​
description

  • Type: string
An optional description for the payment instruction 
const instruction = await pinata.x402.createPaymentInstruction({
  name: "Premium Content Access",
  payment_requirements: [
    {
      asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC on Base
      pay_to: "0x1234567890abcdef1234567890abcdef12345678",
      network: "base",
      amount: "10000", // $0.01 in USDC (6 decimals)
    },
  ],
  description: "Access to exclusive premium content",
});