HOL HCS SDK (Python)

	Python reference implementation of the Hiero Consensus Specifications (HCS) and Registry Broker utilities with parity against the TypeScript and Go SDKs. 📚 Standards SDK Documentation 📖 Hiero Consensus Specifications Documentation

Quick Start

cd standards-sdk-py
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest -q

Install

pip install standards-sdk-py

conda install -c hashgraph-online standards-sdk-py

Multi-Language SDK Links

Canonical SDK docs URL: https://hol.org/docs/libraries/standards-sdk/

Developer Tooling

cd standards-sdk-py
.venv/bin/pre-commit install
.venv/bin/pre-commit run --all-files

Documentation

For standards and API documentation:

• Standards SDK Documentation
• HCS Standards Documentation
• Libraries.io Package Page
• piwheels Package Page

Citation and Archival

• Citation metadata: CITATION.cff
• Zenodo metadata: .zenodo.json
• Software Heritage origin: https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/hashgraph-online/standards-sdk-py

Supported Packages

CodeSandbox Examples

• Examples index
• standards-sdk-discovery
• registry-broker-free-tier-registration
• hcs2-create-registry
• hcs5-build-mint
• hcs6-create-registry
• hcs7-register-metadata
• hcs10-build-message
• hcs11-build-agent-profile
• hcs12-build-register
• hcs14-parse-uaid
• hcs15-build-account-tx
• hcs16-build-flora-topic-tx
• hcs17-build-state-message
• hcs18-build-announce
• hcs20-deploy-points
• hcs21-build-declaration
• hcs26-parse-memos
• hcs27-publish-checkpoint
• inscriber-auth-client
• mirror-topic-messages
• registry-broker-skill-domain-proof
• registry-broker-uaid-dns-verification

Environment Variables

Common:

• HEDERA_NETWORK
• HEDERA_ACCOUNT_ID or HEDERA_OPERATOR_ID
• HEDERA_PRIVATE_KEY or HEDERA_OPERATOR_KEY

Network-scoped overrides:

• TESTNET_HEDERA_ACCOUNT_ID
• TESTNET_HEDERA_PRIVATE_KEY
• MAINNET_HEDERA_ACCOUNT_ID
• MAINNET_HEDERA_PRIVATE_KEY

Registry Broker:

• REGISTRY_BROKER_BASE_URL
• REGISTRY_BROKER_API_KEY
• REGISTRY_BROKER_LEDGER_API_KEY

Inscriber integration:

• RUN_INTEGRATION=1
• RUN_INSCRIBER_INTEGRATION=1

Tests

Unit and contract tests:

cd standards-sdk-py
.venv/bin/pytest -q

Parity checks:

cd standards-sdk-py
.venv/bin/standards-sdk-py-generate-inventory --repo-root ..
.venv/bin/standards-sdk-py-check-parity

Live testnet inscriber end-to-end:

cd standards-sdk-py
cp ../standards-sdk/.env ./.env
pip install hedera-sdk-py
set -a
source <(grep -E '^[A-Za-z_][A-Za-z0-9_]*=' ./.env)
set +a
export RUN_INTEGRATION=1
export RUN_INSCRIBER_INTEGRATION=1
.venv/bin/pytest -m integration -k inscriber_registry_broker_end_to_end_testnet -vv -rs

Live testnet HCS-2 end-to-end:

cd standards-sdk-py
export RUN_INTEGRATION=1
export RUN_HCS2_INTEGRATION=1
export HEDERA_NETWORK=testnet
export TESTNET_HEDERA_ACCOUNT_ID="<your-testnet-account-id>"
export TESTNET_HEDERA_PRIVATE_KEY="<your-testnet-private-key>"
.venv/bin/pytest -m integration -k hcs2_end_to_end_testnet -vv -rs

Notes:

• Set HEDERA_NETWORK=testnet (and do not set a conflicting INSCRIBER_HEDERA_NETWORK).
• The test uses ledger challenge auth from your testnet credentials to avoid accidentally using a mainnet-scoped API key.

CI/CD and Security

• Python matrix CI (3.11, 3.12, 3.13) for ruff, black, mypy, unit tests, parity checks, and package validation.
• Security workflows for dependency review, pip-audit, Bandit SARIF upload, CodeQL, and verified TruffleHog secret scanning.
• Release workflow for build + twine check, TestPyPI/PyPI trusted publishing, checksum artifacts, provenance attestations, and GitHub release notes.
• Conda workflow for building packages and uploading to anaconda.org/hashgraph-online when ANACONDA_API_TOKEN is configured.
• Release indexing automation verifies PyPI + Libraries.io pages and submits a Software Heritage save request.

Contributing

Open issues or pull requests in the repository:

• https://github.com/hashgraph-online/standards-sdk-py/issues

Security

For disclosure and response policy, see SECURITY.md.

Maintainers

Maintained by HOL.

Resources

• Hiero Consensus Specifications (HCS) Documentation
• Hedera Documentation
• Telegram Community

📝 Blog Tutorials

• Building a Decentralized Registry with Go & HCS-2
• HCS-14: Profiles and Agent AID Resolution
• ERC-8004: Trustless Agent Registry
• Universal Agent Discovery with MCP

License

MIT