filecoin-pin
    Preparing search index...

    filecoin-pin

    Filecoin Pin

    NPM

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

    Ready for persistent, verifiable data on Filecoin Mainnet.

    Register for updates and a later 2026 Q2 GA announcement at filecoin.cloud.

    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

    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.

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

    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.

    • Status: Production-ready. It has been recommended to users for months, and is used extensively by the development team.
    • 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.

    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.

    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.

    • Status: Production-ready. Powers the CLI, GitHub Action, filecoin-pin-website, and FOC dealbot.
    • 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

    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.

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

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

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

    See /documentation.

    See Filecoin Pin in action:

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

    Filecoin Pin Architecture

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

    Filecoin Pin Structure

    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.

    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.

    Set the environment variable FILECOIN_PIN_TELEMETRY_DISABLED=true.

    • 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
    npm install -g filecoin-pin

    # 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:

    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.

    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.
    • -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.

    # 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)

    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/

    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

    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.

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

    • 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

    See Documentation above for all guides and references.

    Dual-licensed under MIT + Apache 2.0

    Settings

    Member Visibility

    On This Page

    Filecoin Pin