What Is a Multiaddr? Peer IDs and Addresses in IPFS

A multiaddr is a network address that names every protocol it uses, in order. For example, /ip4/198.51.100.7/tcp/4001/p2p/<peer ID> reads as an IPv4 host, a TCP port, then the peer ID that must answer. IPFS uses this format wherever a node says where it lives.

TL;DR:

• The address part says where to dial; the /p2p/ part says who must answer, and a wrong key fails the connection
• A peer ID comes from the node's public key: Ed25519 IDs start with 12D3KooW, older RSA IDs with Qm
• /ipfs/ and /p2p/ before a peer ID are the same protocol (code 421); libp2p made /p2p/ the default spelling in late 2019
• On AIOZ Pin, multiaddrs appear in the Pinning Service API as origins and delegates

What is a multiaddr?

Multiaddr comes from the multiformats project and writes network addresses as a path of named parts. Its README lists what is wrong with host:port strings. They hide which protocol to use, don't compose for stacks like WebSockets over TLS over TCP, and address ports rather than processes.

A multiaddr fixes that by naming each layer, and you parse it left to right, starting with the outermost protocol. Every part is a valid multiaddr on its own, so /ip4/198.51.100.7 and /tcp/4001 combine into one TCP socket address.

There are two encodings: the text form is for people, while the binary form travels on the wire and swaps each name for a numeric protocol code. We encoded the Kubo docs' example address with a short Python script that follows the spec. The 79-character string /ip4/104.131.131.82/tcp/4001/p2p/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ became 45 bytes.

How do you read a multiaddr?

Read the names as a stack: each name tells you what the next value means, so you never guess whether a number is a port or a host. The parts you will meet most often in IPFS:

In Kubo's default listen list, TCP, QUIC and WebTransport all share port 4001, as in /ip4/0.0.0.0/udp/4001/quic-v1/webtransport. One port serves three transports because the layers above it differ, and our guide to IPFS transports explains why a node offers several at once.

The README also says each part is interpreted in the context of everything to its left. In /ip4/1.2.3.4/tcp/1234/tls/p2p/QmFoo, the /p2p value is passed to the TLS layer as the peer ID it must see. If the remote key doesn't match, the connection fails, even when the IP and port are right.

What is a peer ID in IPFS?

A peer ID is the name a node proves with its private key, and libp2p builds it from the node's encoded public key. Keys that encode to 42 bytes or fewer, such as Ed25519, go in whole as an "identity" multihash, while larger keys such as RSA are hashed with SHA-256 first.

That rule explains the two prefixes you see: RSA peer IDs start with Qm, and Ed25519 peer IDs start with 12D3KooW. Kubo has created Ed25519 keys by default since go-ipfs 0.7.0 (September 2020), and its ipfs init help still says Default: ed25519. Because an Ed25519 peer ID contains the whole public key, you can check that node's signatures with nothing but the ID.

We converted the spec's Ed25519 example into its CIDv1 forms (codec libp2p-key) with the same script:

base58btc   12D3KooWD3eckifWpRn9wQpMG9R9hX3sD158z7EqHWmweQAJU5SA
base36      k51qzi5uqu5dhdmyb9bd18pypu2wp5lpv2xnskfmrqa4lb5knqryrotb05e7or
base32      bafzaajaiaejcal72gwuz2or47oyxxn6b3rkwdmmkrxgkjxzy3rqt5kczyn7lcm3l

All three name the same key, and you will recognize the k51... form from IPNS names, which are keys too. It is not a content CID, though, because the codec marks it as a key rather than data.

Your peer ID stays put while your addresses change: move your laptop from home Wi-Fi to an office network and it keeps its ID but gets new multiaddrs.

/ipfs/ or /p2p/: one protocol, two names

Older guides write peer addresses as /ipfs/QmFoo, the protocol's first name from before libp2p split out of IPFS. In November 2019 the libp2p team announced that tools would print /p2p/QmFoo by default and treat /ipfs as deprecated. Both names map to protocol code 421, so the binary form never changed and neither did the network.

go-ipfs 0.6.0 (June 2020) rewrote the bootstrap list in existing configs to the /p2p/ spelling, and only go-ipfs releases before 0.4.16 can't parse it. Don't confuse any of this with /ipfs/<CID> paths on gateways, which name content rather than peers.

dnsaddr, relay and certhash addresses

Some multiaddrs need a lookup first: a /dnsaddr address tells the node to read TXT records at _dnsaddr.<domain>, and each record holds a full multiaddr. That differs from DNSLink, which stores a content path in TXT records. We ran the lookup for one default bootstrap entry on October 28, 2026:

