Skip to main content
Get started monetizing your private IPFS files with x402 in just a few minutes. With x402, you monetize your private files by setting payment requirements. Payments go directly to your wallet. You control the price and receive the funds.
Before starting, ensure the x402 feature flag is enabled on your account. Contact [email protected] if you need access.

​
Prerequisites

  • Pinata account with x402 feature flag enabled
  • API JWT from Pinata App
  • Private file uploaded to Pinata
  • Ethereum wallet address to receive payments

​
Step 1: Upload a Private File

First, upload a file to Private IPFS: 
curl -X POST https://uploads.pinata.cloud/v3/files \
  -H "Authorization: Bearer YOUR_JWT" \
  -F "[email protected]" \
  -F "network=private"
Save the returned cid for the next step.

​
Step 2: Create a Payment Instruction

Define your payment requirements: 
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 Access",
    "description": "One-time payment for file access",
    "payment_requirements": [
      {
        "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "pay_to": "YOUR_WALLET_ADDRESS",
        "network": "base",
        "description": "Access fee",
        "max_amount_required": "10000"
      }
    ]
  }'
Understanding Payment Amounts: The max_amount_required uses USDC’s smallest unit. USDC has 6 decimals, so to convert USD to the token amount, multiply by 1,000,000:
USD Amountmax_amount_requiredCalculation
$0.01"10000"$0.01 × 1,000,000
$0.10"100000"$0.10 × 1,000,000
$1.00"1000000"$1.00 × 1,000,000
$5.00"5000000"$5.00 × 1,000,000
$10.00"10000000"$10.00 × 1,000,000
Formula: USD Amount × 1,000,000 = token amount Networks:
  • Production: Use "base" with 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
  • Testing: Use "base-sepolia" with 0x036CbD53842c5426634e7929541eC2318f3dCF7e
Save the returned id for the next step.

​
Step 3: Attach CID to Payment Instruction

Link your private file to the payment instruction: 
curl -X PUT https://api.pinata.cloud/v3/x402/payment_instructions/{instruction_id}/cids/{cid} \
  -H "Authorization: Bearer YOUR_JWT"
Replace {instruction_id} with the ID from Step 2 and {cid} with the CID from Step 1.

​
Step 4: Share Your Monetized Content

Your file is now monetized! Share this URL with requesters: 
https://your-gateway.mypinata.cloud/x402/cid/{cid}
Replace your-gateway.mypinata.cloud with your actual dedicated Pinata gateway domain (e.g., my-gateway.mypinata.cloud), and {cid} with your file’s CID.

​
Step 5: Test the Payment Flow

When a requester accesses your URL without payment, the gateway returns a 402 response with payment requirements: 
curl https://your-gateway.mypinata.cloud/x402/cid/{cid}
Response: 
{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "base",
    "maxAmountRequired": "10000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "YOUR_WALLET_ADDRESS",
    "resource": "https://your-gateway.mypinata.cloud/x402/cid/{cid}"
  }],
  "error": "Provide a valid X-Payment header to access this content"
}
After payment is made, requesters can access the file by including the payment proof in the X-Payment header.

​
Next Steps

  • Manage Multiple Files: Attach multiple CIDs to the same payment instruction
  • Update Pricing: Use the Update Payment Instruction endpoint
  • Monitor Access: Check your gateway analytics to track paid downloads
  • Requester Guide: Learn how requesters access paid content in the Accessing Paid Content guide

​
Common Issues

404 Not Found: Verify the CID is private and correctly attached to a payment instruction 403 Forbidden: Check that your API key has the required permissions (OrgFilesWrite) 409 Conflict: If deleting a payment instruction fails, remove all CID attachments first Need help? Contact [email protected]