Metadata-Version: 2.4
Name: axiom-stack
Version: 0.3.0
Summary: Verifiable on-chain attestations for AI agents — Solana-anchored equity + crypto data oracle.
Project-URL: Homepage, https://axiomstack.dev
Project-URL: Documentation, https://axiomstack.dev/developers/api
Project-URL: Repository, https://github.com/AxiomStack-Dev/axiom-stack-python
Project-URL: Issues, https://axiomstack.dev/dashboard/help
Project-URL: Changelog, https://github.com/AxiomStack-Dev/axiom-stack-python/blob/main/CHANGELOG.md
Author-email: Axiom Stack LLC <support@axiomstack.dev>
License: MIT
License-File: LICENSE
Keywords: ai-agent,attestation,axiom,crypto,equity,oracle,rwa,solana
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Requires-Dist: typing-extensions>=4.5; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: twine>=5.1; extra == 'dev'
Description-Content-Type: text/markdown

# 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](https://axiomstack.dev). One client, two surfaces — synchronous and async — with **typed exceptions** mapped 1:1 from the API's RFC 7807 error contract.

```python
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

```bash
pip install axiom-stack
```

Issue a key at [axiomstack.dev/dashboard/keys](https://axiomstack.dev/dashboard/keys) and:

```bash
export AXIOM_API_KEY="axm_live_…"
```

…or write a `~/.axiomrc.json`:

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

## 30-second terminal demo

```bash
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

```python
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

```python
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.

```python
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

```python
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

```python
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

```bash
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](https://axiomstack.dev/developers/api).
Machine-readable spec: [api.axiomstack.dev/v1/openapi.json](https://api.axiomstack.dev/v1/openapi.json).

## License

MIT © Axiom Stack LLC
