{ "openapi": "3.1.0", "info": { "title": "Axiom Stack Oracle API", "summary": "Verifiable on-chain attestations for AI agents \u2014 equity + crypto.", "description": "The Axiom Oracle delivers institutional-grade market data attestations\nwritten to Solana on every request \u2014 agents query with curl + a Bearer\ntoken and receive **`{data, meta}`** envelopes with on-chain proof\n(`attestation_pda` + `write_tx_sig`).\n\n## Tiers (V1)\n\n| Class | Name | Tiers Live | `asset_id` |\n|-------|-----------|--------------------------------------|---------------------------------------------|\n| 2 | Equity | `instant` + `audit` | Ticker, e.g. `AAPL`, `TSLA` |\n| 6 | Crypto | `instant` only (audit \u2192 G6.7b) | Symbol \u2014 `BTC`, `ETH`, `SOL`, `USDC`, `USDT` |\n\nOther classes appear in `/v1/assets/classes` as `coming_soon`.\n\n## Idempotency\nSend an `Idempotency-Key: ` header on POSTs to make the\nrequest safely retryable. The server caches the response for 24h and\nreplays it byte-for-byte on the same key. Reusing the key with a\n*different* request body returns `422 idempotency-replay-mismatch`.\n\n## Rate limits\nEach response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`,\n`X-RateLimit-Reset`, and `RateLimit-Policy` (draft-ratelimit-headers).\n`429 insufficient-quota` includes `Retry-After`.\n\n## Request IDs\nEvery response echoes an `X-Request-ID` (`req_<26-char-base32>`); the\nsame id appears in `meta.request_id` and in every error envelope's\n`request_id`. Include it in support requests.\n\n## Errors\nAll errors are RFC 7807 `application/problem+json` with stable `type`\nURIs at `https://docs.axiomstack.dev/errors/` \u2014 pattern-match on\nthe URI, not on prose.\n", "version": "g6.8.0", "contact": { "name": "Axiom Stack Support", "url": "https://axiomstack.dev/dashboard/help" }, "license": { "name": "Commercial", "url": "https://axiomstack.dev/terms" } }, "servers": [ { "url": "https://api.axiomstack.dev/v1", "description": "Production (Solana devnet program; live data)" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "attestation", "description": "Request + retrieve on-chain attestations." }, { "name": "catalog", "description": "Discovery \u2014 supported asset classes + tiers." }, { "name": "ops", "description": "Operational endpoints (health, version)." } ], "paths": { "/health": { "get": { "operationId": "getHealth", "tags": [ "ops" ], "summary": "Service health + deployed version", "description": "Open endpoint (no auth). Use this to verify the API is reachable\nand to discover the deployed release version + timestamp.\n", "security": [], "responses": { "200": { "description": "Service is healthy.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthEnvelope" } } } } } } }, "/assets/classes": { "get": { "operationId": "listAssetClasses", "tags": [ "catalog" ], "summary": "List supported asset classes and which tiers are live per class", "description": "Open endpoint (no auth). Returns the taxonomy + per-class tier\navailability so agents can program against capability, not hardcoded\nids. `status` is `\"live\"` / `\"coming_soon\"`; `tiers_available`\nis the subset of `[\"instant\", \"audit\"]` that works today.\n", "security": [], "responses": { "200": { "description": "Catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClassCatalogEnvelope" } } } } } } }, "/attestation/instant": { "post": { "operationId": "requestInstantAttestation", "tags": [ "attestation" ], "summary": "Request an instant-tier attestation (<2s data + provisional proof)", "description": "Fetches the data, **submits the on-chain attestation** as a\nregistered provider, and returns the data + provisional proof\n(`attestation_pda` + `write_tx_sig`) in under 2s. The audit\nrecord commits asynchronously (typically within ~30s) \u2014 poll\n`GET /v1/attestation/{pda}` to confirm finalization. Quota debits\non data delivery; a failed async commit does not double-charge.\n", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/XRequestIDIn" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttestationRequest" }, "examples": { "equity": { "summary": "Equity (AAPL)", "value": { "asset_class": 2, "asset_id": "AAPL" } }, "crypto": { "summary": "Crypto (BTC)", "value": { "asset_class": 6, "asset_id": "BTC" } } } } } }, "responses": { "200": { "description": "Instant attestation.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstantEnvelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/IdempotencyReplayMismatch" }, "429": { "$ref": "#/components/responses/InsufficientQuota" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/attestation/audit": { "post": { "operationId": "requestAuditAttestation", "tags": [ "attestation" ], "summary": "Request an audit-tier attestation (~20s synchronous, fully on-chain)", "description": "Synchronous, fully on-chain (~20s end-to-end). Quota debits on\ncommit success.\n\n**V1 scope:** equity only. Requesting `asset_class: 6` (crypto)\nreturns `400 tier-unavailable-for-class` with `tiers_available`\nand a pointer to the next release (G6.7b). Agents should pattern-\nmatch on the `type` URI rather than retrying.\n", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/XRequestIDIn" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttestationRequest" }, "examples": { "equity_audit": { "summary": "Equity audit (AAPL)", "value": { "asset_class": 2, "asset_id": "AAPL" } } } } } }, "responses": { "200": { "description": "Audit attestation (finalized on-chain).", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditEnvelope" } } } }, "400": { "$ref": "#/components/responses/TierUnavailableOrBadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/IdempotencyReplayMismatch" }, "429": { "$ref": "#/components/responses/InsufficientQuota" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/attestation/{pda}": { "get": { "operationId": "fetchAttestationByPDA", "tags": [ "attestation" ], "summary": "Fetch the on-chain attestation record by PDA", "description": "Read-only. Decodes the `AssetStateV2` PDA owned by the Axiom\nprogram and returns the typed `asset_data` variant + the\nattestation chain + the latest snapshot hash. Useful to poll\nfinalization of an instant-tier write, or to verify an audit\nrecord after the fact.\n\nDoes **not** consume quota.\n", "parameters": [ { "in": "path", "name": "pda", "required": true, "schema": { "type": "string", "minLength": 32, "maxLength": 44 }, "description": "Base58 Solana address of the AssetStateV2 PDA." }, { "$ref": "#/components/parameters/XRequestIDIn" } ], "responses": { "200": { "description": "Decoded AssetStateV2.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetStateEnvelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "axm_live_\u2026", "description": "Issue a key in the dashboard (`https://axiomstack.dev/dashboard/keys`).\nTreat it as a password \u2014 never embed in client-side code or check it\ninto source control.\n" } }, "parameters": { "IdempotencyKey": { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Client-chosen unique key (UUID recommended) \u2014 makes the request\nsafely retryable. Server caches the response 24h; the same key\nwith a *different* body returns `422`.\n" }, "XRequestIDIn": { "in": "header", "name": "X-Request-ID", "required": false, "schema": { "type": "string", "pattern": "^req_[a-z0-9]{1,40}$" }, "description": "Optional client-supplied request id (honored if present, else server\nmints `req_<26-char-base32>`). Echoed in `meta.request_id` and in the\n`X-Request-ID` response header.\n" } }, "headers": { "XRequestID": { "schema": { "type": "string", "pattern": "^req_[a-z0-9]{26}$" }, "description": "Server-echoed (or minted) request id." }, "XRateLimitLimit": { "schema": { "type": "integer", "minimum": 0 }, "description": "Period quota for the caller's tier (monthly included)." }, "XRateLimitRemaining": { "schema": { "type": "integer", "minimum": 0 }, "description": "Available attestations now (included_remaining + prepaid)." }, "XRateLimitReset": { "schema": { "type": "integer", "format": "int64" }, "description": "Unix seconds at which the included bucket resets." }, "RateLimitPolicy": { "schema": { "type": "string", "example": "10;w=2592000" }, "description": "Draft-ratelimit-headers policy descriptor." }, "IdempotentReplayed": { "schema": { "type": "string", "enum": [ "true" ] }, "description": "Present when this response is a cached idempotency replay." } }, "schemas": { "Meta": { "type": "object", "required": [ "request_id", "version" ], "properties": { "request_id": { "type": "string", "pattern": "^req_[a-z0-9]{26}$" }, "version": { "type": "string", "enum": [ "v1" ] }, "latency_ms": { "type": "integer", "minimum": 0 } } }, "AssetClass": { "type": "object", "required": [ "id", "name", "status", "tiers_available" ], "properties": { "id": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6 ] }, "name": { "type": "string", "enum": [ "equity", "crypto", "real_estate", "fixed_income", "macro", "commodity" ] }, "status": { "type": "string", "enum": [ "live", "coming_soon" ] }, "tiers_available": { "type": "array", "items": { "type": "string", "enum": [ "instant", "audit" ] } }, "asset_id_format": { "type": "string" }, "examples": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "string" } } }, "ClassCatalogEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "classes" ], "properties": { "classes": { "type": "array", "items": { "$ref": "#/components/schemas/AssetClass" } } } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "HealthEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "status", "version", "deployed_at" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "version": { "type": "string", "example": "g6.8.0" }, "deployed_at": { "type": "string", "format": "date-time" } } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "AttestationRequest": { "type": "object", "required": [ "asset_class", "asset_id" ], "properties": { "asset_class": { "type": "integer", "enum": [ 2, 6 ], "description": "2 = equity, 6 = crypto (V1 supported classes)." }, "asset_id": { "type": "string", "minLength": 1, "description": "Ticker (equity) or symbol (crypto, whitelisted)." } } }, "InstantData": { "type": "object", "required": [ "latency_mode", "data", "source", "attestation_pda", "status" ], "properties": { "latency_mode": { "type": "string", "enum": [ "instant" ] }, "data": { "type": "object", "required": [ "asset_id", "asset_class", "price_micros", "volume_24h" ], "properties": { "asset_id": { "type": "string" }, "asset_class": { "type": "integer", "enum": [ 2, 6 ] }, "price_micros": { "type": "integer", "minimum": 0, "description": "USD \u00d7 1e6" }, "volume_24h": { "type": "integer", "minimum": 0 } } }, "source": { "type": "string", "enum": [ "equity_primary", "equity_backup", "crypto_primary" ], "description": "Abstracted feed label. Never a vendor brand name." }, "attestation_pda": { "type": "string", "description": "Base58 AssetStateV2 PDA." }, "status": { "type": "string", "enum": [ "audit_pending", "audit_failed" ] }, "as_of": { "type": "string", "format": "date-time" }, "expected_commit_by": { "type": "string", "format": "date-time" }, "write_tx_sig": { "type": [ "string", "null" ], "description": "Solana TX signature (null on commit failure)." } } }, "InstantEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/InstantData" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "AttestationEntry": { "type": "object", "required": [ "provider_pubkey", "valuation_score", "confidence_score", "timestamp", "raw_snapshot_hash" ], "properties": { "provider_pubkey": { "type": "string" }, "valuation_score": { "type": "number" }, "confidence_score": { "type": "number" }, "timestamp": { "type": "integer", "format": "int64" }, "raw_snapshot_hash": { "type": "string", "description": "SHA-256 hex of the canonical provider payload." } } }, "AuditData": { "type": "object", "required": [ "latency_mode", "asset_class", "asset_id", "asset_data", "attestations", "attestation_pda" ], "properties": { "latency_mode": { "type": "string", "enum": [ "audit" ] }, "asset_class": { "type": "integer", "enum": [ 2 ] }, "asset_id": { "type": "string" }, "asset_data": { "$ref": "#/components/schemas/AttestationData" }, "attestations": { "type": "array", "items": { "$ref": "#/components/schemas/AttestationEntry" } }, "latest_snapshot_hash": { "type": "string" }, "attestation_pda": { "type": "string" }, "write_tx_sig": { "type": [ "string", "null" ] }, "fee_lamports_paid": { "type": "integer", "format": "int64", "minimum": 0 }, "bump": { "type": "integer", "minimum": 0, "maximum": 255 }, "manual_audit_required": { "type": "boolean" } } }, "AuditEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AuditData" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "AttestationData": { "oneOf": [ { "$ref": "#/components/schemas/EquityVariant" }, { "$ref": "#/components/schemas/CryptoVariant" }, { "$ref": "#/components/schemas/RealEstateVariant" }, { "$ref": "#/components/schemas/FixedIncomeVariant" }, { "$ref": "#/components/schemas/MacroVariant" }, { "$ref": "#/components/schemas/CommodityVariant" } ], "discriminator": { "propertyName": "variant_type", "mapping": { "EquityData": "#/components/schemas/EquityVariant", "CryptoData": "#/components/schemas/CryptoVariant", "RealEstateData": "#/components/schemas/RealEstateVariant", "FixedIncomeData": "#/components/schemas/FixedIncomeVariant", "MacroData": "#/components/schemas/MacroVariant", "CommodityData": "#/components/schemas/CommodityVariant" } } }, "EquityVariant": { "type": "object", "required": [ "variant_type", "closing_price_micros", "volume_24h", "market_cap_usd_millions", "exchange_code" ], "properties": { "variant_type": { "type": "string", "enum": [ "EquityData" ] }, "closing_price_micros": { "type": "integer", "minimum": 0 }, "volume_24h": { "type": "integer", "minimum": 0 }, "market_cap_usd_millions": { "type": "integer", "minimum": 0 }, "exchange_code": { "type": "integer", "minimum": 0, "maximum": 255 } } }, "CryptoVariant": { "type": "object", "required": [ "variant_type", "price_micros", "volume_24h", "as_of_timestamp" ], "properties": { "variant_type": { "type": "string", "enum": [ "CryptoData" ] }, "price_micros": { "type": "integer", "minimum": 0 }, "volume_24h": { "type": "integer", "minimum": 0 }, "as_of_timestamp": { "type": "integer", "format": "int64" } } }, "RealEstateVariant": { "type": "object", "required": [ "variant_type", "monthly_noi_usd" ], "properties": { "variant_type": { "type": "string", "enum": [ "RealEstateData" ] }, "monthly_noi_usd": { "type": "integer", "format": "int64", "minimum": 0 }, "property_pda_v0": { "type": [ "string", "null" ] } } }, "FixedIncomeVariant": { "type": "object", "required": [ "variant_type", "yield_bps", "duration_years_micros", "credit_quality", "maturity_unix" ], "properties": { "variant_type": { "type": "string", "enum": [ "FixedIncomeData" ] }, "yield_bps": { "type": "integer", "minimum": 0, "maximum": 65535 }, "duration_years_micros": { "type": "integer", "minimum": 0 }, "credit_quality": { "type": "integer", "minimum": 0, "maximum": 255 }, "maturity_unix": { "type": "integer", "format": "int64" } } }, "MacroVariant": { "type": "object", "required": [ "variant_type", "value_micros", "indicator_type" ], "properties": { "variant_type": { "type": "string", "enum": [ "MacroData" ] }, "value_micros": { "type": "integer", "format": "int64" }, "indicator_type": { "type": "integer", "minimum": 0, "maximum": 255 } } }, "CommodityVariant": { "type": "object", "required": [ "variant_type", "price_micros", "contract_month", "commodity_code" ], "properties": { "variant_type": { "type": "string", "enum": [ "CommodityData" ] }, "price_micros": { "type": "integer", "minimum": 0 }, "contract_month": { "type": "integer", "minimum": 0 }, "commodity_code": { "type": "integer", "minimum": 0, "maximum": 255 } } }, "AssetState": { "type": "object", "required": [ "pda", "program_id", "asset_class", "asset_id", "asset_data", "attestations", "latest_snapshot_hash", "bump" ], "properties": { "pda": { "type": "string" }, "program_id": { "type": "string" }, "asset_class": { "type": "integer", "enum": [ 1, 2, 6 ] }, "asset_id": { "type": "string" }, "asset_data": { "$ref": "#/components/schemas/AttestationData" }, "attestations": { "type": "array", "items": { "$ref": "#/components/schemas/AttestationEntry" } }, "latest_snapshot_hash": { "type": "string" }, "manual_audit_required": { "type": "boolean" }, "bump": { "type": "integer", "minimum": 0, "maximum": 255 } } }, "AssetStateEnvelope": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AssetState" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "Problem": { "type": "object", "required": [ "type", "title", "status", "instance", "request_id" ], "properties": { "type": { "type": "string", "format": "uri", "description": "Stable error-type URI." }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "request_id": { "type": "string" } }, "additionalProperties": true } }, "responses": { "BadRequest": { "description": "Malformed request, invalid asset_class, or invalid asset_id.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_asset_class": { "summary": "Unsupported class", "value": { "type": "https://docs.axiomstack.dev/errors/invalid-asset-class", "title": "Invalid asset class", "status": 400, "detail": "asset_class must be one of [2 (equity), 6 (crypto)] in V1; got 3.", "instance": "/v1/attestation/instant", "request_id": "req_abc123\u2026", "asset_class": 3, "supported": [ 2, 6 ] } } } } } }, "TierUnavailableOrBadRequest": { "description": "`tier-unavailable-for-class` for crypto audit requests in V1, or a\ngeneral bad-request. The `type` URI disambiguates.\n", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "crypto_audit": { "summary": "Crypto audit not yet available", "value": { "type": "https://docs.axiomstack.dev/errors/tier-unavailable-for-class", "title": "Tier unavailable for class", "status": 400, "detail": "The 'audit' tier is not available for asset_class 6 in V1.", "instance": "/v1/attestation/audit", "request_id": "req_xyz\u2026", "asset_class": 6, "tier_requested": "audit", "tiers_available": [ "instant" ], "note": "Crypto audit tier ships in G6.7b. Use latency_mode=instant for crypto in V1." } } } } } }, "Unauthorized": { "description": "Missing or invalid bearer token.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Forbidden": { "description": "Key is inactive.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "NotFound": { "description": "No AssetStateV2 account at the given PDA.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "IdempotencyReplayMismatch": { "description": "Idempotency-Key replayed with a different request body.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "InsufficientQuota": { "description": "Quota exhausted. Top up USDC or upgrade tier.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "Retry-After": { "schema": { "type": "integer", "minimum": 0 }, "description": "Seconds until the included bucket resets." }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "ServiceUnavailable": { "description": "A dependency (data provider, on-chain RPC, auth store) is temporarily unavailable.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }