Pay with crypto to retrieve a private IPFS file from Pinata by CID via the x402 protocol.
What it does
This x402 endpoint lets you retrieve a private file stored on IPFS through Pinata by specifying its CID (Content Identifier) in the URL path. It uses Coinbase's x402 payment protocol, meaning callers pay per-request with cryptocurrency — no Pinata account or API key required. When called without payment, the endpoint returns an HTTP 402 challenge; once the payment header is satisfied, the private file content is returned.
The endpoint is part of Pinata's account-free IPFS access suite, which also includes endpoints for public and private file uploads. 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 (e.g., `bafkreicg754td66rkwrdrjrk2zmfqkedodyvfqwxpe5mdh5xnxvd73jidq`) identifies the specific file to retrieve.
Documentation beyond the landing page is hosted at docs.pinata.cloud/files/x402. The x402 challenge object returned by the probe was empty, so exact pricing, accepted tokens, and payment network details could not be confirmed from the probe alone. Callers should consult the full Pinata x402 docs for payment specifics.
Capabilities
Use cases
- —Retrieving a specific private file from IPFS without a Pinata account
- —Paying per-request with crypto to access gated IPFS content
- —Building agent workflows that fetch private decentralized storage objects on demand
- —Integrating private IPFS file access into dApps or automated pipelines
Fit
Best for
- —Agents or apps that need on-demand access to private IPFS files without managing API keys
- —Crypto-native workflows where per-request micropayments are preferred over subscriptions
- —Decentralized application backends that retrieve private content by CID
Not for
- —Bulk or high-volume file downloads where a Pinata subscription would be more cost-effective
- —Retrieving publicly pinned IPFS content (use a public gateway instead)
- —Users who cannot transact in cryptocurrency
Quick start
import { fetchWithPayment } from 'x402-fetch';
const res = await fetchWithPayment(
'https://402-server.pinata-marketing-enterprise.workers.dev/v1/retrieve/private/bafkreicg754td66rkwrdrjrk2zmfqkedodyvfqwxpe5mdh5xnxvd73jidq',
{ method: 'GET' }
);
const fileData = await res.blob();
console.log('Retrieved file size:', fileData.size);Endpoint
Quality
The endpoint is live (returns 402 on GET) and the landing page confirms the service's purpose, but the x402 challenge object is empty (no pricing, token, or network info), there is no OpenAPI schema, the /docs path returns 404, and no example request/response bodies are available from the crawl. Most details must be inferred from the landing page description and the URL structure.
Warnings
- —x402 challenge body was empty — pricing, accepted payment tokens, and network details are unknown from the probe alone
- —No OpenAPI or JSON schema available for the endpoint
- —On-server /docs, /api, /pricing, and /README all return 404; full documentation is external at docs.pinata.cloud/files/x402
- —Response content type and format are unknown — could be raw file bytes or JSON wrapper
Citations
- —The service uses Coinbase's x402 Protocol for account-free IPFS accesshttps://402-server.pinata-marketing-enterprise.workers.dev
- —Private IPFS content requires payment to retrievehttps://402-server.pinata-marketing-enterprise.workers.dev
- —Full documentation is at docs.pinata.cloud/files/x402https://402-server.pinata-marketing-enterprise.workers.dev
- —The endpoint returns HTTP 402 on unauthenticated GET requestshttps://402-server.pinata-marketing-enterprise.workers.dev/v1/retrieve/private/bafkreicg754td66rkwrdrjrk2zmfqkedodyvfqwxpe5mdh5xnxvd73jidq