SDK Overview

This page serves as a complete reference to all publicly available classes, methods, types, and utilities provided by the bee-js SDK. After getting started, this is the place to explore everything you can do with bee-js and revisit whenever you need a reminder of how a function works or what a type represents.

The two packages

bee-js is split across two packages:

Package	Contents
@ethersphere/bee-js	The Bee client and everything that talks to a Bee node over HTTP.
@ethersphere/core-sdk	The Swarm primitives with no network access: byte wrappers, chunks, Mantaray, erasure coding, encryption and stamp signing.

Everything core-sdk exports that you are likely to need is re-exported by bee-js, so a single import is usually enough:

import { Bee, Bytes, PrivateKey, Reference, Topic } from '@ethersphere/bee-js'

Install core-sdk directly when you want the primitives without the HTTP client, for example when hashing or signing chunks in a worker or on a server that never contacts a Bee node:

npm install @ethersphere/core-sdk

Namespaces

Operations on the Bee class are grouped into namespaces by subject. Instead of one flat list of methods, you reach bee.data.upload(...), bee.stamp.getAll(...), bee.feed.makeWriter(...) and so on.

Namespace	Purpose
bee.data	Raw data uploads and downloads, backed by /bytes.
bee.file	Single-file uploads and downloads, backed by /bzz.
bee.collection	Multi-file (directory) uploads, backed by /bzz.
bee.chunk	Individual chunk uploads and downloads, backed by /chunks.
bee.feed	Feed readers, writers and manifests.
bee.rollingFeed	Rolling feed readers and writers.
bee.soc	Single owner chunk readers and writers.
bee.messaging	PSS and GSOC messaging.
bee.stamp	Postage batches expressed in amount and depth.
bee.storage	Postage batches expressed in size and duration.
bee.tag	Tags for tracking upload progress.
bee.pin	Local pinning and reuploading.
bee.grantee	Access control (ACT) grantee lists.
bee.stake	Staking and the redistribution game.
bee.status	Node health, version, chain and reserve state.
bee.connectivity	Peers, topology and node addresses.
bee.wallet	Node wallet balances and external withdrawals.
bee.chequebook	Chequebook address, balance, deposits and withdrawals.
bee.cheque	Cheques and cashouts.
bee.balance	SWAP balances with peers.
bee.settlement	SWAP settlements with peers.
bee.transaction	The node's pending transaction queue.

A handful of methods stay directly on bee because they do not belong to any one subject: makeContentAddressedChunk, unmarshalContentAddressedChunk, makeSingleOwnerChunk, unmarshalSingleOwnerChunk, calculateSingleOwnerChunkAddress, createEnvelope and rchash.

Migrating from v12 or earlier

Earlier versions exposed every method directly on bee, for example bee.uploadData and bee.getAllPostageBatch. Those are now bee.data.upload and bee.stamp.getAll. A codemod ships with the library and rewrites the call sites for you. See Migrating from v12 to v13 for the full mapping and the other breaking changes.

Type interfaces

NumberString is a branded type for marking strings that represent numbers. It interops with string and bigint types. Where NumberString is present, number is disallowed in order to avoid pitfalls with unsafe large values.

Byte primitives

All the classes below extend Bytes, therefore the following methods are available on all of them: toUint8Array, toHex, toBase64, toBase32, toUtf8, parsePayloadAsJson, static keccak256, static fromUtf8.

The toString method uses toHex.

Bytes and its subclasses may be constructed with new from Uint8Array or hex string.

Elliptic

Name	Description	Methods
PrivateKey	32 bytes private key	publicKey, sign
PublicKey	64 bytes public key	address, toCompressedUint8Array, toCompressedHex
EthAddress	20 bytes Ethereum address	toChecksum
Signature	65 bytes signature	recoverPublicKey

Swarm

