Store and retrieve

The process of storing and retrieving data using the Filecoin network is slightly different from how most storage platforms work. This tutorial walks you through the whole end-to-end process of keeping your data and then getting it back when you need it! This tutorial should take you about an hour to complete.

Before we start

The process is split into three main parts: the set-up, storing your data and retrieving your data. Each section has several sub-processes that we need to follow.

flowchart TB subgraph set-up [Set up] a1[Get a Lotus full-node]-->a2[Create a Lotus lite-node] a2-->a3[Create a Filecoin address] a3-->a4[Sign up to Filecoin plus] end subgraph Store b1[Package your data]-->b2[Import your data into Lotus] b2-->b3[Find a miner] b3-->b4[Create a storage deal] b4-->b5[Wait for the deal to complete] end subgraph Retrieve c1[Create a retrieval deal]-->c2[Download your data] end set-up --> Store Store --> Retrieve
Set up1. Get access to a Lotus full-node.
2. Start a Lotus lite-node on your local computer.
3. Get a FIL address.
4. Sign up for Filecoin Plus.
Store data1. Package your data.
2. Import your data into Lotus.
3. Find a storage provider through the Filecoin Plus Registry.
4. Create a storage deal.
5. Wait for the deal to complete.
Retrieve data1. Create a retrieval deal.
2. Download your data.

It will take about an hour to complete this tutorial. While there aren’t too many steps involved, there’s a bit of waiting around for the network to process your requests.

Take notes

There are a few things to remember throughout this tutorial, such as Miner IDs and addresses. There is a table at the end of each section showing the information you should record:

Miner IDThe unique identifier for each storage provider.f01000

The above table is an example of what you will see throughout the tutorial; you don’t have to copy it down.

Terms and phrases

This tutorial contains some words and phrases that you might not be familiar with. Refer back to this table if you encounter something you don’t understand:

AddressA string of letters and numbers that other users can send FIL to.
Block explorerA service, usually a website, that lets you view details of a blockchain such as transactions, deals, and addresses.
DealAn agreement between two computers about what to do with some data.
FILThe shorthand representation of the filecoin cryptocurrency. For example: We charge 0.5 FIL per GiB.
Filecoin (upper-case F)The network that transactions and storage deals take place on. For example: Museums can use the Filecoin network to store their digital archives.
filecoin (lower-case f)The cryptocurrency that the Filecoin network runs on. For example: You can use filecoin to pay for your transactions.
MinerAn alternate name for a storage provider.
Private keyA string of letters and numbers that programs use to interact with the Filecoin network. Keep your private key safe, and don’t share it with anyone.
Storage dealAn agreement between a storage provider and a client about what data to store, how long for, and how much the storage provider can charge for storage.
Retrieval dealAn agreement between a storage provider and a client about how much the storage provider can charge to send data to a client.
Storage clientThe user that wants to store something on the Filecoin network. In this tutorial, you are the storage client.
Storage providerA computer on the Filecoin network offering storage space to other users who want to store data. Storage providers are sometimes called miners.
WalletA collection of addresses. Think of each wallet as a folder and each address as a single file in that folder.

Set up

Before you begin storing any data on the Filecoin network, you need to run through a few steps to get everything set up. This section covers getting access to a Lotus full-node, creating a Lotus lite-node on your computer, getting a FIL address, and signing up to Filecoin+.

graph LR A[Get a Lotus node] -->B[Create a local Lotus lite-node] B --> C[Get a FIL address] C --> D[Sign up to Filecoin Plus]

Things to note

As you’re going through this section, make a note of the following variables:

Your Filecoin addressThe public part of your Filecoin address. This address is what other users can use to send your FIL.f1fwavjcfb32nxbczmh3kgdxhbffqjfsfby2otloi


If you are using macOS you must have Homebrew installed. If you are using Linux you must have Snapd installed.

Access a full-node

A Lotus full-node is a computer running the lotus daemon. Full-nodes are unique because they have complete access to the Filecoin blockchain. The computer specifications required to run a Lotus full-node are relatively high and might be out of reach for most end-user laptops and PCs.

