@axiom-stack/sdk

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

@axiom-stack/sdk is the official TypeScript SDK for the Axiom Stack Oracle. Promise-only async, typed exceptions mapped 1:1 from the API's RFC 7807 error contract, dual ESM + CJS output, zero HTTP-client deps (native fetch, Node 18.3+).

import { AxiomClient } from "@axiom-stack/sdk";

const client = new AxiomClient();                            // reads AXIOM_API_KEY
const att = await client.attestInstant({ asset_class: 2, asset_id: "AAPL" });
console.log(att.data.price_micros, att.attestation_pda);     // 308820000  CuN2…

0.4.0 BREAKING: public field names + option keys are now snake_case across the SDK (asset_class, asset_id, api_key, request_id, tx_sig, etc.) to match the wire format + the Python SDK. Old camelCase aliases still work for one version with a console.warn deprecation notice. See CHANGELOG for the full rename map + set AXIOM_SDK_SILENCE_DEPRECATION=1 to silence.

Install

npm install @axiom-stack/sdk

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

export AXIOM_API_KEY="axm_live_…"

…or write ~/.axiomrc.json:

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

30-second terminal demo

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

Library quickstart

import { AxiomClient, newIdempotencyKey } from "@axiom-stack/sdk";

const client = new AxiomClient();

// Equity (live audit + instant)
const aapl = await client.attestInstant({ asset_class: 2, asset_id: "AAPL" });
console.log(aapl.data.price_micros, aapl.request_id);

// Crypto (whitelist: BTC, ETH, SOL, USDC, USDT; instant only in V1)
const btc = await client.attestInstant({ asset_class: 6, asset_id: "BTC" });

// Idempotent retry
const key = newIdempotencyKey();
const a = await client.attestInstant({ asset_class: 2, asset_id: "NVDA" }, { idempotency_key: key });
const b = await client.attestInstant({ asset_class: 2, asset_id: "NVDA" }, { idempotency_key: key });
console.assert(a.attestation_pda === b.attestation_pda);     // replay

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 — branch with instanceof.

import { AxiomClient, TierUnavailableForClass, InsufficientQuota } from "@axiom-stack/sdk";

const client = new AxiomClient();
try {
  await client.attestAudit({ asset_class: 6, asset_id: "BTC" });   // crypto audit not in V1
} catch (e) {
  if (e instanceof TierUnavailableForClass) {
    console.log("available tiers:", e.tiers_available);             // ['instant']
    // downgrade gracefully
    await client.attestInstant({ asset_class: 6, asset_id: "BTC" });
  }
}

try {
  await client.attestInstant({ asset_class: 2, asset_id: "AAPL" });
} catch (e) {
  if (e instanceof InsufficientQuota) {
    console.log(`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

const state = await client.fetchAttestation("CuN2LbSuw227fu2aHLpN6y7sbXun2DPNz6DjncRqJ9RW");
console.log(state.asset_id, state.asset_data.variant_type);    // "AAPL" "EquityData"
console.log(state.attestations.length, "writers");

Discover supported classes + tiers

const classes = await client.listAssetClasses();
for (const c of classes) {
  console.log(c.id, c.name, c.status, c.tiers_available);
}

Configuration precedence

| # | Source | Note | |---|---|---| | 1 | constructor arg (new AxiomClient({ apiKey })) | wins over all | | 2 | AXIOM_API_KEY env var | recommended for prod | | 3 | AXIOM_CONFIG env (path to JSON file) | flexible | | 4 | ~/.axiomrc.json (XDG-aware) | local dev default |

Same precedence applies to baseUrl (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.

Python SDK with the same surface: axiom-stack on PyPI.

License

MIT © Axiom Stack LLC