$ dig +short TXT _dnsaddr.am6.bootstrap.libp2p.io
"dnsaddr=/dns4/lith-1.bootstrap.ipni.io/tcp/4001/p2p/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb"
"dnsaddr=/dns4/lith-1.bootstrap.ipni.io/tcp/4443/wss/p2p/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb"
"dnsaddr=/dns4/lith-1.bootstrap.ipni.io/udp/4001/quic-v1/p2p/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb"

The libp2p addressing spec shows this name pointing at am6.bootstrap.libp2p.io hosts, but today it points at an ipni.io host with the same peer ID. Hosts can move while the identity holds, and our bootstrap nodes guide covers what those peers do.

Relay addresses carry two peer IDs, the relay's and then the target's after /p2p-circuit, which helps peers behind NAT (see the IPFS node types guide). Browser transports add /certhash/ so a browser can trust a self-signed certificate. For the Kubo example peer, the delegated routing endpoint at delegated-ipfs.dev returned 8 addresses to us, including webrtc-direct/certhash ones.

Working with multiaddrs in Kubo

These commands come from the Kubo CLI reference (kubo 0.43.1); we have no IPFS binary on this machine, so they were not run:

ipfs id -f="<addrs>\n"              # your announced addresses
ipfs swarm addrs local --id          # listen addresses plus peer ID
ipfs swarm peers                     # one multiaddr per peer
ipfs swarm connect /ip4/104.131.131.82/tcp/4001/p2p/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ
ipfs swarm peering add <multiaddr>   # always stay connected

Two config keys decide what other peers learn about you: Addresses.Announce replaces the addresses your node advertises, and Addresses.NoAnnounce strips addresses or /ipcidr/ ranges. The server profile fills NoAnnounce with private ranges, so you don't advertise LAN addresses.

How AIOZ Pin handles it

Multiaddrs reach AIOZ Pin through the Pinning Service API, which we serve at https://api.aiozpin.network/api/psa/. In the spec, a pin request may carry origins, up to 20 multiaddrs of peers that already hold the data. The reply may carry delegates, 1 to 20 multiaddrs of the service's own peers that will receive it.

Each entry must end with /p2p/ and a peer ID and should be dialable from the public internet, with the DHT as the fallback when dials fail. In the usual pattern, your node lists its own addresses in origins and connects to each delegate, so the transfer starts without a DHT search. These are the commands our docs give for Kubo (not run):

ipfs pin remote service add pin https://api.aiozpin.network/api/psa/ YOUR_AUTH_JWT
ipfs pin remote add --service=pin --name=<human-readable-name> YOUR_CID
ipfs pin remote ls --service=pin --status=queued,pinning,failed

What the docs don't cover yet: whether our PSA endpoint reads origins or returns delegates. Our native pinByHash call takes only hash_to_pin and metadata, so a pin by CID there relies on the service finding providers itself.

Next step: get a token and add the service to Kubo with the AIOZ Pin Pinning Services API docs.

Frequently Asked Questions

Is a multiaddr the same as a URL?
No. A URL fixes one scheme, host and port layout, while a multiaddr can stack any number of protocols.

Does every multiaddr include a peer ID?
No. /ip4/198.51.100.7/tcp/4001 is valid without one, but add /p2p/ and the peer ID when you want the connection to check who answers.

Can a node's peer ID change?
Only when its key changes: Kubo won't start if the configured peer ID doesn't match the key, and ipfs key rotate is the documented way to switch.

Is a peer ID a CID?
You can write it as one with the libp2p-key codec, but it names a public key, not a file.

Does Ethereum use multiaddr?
It did: ethereum.org calls multiaddr the original Ethereum node address format, now replaced by Ethereum Node Records (ENRs).

Related Reading

• libp2p: The Networking Layer Underneath IPFS: the stack that uses these addresses
• IPFS Bootstrap Nodes: the first peers a new node dials
• Delegated Routing: peer lookups over HTTP
• IPFS Pinning Service API: where origins and delegates live

References

• multiaddr README and protocol table
• libp2p addressing spec
• libp2p peer ID spec
• Kubo CLI reference and Kubo config docs
• IPFS forum: /ipfs to /p2p format change (2019)
• go-ipfs 0.7.0 and go-ipfs 0.6.0 release posts
• Pinning Service API spec
• ethereum.org: network addresses
• AIOZ Pin Pinning Services API docs