Usually, we’d have to spin up a full-node, but we’re going to use a Lotus full-node provided by Protocol Labs for this tutorial. This node, called, is only for practice sessions like this tutorial and should not be relied upon for any production or development purposes.

Install a lite-node

A lite-node lets your computer interact with the Filecoin network without having to run a resource-intensive full-node! Lite-nodes can do things like sign messages and talk to storage providers, but any processes that need data from the blockchain must come from a full-node. Luckily, lite-nodes automatically route any blockchain-based requests to a full-node. For this tutorial, you’re going to run a Lotus lite-node on your local computer and have it connect to a full-node managed by Protocol Labs.

graph LR A(Get a Lotus node) -- blockchain requests -->B[Full-node] A -- storage/retrieval requests --> C[Filecoin miner] B --> D((The Filecoin Blockchain)) C --> D

To install a Lotus lite-node on your computer, you must have the tools required to build a Lotus binary from the GitHub repository.


  1. Add the filecoin-project/lotus Homebrew tap:

    brew tap filecoin-project/lotus
  2. Install Lotus:

    brew install lotus
  3. Lotus is now installed on your computer.


There are two simple ways to install Lotus on Ubuntu:

  1. Update and upgrade your system:

    sudo apt update -y && sudo apt upgrade -y
  2. Download the latest AppImage file from the Lotus GitHub releases page:

  3. Make the AppImage executable:

    chmod +x Lotus-v1.11.1-x86_64.AppImage
  4. Move the AppImage to /usr/local/bin and rename it lotus:

    sudo mv Lotus-v1.11.1-x86_64.AppImage /usr/local/bin/lotus

Head onto the next section to run your Lotus lite-node ↓

  1. To install Lotus using Snap, run:

    snap install lotus-filecoin

Head onto the next section to run your Lotus lite-node ↓

Run a Lotus lite-node

Now that you have Lotus ready to run, you can start a Lotus lite-node on your computer and connect to the Lotus full-node!

  1. Open a terminal windows and run the lotus daemon --lite command, using as the full-node address:

    FULLNODE_API_INFO=wss:// lotus daemon --lite
    2021-06-16T02:00:08.390Z        INFO    markets loggers/loggers.go:56   module ready   {"module": "storage client"}
    2021-06-16T02:00:08.392Z        INFO    markets loggers/loggers.go:56   module ready   {"module": "retrieval client"}
    2021-06-16T02:00:18.190Z        INFO    basichost       basic/natmgr.go:91      DiscoverNAT error:no NAT found
  2. MacOS users may see a warning regarding Lotus. Select Accept incoming connections if you see a warning.

  3. The Lotus daemon will continue to run. You must run further commands from a separate terminal window.

Next up is getting a FIL address ↓

Get a FIL address

Filecoin addresses are similar to regular bank account numbers. Other users can use your address to send you FIL, and you can use your address to pay storage providers for storing and retrieving your data.

There are two parts to a Filecoin address: the public address and the private key. You can freely share your public address with anyone, but you should never share your private key. We’re not going to view any private keys in this tutorial, but it’s essential to understand the difference between your public address and your private key.

  1. Open a new terminal window and create an address using the lotus wallet new command:

    lotus wallet new

    Lotus outputs your public address. Public addresses always start with f1.

  2. Make a note of this address. We’ll use it in an upcoming section.

Backup your address

Your address is made up of two parts: your public address and your private key. The public address is what you see when you run lotus wallet new, and you’re safe to share that address with whoever you want. Your private key, however, must be kept secret and secure. If you lose your private key, you lose access to any FIL stored in that address.

It is incredibly important that you backup your addreses. Storing a copy of your addresses on another device is a great way to ensure you don’t lose access to your funds.

  1. If your public address f1... is still in the terminal window, copy it to your clipboard. If not, list the addresses associated with your Lotus node and copy your public address:

    lotus wallet list
    Address                                    Balance  Nonce  Default
    f1nau67e6k6ggdwluatfz4waexetjfrqmx6fil3nq  0 FIL    0      X
  2. Use lotus wallet export to export your private key, replacing f1... with your public key:

    lotus wallet export f1... > my_address.key

    This will create a new file called my_address.key in the current directory.