Name	Description	Methods
Reference	32/64 bytes reference (chunk, feed)	toCid
Identifier	32 bytes identifier (SOC, Feed)	-
TransactionId	32 bytes transaction ID	-
FeedIndex	8 bytes feed index (BE)	static fromBigInt, toBigInt
Topic	32 bytes topic	static fromString
PeerAddress	32 bytes peer address	-
BatchId	32 bytes batch ID	-
Span	8 bytes span (LE)	static fromBigInt, toBigInt

Tokens

Name	Description	Construction	Conversion	Arithmetic and comparison
DAI	ERC20 DAI token (18 digits)	static fromDecimalString, static fromWei, static fromFloat	toWeiString, toWeiBigInt, toDecimalString, toFloat, toSignificantDigits, exchangeToBZZ	plus, minus, divide, gt, gte, lt, lte, eq
BZZ	ERC20 BZZ token (16 digits)	static fromDecimalString, static fromPLUR, static fromFloat	toPLURString, toPLURBigInt, toDecimalString, toFloat, toSignificantDigits, exchangeToDAI	plus, minus, divide, gt, gte, lt, lte, eq

Both are created through static factories, so they are called without new: BZZ.fromDecimalString('1'). Instances are immutable, and the arithmetic methods return a new instance rather than mutating the receiver.

Units

Name	Description	Methods
Size	A size in bytes	static fromBytes, static fromKilobytes, static fromMegabytes, static fromGigabytes, static parseFromString, toBytes, toGigabytes, toFormattedString
Duration	A span of time	static fromSeconds, static fromHours, static fromDays, static fromWeeks, static fromYears, static fromEndDate, static parseFromString, toSeconds, toHours, toDays

Both use 1000 rather than 1024 as the base for unit conversions, matching the Swarm papers on theoretical and effective storage capacity.

Swarm chunks

Name	Description	Creation
Chunk	Span, max. 4096 bytes payload; address derived from content	makeContentAddressedChunk
SingleOwnerChunk	Identifier, signature, span, max. 4096 bytes payload; address derived from identifier and owner	makeSingleOwnerChunk

Swarm primitives

Name	Description	Methods
MantarayNode	Compact trie with reference values and JSON metadata	addFork, removeFork, calculateSelfAddress, find, findClosest, collect, marshal, unmarshal, saveRecursively, loadRecursively
ChunkSplitter	Streaming BMT that turns a byte stream into chunks	append, finalize, static root, static encryptedRoot
ChunkBuilder	A single chunk under construction	build, hash, encryptedHash
ChunkJoiner	Reassembles a chunk tree back into bytes	join, static collect, static collectEncrypted
Stamper	Signs postage stamps locally	stamp, getState, static fromBlank, static fromState

MerkleTree was renamed

MerkleTree is now ChunkSplitter, and ChunkBuilder.hash() returns a Reference rather than a Uint8Array. The codemod handles both changes.

Swarm objects

Name	Description	Creation
SOCWriter	SingleOwnerChunk writer	bee.soc.makeWriter
SOCReader	SingleOwnerChunk reader	bee.soc.makeReader
FeedWriter	Feed writer	bee.feed.makeWriter
FeedReader	Feed reader	bee.feed.makeReader

Bee API

Every bee-js method that talks to a node is listed below with the endpoint it calls and the least capable node type that can serve it. The tables are grouped by namespace. Most methods call a single endpoint; the few that compose several list each one. Methods that run entirely locally are listed at the end. Refer to the Bee API specifications for the details of each endpoint.

The node mode column reads as a minimum, so a more capable node also serves the endpoint:

• Ultra-light — any node, whether ultra-light, light or full.
• Light — a light node or a full node.
• Full — a full node only.

bee.data

Method	Bee endpoint	Node mode
data.upload	POST /bytes 🔗	Light
data.download	GET /bytes/:reference 🔗	Ultra-light
data.downloadReadable	GET /bytes/:reference 🔗	Ultra-light
data.probe	HEAD /bytes/:reference 🔗	Ultra-light
data.isRetrievable	GET /stewardship/:reference 🔗	Ultra-light

