Docs

Using the Python SDK

This guide shows how to achieve the same outcome as the HTTP quickstart using the Asset Core Python SDK with typed operations.

Prerequisites

  • Python 3.11+
  • Asset Core daemons running locally (see First Commit and Read)
  • pip or uv for package installation

Step 1 - Install the SDK

From the Asset Core repository root:

cd sdk-python
pip install -e .

Or with uv:

uv venv --seed .venv-sdk
source .venv-sdk/bin/activate
cd sdk-python
uv pip install -e .

Step 2 - Create the client

from assetcore_sdk import AssetCoreClient

client = AssetCoreClient(
    write_url="http://127.0.0.1:8080",
    read_url="http://127.0.0.1:8081"
)

The client handles connection pooling and retry logic for you.

Step 3 - Build operations

Use the typed operation builders:

from assetcore_sdk.operations import (
    create_container,
    add_fungible
)

operations = [
    create_container(
        container_id=1001,
        kind="Standard"
    ),
    add_fungible(
        container_id=1001,
        class_id=100,
        key=1,
        quantity=500
    )
]

Each function returns a dictionary matching the JSON operation format.

Step 4 - Send the commit

result = await client.commit(
    operations=operations,
    idempotency_key="sdk-first-commit"
)

print(f"Committed at sequence {result.global_seq}")

Or use the synchronous version:

result = client.commit_sync(
    operations=operations,
    idempotency_key="sdk-first-commit"
)

Step 5 - Read the state

container = await client.get_container_balances(1001)

for balance in container.balances:
    print(f"Class {balance.class_id}: {balance.quantity}")

The response includes typed fields and freshness metadata.

Troubleshooting

”ModuleNotFoundError: assetcore_sdk”

The SDK isn’t installed in your current environment. Ensure you activated the correct virtual environment and ran pip install -e . from the sdk-python directory.

Connection errors

The daemons aren’t running or are on different ports. The SDK raises assetcore_sdk.errors.ConnectionError with details about which daemon failed.

Validation errors

Invalid operation arguments raise assetcore_sdk.errors.ValidationError with the specific field that failed. Check the operation reference for required fields.

Next steps