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; this paid retrieval mechanism is the intended way to fetch them. The CID in the URL (bafkreigapts2hedc4n2in6c5bj7x4eclx4ergaizi7naalcehkhcza7dxa) identifies the specific file to retrieve.
No OpenAPI schema or detailed pricing information was found 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. Pinata's full x402 documentation is referenced at docs.pinata.cloud/files/x402 but was not included in the crawl bundle.
Capabilities
Use cases
- —Retrieving private IPFS files without a Pinata account by paying with crypto
- —Building decentralized apps that gate content behind micropayments
- —Agents autonomously fetching paid private content from IPFS
- —Accessing privately pinned files on Pinata from any client that supports x402
Fit
Best for
- —Developers building crypto-native apps that need private IPFS file access
- —AI agents that need to autonomously pay for and retrieve private content
- —Users who want account-free, pay-per-use access to Pinata-hosted private files
Not for
- —Retrieving publicly pinned IPFS content (use a public gateway instead)
- —Bulk or high-volume file downloads where a Pinata subscription would be cheaper
- —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/bafkreigapts2hedc4n2in6c5bj7x4eclx4ergaizi7naalcehkhcza7dxa',
{ method: 'GET' }
);
const fileData = await res.blob();
console.log('Retrieved file size:', fileData.size);Endpoint
Quality
The endpoint is live and returns a 402 challenge, confirming x402 functionality. However, the challenge object is empty (no payment details captured), there is no OpenAPI schema, no pricing info, and the detailed docs page (docs.pinata.cloud/files/x402) was not crawled. Most fields are inferred from the landing page description and URL structure.
Warnings
- —x402 challenge object was empty — payment terms (token, amount, network) could not be verified from the probe
- —No OpenAPI or JSON schema available for this endpoint
- —Detailed documentation at docs.pinata.cloud/files/x402 was not crawled; capabilities may be incomplete
- —No pricing information found in crawl bundle
- —The CID in the URL is hardcoded to a specific file; it is unclear whether other CIDs work with the same base path without additional documentation
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; public content is available on public gatewayshttps://402-server.pinata-marketing-enterprise.workers.dev
- —Full x402 documentation is hosted at docs.pinata.cloud/files/x402https://402-server.pinata-marketing-enterprise.workers.dev
- —The endpoint returns HTTP 402 with an x402 challenge on GET requestshttps://402-server.pinata-marketing-enterprise.workers.dev/v1/retrieve/private/bafkreigapts2hedc4n2in6c5bj7x4eclx4ergaizi7naalcehkhcza7dxa