Once you have your address in a file, you can copy it to another drive, securely send it to another computer, or even print it out. It’s important to keep this file safe. If anything happens to your Lotus node, you can still access your funds using this file.

Store data

Start storing your data on the Filecoin network. This section covers packaging your data, importing it into your local Lotus lite-node, finding a storage provider through the Filecoin Plus miner registry, creating a storage deal, and then waiting for the deal to complete. There’s a lot to do, so let’s dive in!

Things to note

As you’re going through this section, make a note of the following variables:

Data CIDThe content identifier (CID) of the data that you want to store using Filecoin.bafk2bzaceajz56zudni2hli7id6jvvpo5n4wj5eoxm5xwj2ipthwc2pkgowwu
Storage Provider ID #1The unique identifier for each storage provider. You need to have two storage provider IDs for this tutorial.f01000
Storage Provider ID #2The unique identifier for each storage provider. You need to have two storage provider IDs for this tutorial.f01000
Deal CIDThe content identifier (CID) for a deal made with a storage provider.bafyreict2zhkbwy2arri3jgthk2jyznck47umvpqis3hc5oclvskwpteau

Prepare your data

For this tutorial, we’re going to create a dummy 5GB file full of random data and store it on the Filecoin network.

  1. Move into your home folder:

    cd ~
  2. Create a 5GB block of random data to serve as our payload:

    MacOS users must run:

    dd if=/dev/urandom of=5gb-filecoin-payload.bin bs=1m count=5200

    Linux users should run:

    dd if=/dev/urandom of=5gb-filecoin-payload.bin bs=1M count=5200

    This process will take about 60 seconds to create a dummy file.

We now have our payload file ready to be stored using the Filecoin network.

Add data to Lotus

We need to tell our Lotus lite-node which file we want to store using Filecoin.

  1. Import the payload into the lotus daemon using the import command:

    lotus client import 5gb-filecoin-payload.bin

    Lotus creates a directed acyclic graph (DAG) based off the payload. This process takes a few minutes. Once it’s complete, Lotus will output the payload CID.

    Import 3, Root bafykb...

    This process takes about 60 seconds.

  2. Make a note of the CID bafykb.... This is your Data CID. We’ll use it in an upcoming section.

Now that Lotus knows which file we want to use, we can create a deal with a Filecoin storage provider to store our data!

Find a storage provider via Filecoin Plus

Storage providers get paid either by receiving FIL directly from users for storing their data, winning block rewards from the network, or both!

Getting paid from users is straightforward. If Laika wants to store some data, and Albert is a storage provider, the two of them can create a deal to store Laika’s data for X amount of time for Y FIL.

Block rewards are randomly given to a storage provider every 30 seconds. The more data that a storage provider is storing, the higher their chances of winning the block reward. So if a storage provider accepts a deal from a user to store 5 GB of data, they have 5 chances to win the block reward for each 30 second round.

DataCap acts as a kind of multiplier for block rewards. If a storage provider accepts a deal from a user with DataCap attached, also known as a verified deal , then the Filecoin network treats that deal as though it’s 10x bigger. So a 5 GB deal gives the storage provider 50 chances to win the block reward instead of the usual 5 chances. Some storage providers find DataCap so valuable that they’re willing to make verified deals without charging any FIL! You can find a list of these storage providers using the Filecoin Plus Registry.

Sign up

Signing up to Filecoin Plus is easy and free!

  1. Go to
  2. Under For Clients, click Proceed.
  3. Under Get Verified, click Get DataCap.
  4. Click Automatic Verification.
  5. Click Start next to the GitHub logo.
  6. In the Request field, enter the public address you got from running lotus wallet list. This step may take a few minutes to complete.

We need to find suitable storage providers before we can store our data. The Filecoin network allows storage providers to compete by offering different terms for pricing, acceptable data sizes, and other important deal parameters. It’s also important to consider the storage provider’s location; the closer the storage provider is to you, the faster the storage and retrieval process will be.

We’re going to use the Filecoin Plus Registry to find a couple of storage providers and check their information through the reputation system.

Filecoin Plus Registry

