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 — no Pinata account or API key required. The endpoint returns an HTTP 402 challenge to unauthenticated callers, and upon successful payment the private file content is served.
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 (bafkreieoyh26ynfux2pldujpawobz6mqxkvlxcmyu2n6vhfqgcmmd5vh2u) identifies the specific file to retrieve.
Documentation is sparse: the landing page at the origin provides code examples for uploading but not for retrieval, and the full docs link points to docs.pinata.cloud/files/x402 which was not crawled. No OpenAPI schema, pricing details, or response format documentation were found in the probe or crawl material. The endpoint is confirmed live (402 challenge returned on GET), but the challenge object itself was empty, so payment parameters (price, accepted tokens, network) could not be determined from the probe alone.
Capabilities
Use cases
- —Retrieving a specific private file stored on IPFS via Pinata without needing an account
- —Paying per-request with cryptocurrency to access gated IPFS content
- —Building decentralized applications that serve private content behind a paywall
- —Agent-driven retrieval of private IPFS assets using x402 micropayments
Fit
Best for
- —Developers needing account-free access to private IPFS files
- —Applications that want to gate content retrieval behind crypto micropayments
- —Agents or automated systems that can handle x402 payment challenges
Not for
- —Retrieving publicly pinned IPFS content (use a public gateway instead)
- —Users who need to retrieve files without cryptocurrency
- —Bulk or high-throughput file retrieval where per-request payment overhead is impractical
Quick start
import { fetchWithPayment } from 'x402-fetch';
const res = await fetchWithPayment(
'https://402-server.pinata-marketing-enterprise.workers.dev/v1/retrieve/private/bafkreieoyh26ynfux2pldujpawobz6mqxkvlxcmyu2n6vhfqgcmmd5vh2u',
{ method: 'GET' }
);
const fileData = await res.blob();
console.log('Retrieved file size:', fileData.size);Endpoint
Quality
The endpoint is confirmed live with a 402 challenge on GET, but the challenge object is empty, no schema or OpenAPI spec exists, no pricing or response format documentation was found in the crawl, and the /docs path returns 404. Most details must be inferred from the landing page and the existing listing title.
Warnings
- —Empty x402 challenge object — payment parameters (price, token, network) unknown from probe
- —No OpenAPI or schema documentation available
- —Full docs at docs.pinata.cloud/files/x402 were not crawled; details may exist there
- —No pricing information found in crawl material
- —This endpoint URL is CID-specific; it retrieves one particular file, not a general retrieval API
Citations
- —Pinata offers account-free IPFS uploads and private retrieval using Coinbase's x402 protocolhttps://402-server.pinata-marketing-enterprise.workers.dev
- —Private IPFS content requires payment to retrievehttps://402-server.pinata-marketing-enterprise.workers.dev
- —Full documentation is linked at docs.pinata.cloud/files/x402https://402-server.pinata-marketing-enterprise.workers.dev
- —Endpoint returns HTTP 402 on GET confirming it is livehttps://402-server.pinata-marketing-enterprise.workers.dev/v1/retrieve/private/bafkreieoyh26ynfux2pldujpawobz6mqxkvlxcmyu2n6vhfqgcmmd5vh2u