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.mdto the URL or sendingAccept: 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.
Protocol clients
Section titled “Protocol clients”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
Install for development
Section titled “Install for development”From the repository checkout:
pip install -e ./python/arete-sdkThe base SDK supports Python 3.9+. The optional Solana adapter has its own Python and dependency requirements.
Generate a target
Section titled “Generate a target”Use dependency-backed installation when the descriptor verifies Python:
a4 explore catalog program <slug> --jsona4 install program <slug> --pythonFor local artifact development, the lower-level SDK commands remain available.
They do not replace arete.toml or arete.lock for normal project dependency
management.
Connect to a generated stack
Section titled “Connect to a generated stack”import os
import aretefrom 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) breaksecret_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 reads and builders
Section titled “Program reads and builders”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.
Operations and execution
Section titled “Operations and execution”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.
Generic chain reads
Section titled “Generic chain reads”clock = await client.chain.clock()lamports = await client.chain.lamports(address)accounts = await client.chain.accounts([address])Multi-stack sessions
Section titled “Multi-stack sessions”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()Current recommendation
Section titled “Current recommendation”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.