The Filecoin Plus Registry is a collection of geographically diverse storage providers that are willing to accept low-cost or free storage deals from users. The more storage providers that offer storage in different parts of the world, the faster we can work toward Filecoin’s underlying mission to store humanity’s most important information. It can help you compare storage providers based on their location, pricing and data size limitations, and also their reputation based on their historical performance.

Let’s find a couple of storage providers to store our data.

  1. Go to Filecoin Plus Registry website.

  2. Using the table, find a couple of storage providers that suit your needs. Try to find storage providers that are geographically close to you, minimum file size is lower than 5 GiB, and charge 0 FIL for verified deals.

    A collection of storage providers listed in the Filecoin Plus miner registry.

  3. Once you find suitable storage providers, you can check more detail info about it by clicking the Arrow next to its reputation score.

    storage provider

  4. Make sure to write down the IDs of the storage providers you want to use. We’ll be referring to these IDs in the next section.

Filecoin Plus Registry only represents a small portion of the entire Filecoin mining community, you can also use other Filecoin reputation systems like FilRep to check more storage provider metrics, like storage power in the network, reachability and overall success rate.

Now that you’ve found your storage providers, you can move onto creating a storage deal!

Create a deal

To complete this section, you need the Data CID you received after running lotus client import and the IDs of the storage providers you want to use.

  1. Start the interactive deal process:

    lotus client deal

    The interactive deal assistant will now ask you some questions.

  2. Specify the CID of the payload you want to backup on Filecoin. This is the CID that you got from running lotus client import ~/5gb-filecoin-payload.bin:

    Data CID (from lotus client import): bafykbz...
  3. Wait for Lotus to finish calculating the size of your payload. Lotus calculates this size by counting the individual bits in your payload to ensure that the size is accurate.

    .. calculating data size

    The duration of this process depends on the size of your file and the specification of your Lotus node. In tests, Lotus took around 20 minutes file of a ~7.5GB file with a 4-core CPU and 8GB RAM. These specifications are common for most end-user laptops.

  4. Enter the number of days you want to keep this file on Filecoin. The minimum is 180 days:

    Deal duration (days): 180
  5. Tell Lotus whether or not this is a Filecoin Plus deal. Since you signed up to Filecoin Plus in an earlier step, select yes here:

    Make this a verified deal? (yes/no): yes
  6. Enter the miner IDs from the previous section with an empty space separating the two IDs:

    Miner Addresses (f0.. f0..), none to find: f01000 f01001
  7. Confirm your transaction by entering yes:

    Proposing from f136b5uqa73jni2rr745d3nek4uw6qiy6b6zmmvcq
            Balance: 2 FIL
    Piece size: 8GiB (Payload size: 7.445GiB)
    Duration: 7200h0m0s
    Total price: ~0 FIL (0 FIL per epoch)
    Verified: true
    Accept (yes/no): yes
  8. Lotus will returns two Deal CIDs:

    .. executing
    Deal (f01000) CID: bafyreict2zhkbwy2arri3jgthk2jyznck47umvpqis3hc5oclvskwpteau
    Deal (f01001) CID: bafeauyreict2zhkbwy2arri3jgthk2jyznck47umvpqis3hc5oclvskwpt
  9. Take a note of the deal CIDs baf....

Check the deal status

Once the data has been sent to the storage clients, the storage deals can take up to 24 hours to complete. You can check the progress of your deals.

  1. List successful and pending deals by using the lotus client list-deals command:

    lotus client list-deals --show-failed

    DO NOT TURN OFF YOUR LOTUS NODE! Your Lotus lite-node needs to remain online until the deal state has reached StorageDealActive. See the Processing states table below to find out which states happen and when.

  2. You can check the progress of any data transfers by running lotus client list-transfers:

    lotus client list-transfers

    This command will output something like:

    Sending Channels
    ID                   Status   Sending To   Root Cid     Initiated?  Transferred  Voucher
    1620782601911586915  Ongoing  ...KPFTTwY7  ...zyd3kapm  Y           224.1MiB     ...bqhcidjmajbelhlxfqry3d7qlu3tvar45a"}}
    Receiving Channels

    If the output of lotus client list-transfers is empty, then your transfer has finished:

    lotus client list-transfers
    Sending Channels
    Receiving Channels

