Pay with crypto to retrieve a private IPFS file from Pinata by CID via the x402 protocol.
What it does
This x402-enabled endpoint lets callers retrieve a specific private file stored on IPFS through Pinata, identified by its CID (Content Identifier). Instead of requiring a Pinata account or API key, the endpoint uses Coinbase's x402 payment protocol: an unauthenticated GET request returns an HTTP 402 challenge, and once payment is made the private content is served back.
The endpoint is part of Pinata's account-free IPFS service suite, which also offers public and private file uploads. Private files pinned through the companion upload endpoint can later be retrieved through endpoints like this one by paying per-request. The x402 challenge mechanism handles payment negotiation automatically when used with an x402-compatible client (e.g., `fetchWithPayment` from the x402 SDK).
Note that the specific CID in this endpoint URL (`bafkreifm6sroj5jdnkbjojh5ra5hiybj3rwq52focjvaup7dn5amqll4ne`) is baked into the path, meaning this particular listing retrieves one specific private file. The general pattern is `https://402.pinata.cloud/v1/retrieve/private/{cid}`. Documentation is available at docs.pinata.cloud/files/x402, though the on-server /docs path returns 404. The x402 challenge was captured live but returned an empty challenge body, so pricing details and accepted payment methods could not be confirmed from the probe alone.
Capabilities
Use cases
- —Retrieving a specific private file stored on IPFS without needing a Pinata account or API key
- —Paying per-request for access to gated IPFS content using cryptocurrency
- —Integrating private IPFS file access into an agent workflow via x402-compatible clients
- —Building decentralized applications that gate content behind micropayments
Fit
Best for
- —Agents or apps that need to fetch private IPFS content without managing API keys
- —Crypto-native workflows that can pay per-request via x402
- —Accessing specific known CIDs stored privately on Pinata
Not for
- —Bulk retrieval of many files (each CID is a separate endpoint/payment)
- —Users who need free or subscription-based IPFS access (this is pay-per-request)
- —Retrieving public IPFS content (use a public gateway instead)
Quick start
import { fetchWithPayment } from 'x402-fetch';
const res = await fetchWithPayment(
'https://402.pinata.cloud/v1/retrieve/private/bafkreifm6sroj5jdnkbjojh5ra5hiybj3rwq52focjvaup7dn5amqll4ne',
{ method: 'GET' }
);
const data = await res.blob();
console.log('Retrieved file size:', data.size);Endpoint
Quality
The endpoint is live (402 challenge captured) but the challenge body is empty, so pricing, accepted tokens, and payment details are unknown. No OpenAPI schema, no on-server docs, and no example response structure are available. The listing is largely inferred from the landing page description and the general x402 pattern.
Warnings
- —x402 challenge body was empty — pricing and accepted payment methods could not be determined from the probe
- —No OpenAPI or schema documentation available at the endpoint origin
- —The /docs path on the server returns 404; full docs are hosted externally at docs.pinata.cloud/files/x402
- —This endpoint URL is CID-specific; the listing represents retrieval of one particular private file, not a general-purpose API
Citations
- —Pinata offers account-free IPFS uploads and private file retrieval using Coinbase's x402 protocolhttps://402-server.pinata-marketing-enterprise.workers.dev
- —Full documentation is available at docs.pinata.cloud/files/x402https://402-server.pinata-marketing-enterprise.workers.dev
- —The endpoint returned a 402 status with an empty challenge body on GEThttps://402-server.pinata-marketing-enterprise.workers.dev/v1/retrieve/private/bafkreifm6sroj5jdnkbjojh5ra5hiybj3rwq52focjvaup7dn5amqll4ne