HTTP 402 ("Payment Required") has been part of the spec since 1997, reserved for future payment systems but never implemented. The x402 protocol finally defines how it works, standardizing how payments attach to content at the protocol level. Pinata is the first platform to ship x402 v1 in production.

Pinata x402 lets you generate revenue directly from digital files. Attach payment conditions to private files on IPFS. Set a price in USDC. Share a link. Payments verify instantly through Coinbase Facilitator on Base, and access is granted automatically. No integrations, no payment processors, no app store fees.

This transforms file sharing into a monetized transaction. It gives teams a direct path to build revenue models around AI models, game content, data feeds, or any file-based product.

How It Works

Upload a Private File

A file is uploaded to Pinata's private IPFS network. It remains fully private and accessible only through your dedicated gateway.

Attach a Payment Instruction

Each file carries a "Payment Instruction" defining its unlock criteria: price, token (USDC), recipient wallet, and network (Base or Base Sepolia). Payment Instructions are created through the Pinata v3 API and are fully reusable. Attach one to multiple files or create unique instructions per file.

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 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"
      }
    ]
  }'

Then attach it to your CID:

curl -X PUT https://api.pinata.cloud/v3/x402/payment_instructions/{instruction_id}/cids/{cid} \
  -H "Authorization: Bearer YOUR_JWT"

Share the Gateway Link

When someone requests access at https://<your-gateway>/x402/cid/:cid, they see a "402 Payment Required" response if unpaid. The gateway returns payment requirements following the x402 v1 spec. Once payment is complete, the buyer includes an X-Payment header with their request. The gateway verifies the payment proof with Coinbase Facilitator, settles the transaction on-chain, and streams the file. Payment verification and settlement happen in seconds.

What You Can Build

Pinata x402 allows any digital asset to become a monetized product. The protocol doesn't care what's in the file, only that someone paid to access it. This opens up new business models for teams building on IPFS, from AI labs distributing model weights to game studios selling content directly to players.

The flexibility of Payment Instructions means you can price content however makes sense for your business. One instruction across thousands of files, or unique pricing per asset. Update prices anytime through the API, and all mapped files reflect the change instantly.

• AI Models and Datasets
  Charge for access to model weights, training data, or generated outputs. Ideal for AI teams managing high-value assets.
• Game Content Distribution
  Offer downloadable assets, maps, or expansions, with instant access once payment is verified.
• Paid Data Feeds
  Monetize real-time or historical data. Set different prices for different datasets or time ranges.
• Digital Resources
  Sell toolkits, documents, or design assets directly, without additional software layers.
• Developer APIs
  Implement per-file paywalls for data-backed APIs, controlling access and revenue from a single rule.

Why Build on Pinata

Building payment infrastructure is hard. Integrating with blockchain payment systems, handling verification, managing transaction state, dealing with edge cases. It's months of work before you ship a single paid file. Pinata x402 eliminates all of it.

We built x402 into the platform so you can focus on your product, not payment plumbing. The gateway handles enforcement, Coinbase Facilitator handles settlement, and you manage everything through a simple REST API. This isn't a SDK you integrate. It's infrastructure that just works.

• We integrated Coinbase Facilitator so you don't have to.
  Payment verification, blockchain settlement, transaction validation. All handled at the gateway. You define Payment Instructions through the API and attach them to CIDs. That's it.
• Dedicated gateways mean you control access.
  Every Pinata account gets its own dedicated gateway. Your x402 URLs are yours. No shared infrastructure, no platform limitations. Access control is enforced at the gateway layer, per file.
• Protocol-level enforcement means no backend complexity.
  Payment requirements live at the content layer. If someone tries to access a CID without paying, the gateway blocks it automatically. No application logic needed.
• Test on Base Sepolia before going live.
  Build the full payment flow without spending real money. Same API, same gateway behavior, same x402 v1 spec. Ship with confidence.

The Future of File-Based Commerce

Pinata x402 makes files active participants in commerce. By embedding payments at the protocol level, it enables direct transactions where access itself becomes the product.

Upload, set your price, share your link. Every file can now carry its own business model.

Check out the docs to get started: https://docs.pinata.cloud/files/x402