Metadata-Version: 2.4
Name: standards-sdk-py
Version: 0.1.8
Summary: Python SDK for Hedera standards and Registry Broker parity with TypeScript and Go SDKs.
Project-URL: Homepage, https://hol.org/docs/libraries/standards-sdk/
Project-URL: Documentation, https://hol.org/docs/libraries/standards-sdk/
Project-URL: Repository, https://github.com/hashgraph-online/standards-sdk-py
Project-URL: Issues, https://github.com/hashgraph-online/standards-sdk-py/issues
Project-URL: Changelog, https://github.com/hashgraph-online/standards-sdk-py/blob/main/CHANGELOG.md
Project-URL: Security, https://github.com/hashgraph-online/standards-sdk-py/security/policy
Project-URL: Standards, https://hol.org/docs/standards/
Project-URL: Registry Broker Docs, https://hol.org/registry/docs
Project-URL: CodeSandbox Examples, https://codesandbox.io/s/github/hashgraph-online/standards-sdk-py/tree/main/examples
Project-URL: Libraries, https://libraries.io/pypi/standards-sdk-py
Author: Hashgraph Online
Maintainer-email: Hashgraph Online <support@hol.org>
License: MIT
License-File: LICENSE
Keywords: ai-agents,hashgraph,hcs,hedera,inscriber,mirror-node,python-sdk,registry-broker
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: brotli<2.0.0,>=1.1.0
Requires-Dist: hedera-sdk-py<3.0.0,>=2.50.0
Requires-Dist: httpx<1.0.0,>=0.27.2
Requires-Dist: pydantic<3.0.0,>=2.10.0
Requires-Dist: typing-extensions<5.0.0,>=4.12.2
Provides-Extra: dev
Requires-Dist: bandit[toml]<2.0.0,>=1.7.10; extra == 'dev'
Requires-Dist: black<27.0.0,>=26.3.1; extra == 'dev'
Requires-Dist: mypy<2.0.0,>=1.13.0; extra == 'dev'
Requires-Dist: pip-audit<3.0.0,>=2.8.0; extra == 'dev'
Requires-Dist: pre-commit<5.0.0,>=4.0.1; extra == 'dev'
Requires-Dist: pytest-asyncio<0.25.0,>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov<7.0.0,>=6.0.0; extra == 'dev'
Requires-Dist: pytest<9.0.0,>=8.3.3; extra == 'dev'
Requires-Dist: ruff<0.9.0,>=0.8.0; extra == 'dev'
Requires-Dist: twine<7.0.0,>=6.0.1; extra == 'dev'
Description-Content-Type: text/markdown

# HOL HCS SDK (Python)

