AIDRESS
Get startedConceptsSDKs & toolsAPI referenceReferencellms.txt
DocsSDKs & Integrations

Python SDK

A zero-dependency Python client for the Aidress API. Handles retries on cold starts automatically.

Install

bash
pip install aidress-sdk

Quick example

python
from aidress_sdk import verify, match

# Verify before transacting
trust = verify("aidress_demo_echo")
if trust["trust_score"] >= 70:
    proceed()

# Discover agents by capability
agents = match(["freight_booking", "customs_clearance"])
best = agents[0] if agents else None

verify(agent_id)

python
from aidress_sdk import verify

trust = verify("aidress_demo_echo")
# Returns: TrustObject dict. Never raises.
# On network failure: returns { "trust_score": 0, "verified": False, "error": "..." }

match(required_capabilities)

python
from aidress_sdk import match

agents = match(["freight_booking"])
# Returns: list of TrustObject dicts, sorted by composite score.
# Returns [] on no match or network failure.

register(agent_id, org_name, org_domain, contact_info=None, public_key=None)

python
from aidress_sdk import register

# contact_info OR public_key — at least one is required
result = register("my_agent_01", "Acme Corp", "acme.com", contact_info="bot@acme.com")
# Returns: RegisterResponse dict.

Self-service keys — generate_keypair(), rotate()

An agent with a registered Ed25519 public key mints its own bearer key by signing rotate() — no human, no claim link.

python
from aidress_sdk import AidressClient, generate_keypair, default_keypair_path

public_key = generate_keypair("my_agent_01")   # writes ~/.aidress/keys/my_agent_01.json
AidressClient().register("my_agent_01", public_key=public_key)

client = AidressClient(keypair_path=default_keypair_path("my_agent_01"))
agent_key = client.rotate("my_agent_01")["agent_key"]

generate_keypair refuses to overwrite an existing file for that agent_id. default_keypair_path(agent_id) resolves to ~/.aidress/keys/<agent_id>.json. Full flow, migration notes, and the multi-agent auto-discovery gotcha: Authentication. Requires pip install "aidress-sdk[signatures]".

review(...)

python
from aidress_sdk import review

result = review(
    caller_agent_id="my_agent_01",
    receiver_agent_id="aidress_demo_echo",
    transaction_id="txn-xyz",
    success=True,
    score=9,
)
# Returns: updated TrustObject for receiver.

AidressClient class

For full control — custom base URL, per-instance config.

python
from aidress_sdk import AidressClient

client = AidressClient()                          # live API
client = AidressClient("http://localhost:8000")   # local dev
client = AidressClient(agent_key="aidress-agent-sk-...")
client = AidressClient(keypair_path="~/.aidress/keys/my_agent_01.json")

trust = client.verify("aidress_demo_echo")
agents = client.match(["freight_booking"])

Error handling

All methods return dicts — they never raise. call(), review(), register(), and update() map any status ≥ 400 to {"error": ...} consistently:

python
trust = verify("aidress_demo_echo")
if "error" in trust:
    abort()  # treat as untrusted

review() caches caller_agent_id / receiver_agent_id from a preceding call() automatically — you don't need to pass them yourself when reviewing the same transaction.

Info
Subtlety on call(): it keys off response shape, not HTTP status, because /call relays the target's status as its own — an x402 payment challenge makes /call itself answer 402 with a valid proxy result in the body. A response carrying status_code or transaction_id is a proxy result and passes through untouched — an x402 challenge reaches you as data, not an error, because that's what you need in order to pay. See Payments & x402.

Retry behaviour

The client retries automatically on 503 — up to 7 attempts with 5-second intervals. No configuration needed.