bee.file

Method	Bee endpoint	Node mode
file.upload	POST /bzz 🔗	Light
file.download	GET /bzz/:reference 🔗	Ultra-light
file.download with path	GET /bzz/:reference/:path 🔗	Ultra-light
file.downloadReadable	GET /bzz/:reference 🔗	Ultra-light

bee.collection

Method	Bee endpoint	Node mode
collection.upload	POST /bzz 🔗	Light
collection.uploadFromDirectory Node.js	POST /bzz 🔗	Light
collection.uploadFromFileList Browser	POST /bzz 🔗	Light
collection.streamFromDirectory Node.js	POST /chunks 🔗	Light
collection.stream Browser	POST /chunks 🔗	Light

bee.chunk

Method	Bee endpoint	Node mode
chunk.upload	POST /chunks 🔗	Light
chunk.download	GET /chunks/:reference 🔗	Ultra-light

bee.feed

Method	Bee endpoint	Node mode
feed.createManifest	POST /feeds/:owner/:topic 🔗	Light
FeedReader.downloadReference / downloadPayload	GET /feeds/:owner/:topic 🔗	Ultra-light
FeedWriter.uploadReference / uploadPayload	POST /soc/:owner/:identifier 🔗	Light
feed.fetchLatestUpdate	GET /feeds/:owner/:topic 🔗	Ultra-light
feed.isRetrievable	GET /feeds/:owner/:topic 🔗, or GET /chunks/:reference 🔗 once per index when given an index	Ultra-light

bee.rollingFeed

Method	Bee endpoint	Node mode
RollingFeedReader.downloadReference / downloadPayload	GET /feeds/:owner/:topic 🔗	Ultra-light
RollingFeedWriter.uploadReference / uploadPayload	POST /soc/:owner/:identifier 🔗	Light
RollingFeedWriter.isCaughtUp	GET /feeds/:owner/:topic 🔗	Ultra-light
RollingFeedWriter.catchUp	GET /feeds/:owner/:topic 🔗, GET /chunks/:reference 🔗 and POST /soc/:owner/:identifier 🔗	Light

bee.soc

Method	Bee endpoint	Node mode
SOCWriter.upload	POST /soc/:owner/:identifier 🔗	Light
SOCReader.download	GET /chunks/:reference 🔗	Ultra-light

bee.messaging

Method	Bee endpoint	Node mode
messaging.pssSend	POST /pss/send/:topic/:target 🔗	Light
messaging.pssSubscribe Websocket	GET /pss/subscribe/:topic 🔗	Full
messaging.pssReceive	GET /pss/subscribe/:topic 🔗	Full
messaging.gsocSend	POST /soc/:owner/:identifier 🔗	Light
messaging.gsocSubscribe Websocket	GET /gsoc/subscribe/:address	Full

bee.stamp

Method	Bee endpoint	Node mode
stamp.create	POST /stamps/:amount/:depth 🔗	Light
stamp.get	GET /stamps/:batchId 🔗	Light
stamp.getAll	GET /stamps 🔗	Light
stamp.getBuckets	GET /stamps/:batchId/buckets 🔗	Light
stamp.getGlobal	GET /batches/:batchId 🔗	Light
stamp.getAllGlobal	GET /batches 🔗	Light
stamp.topUp	PATCH /stamps/topup/:batchId/:amount 🔗	Light
stamp.dilute	PATCH /stamps/dilute/:batchId/:depth 🔗	Light
stamp.updateLabel	PATCH /stamps/:batchId 🔗	Light
stamp.calculateTopUpForBZZ	GET /chainstate 🔗	Light

stamp.create also reads GET /chainstate to check the amount against the current price, and then polls GET /stamps/:batchId until the batch is usable, unless you pass waitForUsable: false.

bee.storage

