# How to Convert Swarm Hashes to Content Identifiers (CIDs) Using the Swarm CID Converter

> Easily convert Swarm hashes to Content Identifiers CIDs and back with the Swarm CID Converter. Enable seamless interoperability between Swarm and IPFS ecosystems. Learn how today.

- Repository: [Ethersphere/awesome-swarm](https://github.com/ethersphere/awesome-swarm)
- Tags: how-to-guide
- Published: 2026-03-01

---

**TLDR:** The Swarm CID Converter is a lightweight Node.js utility that translates Swarm hashes (bzz:/…) into standard IPFS Content Identifiers (CIDs) and back, enabling seamless interoperability between the Swarm and IPFS ecosystems.

While Swarm stores data using its native addressing scheme (the Swarm hash), modern decentralized applications commonly rely on the IPFS Content Identifier (CID) format. The **Swarm CID Converter**, referenced in the `ethersphere/awesome-swarm` repository, bridges this gap by providing bidirectional translation between these addressing systems. This standalone tool parses Swarm's multihash format and constructs CID v1 strings using the appropriate multicodec and multibase encodings.

## What Is the Swarm CID Converter?

The **Swarm CID Converter** is a lightweight utility that understands both Swarm and CID encoding rules, enabling developers to convert Swarm hashes or links to CID format and vice versa. According to the `awesome-swarm` source code, the tool is listed in [`README.md`](https://github.com/ethersphere/awesome-swarm/blob/main/README.md) at line 66 with the description: *"Convert Swarm hashes or links to CID and vice versa"*.

The converter performs three core operations:

- **Swarm hash parsing** – Recognizes raw multihash formats used by Swarm (`bzz:/…` or `bzz-raw:/…`) and extracts the underlying SHA-256 digest.
- **CID construction** – Builds a CID v1 using the extracted digest, selecting the appropriate multicodec (`ethash` for Swarm) and multibase (`base58btc` or `base32`).
- **Reverse conversion** – Re-creates original Swarm URLs from CIDs that were derived from Swarm hashes, allowing seamless round-tripping between ecosystems.

The tool is maintained in its own repository at `agazso/swarm-cid-converter` and does not form part of the `awesome-swarm` source code itself.

## Installation and Setup

Because the conversion logic is pure data transformation, the tool runs on any platform with a recent Node.js runtime. You can also compile it to a tiny WebAssembly module for browser usage.

Install the CLI globally using npm:

```bash
npm install -g swarm-cid-converter

```

## Converting Swarm Hashes to CIDs

To **convert a Swarm hash to a CID**, use the `to-cid` command followed by the Swarm URL or hash:

```bash
swarm-cid-converter to-cid bzz:/b5d5f0c9...

```

This command takes a Swarm hash (such as `bzz:/…`) and prints a CID v1 string (such as `bafy...`).

For programmatic use in Node.js applications, import the `toCid` function from the library:

```javascript
const { toCid } = require('swarm-cid-converter');

const cid = toCid('bzz:/...');
console.log(cid);

```

## Converting CIDs Back to Swarm Hashes

The converter also supports **reverse conversion** from CIDs back to Swarm URLs using the `to-swarm` command:

```bash
swarm-cid-converter to-swarm bafy2bz...

```

This decodes the CID, restores the original Swarm multihash, and outputs a Swarm URL (`bzz:/…`).

In JavaScript, use the `toSwarm` function:

```javascript
const { toSwarm } = require('swarm-cid-converter');

const swarmUrl = toSwarm('bafy...');
console.log(swarmUrl);

```

## Batch Processing Multiple Hashes

To process multiple hashes efficiently, you can pipe a file of Swarm hashes through the converter using standard Unix utilities:

```bash
cat hashes.txt | xargs -n1 swarm-cid-converter to-cid

```

This batch-converts each line in [`hashes.txt`](https://github.com/ethersphere/awesome-swarm/blob/main/hashes.txt) to its corresponding CID representation.

## Technical Implementation Details

The Swarm CID Converter implements industry-standard multiformat specifications to ensure compatibility. When converting Swarm hashes to CIDs, the tool:

1. Extracts the SHA-256 digest from the Swarm multihash
2. Constructs a CID v1 with the `ethash` multicodec (indicating Swarm content)
3. Encodes the result using `base58btc` or `base32` multibase

This approach ensures that the resulting CIDs are valid IPFS Content Identifiers that reference the same underlying content as the original Swarm hashes.

## Summary

- The **Swarm CID Converter** enables bidirectional conversion between Swarm hashes and IPFS Content Identifiers (CIDs).
- The tool is listed in `ethersphere/awesome-swarm` at [`README.md`](https://github.com/ethersphere/awesome-swarm/blob/main/README.md) line 66 and maintained separately at `agazso/swarm-cid-converter`.
- Use `swarm-cid-converter to-cid` or the `toCid()` function to convert Swarm hashes to CIDs.
- Use `swarm-cid-converter to-swarm` or the `toSwarm()` function for reverse conversion.
- The converter supports CID v1 with the `ethash` multicodec and works as both a CLI tool and a Node.js library.

## Frequently Asked Questions

### What is the difference between a Swarm hash and a CID?

A **Swarm hash** uses Swarm's native multihash format (typically prefixed with `bzz:/` or `bzz-raw:/`) to address content in the Swarm decentralized storage network. A **CID** (Content Identifier) is the addressing format used by IPFS and other systems in the multiformat ecosystem. While both represent cryptographic hashes of content, they use different encoding schemes and multicodec identifiers.

### Can I use the Swarm CID Converter in a browser?

Yes. Although the primary distribution is a Node.js CLI tool and library, the conversion logic is pure data transformation that can be compiled to a tiny WebAssembly module for browser usage. You can also use the JavaScript library directly in browser environments with appropriate bundling.

### Where can I find the source code for the Swarm CID Converter?

The source code is maintained in the `agazso/swarm-cid-converter` repository on GitHub. While the `ethersphere/awesome-swarm` repository lists and describes the tool in its [`README.md`](https://github.com/ethersphere/awesome-swarm/blob/main/README.md) file, the actual implementation resides in the separate converter repository.

### Is the conversion between Swarm hashes and CIDs lossless?

Yes. The conversion is **lossless and bidirectional**. The tool extracts the underlying SHA-256 digest from Swarm hashes and repackages it as a CID v1 using the `ethash` multicodec. Because no data is discarded during this transformation, you can convert a Swarm hash to a CID and back to the original Swarm URL without data loss.