Skip to main content
x402 requires a feature flag to be enabled on your Pinata account. Contact [email protected] to request access.
Pinata’s x402 enables you to monetize your private IPFS files by receiving USDC payments directly to your wallet. You set the price, you receive the payment.
x402 is currently available through the Pinata API v3. SDK support coming soon.

​
Overview

Pinata’s x402 implementation enables:
  • Monetization of private IPFS content using Payment Instructions
  • You receive payments directly to your wallet address. Payments go to you, not Pinata.
  • Flexible payment requirements configurable per file or group of files
  • USDC payments on Base (mainnet) and Base Sepolia (testnet)
  • Gateway-level enforcement through the x402 protocol

​
Network Configuration

NetworkUSDC Token AddressUse Case
Base (Mainnet)0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913Production monetization
Base Sepolia (Testnet)0x036CbD53842c5426634e7929541eC2318f3dCF7eTesting payment flows

​
Payment Instructions API

Create and manage payment requirements for your private content:

List Instructions

View all payment instructions

Create Instruction

Define new payment requirements

Get Instruction

Retrieve instruction details

Update Instruction

Modify payment requirements

Delete Instruction

Remove payment instructions

​
CID Management

Attach payment instructions to your private files:

List CIDs

View attached CIDs

Add CID

Attach CID to instruction

Remove CID

Detach CID from instruction

​
How It Works

  1. Upload a private file to Pinata IPFS
  2. Create a Payment Instruction with your desired payment requirements
  3. Attach the CID of your private file to the Payment Instruction
  4. Share your x402 gateway URL: https://your-gateway.mypinata.cloud/x402/cid/{cid}
  5. Requesters make USDC payments through your gateway to access content
You must use your own dedicated Pinata gateway domain. Replace your-gateway.mypinata.cloud with your actual gateway domain throughout these examples.

​
Example Workflow

# 1. Create a payment instruction
curl -X POST https://api.pinata.cloud/v3/x402/payment_instructions \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Content",
    "payment_requirements": [{
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "pay_to": "0xYourWalletAddress",
      "network": "base",
      "description": "Access fee",
      "max_amount_required": "10000"
    }]
  }'

# 2. Attach CID to payment instruction
curl -X PUT https://api.pinata.cloud/v3/x402/payment_instructions/{instruction_id}/cids/{cid} \
  -H "Authorization: Bearer YOUR_JWT"

# 3. Share the x402 gateway URL
# https://your-gateway.mypinata.cloud/x402/cid/{cid}

​
Why Use Payment Instructions

The Payment Instructions API enables you to monetize your private content by setting custom payment requirements and receiving payments directly to your wallet. Key benefits:
  • You get paid for your content. Set your own prices and receive USDC payments directly.
  • Flexible pricing for different files or groups of files
  • Reusable payment instructions that can be attached to multiple CIDs
  • Full control over payment requirements, pricing, and access

​
Legacy Endpoints

These endpoints are maintained for backward compatibility:

/pin (Legacy)

Upload to either Public or Private IPFS

/retrieve (Legacy)

Access a file on Private IPFS