Skip to main content

Keep Your Data Alive

The swarm comprises the sum total of all storage space provided by all of our nodes, called the DISC (Distributed Immutable Store of Chunks). The right to write data into this distributed store is determined by the postage stamps that have been attached.

Fund your node's wallet.#

To start up your node, you will already have provided your node with XDAI for gas and BZZ which was transferred into your chequebook when your node was initialised. This will be used to interact with other nodes using the SWAP protocol. In order to access more funds to buy batches of stamps, your wallet must be funded with BZZ. The easiest way to acheive this is to withdraw funds from your chequebook:

curl -XPOST "http://localhost:1635/chequebook/withdraw?amount=1000"

Purchase a Batch of Stamps#

Stamps are created in batches, so that storer nodes may calculate the validity of a chunk's stamp with only local knowledge. This enables the privacy you enjoy in the swarm.

Stamp batches are created in buckets with a depth 16. The entire swarm address space is divided into 2^16 = 65,536 different buckets. When uploaded, each of your file's are split into 4kb chunks and assigned to a specific bucket based on it's address.

When creating a batch you must specify two values, batch depth and amount.


The amount represents the quantity of BZZ that is assigned to this batch. The total amount of BZZ that will be paid for the batch is calulated from this figure and the batch depth.

The paid amount forms the balance of the batch. This balance is then slowly depleted as time ticks on and blocks are mined on the XDAI blockchain.

Batch Depth#

The batch depth determines how many chunks are allowed to be in each bucket. The number of chunks allowed in each bucket is calculated to be a 2^(batch depth - bucket depth) = 2^(batch depth - 16).

Calculating the Depth and Amount of Your Batch of Stamps#

Postage Stamps are a brand new feature addition to Swarm, and it's early days in the conception of how to get the best out of the stamp batches.

Right now, the easiest way to start uploading content, is to buy a large enough batch so that it is incredibly unlikely you will end up with too many chunks falling into the same bucket.

The amount you specify will determine the amount of time your chunks live in the swarm. Because pricing is variable, it is not possible to predict with accuracy exactly when your chunks will run out of balance, however, it can be estimated based on the current price and the remaining batch balance.

For now, we suggest you specify depth 20 and amount 10000000 for your batches. This should be ample to upload quite some data, and to keep your files in the swarm for the forseeable future.


When you purchase a batch of stamps, you agree to burn BZZ. Although your 'balance' slowly decrements as time goes on, there is no way to withdraw BZZ from a batch. This is an outcome of Swarm's decentralised design, to read more about how the swarm fits together, read The Book of Swarm .

curl -s -XPOST http://localhost:1635/stamps/10000000/20

Once your batch has been purchased, it will take a few minutes for other Bee nodes in the Swarm to catch up and register your batch. Allow some time for your batch to propagate in the network before proceeding to the next step.

Look out for more ways to more accurately estimate the correct size of your batch coming soon!

To check on your stamps, send a GET request to the stamp endpoint.

curl http://localhost:1635/stamps

When uploading content which has been stamped using an already expired postage stamp, the node will not attempt to sync the content. You are advised to use longer-lived postage stamps and encrypt your content to work around this. It is not possible to reupload unencrypted content which was stamped using an expired postage stamp. We're working on improving on this.

Calculating the Remaining TTL of Your Batch#


At present, TTL is a primitive calculation based on the current storage price and the assumption that storage price will remain static in the future. As more data is uploaded into Swarm, the price of storage will begin to increase. For data that it is important to keep alive, make sure your batches have plenty of time to live!

In order to make sure your batch has sufficient remaining balance to be stored and served by nodes in its neighbourhood of responsibility, you must regularly check on its time to live and act accordingly. The time to live is the number of seconds before the chunks will be considered for garbage collection by nodes in the network.

The remaining time to live in seconds is shown in the returned json object as the value for batchTTL.

curl "http://localhost:1635/stamps"
"stamps": [
"batchID": "6d32e6f1b724f8658830e51f8f57aa6029f82ee7a30e4fc0c1bfe23ab5632b27",
"utilization": 0,
"usable": true,
"label": "",
"depth": 20,
"amount": "113314620",
"bucketDepth": 16,
"blockNumber": 19727733,
"immutableFlag": false,
"exists": true,
"batchTTL": 68795140

Top Up Your Batch#


Don't let your batch run out! If it does, you will need to restamp and resync your content.

If your batch is starting to run out, or you would like to extend the life of your batch to protect against storage price rises, you can increase the batch TTL by topping up your batch using the stamps endpoint, passing in the relevant batchID into the HTTP PATCH request.

curl -X PATCH "http://localhost:1635/stamps/topup/6d32e6f1b724f8658830e51f8f57aa6029f82ee7a30e4fc0c1bfe23ab5632b27/10000000"