swarm-bee 0.5.0

Python client for the Swarm Bee API. Functional parity with bee-js / bee-go / bee-rs.

bee-py

Python client for the Swarm Bee API. Async-first (httpx), Python 3.10+, fully type-checked (mypy --strict).

The functional target is parity with bee-js (canonical TypeScript client), bee-go (typed Go port), and bee-rs (Rust port). bee-go is the primary reference for shape and behavior; bee-js is the source of truth for wire-format edge cases.

Status: alpha (0.3.0). Primitives + bytes / chunk / SOC / bzz upload + download + postage CRUD + offline Stamper against API 8.0.0. See the roadmap below for what comes next.

Install

pip install swarm-bee
# or
uv add swarm-bee

The PyPI distribution name is swarm-bee (the natural bee-py was blocked by PyPI's typosquat protection — too close to the unrelated beepy project). The GitHub repo is still ethswarm-tools/bee-py to match the bee-go / bee-rs sibling naming, and the import name is bee:

from bee import Bee, AsyncBee

Quick start (async)

import asyncio
from bee import AsyncBee

async def main() -> None:
    async with AsyncBee("http://localhost:1633") as client:
        health = await client.debug.health()
        print(f"bee {health.version} api {health.api_version}")

asyncio.run(main())

Quick start (sync)

from bee import Bee

with Bee("http://localhost:1633") as client:
    health = client.debug.health()
    print(f"bee {health.version} api {health.api_version}")

Both clients share the same surface — Bee wraps AsyncBee with httpx.Client instead of httpx.AsyncClient. Choose whichever fits your codebase.

Layout

Module	bee-go counterpart	Scope
bee.swarm	pkg/swarm	Typed bytes, BMT, SOC, BZZ/DAI, Duration, Size, errs
bee.api	pkg/api	Upload/download options, pin, tag, grantee, envelope
bee.file	pkg/file	Data/file/chunk/SOC/feed/collection uploads
bee.postage	pkg/postage	Batch CRUD, pure stamp math
bee.debug	pkg/debug	Health, versions, accounting, chequebook, stake
bee.pss	pkg/pss	PSS send/subscribe/receive (websocket)
bee.gsoc	pkg/gsoc	GSOC send/subscribe + offline SOC address
bee.manifest	pkg/manifest	Mantaray trie, v0.2 wire format, ResourceLocator
bee.storage	bee-js only	High-level buy_storage / extend_storage_*
bee.dev	bee-js only	BeeDev newtype around Bee

Stack

• httpx (async + sync HTTP), websockets for live subscriptions (TBD)
• coincurve (libsecp256k1 C bindings) for ECDSA — same C-bindings perf story as bee-rs v1.2.0
• eth-hash[pycryptodome] for keccak256
• Standard-library dataclasses, enum, tarfile for structured payloads — no pydantic dependency

Bee version compatibility

This client targets Bee 2.7.2-rc1 / API 8.0.0 (the values pinned in bee.debug.SUPPORTED_BEE_VERSION_EXACT and bee.debug.SUPPORTED_API_VERSION). At startup, prefer client.debug.is_supported_api_version() for a major-compatible check or client.debug.is_supported_exact_version() for a strict pin. Older or newer Bee instances usually work — unknown response fields are ignored — but new endpoints will return 404 and breaking wire-format changes will surface as BeeJsonError.

Roadmap

Milestone	Scope
0.1.x	Primitives (typed bytes, BMT, SOC), client plumbing, debug.health/versions ✅
0.2.x	Bytes / file upload + download (CAC, SOC, plain reference) ✅
0.3.x	Postage batches, stamp math, Stamper ✅
0.4.x	Mantaray manifest, collection upload/download, ResourceLocator
0.5.x	Feeds, GSOC, PSS
0.6.x	Full bee.api (pin, tag, grantee, envelope, stewardship)
0.7.x	bee.debug (accounting, chequebook, stake, transactions, topology)
1.0.0	Functional parity with bee-js / bee-go / bee-rs at API 8.0.0

Development

bee-py is uv-managed. Install uv once:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then in this repo:

uv sync                    # create venv + install deps
uv run pytest              # run tests
uv run ruff check          # lint
uv run ruff format --check # format check
uv run mypy                # type check

License

MIT — see LICENSE.