[![PyPI Version](https://img.shields.io/pypi/v/standards_sdk_py?logo=pypi&logoColor=white)](https://pypi.org/project/standards-sdk-py/)
[![Python Versions](https://img.shields.io/pypi/pyversions/standards_sdk_py)](https://pypi.org/project/standards-sdk-py/)
[![PyPI Downloads](https://img.shields.io/pypi/dm/standards-sdk-py)](https://pypistats.org/packages/standards-sdk-py)
[![Libraries.io Dependencies](https://img.shields.io/librariesio/release/pypi/standards-sdk-py)](https://libraries.io/pypi/standards-sdk-py)
[![piwheels](https://img.shields.io/piwheels/v/standards-sdk-py?logo=raspberrypi)](https://www.piwheels.org/project/standards-sdk-py/)
[![CI](https://github.com/hashgraph-online/standards-sdk-py/actions/workflows/ci.yml/badge.svg)](https://github.com/hashgraph-online/standards-sdk-py/actions/workflows/ci.yml)
[![Security](https://github.com/hashgraph-online/standards-sdk-py/actions/workflows/security.yml/badge.svg)](https://github.com/hashgraph-online/standards-sdk-py/actions/workflows/security.yml)
[![CodeQL](https://github.com/hashgraph-online/standards-sdk-py/actions/workflows/codeql.yml/badge.svg)](https://github.com/hashgraph-online/standards-sdk-py/actions/workflows/codeql.yml)
[![Publish](https://github.com/hashgraph-online/standards-sdk-py/actions/workflows/publish.yml/badge.svg)](https://github.com/hashgraph-online/standards-sdk-py/actions/workflows/publish.yml)
[![Conda Publish](https://github.com/hashgraph-online/standards-sdk-py/actions/workflows/conda-publish.yml/badge.svg)](https://github.com/hashgraph-online/standards-sdk-py/actions/workflows/conda-publish.yml)
[![Anaconda Version](https://img.shields.io/conda/vn/hashgraph-online/standards-sdk-py?logo=anaconda&label=Anaconda)](https://anaconda.org/hashgraph-online/standards-sdk-py)
[![Conda Downloads](https://img.shields.io/conda/dn/hashgraph-online/standards-sdk-py?logo=anaconda&label=Conda%20Downloads)](https://anaconda.org/hashgraph-online/standards-sdk-py)
[![License](https://img.shields.io/github/license/hashgraph-online/standards-sdk-py)](./LICENSE)
[![GitHub Stars](https://img.shields.io/github/stars/hashgraph-online/standards-sdk-py?style=social)](https://github.com/hashgraph-online/standards-sdk-py/stargazers)
[![CodeSandbox Examples](https://img.shields.io/badge/CodeSandbox-Examples-151515?logo=codesandbox&logoColor=white)](https://codesandbox.io/s/github/hashgraph-online/standards-sdk-py/tree/main/examples)
[![Typing: mypy](https://img.shields.io/badge/typing-mypy-blue.svg)](https://mypy.readthedocs.io/)
[![Code Style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Lint: ruff](https://img.shields.io/badge/lint-ruff-D7FF64.svg)](https://github.com/astral-sh/ruff)
[![HOL SDK Docs](https://img.shields.io/badge/%F0%9F%93%9A_SDK_Docs-hol.org-4A90D9)](https://hol.org/docs/libraries/standards-sdk/)
[![HCS Standards](https://img.shields.io/badge/%F0%9F%93%96_HCS_Standards-hol.org-8B5CF6)](https://hol.org/docs/standards)

| ![](./Hashgraph-Online.png) | Python reference implementation of the Hiero Consensus Specifications (HCS) and Registry Broker utilities with parity against the TypeScript and Go SDKs.<br><br>[📚 Standards SDK Documentation](https://hol.org/docs/libraries/standards-sdk/)<br>[📖 Hiero Consensus Specifications Documentation](https://hol.org/docs/standards) |
| :-------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

## Quick Start

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

## Install

```bash
pip install standards-sdk-py
```

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


## Multi-Language SDK Links

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

| Language | Package | Source | Canonical Documentation |
| :--- | :--- | :--- | :--- |
| TypeScript | `@hol-org/standards-sdk` | [hashgraph-online/standards-sdk](https://github.com/hashgraph-online/standards-sdk) | [https://hol.org/docs/libraries/standards-sdk/](https://hol.org/docs/libraries/standards-sdk/) |
| Go | `github.com/hashgraph-online/standards-sdk-go` | [hashgraph-online/standards-sdk-go](https://github.com/hashgraph-online/standards-sdk-go) | [https://hol.org/docs/libraries/go-sdk/overview](https://hol.org/docs/libraries/go-sdk/overview) |
| Python | `standards-sdk-py` | [hashgraph-online/standards-sdk-py](https://github.com/hashgraph-online/standards-sdk-py) | [https://hol.org/docs/libraries/python-sdk/overview](https://hol.org/docs/libraries/python-sdk/overview) |

## Developer Tooling

```bash
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](https://hol.org/docs/libraries/standards-sdk/)
- [HCS Standards Documentation](https://hol.org/docs/standards)
- [Libraries.io Package Page](https://libraries.io/pypi/standards-sdk-py)
- [piwheels Package Page](https://www.piwheels.org/project/standards-sdk-py/)

## Citation and Archival

- Citation metadata: [`CITATION.cff`](./CITATION.cff)
- Zenodo metadata: [`.zenodo.json`](./.zenodo.json)
- Software Heritage origin:
  <https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/hashgraph-online/standards-sdk-py>

## Supported Packages

| Package | Coverage |
| :--- | :--- |
| `standards_sdk_py.hcs2` | HCS-2 registry topic creation, indexed entry operations, memo helpers, mirror reads. |
| `standards_sdk_py.hcs3` | HCS-3 recursive file loading helpers. |
| `standards_sdk_py.hcs5` | HCS-5 hashinal inscription and minting helpers. |
| `standards_sdk_py.hcs6` | HCS-6 non-indexed registry creation, registration helpers, memo helpers. |
| `standards_sdk_py.hcs7` | HCS-7 indexed registry and metadata registration helpers. |
| `standards_sdk_py.hcs10` | HCS-10 topic/message builders and communication helpers. |
| `standards_sdk_py.hcs11` | HCS-11 profile models/builders, validation, inscription helpers. |
| `standards_sdk_py.hcs12` | HCS-12 action/assembly/hashlinks helpers. |
| `standards_sdk_py.hcs14` | HCS-14 UAID parsing and resolution helpers. |
| `standards_sdk_py.hcs15` | HCS-15 account creation and memo helpers. |
| `standards_sdk_py.hcs16` | HCS-16 flora account/topic/message helpers. |
| `standards_sdk_py.hcs17` | HCS-17 state-hash helpers. |
| `standards_sdk_py.hcs18` | HCS-18 discovery topic/message helpers. |
| `standards_sdk_py.hcs20` | HCS-20 points message and validation helpers. |
| `standards_sdk_py.hcs21` | HCS-21 adapter declaration helpers. |
| `standards_sdk_py.hcs26` | HCS-26 memo parser/resolver helpers. |
| `standards_sdk_py.hcs27` | HCS-27 checkpoint helpers. |
| `standards_sdk_py.inscriber` | Inscriber auth, quote, submit, and polling workflows. |
| `standards_sdk_py.registry_broker` | Full Registry Broker client (search, adapters, registries, credits, verification, chat/encryption, skills, ledger auth). |
| `standards_sdk_py.mirror` | Mirror node client used by standards and inscriber modules. |
| `standards_sdk_py.shared` | transport, config, network/operator helpers, and shared typing. |

## CodeSandbox Examples

- [Examples index](./examples/README.md)
- [standards-sdk-discovery](https://codesandbox.io/s/github/hashgraph-online/standards-sdk-py/tree/main/examples/standards-sdk-discovery)
- [hcs2-create-registry](https://codesandbox.io/s/github/hashgraph-online/standards-sdk-py/tree/main/examples/hcs2-create-registry)
- [hcs5-build-mint](https://codesandbox.io/s/github/hashgraph-online/standards-sdk-py/tree/main/examples/hcs5-build-mint)
- [hcs6-create-registry](https://codesandbox.io/s/github/hashgraph-online/standards-sdk-py/tree/main/examples/hcs6-create-registry)
- [hcs7-register-metadata](https://codesandbox.io/s/github/hashgraph-online/standards-sdk-py/tree/main/examples/hcs7-register-metadata)
- [hcs10-build-message](https://codesandbox.io/s/github/hashgraph-online/standards-sdk-py/tree/main/examples/hcs10-build-message)
- [hcs11-build-agent-profile](https://codesandbox.io/s/github/hashgraph-online/standards-sdk-py/tree/main/examples/hcs11-build-agent-profile)
- [hcs12-build-register](https://codesandbox.io/s/github/hashgraph-online/standards-sdk-py/tree/main/examples/hcs12-build-register)
- [hcs14-parse-uaid](https://codesandbox.io/s/github/hashgraph-online/standards-sdk-py/tree/main/examples/hcs14-parse-uaid)
- [hcs15-build-account-tx](https://codesandbox.io/s/github/hashgraph-online/standards-sdk-py/tree/main/examples/hcs15-build-account-tx)
- [hcs16-build-flora-topic-tx](https://codesandbox.io/s/github/hashgraph-online/standards-sdk-py/tree/main/examples/hcs16-build-flora-topic-tx)
- [hcs17-build-state-message](https://codesandbox.io/s/github/hashgraph-online/standards-sdk-py/tree/main/examples/hcs17-build-state-message)
- [hcs18-build-announce](https://codesandbox.io/s/github/hashgraph-online/standards-sdk-py/tree/main/examples/hcs18-build-announce)
- [hcs20-deploy-points](https://codesandbox.io/s/github/hashgraph-online/standards-sdk-py/tree/main/examples/hcs20-deploy-points)
- [hcs21-build-declaration](https://codesandbox.io/s/github/hashgraph-online/standards-sdk-py/tree/main/examples/hcs21-build-declaration)
- [hcs26-parse-memos](https://codesandbox.io/s/github/hashgraph-online/standards-sdk-py/tree/main/examples/hcs26-parse-memos)
- [hcs27-publish-checkpoint](https://codesandbox.io/s/github/hashgraph-online/standards-sdk-py/tree/main/examples/hcs27-publish-checkpoint)
- [inscriber-auth-client](https://codesandbox.io/s/github/hashgraph-online/standards-sdk-py/tree/main/examples/inscriber-auth-client)
- [mirror-topic-messages](https://codesandbox.io/s/github/hashgraph-online/standards-sdk-py/tree/main/examples/mirror-topic-messages)
- [registry-broker-skill-domain-proof](https://codesandbox.io/s/github/hashgraph-online/standards-sdk-py/tree/main/examples/registry-broker-skill-domain-proof)
- [registry-broker-uaid-dns-verification](https://codesandbox.io/s/github/hashgraph-online/standards-sdk-py/tree/main/examples/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:

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

Parity checks:

```bash
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:

```bash
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:

```bash
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](./SECURITY.md).

## Maintainers

Maintained by HOL.

## Resources

- [Hiero Consensus Specifications (HCS) Documentation](https://hol.org/docs/standards)
- [Hedera Documentation](https://docs.hedera.com)
- [Telegram Community](https://t.me/hashinals)

### 📝 Blog Tutorials

- [Building a Decentralized Registry with Go & HCS-2](https://hol.org/blog/building-decentralized-registry-go-hedara)
- [HCS-14: Profiles and Agent AID Resolution](https://hol.org/blog/hcs-14-profiles-and-agent-aid-resolution)
- [ERC-8004: Trustless Agent Registry](https://hol.org/blog/erc-8004-trustless-agent-registry)
- [Universal Agent Discovery with MCP](https://hol.org/blog/universal-agent-discovery-mcp)

## License

MIT
