Filecoin Pin

Store IPFS content on Filecoin's decentralized storage network with verifiable persistence.

Status

Ready for persistent, verifiable data on Filecoin Mainnet.

Register for updates and a later 2025 Q4 GA announcement at filecoin.cloud.

What is Filecoin Pin?

Filecoin Pin is a fully decentralized persistence layer for IPFS content using the global network of Filecoin storage providers with cryptographic guarantees.

When you use Filecoin Pin, your IPFS data gains:

• Verifiable persistence - Storage providers must cryptographically prove daily that they continue to store and serve your data
• Economic incentives - You only pay when storage proofs are successfully delivered and verified onchain
• Decentralized infrastructure - Your data can be stored across a global network of independent storage providers
• Seamless IPFS integration - Continue using standard IPFS Mainnet tooling (e.g., Kubo, Helia, HTTP Gateways) while gaining Filecoin's persistence guarantees
• Sovereign data - Choose your providers, audit storage proofs and payments onchain, with no dependency on a single company

Who is Filecoin Pin for?

Filecoin Pin is designed for developers building on IPFS who need trustless, economically-incentivized persistence for their content. Whether you're building dApps, CI/CD workflows, static websites, AI agents, or other applications, Filecoin Pin provides the missing persistence layer for IPFS.

Affordances

Filecoin Pin offers multiple affordances to integrate Filecoin storage into your workflow:

CLI

Upload IPFS files directly to Filecoin via the command line. Perfect for developers who want to integrate Filecoin storage into scripts, workflows, or local development environments.

• Repository: This repo (filecoin-project/filecoin-pin)
• Documentation:
  • Run filecoin-pin --help to see all available commands and options.
  • CLI Walkthrough
• Installation: npm install -g filecoin-pin
• Update notice: Every command quickly checks npm for a newer version and prints a reminder when one is available. Disable with --no-update-check.

GitHub Action

Automatically publish websites or build artifacts to IPFS and Filecoin as part of your CI/CD pipeline. Ideal for static websites, documentation sites, and automated deployment workflows.

• Repository: This repo (see upload-action/)
• Documentation:
  • GitHub Action Walkthrough
• Example in Production: filecoin-pin-website CI pipeline

JavaScript Library

Use Filecoin Pin programmatically in your Node.js or browser applications. The library provides both a high-level API for common use cases and granular core modules for advanced customization.

• Repository: This repo (filecoin-project/filecoin-pin)
• Documentation:
  • API Reference (TypeDoc-generated documentation)
  • High-level API: import { … } from 'filecoin-pin' (recommended for most use cases)
  • Core modules: import { … } from 'filecoin-pin/core/*' (CAR files, payments, Synapse SDK, uploads, UnixFS)
• Installation: npm install --save filecoin-pin

IPFS Pinning Server (Daemon Mode)

Run a localhost IPFS Pinning Service API server that implements the IPFS Pinning Service API specification. This allows you to use standard IPFS tooling (like ipfs pin remote) while storing data on Filecoin.

• Repository: This repo (filecoin-pin server command in CLI)
• Usage: PRIVATE_KEY=0x... npx filecoin-pin server (or use session key auth — see Configuration)
• Status: Works and is tested, but hasn't received as many features as the CLI. If it would benefit your usecase, please comment on tracking issue so we can be better informed when it comes to prioritizing.

Management Console GUI

Web-based management console for monitoring and managing your Filecoin Pin deployments. This is effectively a Web UI equivalent to the CLI.

• Status: Planned
• Tracking: See issue #74 for updates. Please leave a comment about your usecase if this would be particularly beneficial.

Documentation

See /documentation.

Examples

See Filecoin Pin in action:

• upload-action - Example GitHub Action workflows demonstrating automated IPFS/Filecoin uploads
• filecoin-pin-website - Demo dApp showing browser-based file uploads to Filecoin
  • Walkthrough
  • 🎥 Recording 1
  • 🎥 Recording 2

Architecture

The Big Picture

Filecoin Pin bridges IPFS and Filecoin to provide verifiable persistence for content-addressed data:

Filecoin Pin Structure

This repository contains multiple affordances for user interaction and a shared library for consistent functionality:

The Synapse SDK is the main library, as it's doing the work of interfacing with the rest of Filecoin Onchain Cloud including smart contracts, Filecoin Storage Providers, and more.

Helia is leveraged for turning files and directories into IPFS compatible data, which we output in CAR format.

The affordances were discussed more above. All affordances use the same core library, ensuring consistent behavior and making it easy to add new interfaces in the future.

CLI Telemetry

Filecoin Pin's CLI collects telemetry. A few things:

• Telemetry always has a way to be disabled.
• We don't collect Personal identifiable information (PII).
• With our end user affordance we expect to make telemetry on by default, requiring a consumer/user to opt out. We are defaulting as "enabled" to help make sure we have a good pulse on the user experience and can address issues correctly.
• In this pre-v1 season, we are particularly focused on helping maintainers validate functionality and iron out problems throughout the whole Filecoin Onchain Cloud stack that filecoin-pin relies on.

How to disable CLI telemetry

Set the environment variable FILECOIN_PIN_TELEMETRY_DISABLED=true.

Quick Start

Prerequisites

• Node.js 24+ for CLI and library usage
• Filecoin wallet (Calibration testnet or Mainnet) with:
  • For Calibration testnet:
    • Test FIL for transaction gas (Faucet)
    • Test USDFC stablecoin for storage payments (USDFC Faucet)
  • For Mainnet:
    • FIL for transaction gas
    • USDFC stablecoin for storage payments

Installation

npm install -g filecoin-pin

