# Accumulate Python SDK

> Build on the Accumulate blockchain from Python. Package: `accumulate-sdk-opendlt` (v2.3.0).

## Install
```
pip install accumulate-sdk-opendlt
```
Import: `from accumulate_client import Accumulate, TxBody, SmartSigner, QuickStart`

## Canonical usage
Connect, build a transaction body with `TxBody`, then sign + submit + wait with `SmartSigner`. **1 ACME = 1e8 base units.**
```
client = QuickStart.kermit()   # or Accumulate.testnet()/mainnet()/devnet()
# body = TxBody.<operation>(...)
result = SmartSigner(signer).sign_submit_and_wait(principal, body)
```

## Rules
- **Amounts:** 1 ACME = 1e8 base units. Never pass whole ACME as-is; use the `Amount` helper.
- **Custom tokens have their OWN precision**, set when the token is created — it is not 1e8. Issuing `1000` against a precision-8 token mints `0.00001` tokens, not 1000, and the transaction succeeds either way. Convert with the token helper (`Amount.token(whole, precision)` / `Amount::token` / `Amount.Token`) rather than passing a raw number.
- **Testnet first:** target Kermit and fund lite accounts via the faucet before spending.
- **Prerequisites matter:** create an ADI, then buy credits for its key page before it can sign; wait for balances/credits to settle before the next step.
- **Errors are typed:** catch `AccumulateError` (`except AccumulateError as e:`) and branch on the code. The full catalog — every code, its `retryable` flag, and the fix — is the **Error catalog** section of `llms-full.txt`. **Retry ONLY `ACC_NETWORK_UNAVAILABLE` / `ACC_INTERNAL`;** every other code is a condition that will not change on its own, so retrying it just burns turns.
- **One canonical client:** connect with `Accumulate`, build with `TxBody`, sign with `SmartSigner`. Do not hand-roll envelopes/signing, and ignore any alternate or legacy client classes — this is the only path you need.

## CLI (no code required)
```
pip install accumulate-sdk-opendlt
accumulate query acc://<account>            # any account
accumulate balance acc://<lta>              # token balance
accumulate faucet acc://<lta>               # testnet ACME
```
Scoped invocation (no global shim): `python -m accumulate_client.cli`
- **`--json` emits exactly one envelope object on stdout**, nothing else. Logs go to stderr.
- **Exit codes:** `0` ok · `1` operation failed · `2` usage error · `3` network unreachable. Branch on these without parsing.
- Failures carry the same `ACC_*` codes and `retryable` flag as the SDK, so the retry decision is identical either way.
- `accumulate --help --json` returns the whole command tree (verbs, flags, types) in one call.
- Defaults to testnet. Mainnet needs `--network mainnet` AND `ACCUMULATE_ALLOW_MAINNET=1`.

## Resources
- Full API digest: `llms-full.txt`
- Repository guide (build/test/lint, for working ON this SDK): `AGENTS.md`
- Runnable end-to-end examples: `examples/v3/`
- 25 operations across 7 categories.

## Operations
- `generate_keys` — Generate Keys (utility)
- `faucet` — Faucet (utility)
- `wait_for_balance` — Wait For Balance (utility)
- `wait_for_credits` — Wait For Credits (utility)
- `add_credits` — Add Credits (credits)
- `create_identity` — Create Identity (identity)
- `create_key_book` — Create Key Book (identity)
- `create_key_page` — Create Key Page (identity)
- `create_token_account` — Create Token Account (account)
- `create_data_account` — Create Data Account (account)
- `create_token` — Create Token (account)
- `send_tokens` — Send Tokens (transaction)
- `issue_tokens` — Issue Tokens (transaction)
- `burn_tokens` — Burn Tokens (transaction)
- `write_data` — Write Data (transaction)
- `query_account` — Query Account (query)
- `update_key_page` — Update Key Page (authority)
- `update_key` — Update Key (authority)
- `create_lite_token_account` — Create Lite Token Account (account)
- `transfer_credits` — Transfer Credits (credits)
- `burn_credits` — Burn Credits (credits)
- `write_data_to` — Write Data To (transaction)
- `lock_account` — Lock Account (authority)
- `update_account_auth` — Update Account Auth (authority)
- `co_sign` — Co Sign (authority)