Deal states

Because of the complex nature of Lotus and the Filecoin network, deals can be in one of many different states.

Processing states

The following table is the list of states that a deal should enter, assuming there are no errors. This list is in chronological order, from when the deal is first created to when it has completed successfully:

StorageDealUnknownThe current status of a deal is undefined or unknown. This could be because your full-node is out of sync.
StorageDealReserveClientFundsThe client is checking that it has enough FIL for the deal.
StorageDealClientFundingThe client has deposited funds into the StorageMarketActor and is waiting for the funds to appear.
StorageDealFundsReservedYour FIL has been deposited into escrow and is ready to be used to pay for the deal.
StorageDealStartDataTransferThe storage provider is ready to accept data from the client Lotus node.
StorageDealTransferringThe data is being transferred from the client Lotus node to the storage provider.
StorageDealCheckForAcceptanceThe client is waiting for a storage provider to seal and publish a deal.
StorageDealProposalAcceptedThe storage provider intends to accept a storage deal proposal; however, the storage provider has not made any commitment to do so at this point.
StorageDealAwaitingPreCommitA deal is ready and must be pre-committed.
StorageDealSealingThe storage provider, is sealing data into a sector. The larger your data payload, the longer this will take.
StorageDealActiveThe data is in a sealed sector, and the storage provider can provide the data back to you.
StorageDealExpiredA deal has passed its final epoch. The storage provider could still have the data available but is under no obligation to provide it to anyone.
Error states

The following deal states mean there was a failure somewhere along the line, in alphabetical order:

StorageDealErrorThere has been an unforeseen error. No further updates will occur.
StorageDealFailingSomething has gone wrong in a deal. Once data is cleaned up, the deal will finalize.
StorageDealProposalNotFoundYour full-node cannot find the deal you are looking for. This could be because it doesn’t exist, or your full-node is out of sync.
StorageDealProposalRejectedThe storage provider, has chosen not to accept this deal. The storage provider may have provided a reason alongside this status message, but not always.
StorageDealRejectingThe storage provider has rejected the deal. This comes immediately before StorageDealProposalRejected.
StorageDealSlashedThe data was in a sector, and the storage provider got slashed for failing to prove that the data was available.
Informational states

The following deal states are informational, and do not mean that a deal has failed. This list is in alphabetical order:

StorageDealAcceptWaitThe storage provider is running custom decision logic to decide whether or not to accept the deal. The deal will have this status until the custom logic comes to a decision.
StorageDealClientTransferRestartA storage deal data transfer from a client to a storage provider has restarted after a pause, likely caused by StorageDealProviderTransferAwaitRestart.
StorageDealFinalizingAll the data is within the sector, and the storage provider is performing the final checks to make sure that all the data is correct.
StorageDealProviderFundingThe storage provider has deposited funds into StorageMarketActor and is waiting for the funds to appear.
StorageDealProviderTransferAwaitRestartThe storage provider restarted while data was being transferred from the client to the storage provider. Once the storage provider is back online, it will wait for the client to resume the transfer.
StorageDealPublishThe deal is ready to be published on-chain.
StorageDealPublishingThe deal has been published but is yet to appear on-chain.
StorageDealReserveProviderFundsThe storage provider is checking that it has enough FIL for the deal.
StorageDealStagedThe deal has been published, and data is ready to be put into a sector. At this point, the storage provider has fully committed to storing your data.
StorageDealValidatingThe storage provider is validating that the deal parameters are good for a proposal.
StorageDealVerifyDataAll the data has been transferred, and the storage provider is now attempting to verify it against the PieceCID.
StorageDealWaitingForDataEither a manual transfer is occurring, or the storage provider has not received a data-transfer request from the client.

These states come from the Lotus project GitHub repository.

Retrieve data

In the previous step, you stored some data on the Filecoin network. It takes up to 24 hours for a storage provider to seal the data. If it’s been more than 24 hours since you completed the last section, great! If not, don’t worry; you can still follow this page to retrieve some example data that’s already on the Filecoin network.

Restart the Lotus

