Pay with crypto to retrieve a private IPFS file from Pinata by CID via x402.
What it does
This x402 endpoint lets you retrieve a private file stored on IPFS through Pinata by specifying its Content Identifier (CID) in the URL path. It uses the Coinbase x402 payment protocol, meaning callers pay per-request with cryptocurrency instead of needing a Pinata account or API key. The endpoint returns an HTTP 402 challenge to unauthenticated callers, and once payment is satisfied the private file content is delivered.
The endpoint is part of Pinata's account-free IPFS access suite, which also includes public and private upload endpoints. Private files on Pinata are not accessible through public IPFS gateways, so this paid retrieval mechanism is the intended way to fetch them. The CID in the URL path (bafkreiefdk5omvmbtuysrnjq5khpnmqjre4wpzdwwsvw37llcmvg6klf3u) identifies the specific file to retrieve.
Documentation is sparse — the full docs link points to https://docs.pinata.cloud/files/x402 but no detailed schema or pricing information was captured in the crawl. The x402 challenge object returned by the probe was empty, so the exact payment terms (token, network, amount) could not be confirmed from the probe alone. Callers should use an x402-compatible payment library (such as fetchWithPayment from the x402 SDK) to handle the payment negotiation automatically.
Capabilities
Use cases
- —Retrieve a specific private IPFS file without a Pinata account by paying with crypto
- —Build decentralized applications that gate private content behind micropayments
- —Access privately pinned IPFS content programmatically using x402-compatible agents
Fit
Best for
- —Agents or apps that need on-demand access to private IPFS files without managing API keys
- —Crypto-native workflows where micropayments replace subscription-based storage access
- —Decentralized content retrieval where account creation is undesirable
Not for
- —Bulk retrieval of many files (each CID requires a separate paid request to a distinct URL)
- —Users who already have a Pinata account with API key access to their private files
- —Retrieving publicly pinned IPFS content (use a public gateway instead)
Quick start
import { fetchWithPayment } from 'x402-fetch';
const res = await fetchWithPayment(
'https://402-server.pinata-marketing-enterprise.workers.dev/v1/retrieve/private/bafkreiefdk5omvmbtuysrnjq5khpnmqjre4wpzdwwsvw37llcmvg6klf3u',
{ method: 'GET' }
);
const fileData = await res.blob();
console.log('Retrieved file size:', fileData.size);Endpoint
Quality
The endpoint is live (402 challenge returned on GET), but the challenge body was empty so payment terms are unknown. No OpenAPI schema, no detailed docs were captured, and pricing/token information is absent. The listing is largely inferred from the landing page description and URL structure.
Warnings
- —x402 challenge object was empty — payment terms (amount, token, network) could not be determined from the probe
- —No OpenAPI or schema documentation available; response format is inferred
- —Full docs at docs.pinata.cloud/files/x402 were not crawled; details may differ from what is described here
- —This endpoint URL is CID-specific; retrieving a different file requires changing the CID in the path
Citations
- —Pinata offers account-free IPFS uploads and private file retrieval using Coinbase's x402 protocolhttps://402-server.pinata-marketing-enterprise.workers.dev
- —Private IPFS content can be paid to retrieve via x402https://402-server.pinata-marketing-enterprise.workers.dev
- —Full documentation is linked at docs.pinata.cloud/files/x402https://402-server.pinata-marketing-enterprise.workers.dev