Arxi Decision Gate Asset Core
Docs
Asset Core Docs

Deterministic world-state engine documentation and API references.

Decision Gate 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. It is the recommended path for teams who want strong type safety while staying aligned with the public HTTP contract.

Prerequisites

Make sure the daemons are running and that you have valid tokens for read and write access. The SDK does not bypass any authorization checks; it simply wraps the same HTTP endpoints.

  • Python 3.11+
  • Asset Core daemons running locally with bearer tokens available (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

import os
from assetcore_sdk import AssetCoreClient

write_client = AssetCoreClient(
    base_url="http://127.0.0.1:8080",
    api_key=os.environ["ASSETCORE_WRITE_TOKEN"],
)

read_client = AssetCoreClient(
    base_url="http://127.0.0.1:8081",
    api_key=os.environ["ASSETCORE_READ_TOKEN"],
)

The SDK is a pure HTTP client, so use separate instances for write and read tokens. This mirrors production deployments where write and read tokens have different roles.

Step 3 - Build operations

Use the typed operation builders:

from assetcore_sdk.operations import CreateContainer, AddFungible

operations = [
    CreateContainer(
        container_id=1001,
        kind={"type": "balance"},
        owner=None,
        policies=None,
    ),
    AddFungible(
        class_id=100,
        key=1,
        quantity=500,
        location={"container_id": 1001, "kind": "balance"},
    ),
]

Each builder produces a typed operation that the client converts into the JSON envelope. This makes it easier to catch invalid fields before they reach the daemon.

Step 4 - Send the commit

result = await write_client.commit_operations(
    operations,
    idempotency_key="sdk-first-commit-2026-01-15",
    namespace_id=5001,
)

print(f"Committed at world seq {result.world_seq_start}")

Or use the synchronous version:

result = write_client.commit_operations_sync(
    operations,
    idempotency_key="sdk-first-commit-2026-01-15",
    namespace_id=5001,
)

Step 5 - Read the state

container = await read_client.get_container_balances(1001, namespace_id=5001)

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

The response includes typed fields and freshness metadata. Use those freshness fields to confirm that your read path is caught up with the commit log.

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.HttpError with transport details.

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