axiom-stack 0.5.0

Verifiable on-chain attestations for AI agents — Solana-anchored equity + crypto data oracle.

axiom-stack

Verifiable on-chain attestations for AI agents — equity + crypto data oracle anchored on Solana.

axiom-stack is the official Python SDK for the Axiom Stack Oracle. One client, two surfaces — synchronous and async — with typed exceptions mapped 1:1 from the API's RFC 7807 error contract.

from axiom_stack import AxiomClient

client = AxiomClient()                                     # reads AXIOM_API_KEY
att = client.attest_instant(asset_class=2, asset_id="AAPL")
print(att.data.price_micros, att.attestation_pda)          # 308820000  CuN2…

Install

pip install axiom-stack

Issue a key at axiomstack.dev/dashboard/keys and:

export AXIOM_API_KEY="axm_live_…"

…or write a ~/.axiomrc.json:

{ "default": { "api_key": "axm_live_…" } }

30-second terminal demo

pip install axiom-stack
export AXIOM_API_KEY="axm_live_…"
axiom query BTC --crypto         # → JSON attestation, on-chain
axiom query AAPL --format table  # ASCII table

Library quickstart

from axiom_stack import AxiomClient

with AxiomClient() as client:
    # Equity (live audit + instant)
    aapl = client.attest_instant(asset_class=2, asset_id="AAPL")
    print(aapl.data.price_micros, aapl.request_id)

    # Crypto (whitelist: BTC, ETH, SOL, USDC, USDT; instant only in V1)
    btc = client.attest_instant(asset_class=6, asset_id="BTC")

    # Idempotent retry
    from axiom_stack import new_idempotency_key
    key = new_idempotency_key()
    nvda1 = client.attest_instant(asset_class=2, asset_id="NVDA", idempotency_key=key)
    nvda2 = client.attest_instant(asset_class=2, asset_id="NVDA", idempotency_key=key)  # replay
    assert nvda1.attestation_pda == nvda2.attestation_pda

Async

import asyncio
from axiom_stack import AsyncAxiomClient

async def main():
    async with AsyncAxiomClient() as client:
        att = await client.attest_instant(asset_class=2, asset_id="TSLA")
        print(att.data.price_micros)

asyncio.run(main())

Typed errors

Every error from the API is application/problem+json with a stable type URI at https://docs.axiomstack.dev/errors/<slug>. The SDK translates each URI into a specific exception class — write except TierUnavailableForClass: instead of parsing error strings.

from axiom_stack import AxiomClient, TierUnavailableForClass, InsufficientQuota

client = AxiomClient()
try:
    client.attest_audit(asset_class=6, asset_id="BTC")     # crypto audit not in V1
except TierUnavailableForClass as e:
    print("available tiers:", e.tiers_available)            # ['instant']
    # downgrade gracefully
    client.attest_instant(asset_class=6, asset_id="BTC")

try:
    client.attest_instant(asset_class=2, asset_id="AAPL")
except InsufficientQuota as e:
    print(f"retry in {e.retry_after_seconds}s; request_id={e.request_id}")

Full exception hierarchy: AxiomError → AxiomAPIError → Unauthorized / Forbidden / InvalidRequest / TierUnavailableForClass / NotFound / IdempotencyReplayMismatch / InsufficientQuota / ServiceUnavailable / InternalServerError. Plus AxiomConnectionError for transport-level failures.

Read an on-chain attestation by PDA

state = client.fetch_attestation("CuN2LbSuw227fu2aHLpN6y7sbXun2DPNz6DjncRqJ9RW")
print(state.asset_id, state.asset_data.variant_type)        # "AAPL" "EquityData"
print(len(state.attestations), "writers")

Discover supported classes + tiers

for c in client.list_asset_classes():
    print(c.id, c.name, c.status, c.tiers_available)

Configuration precedence

#	Source	Note
1	constructor arg (AxiomClient(api_key=…))	wins over all
2	AXIOM_API_KEY env var	recommended for prod
3	AXIOM_CONFIG env (path to JSON file)	flexible
4	~/.axiomrc.json	local dev default

The same precedence applies to base_url (env: AXIOM_BASE_URL). The base URL defaults to https://api.axiomstack.dev.

CLI reference

axiom query <asset_id> [--class equity|crypto|<int>] [--latency instant|audit]
                       [--format json|table] [--key <axm_live_…>] [--base-url URL]

# Shortcuts
axiom query AAPL                  # equity instant
axiom query BTC --crypto          # equivalent to --class crypto
axiom query AAPL --latency audit  # audit tier (equity only in V1)

API reference

Full OpenAPI 3.1 spec + endpoint reference: axiomstack.dev/developers/api. Machine-readable spec: api.axiomstack.dev/v1/openapi.json.

Publishing checklist (maintainers)

Pre-publish gates for python -m twine upload:

1. pytest — all unit + mocked tests green (real_api marker deselected by default).
2. pytest -m real_api — end-to-end roundtrip against api.axiomstack.dev with a live AXIOM_API_KEY. Required before bumping the version on PyPI.
3. python -m build — wheel + sdist build clean.
4. python -m twine check dist/* — PyPI metadata sanity.

Codified at G6.12 P5 from feedback_sdk_mocked_tests_dont_catch_type_drift (G6.11 SDK 0.3.0 publish — mocked tests missed a wire/SDK type drift; Mark caught it on the first real query against prod).

License

MIT © Axiom Stack LLC