Getting Started
Install Filecoin Pin, connect your wallet, deposit storage credit, and pin your first file to Filecoin in around 10 minutes.
This guide walks you through pinning your first file to Filecoin using the Filecoin Pin CLI. By the end, you'll 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 don't have one set up, see Wallets and 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.
Node.js 24 or later - the Filecoin Pin CLI runs on Node.js. Install from nodejs.org or via your package manager.
📦 Install the Filecoin Pin CLI
Install the CLI globally with npm:
Verify the installation:
To see all available commands at any time:
🔐 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:
Open the MetaMask extension.
Click the three dots next to your account name.
Select Account details.
Click Show private key.
Enter your MetaMask password.
Copy the private key shown.
The private key is a 64-character hex string, with or without an 0x prefix.
2️⃣ Save or export the private key
The Filecoin Pin CLI does not store your key, but a .env file is still a local file on disk. Use a private working directory, keep .env out of git, and delete the file when you no longer need it.
Create a file named .env in your working directory containing:
Then secure it and load it into your shell:
For a one-off shell session, you can avoid writing the key to disk and export it directly instead:
💰 Set up payments
Filecoin Pin uses Filecoin Pay to manage storage payments. Before you can pin anything, you need to:
Authorise the Warm Storage Service contract to spend USDFC on your behalf.
Deposit USDFC into Filecoin Pay so storage providers can be paid.
The CLI walks you through both steps interactively.
The CLI will guide 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.
If you don't have enough FIL for gas or USDFC for storage, the CLI will tell you and stop. 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.
Coming from Storacha? Refer to the email we sent you for the specific USDFC amount we'd recommend depositing for your dataset size.
4️⃣ Confirm the deposit
The CLI submits the deposit transaction onchain and shows the transaction hash and your new storage capacity.
You should see something like:
💵 Top up your runway (optional)
If you want to ensure your deposit covers a specific number of days at your current storage usage, run:
This deposits (or withdraws) the right amount of USDFC to give you exactly 30 days of runway based on what you're currently storing. You can use any number of days you like.
To check your current deposit balance, runway, and payment status at any time:
📌 Pin your first file
Now you're ready to pin. Create a test file:
Pin it to Filecoin:
The CLI will:
Pack your file into IPFS-compatible format (a CAR file).
Select storage providers automatically.
Store your file with two providers for redundancy.
Verify the upload was advertised to IPNI indexers.
You should see something like:
The Root CID is your IPFS Content Identifier - it's how you'll retrieve your data. Save it somewhere.
You can also pin a directory by passing the directory path instead of a file:
🌐 Retrieve your file
Your file is now retrievable via standard IPFS tooling using its Root CID. For example:
Or via the dweb.link gateway:
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:
Then get the full on-chain detail for a specific data set:
This queries the smart contracts directly, so the values are live blockchain state.
You'll see something like:
Key things to look for:
Status:
live- your data set is active and being proved.PDP rail ID - your active storage-proof payment rail.
Min proving period - how often the provider must submit a fresh proof.
Provider Service URL - direct retrieval endpoint for your pieces.
CommP / Root CID per piece - the piece CID is what the provider proves; the Root CID is what you use to retrieve.
🎉 You're Done!
You've successfully pinned your first file to Filecoin. You now have:
✅ The Filecoin Pin CLI installed and configured
✅ Your wallet connected with funded payments on Filecoin Pay
✅ Files pinned to two Filecoin storage providers with daily cryptographic proofs
✅ Your content retrievable via standard IPFS gateways
🔜 Next Steps
📖 Run
filecoin-pin --helpto explore advanced usage, including auto-funding and custom provider selection.🔍 Want to understand what's happening behind the scenes? Read Behind the Scenes of Adding a File for a deep dive into each step.
🤖 Automate pinning in your CI/CD pipeline with the Filecoin Pin GitHub Action.
💬 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.
Last updated