bee.storage is the size and duration view of bee.stamp, so every method here also reads GET /chainstate to convert a Size and Duration into the depth and amount the endpoints below take. storage.extend and storage.extendSize call the top-up endpoint, the dilute endpoint, or both, depending on whether the duration, the size, or both have to grow.

Method	Bee endpoint	Node mode
storage.getCost	GET /chainstate 🔗	Light
storage.buy	POST /stamps/:amount/:depth 🔗	Light
storage.extend	PATCH /stamps/topup/:batchId/:amount 🔗, PATCH /stamps/dilute/:batchId/:depth 🔗	Light
storage.extendSize	PATCH /stamps/topup/:batchId/:amount 🔗, PATCH /stamps/dilute/:batchId/:depth 🔗	Light
storage.extendDuration	PATCH /stamps/topup/:batchId/:amount 🔗	Light
storage.getExtensionCost	GET /stamps/:batchId 🔗	Light
storage.getSizeExtensionCost	GET /stamps/:batchId 🔗	Light
storage.getDurationExtensionCost	GET /stamps/:batchId 🔗	Light
storage.rename	PATCH /stamps/:batchId 🔗	Light

bee.tag

Method	Bee endpoint	Node mode
tag.create	POST /tags 🔗	Light
tag.get	GET /tags/:id 🔗	Light
tag.getAll	GET /tags 🔗	Light
tag.update	PATCH /tags/:id 🔗	Light
tag.delete	DELETE /tags/:id 🔗	Light

bee.pin

Method	Bee endpoint	Node mode
pin.add	POST /pins/:reference 🔗	Ultra-light
pin.get	GET /pins/:reference 🔗	Ultra-light
pin.getAll	GET /pins 🔗	Ultra-light
pin.remove	DELETE /pins/:reference 🔗	Ultra-light
pin.reuploadData	PUT /stewardship/:reference 🔗	Light

bee.grantee

Method	Bee endpoint	Node mode
grantee.create	POST /grantee 🔗	Light
grantee.get	GET /grantee/:reference 🔗	Light
grantee.patch	PATCH /grantee/:reference 🔗	Light

bee.stake

Method	Bee endpoint	Node mode
stake.deposit	POST /stake 🔗	Full
stake.get	GET /stake 🔗	Full
stake.getMinimumDeposit	GET /stake 🔗	Full
stake.getWithdrawable	GET /stake/withdrawable 🔗	Full
stake.withdrawSurplus	DELETE /stake/withdrawable 🔗	Full
stake.migrate	DELETE /stake 🔗	Full
stake.getRedistributionState	GET /redistributionstate 🔗	Full
stake.setRedistributionEnabled	PATCH /redistributionstate	Full

bee.status

Method	Bee endpoint	Node mode
status.getHealth	GET /health 🔗	Ultra-light
status.getReadiness	GET /readiness 🔗	Ultra-light
status.getNodeInfo	GET /node 🔗	Ultra-light
status.get	GET /status 🔗	Ultra-light
status.getChainState	GET /chainstate 🔗	Light
status.getReserveState	GET /reservestate 🔗	Full
status.getVersions	GET /health 🔗	Ultra-light
status.isSupportedApiVersion	GET /health 🔗	Ultra-light
status.isSupportedExactVersion	GET /health 🔗	Ultra-light

bee.connectivity

Method	Bee endpoint	Node mode
connectivity.isConnected	GET /	Ultra-light
connectivity.checkConnection	GET /	Ultra-light
connectivity.isGateway	GET /gateway	Ultra-light
connectivity.getNodeAddresses	GET /addresses 🔗	Ultra-light
connectivity.getPeers	GET /peers 🔗	Ultra-light
connectivity.getBlocklist	GET /blocklist 🔗	Ultra-light
connectivity.removePeer	DELETE /peers/:peer 🔗	Ultra-light
connectivity.ping	POST /pingpong/:peer 🔗	Ultra-light
connectivity.getTopology	GET /topology 🔗	Ultra-light