If you closed Lotus or shutdown your computer since you completed the previous section, you’ll need to restart the lotus daemon.

  1. Open a terminal window.

  2. Start a Lotus lite-node and connect to

    FULLNODE_API_INFO=wss:// lotus daemon --lite
  3. The Lotus daemon will continue to run. You must run further commands from a separate terminal window.

Next up is checking your balance ↓

Check address balance

Before you can retrieve data from a storage provider, you need to check that you have enough FIL to pay for the retrieval.

  1. List all the addresses on this Lotus lite-node:

    lotus wallet list

    Lotus will output something like:

    > Address                                    Balance  Nonce  Default
    > f16mwizoeloamhp4dea4uy367mlihddw2mflnb5vy  10 FIL   0      X

    Any balance above 0.1 FIL is enough to retrieve the data we are requesting in this tutorial.

Get the deal information

Before you can send a retrieval request, you need to collect some information to structure the command. You will need:

Miner IDThis is the ID of the storage provider where the data is stored.
Data CIDThis variable is also sometimes called the Payload CID.
AddressThe public address that was initially used to create the storage deal.

We’re going to gather this information now.

  1. Copy this address to your clipboard: f16wc2ees6nkmk4pguoaaly4zdkeemaajjbv7aqgq.

    If you want to retrieve data that you stored you can use that address in place of the one we’re using in this tutorial. If you’d like to use the address on your local Lotus note, run lotus wallet list and copy it to your clipboard.

    Remember, you will not be able to retrieve data stored less than 24 hours ago.

  2. Go to

  3. Paste the address in the search bar and press ENTER to search for deals made by that address: showing all the deals made by a single address.

    The default address supplied in this tutorial f16wc2ees... has only submitted one storage deal, so you’ll only see one row in If you are using a different address, you may see multiple rows. If you don’t see any rows, the address you searched for has not yet completed a deal. The address may have submitted a deal, but the storage provider is yet to seal the data. Deals will only show up here once the storage provider has completed sealing the data.

  4. Click anywhere on a row to view information about that specific deal:

    Information about a particular deal.

  5. Make a note of the Payload CID and the Miner ID. You’ll need both of these to create the retrieval command in the next step.

Send a retrieval request

Next up is creating the command for Lotus to run. The structure for a retrieval command is: lotus client retrieve --miner <MINER ID> <DATA CID> ~/output-file

  1. Using the template above, create the command substituting <MINER ID> and <DATA CID> with the variables you got in the previous step. Your command should look something like this:

    lotus client retrieve --miner f07709 mAVWg5AIgFw51hfKzfy8nRsKHlMtT8/DPBJhn1f9eFyOSeldlAiE output-file

    The output-file is the name of the file that you’d like to save. You can also add a path to this variable:

    lotus client retrieve --miner f0100 mAVW...lAiE ~/Downloads/filecoin-download.tar
  2. Run the command. After submitting this command, your Lotus lite-node will send the retrieval request to the storage provider and wait for a response:

    > Recv: 0 B, Paid 0 FIL, ClientEventOpen (DealStatusNew)
    > Recv: 0 B, Paid 0 FIL, ClientEventDealProposed (DealStatusWaitForAcceptance)
    > Recv: 0 B, Paid 0 FIL, ClientEventDealAccepted (DealStatusAccepted)
    > ...
  3. Wait for the process to finish:

    > Recv: 66.33 KiB, Paid 0.00000000000013584 FIL, ClientEventPaymentSent (DealStatusFinalizing)
    > Recv: 66.33 KiB, Paid 0.00000000000013584 FIL, ClientEventComplete (DealStatusFinalizingBlockstore)
    > Recv: 66.33 KiB, Paid 0.00000000000013584 FIL, ClientEventBlockstoreFinalized (DealStatusCompleted)

    You must keep the lotus daemon running for the duration of this process.

  4. That’s it!

This marks the end of the Filecoin Store and Retrieve tutorial! By now you should have a good understanding of how the storage and retrieval process works on the Filecoin network, and also have some ideas on how to integrate this process into your projects! Feel free to carry on playing around with storing and retrieving data using Lotus and Filecoin. If you need a hand or get stuck, check out the Filecoin Slack for help.

Edit this page on GitHub