Basic Usage

# 0. Set up authentication (choose one):
#    Private key:   export PRIVATE_KEY=0x...
#                   (or pass --private-key <key> to each command)
#    Session key:   export WALLET_ADDRESS=0x... SESSION_KEY=0x...
#                   (or pass --wallet-address <addr> --session-key <key> to each command)

# 1. Configure payment permissions (one-time setup)
filecoin-pin payments setup --auto

# 2. Upload a file to Filecoin (defaults to Mainnet)
filecoin-pin add myfile.txt

# 3. Verify storage with cryptographic proofs
filecoin-pin data-set <dataset-id>

# To use Calibration testnet (not persistent) instead:
filecoin-pin add myfile.txt --network calibration

For detailed guides, see:

• CLI: Complete CLI walkthrough
• GitHub Action: CI/CD integration guide

Configuration

Configuration of the Filecoin Pin CLI can be performed either with arguments, or environment variables.

The Pinning Server requires the use of environment variables, as detailed below.

Network Selection

Filecoin Pin supports Mainnet, Calibration testnet, and local devnet networks. By default, the CLI uses Mainnet.

Using the CLI:

# Use Mainnet (default)
filecoin-pin add myfile.txt

# Explicitly specify Mainnet
filecoin-pin add myfile.txt --network mainnet

# Use Calibration testnet
filecoin-pin add myfile.txt --network calibration

# Use a local foc-devnet (reads config from devnet-info.json, details below)
filecoin-pin add myfile.txt --network devnet

Using environment variables:

# Set network via environment variable
export NETWORK=mainnet
filecoin-pin add myfile.txt

# Or override RPC URL directly
export RPC_URL=wss://wss.node.glif.io/apigw/lotus/rpc/v1
filecoin-pin add myfile.txt

Selection rules:

• --network and --rpc-url (and their NETWORK / RPC_URL env equivalents) are mutually exclusive. Passing both is an error.
• When --rpc-url (or RPC_URL) is set, Filecoin Pin probes the endpoint's eth_chainId at startup and uses the matching chain (mainnet, calibration, or a configured devnet).
• When neither is set, Filecoin Pin defaults to Mainnet.

Local Development with foc-devnet

When using --network devnet, Filecoin Pin reads connection details from a running foc-devnet instance:

• Private key: Automatically resolved from devnet-info.json (no PRIVATE_KEY needed)
• RPC URL: Read from the devnet chain configuration
• Contract addresses: Resolved from the devnet chain definition
• IPNI verification: Automatically skipped (no IPNI infrastructure on devnet)

Environment variables for devnet:

| Variable | Description | Default | |----------|-------------|---------| | FOC_DEVNET_BASEDIR | Override the foc-devnet base directory | ~/.foc-devnet | | DEVNET_INFO_PATH | Explicit path to devnet-info.json (overrides basedir) | <basedir>/state/latest/devnet-info.json | | DEVNET_USER_INDEX | Which user from devnet-info.json to use | 0 |

Common CLI Arguments

• -h, --help: Display help information for each command
• -V, --version: Output the version number
• -v, --verbose: Verbose output
• --private-key: Ethereum-style (0x) private key (wallet and signer), funded with USDFC
• --wallet-address: Session key mode: owner wallet address
• --session-key: Session key mode: scoped signing key registered to the wallet
• --network: Filecoin network to use: mainnet, calibration, or devnet (default: mainnet). Mutually exclusive with --rpc-url.
• --rpc-url: Filecoin RPC endpoint. Filecoin Pin probes its eth_chainId to derive the chain. Mutually exclusive with --network.

Other arguments are possible for individual commands, use --help to find out more.

Environment Variables

# Required
PRIVATE_KEY=0x...              # Ethereum private key with USDFC tokens

# Optional - Network Configuration
NETWORK=mainnet                # Network to use: mainnet, calibration, or devnet (default: mainnet)
RPC_URL=wss://...              # Filecoin RPC endpoint (overrides NETWORK if specified)
                               # Mainnet: wss://wss.node.glif.io/apigw/lotus/rpc/v1
                               # Calibration: wss://wss.calibration.node.glif.io/apigw/lotus/rpc/v1

# Optional for Pinning Server Daemon
PORT=3456                      # Daemon server port
HOST=localhost                 # Daemon server host
DATABASE_PATH=./pins.db        # SQLite database location
CAR_STORAGE_PATH=./cars        # CAR file storage directory
LOG_LEVEL=info                 # Logging verbosity (info, debug, error)

Default Data Directories

When DATABASE_PATH and CAR_STORAGE_PATH are not specified, data is stored in platform-specific locations:

• Linux: ~/.local/share/filecoin-pin/
• macOS: ~/Library/Application Support/filecoin-pin/
• Windows: %APPDATA%/filecoin-pin/

Development

Want to contribute to Filecoin Pin or run it locally? See DEVELOPMENT.md for setup, scripts, debugging tips, HTTP tracing, running against a local devnet, and working with an unpublished synapse-sdk checkout.

Repository development uses pnpm workspaces. The published package can still be installed with npm, pnpm, or other package managers.

Community and Support

Contributing

Interested in contributing? Please read our Contributing Guidelines for information on commit conventions, PR workflows, etc.

Get Help

• Issues: Found a bug or have a feature request? Open an issue in this repository
• Community Discussion: Join the conversation in Filecoin Slack's public #fil-foc channel

Documentation

• documentation/ - Additional documentation about how filecoin-pin works, design decisions, etc.
• docs.filecoin.io - Filecoin Pin guides and tutorials

License

Dual-licensed under MIT + Apache 2.0