Quick Start with Filecoin Pin

This guide walks you through pinning your first file to Filecoin using the Filecoin Pin CLI. By the end, you will be set up to:

• Install the Filecoin Pin CLI
• Connect your Ethereum-style wallet on Filecoin
• Deposit storage credit on Filecoin Pay
• Pin a file to Filecoin and retrieve it using standard IPFS tooling

Prerequisites

Before starting, make sure you have:

• An Ethereum-style wallet on Filecoin: MetaMask is the easiest option. If you do not have one set up, see MetaMask setup.
• FIL in your wallet: to pay transaction gas fees on Filecoin.
• USDFC in your wallet: to pay for storage. USDFC is the stablecoin used by Filecoin Onchain Cloud. The easiest way to get some is to swap FIL for USDFC on Sushi.

Install the Filecoin Pin CLI

Install the CLI globally with npm:

npm install -g filecoin-pin

Verify the installation:

filecoin-pin --version

To see all available commands at any time:

filecoin-pin --help

Connect Your Wallet

The Filecoin Pin CLI signs transactions using your wallet’s private key. You provide it as an environment variable; the CLI reads it directly and never stores it on disk.

1. Export your private key from MetaMask

   Treat your private key like a password

   Anyone with your private key has full control of your wallet and any funds in it. Never paste it into a website, share it over chat, commit it to a repository, or store it in plain text on a shared system.

   In MetaMask:

   1. Open the MetaMask extension.
   2. Click the three dots next to your account name.
   3. Select Account details.
   4. Click Show private key.
   5. Enter your MetaMask password.
   6. Copy the private key shown.

   The private key is a 64-character hex string, with or without an 0x prefix.

2. Save the private key to a .env file

   Create a file named .env in your working directory containing:

   export PRIVATE_KEY="0xYOUR_PRIVATE_KEY_HERE"

   Then secure it and load it into your shell:

   chmod 600 .env
   source .env

   Add .env to your .gitignore if you are inside a git repository.

Set Up Payments

Filecoin Pin uses Filecoin Pay to manage storage payments. Before you can pin anything, you need to:

1. Authorize the Warm Storage Service contract to spend USDFC on your behalf.
2. Deposit USDFC into Filecoin Pay so storage providers can be paid.

The CLI walks you through both steps interactively:

filecoin-pin payments setup

The CLI guides you through the following stages:

1. Connect and check balances

   The CLI confirms it can connect to Filecoin Mainnet and reports your wallet’s FIL and USDFC balances.

   Note

   If you do not have enough FIL for gas or USDFC for storage, the CLI tells you and stops. Top up your wallet and try again.

2. Review pricing

   The CLI shows current storage pricing per GiB per month and per TiB per month. Use this to estimate how much USDFC you want to deposit.

3. Choose a deposit amount

   The CLI asks: “Would you like to deposit USDFC to enable storage?” Answer Yes.

   It then shows example monthly costs for common storage amounts (100 GiB, 1 TiB, 10 TiB) so you can pick a sensible deposit. When prompted “How much USDFC would you like to deposit?”, enter the amount you want. A first-time deposit of 10.0 USDFC is a reasonable starting point.

4. Confirm the deposit

   The CLI submits the deposit transaction on-chain and shows the transaction hash and your new storage capacity.

   Example output

   ✓ Deposit complete
     Deposit tx: 0x1234...abcd
   
   New Storage Capacity:
     Total deposit: 10.00 USDFC
     Capacity: ~XX GiB for 1 month

Top Up Your Runway (Optional):

Once you have data stored, you can top up your deposit to cover a specific number of days at your current usage:

filecoin-pin payments fund --days 30

This deposits (or withdraws) the right amount of USDFC to give you exactly 30 days of runway based on what you are currently storing. You can use any number of days you like.

Note

payments fund --days <n> computes the target from your current storage rate, so it only works after you have pinned something. Before your first upload it reports No active spend detected — set an explicit target with filecoin-pin payments fund --amount <usdfc> instead, or just come back to this step after pinning your first file.

To check your current deposit balance, runway, and payment status at any time:

filecoin-pin payments status

Pin Your First File

Now you are ready to pin. Create a test file:

echo "Hello Filecoin Pin! This is my first file stored on Filecoin with verifiable proofs of storage and retrievable over IPFS." > demo.txt

Note

Pieces have a minimum size of 127 bytes once packed. Very small files (a few bytes) are rejected, so make sure your test file has a little content.

Pin it to Filecoin:

filecoin-pin add demo.txt

The CLI will:

1. Pack your file into IPFS-compatible format (a CAR file).
2. Select storage providers automatically.
3. Store your file with two providers for redundancy.
4. Verify the upload was advertised to IPNI indexers.

Example output

Filecoin Pin Add

✓ File validated (122.0 B)
✓ Connected to Filecoin - Mainnet
✓ File packed with root CID: bafybeihkoviema7g3gxyt6la7vd5ho32ictqbilu3wnlo3rs7ewhnp7lly
✓ [Primary] Stored on provider 2
✓ [Secondary] Stored on provider 9
✓ IPNI provider records found. IPFS retrieval possible.

━━━ Add Complete ━━━

Root CID:  bafybeihkoviema7g3gxyt6la7vd5ho32ictqbilu3wnlo3rs7ewhnp7lly
Piece CID: bafkzcibcfab4grpgq6e6rva4kfuxfcvibdzx3kn2jdw6q3zqgwt5cou7j6k4wfq
Copies:    2/2

Add completed successfully

The Root CID is your IPFS Content Identifier; it is how you will retrieve your data. Save it somewhere.

You can also pin a directory by passing the directory path instead of a file:

mkdir my-data
echo "File 1" > my-data/file1.txt
echo "File 2" > my-data/file2.txt
filecoin-pin add my-data/

Retrieve Your File

Your file is now retrievable via standard IPFS tooling using its Root CID.

For example, via a subdomain gateway:

https://<YOUR_ROOT_CID>.ipfs.inbrowser.link

Or via the dweb.link gateway:

https://dweb.link/ipfs/<YOUR_ROOT_CID>

Try opening one of those URLs in your browser; your file should load. You can also retrieve it programmatically using any IPFS-compatible client (Kubo, Helia, Lassie, etc.) by referencing the Root CID.

Inspect Your Storage Proofs

Filecoin storage providers must cryptographically prove daily that they continue to store your data. You can inspect those proofs and the on-chain payment rails at any time.

List the data sets associated with your wallet:

filecoin-pin data-set ls

Then get the full on-chain detail for a specific data set:

filecoin-pin data-set show <DATASET_ID>

This queries the smart contracts directly, so the values are live blockchain state.

Example output

Filecoin Onchain Cloud Data Set Details for #14081

#14081
  Status: live
  CDN add-on: enabled

  Provider
    ID: 4
    Name: <provider-name>
    Service URL: https://<provider-service-url>

  Metadata
    source: "filecoin-pin"
    withCDN: ""
    withIPFSIndexing: ""

  Payment
    PDP rail ID: 17487
    FilBeam rail ID: 17490
    FilBeam cache-miss rail ID: 17489
    Payer: 0xYOUR_WALLET_ADDRESS
    Payee: 0xPROVIDER_ADDRESS

  Pieces
    Total pieces: 1
    Total size: 219.0 B

    #0 (active)
      PieceCID: bafkzcib...
      Metadata
        ipfsRootCID: "bafkrei..."
        name: "demo.txt"

Key things to look for:

• Status live: your data set is active and being proved.
• CDN add-on: whether the FilBeam CDN retrieval add-on is enabled for this data set.
• PDP rail ID: your active storage-proof payment rail.
• Provider Service URL: direct retrieval endpoint for your pieces.
• PieceCID / ipfsRootCID per piece: the PieceCID is what the provider proves; the ipfsRootCID (your Root CID) is what you use to retrieve.

You have successfully pinned your first file to Filecoin.

Next Steps

• Run filecoin-pin --help to explore advanced usage, including auto-funding and custom provider selection.
• Want to understand what is happening behind the scenes? Read Behind the Scenes of Adding a File for a deep dive into each step.
• Join the community in Filecoin Slack #fil-foc for help, discussion, and updates.
• Found a bug or have a feature request? Open an issue on GitHub.