Skip to content

Arete documentation

Python SDK

For the complete documentation index optimized for AI agents, see llms.txt or llms-full.txt. A markdown version of this page is available by appending .md to the URL or sending Accept: text/markdown.

For AI agents: the documentation index is at llms.txt (full corpus: llms-full.txt). A markdown source for this page is /sdks/python.md.

The Python SDK follows the same conceptual model as TypeScript and Rust: generated programs, generated stacks, typed account reads, live views, shared chain reads, local wallet signing, and application sessions.

The repository includes protocol clients and generation through a4 install protocol <package> --python. Select Python only when the exact package descriptor verifies it, and account for the publication status above. The generated README describes its imports, typed step methods, and rejection codes.

Clients expose instances, participants, wallet action discovery, metadata, events, intent tracking, and receipts. Use await client.actions(wallet) for wallet actions, one page at a time, and await client.instances_for_wallet(wallet, relation="creator") for every instance the wallet created, across pages (relation="role:<name>" for a role it holds; no relation for every related instance). Receipt helpers are verify_receipt and verify_receipt_on_chain. Preserve the prepared transactions when signing locally and track the existing execution after submission.

Protocol integration · Execution lifecycle · Protocol reference

From the repository checkout:

Terminal window
pip install -e ./python/arete-sdk

The base SDK supports Python 3.9+. The optional Solana adapter has its own Python and dependency requirements.

Use dependency-backed installation when the descriptor verifies Python:

Terminal window
a4 explore catalog program <slug> --json
a4 install program <slug> --python

For local artifact development, the lower-level SDK commands remain available. They do not replace arete.toml or arete.lock for normal project dependency management.

import os
import arete
from my_generated_stack import MY_STACK
async def main():
async with await arete.Arete.connect(
MY_STACK,
auth=arete.AuthConfig(secret_key=os.environ["ARETE_API_KEY"]),
) as client:
rows = await client.views.position.list.get(take=10)
async for update in client.views.position.list.watch(take=10):
print(update.op, update.key)
break

secret_key takes an agent key (a4_ak_...) or secret key (a4_sk_...) for servers, agents and local scripts. With no auth option set, the SDK uses ARETE_API_KEY if it is set, and otherwise the key from your a4 login, so a script on a machine logged in with a4 needs no key setup. Anything shipped to a browser uses an origin-bound publishable key (publishable_key) instead, created with a4 auth keys create-publishable --origin <scheme://host[:port]>.

Generated names depend on the installed stack. Inspect its package rather than copying identifiers from another example.

get() and get_one() open a subscription for the query (or reuse an equivalent active one), wait for its initial snapshot, and release it. A query that fails raises its error. So does a read cut short by the connection: a terminal connection failure raises AreteConnectionError with code CONNECTION_ERROR, and a disconnect raises code CONNECTION_CANCELLED. If no snapshot arrives within timeout seconds (5 by default), they raise InitialDataTimeoutError; pass timeout=None to wait indefinitely.

program = client.programs.my_program
account = await program.accounts.position.fetch(position_address)
pda, bump = program.pdas.position.derive(owner=owner)
instruction = program.raw.deposit.build(
owner=owner,
amount=1_000_000,
)

Raw builders are pure and can also be exposed as standalone generated helpers. Connected account readers use the exact Program Read descriptor.

prepared = await program.transactions.deposit.prepare(
owner=owner,
amount={"ui": "10.5"},
)
inspection = await client.inspect_operation(prepared)
receipt = await client.execute(prepared)

Wallets implement the SDK’s wallet-adapter protocol. Signing remains local. Execution preserves the same conservative outcomes as the other SDKs: confirmed, definitely not submitted, submitted with unknown outcome, or failed on chain.

clock = await client.chain.clock()
lamports = await client.chain.lamports(address)
accounts = await client.chain.accounts([address])
session = await arete.create_session(
stacks={"markets": MARKETS_STACK, "positions": POSITIONS_STACK},
programs={"token": SPL_TOKEN_PROGRAM},
auth=auth,
)
async for row in session.stacks.positions.views.position.list.use():
print(row)
break
await session.close()

Use Python for local development and verified generated targets, but confirm publication and compatibility requirements before choosing it for a production integration. The generated descriptor and install output take precedence over this overview.