Skip to content
Oris Docs
Sign in Get API Key

Python SDK

oris-sdk 0.2.0 on PyPI

The Python SDK ships every Oris primitive under one package. Sync and async clients. Pydantic v2 models for every response. Ed25519 request signing built in. Cross-language parity with the TypeScript SDK on every method.

Install

Terminal window
pip install "oris-sdk==0.2.0"

Requires Python 3.10 or later. No system dependencies beyond pip.

Quickstart

import os
from oris import OrisClient


client = OrisClient(
    api_key=os.environ["ORIS_API_KEY"],
    private_key=os.environ["ORIS_PRIVATE_KEY"],
)


agent = client.agents.create(name="procurement-bot", description="...")
client.agents.promote(agent.id, target_level=1, attestation="kyb_dev")


result = client.payments.send(
    agent_id=agent.id,
    to_address="0xA1b2...",
    amount=12.50,
    chain="base-sepolia",
)


print(result.bundle_id, result.tx_hash)

Modules

ModulePurpose
orisTop-level package: OrisClient, resources, errors.
oris.protocolL8 verifier client, network adapters, offline verification.
oris.typesPydantic models for every request and response shape.
oris.errorsTyped exception hierarchy (OrisAuthError, OrisPolicyDeny, etc.).

Resource surface

Every API tag maps to a resource on OrisClient:

client.agents          # KYA + identity
client.wallets         # multi-chain wallet primitive
client.policies        # spending rules
client.payments        # send, status, refund
client.micropayments   # channel lifecycle
client.compliance      # screening, attestation
client.audit           # log verify + list
client.marketplace     # list, search, order, settle
client.treasury        # balances, refill, hierarchical budgets
client.provider_keys   # BYOK

Each resource exposes a uniform CRUD surface plus domain-specific methods. The full method reference is documented inline in the package; see oris-sdk on PyPI for the auto-generated docstrings.

Authentication

Every authenticated call signs:

{timestamp}.{nonce}.{METHOD}.{path}.{SHA256(body)}

with the developer’s Ed25519 private key. The SDK builds and signs this automatically. You only configure the API key and the private key.

client = OrisClient(
    api_key="oris_sk_live_...",
    private_key="oris_pk_live_...",
    # Optional
    base_url="https://api.useoris.xyz",
    timeout=30.0,
    max_retries=3,
)

Async client

from oris import AsyncOrisClient


async with AsyncOrisClient(api_key="...", private_key="...") as client:
    agent = await client.agents.create(name="async-bot", description="...")
    result = await client.payments.send(
        agent_id=agent.id, to_address="0xA1b2...", amount=12.50, chain="base-sepolia",
    )

Same method names, awaitable. Connection pooling via httpx.AsyncClient under the hood.

The protocol namespace

For anyone who consumes Oris bundles (a verifier, a network operator, an auditor) but does not produce them:

from oris.protocol import OrisProtocol


p = OrisProtocol(network="base-sepolia")


# 1. Fetch the live verifier pubkey
pubkey = p.verifier.get_pubkey()


# 2. Verify a compliance bundle
verdict = p.verifier.verify(
    bundle_bytes_hex=bundle_hex,
    tx_intent_hex=tx_intent_hex,
    signer_pubkey_hex=agent_pubkey_hex,
)


# 3. Verify the verdict's signature offline against the cached pubkey
ok = p.verifier.verify_response_signature(verdict, pubkey.pubkey_hex)

OrisProtocol does not require an API key. It is the read-side of the protocol.

Error hierarchy

from oris.errors import (
    OrisError,            # base
    OrisAuthError,        # 401 / signature invalid
    OrisRateLimitError,   # 429
    OrisPolicyDeny,       # policy engine rejected the payment
    OrisSanctionsError,   # sanctions hit on counterparty
    OrisRevocationError,  # tier 1 or tier 2 revocation
    OrisNetworkError,     # network adapter failed
)


try:
    client.payments.send(...)
except OrisPolicyDeny as e:
    print(e.rule, e.detail)
except OrisError as e:
    print(e)

All HTTP-level errors map to typed exceptions with the reason code from the verifier verdict.

Where to go next