GET /gateway is not part of the Bee API specification. Some gateway tooling exposes it, and connectivity.isGateway returns false on any node that does not.

bee.wallet

Method	Bee endpoint	Node mode
wallet.getBalance	GET /wallet 🔗	Light
wallet.withdrawBZZ	POST /wallet/withdraw/bzz 🔗	Light
wallet.withdrawDAI	POST /wallet/withdraw/nativetoken 🔗	Light

bee.chequebook

Method	Bee endpoint	Node mode
chequebook.getAddress	GET /chequebook/address 🔗	Light
chequebook.getBalance	GET /chequebook/balance 🔗	Light
chequebook.deposit	POST /chequebook/deposit 🔗	Light
chequebook.withdraw	POST /chequebook/withdraw 🔗	Light

bee.cheque

Method	Bee endpoint	Node mode
cheque.getAllLatest	GET /chequebook/cheque 🔗	Light
cheque.getAllLatestForPeer	GET /chequebook/cheque/:peer 🔗	Light
cheque.getLastCashoutAction	GET /chequebook/cashout/:peer 🔗	Light
cheque.cashoutLast	POST /chequebook/cashout/:peer 🔗	Light

bee.balance

Method	Bee endpoint	Node mode
balance.getAll	GET /balances 🔗	Light
balance.getPeer	GET /balances/:peer 🔗	Light
balance.getAllPastDueConsumption	GET /consumed 🔗	Light
balance.getAllPastDueConsumptionForPeer	GET /consumed/:peer 🔗	Light

bee.settlement

Method	Bee endpoint	Node mode
settlement.getAll	GET /settlements 🔗	Light
settlement.get	GET /settlements/:peer 🔗	Light

bee.transaction

Method	Bee endpoint	Node mode
transaction.getAll	GET /transactions 🔗	Light
transaction.get	GET /transactions/:id 🔗	Light
transaction.rebroadcast	POST /transactions/:id 🔗	Light
transaction.cancel	DELETE /transactions/:id 🔗	Light

Directly on bee

Method	Bee endpoint	Node mode
createEnvelope	POST /envelope/:reference 🔗	Light
rchash	GET /rchash/:depth/:anchor1/:anchor2 🔗	Full

Methods that make no request

The remaining public methods run entirely locally, so no endpoint or node mode applies to them:

Method	What it does
bee.makeContentAddressedChunk	Builds a content addressed chunk from a payload.
bee.unmarshalContentAddressedChunk	Parses raw bytes back into a content addressed chunk.
bee.makeSingleOwnerChunk	Signs a content addressed chunk into a single owner chunk.
bee.unmarshalSingleOwnerChunk	Parses raw bytes back into a single owner chunk.
bee.calculateSingleOwnerChunkAddress	Derives a SOC address from an identifier and an owner.
collection.hashDirectory	Hashes a local directory to get its Swarm reference without uploading it.
feed.makeReader / feed.makeWriter	Construct the FeedReader and FeedWriter whose own methods are listed above.
soc.makeReader / soc.makeWriter	Construct the SOCReader and SOCWriter whose own methods are listed above.
messaging.gsocMine	Mines the signer whose SOC address falls into the target node's neighborhood.

The Utils namespace below is local as well.

Utils

Utilities are exposed under the Utils namespace: import { Utils } from '@ethersphere/bee-js'.

General

• getCollectionSize
• getFolderSize
• makeCollectionFromFileList

PSS

• makeMaxTarget

Erasure Coding

• approximateOverheadForRedundancyLevel
• getRedundancyStat
• getRedundancyStats

Stamps

• getAmountForDuration
• getDepthForSize
• getStampCost
• getStampDuration
• getStampEffectiveBytes
• getStampEffectiveBytesBreakpoints
• getStampTheoreticalBytes
• getStampUsage
• convertEnvelopeToMarshaledStamp
• mapPostageBatch
• unmapPostageBatch