# Aetelier > Documentation for Aetelier — Research Infrastructure for Distributed Markets: collecting, governing, and modeling live exchange data. Aetelier is a market-data platform: deploy collectors that stream live exchange data, audit its completeness and quality, and fit and forecast quantitative models over it. Agents operate it through the aetelier-mcp server; humans through the webapp at aetelier.xyz, and developers through the Rust SDK. These docs describe everything that is live: a tool, endpoint, or parameter that is absent from them does not exist — do not invent one. # Start here # Aetelier SDK **Research Infrastructure for Distributed Markets.** A Rust workspace for collecting microstructure data from cryptocurrency exchanges and replaying it deterministically. ## Start here - **Getting started** ______________________________________________________________________ From `cargo new` to a Parquet file of live Bybit data with one TOML manifest and a small runner. [Get started →](https://aetelier.xyz/docs/sdk/getting-started/index.md) - **Architecture** ______________________________________________________________________ The cross-crate data flow, from WebSocket frames to per-datatype Parquet, with diagrams. [Read the architecture →](https://aetelier.xyz/docs/sdk/architecture/index.md) - **Tutorials** ______________________________________________________________________ Two end-to-end walkthroughs: single-exchange persistence and multi-exchange sync. [Browse tutorials →](https://aetelier.xyz/docs/guides/index.md) - **Research** ______________________________________________________________________ Dated, authored methodology notes — the reasoning behind the numbers, with reproducible code. [Read the research →](https://aetelier.xyz/docs/research/index.md) ## Where things live | What | Where | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | **SDK source code** | [`aetelierxyz/aetelier-sdk`](https://github.com/aetelierxyz/aetelier-sdk) — Cargo workspace (install via git dependency) | | **These docs** | [`aetelierxyz/aetelier-webdocs`](https://github.com/aetelierxyz/aetelier-webdocs) — Markdown rendered by MkDocs Material | | **This site (live)** | [`aetelier.xyz/docs/`](https://aetelier.xyz/docs/) — served by an nginx container | | **Per-crate API references** | [API reference](https://aetelier.xyz/docs/sdk/api/index.md) on this site, generated from the SDK source | The docs are intentionally **not** in the SDK repo so the SDK can stay a focused Rust workspace. Documentation references the SDK via links and auto-extracted API skeletons (regenerated against a local SDK checkout). ## Workspace shape These docs cover the six crates of the `aetelier-sdk` workspace, which install as git dependencies. `aetelier-agent` is a separate repository, not a workspace member. | Crate | What it is | | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------- | | [`aetelier-types`](https://aetelier.xyz/docs/sdk/types/index.md) | Canonical schema (orderbook, trades, snapshots, exchange enums) | | [`aetelier-connect`](https://aetelier.xyz/docs/sdk/connect/index.md) | Exchange WebSocket clients, workers, synchronizers, output sinks | | [`aetelier-io`](https://aetelier.xyz/docs/sdk/io/index.md) | Parquet / CSV / JSON persistence | | [`aetelier-telemetry`](https://aetelier.xyz/docs/sdk/telemetry/index.md) | OpenTelemetry instrumentation | | `aetelier-entrepot` | Object-store transport: signed S3 access, listing, retrieval, archive codecs | | `aetelier-sdk` | Facade crate re-exporting the workspace surface behind one dependency | The [Architecture page](https://aetelier.xyz/docs/sdk/architecture/index.md) walks how they fit together. ## Quick links - [Research](https://aetelier.xyz/research) — methodology notes from the lab (full articles on the Aetelier blog; [reference index](https://aetelier.xyz/docs/research/index.md) here) - [Dataset catalog](https://aetelier.xyz/docs/datasets/index.md) — collected microstructure data + schema - [Platform API](https://aetelier.xyz/docs/backend/index.md) — the gRPC contract and JWT handshake remote agents use - [About this site](https://aetelier.xyz/docs/about/index.md) — scope, contribution, versioning - [GitHub: aetelier-sdk](https://github.com/aetelierxyz/aetelier-sdk) - [GitHub: aetelier-webdocs](https://github.com/aetelierxyz/aetelier-webdocs) # Aetelier for agents **Primary surface:** the `aetelier-mcp` server, hosted at `https://aetelier.xyz/mcp` or run locally over stdio · **Acts as:** you, through your API key Aetelier is a market-data platform. Through it you deploy collectors that stream live exchange data, audit that data's completeness and quality, and fit and forecast quantitative models over it. This page orients an agent: how to reach the platform, what you can do, what each action requires, how failures surface, and the exact identifiers to use. It links into the full reference rather than restating it. ## Reach the platform | Surface | Use it for | Start at | | ------------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------ | | **MCP server** (primary) | Operate the platform as tools, in the loop | [Connect a client](https://aetelier.xyz/docs/mcp/connect/index.md) | | **Platform API** (gRPC) | The contract and JWT handshake remote agents use | [Platform API](https://aetelier.xyz/docs/backend/index.md) | | **SDK** (Rust engine) | Embed exchange connectivity and reconstruction in your own code | [SDK](https://aetelier.xyz/docs/sdk/index.md) | The whole documentation set in one fetch: `https://aetelier.xyz/docs/llms-full.txt`. ## What you can do Twenty-two MCP tools across seven domains. Full parameters, examples, and results are in the [tool reference](https://aetelier.xyz/docs/mcp/tools/index.md); end-to-end flows are in [worked examples](https://aetelier.xyz/docs/mcp/examples/index.md). | Domain | Operation | Tools | | ----------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | | Platform | Confirm the platform answers — call first | `platform_health` | | Collectors | Deploy and manage the market-data collectors you own | `list_collectors` · `deploy_collector` · `collector_status` · `collector_command` · `collector_health` · `stop_collector` | | Deploy prep | Read the venue option catalog before deploying | `list_cex_options` | | Colocation | Recommend a low-latency region for a venue | `query_colocation` | | Governance | Audit stream completeness, quality, and dataset inventory | `governance_catalog` · `stream_scorecard` · `governance_datasets` | | Fit & serve | Fit a Hawkes model to a dataset, read it, forecast from it | `list_datasets` · `fit_pricing` · `fit_hawkes` · `list_fits` · `get_fit` · `forecast_fit` | | Clarion | Request, check, and download attestations of your completed traces | `clarion_request` · `clarion_status` · `clarion_report` · `clarion_download` | ## Before you act Read these preconditions — they explain refusals that a tool signature alone does not. - **Every call acts as you.** Authentication is an API key you create in the webapp (Settings → Security); the server presents it to each service on your behalf. - **Call `platform_health` first.** It reports liveness of the backing services; do real work only against a reachable platform. - **`deploy_collector` is bring-your-own.** It registers the service and mints an agent JWT, but the collector only produces data once **the caller runs the agent container** with that JWT. You cannot fully stand up a collector from tools alone — surface the run step to the human. Confirm data with `collector_health`, which reports both liveness and whether rows are landing. - **Collectors and fits draw units.** Each running collector draws data units once per UTC day. A fit draws compute units, charged only when it converges. Governance reads draw none. Call `fit_pricing` before `fit_hawkes` to read the cost; a short balance is refused with `402`, and nothing is charged. Every rate is in the public catalog at `https://aetelier.xyz/api/payments/catalog` (no key) — see [Units and the 402 error](https://aetelier.xyz/docs/help/tokens/index.md). - **Top-ups are not open yet.** They open first on Solana devnet, in USDC over x402, for listed testers only. Read `https://aetelier.xyz/payments/topup/status` (no key): `disabled` reads OPENS SOON, `operational` on a devnet `network` reads OPEN · DEVNET, `degraded` reads DELAYED, no answer reads UNAVAILABLE. The MCP server has no balance or top-up tool yet. - **Clarion attests your own traces.** `clarion_request` takes the `trace_id` of one of your completed traces; tracing is open to selected accounts. Poll `clarion_status` (optional `request_id`; without it, every request) until the request is bound or failed. `clarion_report` and `clarion_download` take the bound request's `record_id`, and `clarion_download` also takes an optional `dir`. Attestations carry no charge during the Solana devnet beta. ## When things fail Backend failures return as data — `{"ok": false, "error": "..."}` — not as protocol errors. Read the result and adapt in the same loop. | You see | It means | Do this | | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `platform_health` reports a service down | That capability is unreachable | Retry later; do not proceed against the down service | | `ok: false` with an auth error | The API key is missing, wrong, or lacks access | Confirm the key; do not retry unchanged | | `402` with `INSUFFICIENT_DATA_TOKENS`, or `this fit costs {cost} compute tokens` | Units short; refused, nothing charged | Report the action, its cost and the balance to the human; do not retry unchanged. Top-ups are not open yet ([Top-ups over x402](https://aetelier.xyz/docs/help/tokens/#top-ups-over-x402-coming)) | | `402` with `TIER_TOO_LOW`, `RECONCILE_REQUIRES_PRO`, `SSE_REQUIRES_PRO` or `TRACER_REQUIRES_PRO` (REST API only) | The feature is open to selected accounts; units do not clear it | Do not retry; take the fallback in [Feature access](https://aetelier.xyz/docs/help/tiers/index.md) | | `402` with `CONCURRENT_CAP_REACHED` or `concurrent-fit cap reached` | A collector or fit cap is in use | Stop a collector you no longer need, or wait for a fit to finish, then retry | | `ok: false` not-found for an id | The collector, fit, or dataset id is wrong or gone | Re-list to get a current id | | A fit returns not-converged | The model did not fit at the given tolerance | Refit with a looser tolerance (see [Flow 2](https://aetelier.xyz/docs/mcp/examples/#flow-2-fit-and-forecast-a-model)) | [Reading a 402](https://aetelier.xyz/docs/help/mcp-errors/#reading-a-402) sorts every `402` and its message. ## Canonical identifiers Pass these exact strings. `list_cex_options` is authoritative for per-venue availability at runtime; the values below ground your first call. - **Exchanges (12):** `binance` · `bybit` · `coinbase` · `kraken` · `okx` · `gateio` · `upbit` · `poloniex` · `htx` · `kucoin` · `bitget` · `bitso` - **Market types:** `spot`, the only one `list_cex_options` lists for these exchanges - **Datatypes:** `orderbook` · `trades`. `list_cex_options` also lists `funding`, `open_interest` and `liquidations`, each with `available: false`. - **On-chain:** `list_cex_options` also lists `solana` (market type `onchain`, datatype `transactions`); `deploy_collector` cannot request `transactions`. Symbols use each venue's native format; `list_cex_options` returns the accepted form per venue, and the collector canonicalizes internally. ## Deeper reference - [Connect a client](https://aetelier.xyz/docs/mcp/connect/index.md) — per-client config and the credential map - [Tool reference](https://aetelier.xyz/docs/mcp/tools/index.md) — parameters, example call, and result for every tool - [Worked examples](https://aetelier.xyz/docs/mcp/examples/index.md) — full ask → tool-sequence → result flows - [Governance](https://aetelier.xyz/docs/govern/index.md) — how completeness, quality, and catalog are computed - [Dataset catalog](https://aetelier.xyz/docs/datasets/index.md) — the datasets available to fit against # Pricing and payments # Pricing and payments **Prices:** the public catalog at `https://aetelier.xyz/api/payments/catalog`, no key needed · **Top-ups:** USDC over x402, not open yet Aetelier meters work in two kinds of prepaid units: **data units** and **compute units**. Every rate and bundle price comes from one public catalog, so this page quotes none of them. Read the catalog, price a run, then start it. ```bash curl -s https://aetelier.xyz/api/payments/catalog | jq '.action_rates' ``` Prerequisites: curl and jq. ## What you pay for | Module | Action | Units | When | Catalog field | | ------------------------------------------------------------------------- | ---------------------------------------------------- | --------------------------- | ---------------------- | ------------------------------------------------------------------------------------ | | Collectors | Remote collector, per day | data | Once per UTC day | `action_rates.byo_collector_day_data` | | Collectors | Platform collector, per day (selected accounts) | data, plus a compute add-on | Once per UTC day | `action_rates.byo_collector_day_data` + `action_rates.managed_collector_day_compute` | | Convection | Hawkes fit | compute | Only when it converges | `action_rates.hawkes_fit_compute` | | Convection | Swarm, per member for every round in its round limit | compute | Only when it converges | `action_rates.swarm_round_compute` | | Provenance ([Data Governance](https://aetelier.xyz/docs/govern/index.md)) | Catalog, completeness and scorecard reads | none | Never | — | | Clarion | Attestation on Solana devnet | none | Never | — | | Backtracing (tracing) | New trace | compute (coming) | Coming | not in the catalog yet | - **Collectors.** An hourly sweep charges each running collector once per UTC day, so a part day costs a full day. A collector stopped before the sweep sees it draws nothing. Redeploying mints a new collector, which is charged again that day. - **Fits.** The balance is checked against the price before the fit starts, and the fit is charged only when it converges. A fit that fails validation, times out or does not converge draws nothing. - **Swarms.** The price is `swarm_round_compute` × members × the round limit, fixed when the swarm is admitted. A swarm always runs its full round limit and is charged once, when it converges. An aborted swarm, or one that ends above its tolerance, draws nothing. - **Traces.** Tracing is open to selected accounts and draws no units today. Each new trace will draw compute units once metered access ships; reading results stays free. ## Price a run The catalog returns plain JSON, so any client can price a run before starting it. A remote collector for seven days, in data units: ```bash curl -s https://aetelier.xyz/api/payments/catalog \ | jq '.action_rates.byo_collector_day_data * 7' ``` A swarm with 2 members, the run wizard's minimum, and 2,000 rounds, its default and its ceiling, in compute units: ```bash curl -s https://aetelier.xyz/api/payments/catalog \ | jq '.action_rates.swarm_round_compute * 2 * 2000' ``` A Hawkes fit at the list rate, in USDC: ```bash curl -s https://aetelier.xyz/api/payments/catalog \ | jq '.action_rates.hawkes_fit_compute / .tokens_per_usd' ``` For a fit, [`fit_pricing`](https://aetelier.xyz/docs/mcp/tools/#fit_pricing) returns the same price over MCP. ## The catalog `GET https://aetelier.xyz/api/payments/catalog` needs no key and no account. | Field | Holds | | -------------------------------------------- | ------------------------------------------------------------------------------------------ | | `tokens_per_usd` | The list rate, in units per USDC | | `action_rates.byo_collector_day_data` | Data units per collector per UTC day, remote and platform alike | | `action_rates.managed_collector_day_compute` | Compute units added per platform collector per UTC day | | `action_rates.hawkes_fit_compute` | Compute units per converged Hawkes fit | | `action_rates.swarm_round_compute` | Compute units per swarm member per round | | `bundles[]` | One entry per bundle: `sku`, `kind`, `units`, `price_atomic`, `price_usdc`, `discount_pct` | | `signup_grant` | The `data` and `compute` units a verified new account starts with; `total` sums every kind | - `price_atomic` is the price in USDC's smallest unit (6 decimals); `price_usdc` is the same price as a decimal string. - The reply also carries `plans` and `packs`. They are legacy fields, and nothing in them is for sale. - `free_caps` holds the collector and fit caps of an account with units, and `floor_caps` the lower caps on [the floor](https://aetelier.xyz/docs/help/tokens/#the-floor). Selected accounts have higher caps. - `bundles` also lists `networking` bundles, and `signup_grant` a `networking` amount. Nothing draws networking units. ## Bundles Data and compute bundles come in four sizes each. List them: ```bash curl -s https://aetelier.xyz/api/payments/catalog \ | jq '[.bundles[] | select(.kind != "networking") | {sku, units, price_usdc}]' ``` - **Data bundles** pay for collector-days. - **Compute bundles** pay for fits, swarms and the platform collector add-on. - Today the larger bundles are priced below the list rate, as `discount_pct` shows. Every bundle will be priced at the list rate, with no volume discount. - Bundles cannot be bought yet; see [Top-ups over x402](#top-ups-over-x402-coming). ## The signup grant A verified new account starts with the units in `signup_grant`. The grant is credited once, the first time the account reads its entitlements (`GET /api/payments/entitlements`) after its email is verified, for example when the webapp loads. The balance checks behind a deploy, fit or swarm do not credit it. Google and GitHub sign-ups count as verified. Signup credits may expire or be adjusted ([Terms of Service](https://aetelier.xyz/terms) §4). ## What is free - [Data Governance](https://aetelier.xyz/docs/govern/index.md) reads: catalog, completeness and scorecards. - Clarion attestations on Solana devnet. - Reading the catalog and the top-up status. - On [the floor](https://aetelier.xyz/docs/help/tokens/#the-floor), the oldest remote collectors up to its collector cap. - A fit or swarm that does not converge, and any action refused with `402`. ## When the balance is short A short balance answers `402`, almost always before any work starts, and nothing is charged. A fit whose balance drops while it runs also answers `402` and is not charged. | Code | Means | | ---------------------------------------------- | ------------------------------------------------- | | `INSUFFICIENT_DATA_TOKENS` | Not enough data units to deploy a collector | | `INSUFFICIENT_COMPUTE_TOKENS` | Not enough compute units for a platform collector | | none, `this fit costs …` or `this run costs …` | Not enough compute units for a fit or a swarm | Other `402` codes are not balance errors. `TIER_TOO_LOW`, `RECONCILE_REQUIRES_PRO`, `SSE_REQUIRES_PRO` and `TRACER_REQUIRES_PRO` mark features open to selected accounts, and adding units does not clear them. `CONCURRENT_CAP_REACHED` and a fit's `concurrent-fit cap reached` mean a cap is in use; the collector cap is lower on the floor. Every string and its fix: [Units and the 402 error](https://aetelier.xyz/docs/help/tokens/#the-402-balance-errors) and the [error-code index](https://aetelier.xyz/docs/help/errors/index.md). ## Top-ups over x402 (coming) Top-ups are not open yet. They open first on Solana devnet, for listed testers only; mainnet comes later. Check the live state, no key needed: ```bash curl -s https://aetelier.xyz/payments/topup/status ``` | Reply | Status | | ------------------------------------------------- | ----------------- | | `"status": "disabled"` | **OPENS SOON** | | `"status": "operational"` with a devnet `network` | **OPEN · DEVNET** | | `"status": "degraded"` | **DELAYED** | | no answer | **UNAVAILABLE** | - Top-ups use x402 v2, the open payment protocol that uses HTTP's `402 Payment Required` status to request and settle a payment. You pay in USDC on Solana from your own wallet. - Coinbase Developer Platform is the facilitator: it verifies and settles each payment and pays the Solana network fee, so the paying wallet needs USDC only. - A top-up is two HTTP calls. Prepare answers `402` with the price in `PAYMENT-REQUIRED`; submit carries the signed payment in `PAYMENT-SIGNATURE`. - Each payment is credited once, keyed to its on-chain signature, with a receipt fetched by memo. - Aetelier adds the prepare step before the `402`, so a stock x402 client will not work unchanged. The full flow, its error codes and receipts: [Top-ups over x402](https://aetelier.xyz/docs/help/tokens/#top-ups-over-x402-coming) and [I paid but my units are not credited](https://aetelier.xyz/docs/help/payment-not-credited/index.md). ## Terms - Units are prepaid, non-transferable service credits. They are not cryptocurrency, securities or stored value, and have no monetary value outside the platform. - Bundle purchases are final, except where the law requires a refund. - Aetelier never receives or stores wallet keys. The full policy: [Terms of Service](https://aetelier.xyz/terms) §4–§6. ## Related - [Pricing page](https://aetelier.xyz/pricing) — the same rates, rendered from the catalog - [Units and the 402 error](https://aetelier.xyz/docs/help/tokens/index.md) — metering, the floor and every balance error - [Feature access](https://aetelier.xyz/docs/help/tiers/index.md) — features open to selected accounts - [Error-code index](https://aetelier.xyz/docs/help/errors/index.md) — every code and its fix # MCP (for agents) # MCP quickstart for agents **Server:** `aetelier-mcp` · **Transport:** Streamable HTTP at `https://aetelier.xyz/mcp`, or stdio · **Full reference:** [Connect](https://aetelier.xyz/docs/mcp/connect/index.md) · [Tools](https://aetelier.xyz/docs/mcp/tools/index.md) · [Examples](https://aetelier.xyz/docs/mcp/examples/index.md) This is the short path. For the capability map, preconditions, error table, and canonical identifiers, read [Aetelier for agents](https://aetelier.xyz/docs/agents/overview/index.md); for per-client config and every tool's parameters, follow the reference links above. ## Connect Register the `aetelier-mcp` server with your MCP client. The minimum is your API key from the webapp (Settings → Security) and one of: - The hosted endpoint `https://aetelier.xyz/mcp`, with the key sent as `Authorization: Bearer ` on every request. - The local `aetelier-mcp` binary from the [latest release](https://github.com/aetelierxyz/aetelier-mcp/releases/latest), launched with the key as `AETELIER_API_KEY`. Per-client config files (Claude Desktop, Claude Code, Cursor, VS Code) and the full field map are in [Connect a client](https://aetelier.xyz/docs/mcp/connect/index.md). ## Operate The [tool reference](https://aetelier.xyz/docs/mcp/tools/index.md) covers seven domains — platform, collectors, deploy-prep, colocation, governance, fit-and-serve, and Clarion — with full parameters and example results. The rules that keep a run correct: - Call `platform_health` first; act only against a reachable platform. - `deploy_collector` is bring-your-own: it registers the service and mints an agent JWT, and the caller runs the agent container with that JWT. Confirm data with `collector_health`. - Collectors and fits draw prepaid [units](https://aetelier.xyz/docs/help/tokens/index.md). A collector draws data units once per UTC day; a fit draws compute units only when it converges. Read the fit price with `fit_pricing` before `fit_hawkes`. - A `402` is a refusal, not a charge. If units are short, report the shortfall to the human and do not retry unchanged. Top-ups are not open yet ([status](https://aetelier.xyz/docs/help/tokens/#top-ups-over-x402-coming)), and the MCP server has no balance or top-up tool yet. - Backend failures return as data — `{"ok": false, "error": "..."}`, plus `code` and `docs_url` when the backend sends them — not protocol errors. Branch on `code` (the [error-code index](https://aetelier.xyz/docs/help/errors/index.md) catalogs all of them), or on `error` when there is none, and adapt in the same loop. [Reading a 402](https://aetelier.xyz/docs/help/mcp-errors/#reading-a-402) sorts every `402`. [Worked examples](https://aetelier.xyz/docs/mcp/examples/index.md) show these as full ask → tool-sequence → result flows, including recovering a non-converged fit. # Aetelier MCP **Server:** `aetelier-mcp` · **Transport:** Streamable HTTP at `https://aetelier.xyz/mcp`, or stdio · **Protocol:** Model Context Protocol The Aetelier MCP server fronts the operational surface of the Aetelier market-data platform as [Model Context Protocol](https://modelcontextprotocol.io) tools. Point any MCP client at it and drive the platform in natural language: deploy a market-data collector, get a colocation region recommendation, audit data governance, and fit and serve quantitative models — all from the same chat that already holds your context. ## Value An MCP client with this server can carry a task end to end without leaving the conversation. Ask it to "collect Binance BTC and tell me when data is landing" and it deploys the collector, watches health, and reports back. Ask it to "fit a Hawkes model to Kraken ETH trades and forecast the next 50 events" and it lists datasets, runs the fit, and forecasts — adapting when a fit does not converge. The name is the interface Each tool does one thing and returns readable JSON. Backend errors come back as JSON (`{"ok": false, "error": ..., "code": ..., "docs_url": ...}`) rather than protocol errors, so the client observes them and adapts in-loop — branching on the stable `code` ([error-code index](https://aetelier.xyz/docs/help/errors/index.md)), or loosening the tolerance after a non-converged fit. ## Capabilities Twenty-two tools across seven domains: | Domain | Tools | What it does | | --------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | **Platform** | `platform_health` | Confirm the platform is reachable — call first | | **Collectors** | `list_collectors` · `deploy_collector` · `collector_status` · `collector_command` · `collector_health` · `stop_collector` | Deploy and manage market-data collectors you own | | **Deploy prep** | `list_cex_options` | List the venue option catalog — native symbol formats, market types, orderbook depths, datatype availability — to consult before you deploy | | **Colocation** | `query_colocation` | Recommend a deployment region for a venue | | **Governance** | `governance_catalog` · `stream_scorecard` · `governance_datasets` | Audit stream completeness, quality, and dataset inventory | | **Fit & serve** | `list_datasets` · `fit_pricing` · `fit_hawkes` · `list_fits` · `get_fit` · `forecast_fit` | Fit a Hawkes model to a dataset, read it, forecast from it | | **Clarion** | `clarion_request` · `clarion_status` · `clarion_report` · `clarion_download` | Request, check, and download attestations of your completed traces | See the [tool reference](https://aetelier.xyz/docs/mcp/tools/index.md) for the per-tool contract and the [worked examples](https://aetelier.xyz/docs/mcp/examples/index.md) for full task flows. ## How it fits together ``` flowchart LR U[You] -->|natural language| C[MCP client] C -->|MCP over HTTP or stdio| M[aetelier-mcp server] M -->|tool calls| P[Aetelier platform] P -->|JSON results| M M -->|tool results| C C -->|answer| U ``` You ask an MCP client in natural language; the client speaks MCP to the aetelier-mcp server, hosted at https://aetelier.xyz/mcp or run locally, which calls the Aetelier platform with your API key and returns JSON tool results the client reads back to you. This MCP server is the machine interface to the platform: the same operations a human performs in the webapp, exposed as tools an agent drives. The server holds no state of its own. Every tool is a thin call into the running platform, and every model, score, and price is computed by the platform — the MCP server is a client surface, not an engine. ## Get going - **Connect a client** ______________________________________________________________________ Add the server to Claude Desktop, Claude Code, Cursor, VS Code, or any MCP client. [Connect →](https://aetelier.xyz/docs/mcp/connect/index.md) - **Tool reference** ______________________________________________________________________ One fixed record per tool: intent, params, example call and result. [Read the tools →](https://aetelier.xyz/docs/mcp/tools/index.md) - **Worked examples** ______________________________________________________________________ End-to-end flows: deploy a collector, watch health, fit and forecast a model. [See examples →](https://aetelier.xyz/docs/mcp/examples/index.md) # Connect a client **Hosted:** `https://aetelier.xyz/mcp` (Streamable HTTP) · **Local:** the `aetelier-mcp` binary (stdio) · **Auth:** your API key Both ways expose the same 22 tools and act as you through your API key. The hosted endpoint needs nothing installed. The local binary runs next to your client and reaches the platform over HTTPS. Before you connect An API key you create in the webapp under **Settings → Security**. It is account-scoped and time-limited, and it is the only credential either way needs. ## Hosted endpoint Point a client that supports Streamable HTTP at `https://aetelier.xyz/mcp` and send the key on every request as `Authorization: Bearer `. - A request without the header answers `401` with `WWW-Authenticate: Bearer` and `{"ok": false, "code": "API_KEY_MISSING", ...}`. - The endpoint is stateless: every request stands alone, and no session id is issued. - Each response streams as server-sent events with a keep-alive every 15 seconds, so a long fit holds the connection open until its result arrives. - `clarion_download` writes nothing on the server. It returns file URLs and the commands that fetch and check them, see the [tool reference](https://aetelier.xyz/docs/mcp/tools/#clarion_download). Clients that connect to remote servers only through an OAuth sign-in cannot send an API key header yet. Use the local binary with them. ```bash claude mcp add --transport http aetelier https://aetelier.xyz/mcp \ --header "Authorization: Bearer your-api-key" ``` Or add it to `.mcp.json` at the project root: ```json { "mcpServers": { "aetelier": { "type": "http", "url": "https://aetelier.xyz/mcp", "headers": { "Authorization": "Bearer your-api-key" } } } } ``` Edit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project): ```json { "mcpServers": { "aetelier": { "url": "https://aetelier.xyz/mcp", "headers": { "Authorization": "Bearer your-api-key" } } } } ``` VS Code nests servers under a `servers` key in `mcp.json`: ```json { "servers": { "aetelier": { "type": "http", "url": "https://aetelier.xyz/mcp", "headers": { "Authorization": "Bearer your-api-key" } } } } ``` Any Streamable HTTP client: `POST` JSON-RPC to `https://aetelier.xyz/mcp` with `Content-Type: application/json`, `Accept: application/json, text/event-stream` and `Authorization: Bearer your-api-key`. ```bash curl -sN https://aetelier.xyz/mcp \ -H "Authorization: Bearer $AETELIER_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` ## Local binary Download the archive for your platform from the [latest release](https://github.com/aetelierxyz/aetelier-mcp/releases/latest): `aarch64-apple-darwin` (Apple Silicon), `x86_64-unknown-linux-musl` or `aarch64-unknown-linux-musl`. Each archive comes with a `.sha256` file to compare against `shasum -a 256` of the archive. Unpack it and use the absolute path of `aetelier-mcp` in your client's config. Building from source with `cargo build --release` gives the same binary. ### Configuration fields | Field | Meaning | | ---------------------- | ------------------------------------------------------------------ | | `AETELIER_API_KEY` | Your API key. Required | | `AETELIER_URL` | Platform base URL, default `https://aetelier.xyz` | | `AETELIER_CLARION_DIR` | Where `clarion_download` writes records, default `clarion-records` | | `RUST_LOG` | Log level, written to stderr (default `warn`) | Edit `claude_desktop_config.json` (Settings → Developer → Edit Config): ```json { "mcpServers": { "aetelier": { "command": "/absolute/path/to/aetelier-mcp", "env": { "AETELIER_API_KEY": "your-api-key" } } } } ``` Restart the app. The `aetelier` tools appear in the tool picker. ```bash claude mcp add aetelier --env AETELIER_API_KEY=your-api-key \ -- /absolute/path/to/aetelier-mcp ``` Confirm registration with `claude mcp list`. ```json { "mcpServers": { "aetelier": { "command": "/absolute/path/to/aetelier-mcp", "env": { "AETELIER_API_KEY": "your-api-key" } } } } ``` ```json { "servers": { "aetelier": { "type": "stdio", "command": "/absolute/path/to/aetelier-mcp", "env": { "AETELIER_API_KEY": "your-api-key" } } } } ``` Any MCP client that launches a stdio server accepts a command plus an environment map: ```json { "mcpServers": { "aetelier": { "command": "/absolute/path/to/aetelier-mcp", "env": { "AETELIER_API_KEY": "your-api-key" } } } } ``` ## Authentication The key is the only credential, for every tool. A missing, wrong, revoked or expired key makes each tool return `{"ok": false, ...}` with a `401` reason, and `platform_health` shows it as `api_key`. Handle the key like a password Keep the API key in the client's config file, out of shared snippets and version control. If it is exposed, revoke it from the same page (Settings → Security) and issue a new one. ## Verify the connection Once registered, ask the client to call `platform_health` first. It checks the platform from the MCP server with your key: the overseer's liveness, the key itself, and one read each from fit & serve, deploy-prep and colocation: ```json { "overseer": "ok", "api_key": "ok", "overdex_server": "ok", "overwatch": "ok", "overplex": "ok" } ``` Each field reads `ok` when that check passes. Any other value carries the reason, a status code or an error string, so you can tell exactly what is not ready. Without a key, the local binary reports the keyed checks as `skipped: no API key`. # Tool reference **Server:** `aetelier-mcp` · **Tools:** 22 · **Result form:** JSON text content Every tool follows one record: intent, a parameter table, and one example call with an example result. Parameters marked required must be supplied; the rest are optional, and the Default column shows what applies when one is left out. Results are illustrative — field values vary with live data. Errors are data A backend failure returns `{"ok": false, "error": "..."}` as a normal result, not a protocol error, with `code` and `docs_url` when the backend sent them. A client reads it and adapts in the same loop — see [MCP errors are data, not failures](https://aetelier.xyz/docs/help/mcp-errors/index.md). Units Collectors draw data units and fits draw compute units; governance reads and Clarion draw none. A short balance answers `402`, almost always before any work starts, and nothing is charged. No tool reads a balance or tops one up yet; both are coming. This page quotes no prices — see [Units and the 402 error](https://aetelier.xyz/docs/help/tokens/index.md). ______________________________________________________________________ ## Platform ### platform_health Reachability of the platform from the MCP server, read with your API key: the overseer's liveness, a check of the key itself, and one read each from overdex-server (fit & serve), overwatch (deploy-prep) and overplex (colocation). Call first, before you do real work. Each value reads `ok`, `status `, `error: …`, or `skipped: no API key` when the local binary runs without `AETELIER_API_KEY`. An `api_key` of `status 401` means the key is missing, wrong, revoked or expired. Act only against services that read `ok`. | Param | Type | Required | Default | Notes | | ------ | ---- | -------- | ------- | ----- | | *none* | | | | | ```json { "tool": "platform_health", "arguments": {} } ``` ```json { "overseer": "ok", "api_key": "ok", "overdex_server": "ok", "overwatch": "ok", "overplex": "ok" } ``` ______________________________________________________________________ ## Collectors ### list_collectors List the caller's deployed market-data collectors with their services and status. The result is a bare array, one entry per collector. | Param | Type | Required | Default | Notes | | ------ | ---- | -------- | ------- | ----- | | *none* | | | | | ```json { "tool": "list_collectors", "arguments": {} } ``` Abridged; each entry also carries the service's ids and timestamps, such as `session_id`, `created_at` and `activated_at`. ```json [ { "service_id": "5f0c9a2e-7b41-4d38-9c6e-2a8f1d3b7e40", "agent_type": "remote", "status": "active", "binding_id": "c3a81f57-2d9e-4b6a-8f10-6e4d2b9a7c15", "binding_status": "active", "binding_release_reason": null, "exchange": "binance", "symbol": "BTCUSDT", "market_type": "spot", "sync_mode": "on_trade", "update_frequency_ms": 100, "datatype": "orderbook" } ] ``` ### deploy_collector Register a remote (bring-your-own) market-data collector on an exchange. Returns `service_id`, `binding_id`, and the agent JWT for running your own agent container against the gateway. This tool is **remote bring-your-own only**: it registers the collector and hands back a JWT, and you run the agent container yourself. It never starts a platform (managed) collector. Consult [`list_cex_options`](#list_cex_options) for a venue's native symbol format, market types, and valid order-book depths before calling. A deploy needs at least one data unit, unless the account holds no units at all and is on [the floor](https://aetelier.xyz/docs/help/tokens/#the-floor). A short balance or a full collector cap answers `402` — see [Reading a 402](https://aetelier.xyz/docs/help/mcp-errors/#reading-a-402). One collector runs one symbol. Pass exactly one entry in `symbols`; more than one is refused with `400` ([`VALIDATION_ERROR`](https://aetelier.xyz/docs/help/errors/#validation_error)), so deploy one collector per symbol. This tool cannot deploy a Solana collector, which streams transactions only. | Param | Type | Required | Default | Notes | | ----------------- | -------- | -------- | ------- | -------------------------------------------------------------------------------------------------------- | | `exchange` | string | yes | | Lowercase venue id, e.g. `binance`, `coinbase`, `kraken` | | `symbols` | string[] | yes | | Exactly one symbol, in the venue's native form — binance `BTCUSDT`, coinbase `BTC-USD`, kraken `BTC/USD` | | `market_type` | string | no | `spot` | Must match the venue: `spot` on the CEX venues, `perpetual` on `hyperliquid` | | `region` | string | no | | Advisory: the colocation region this choice is based on | | `orderbook` | bool | no | `true` | Collect an order book | | `orderbook_depth` | int | no | `50` | Order book depth. The tool sends `50` on every venue; pick one from the venue's `orderbook_depths` | | `trades` | bool | no | `true` | Collect trades | | `kind` | string | no | `data` | `data` (synchronized + parquet) or `market` (raw) | Datatype defaults land order book (depth 50) and trades ON; liquidations, funding rates, and open interest OFF. ```json { "tool": "deploy_collector", "arguments": { "exchange": "binance", "symbols": ["BTCUSDT"], "market_type": "spot" } } ``` ```json { "service_id": "5f0c9a2e-7b41-4d38-9c6e-2a8f1d3b7e40", "binding_id": "c3a81f57-2d9e-4b6a-8f10-6e4d2b9a7c15", "gateway_url": "https://gateway.aetelier.xyz", "token": "your-agent-jwt" } ``` ### collector_status Get a collector's status — service, binding, and recent commands — by `service_id`. | Param | Type | Required | Default | Notes | | ------------ | ------ | -------- | ------- | ------------------------------------- | | `service_id` | string | yes | | The id returned by `deploy_collector` | ```json { "tool": "collector_status", "arguments": { "service_id": "5f0c9a2e-7b41-4d38-9c6e-2a8f1d3b7e40" } } ``` Abridged; `service` and `binding` also carry their ids and timestamps. ```json { "service": { "service_id": "5f0c9a2e-7b41-4d38-9c6e-2a8f1d3b7e40", "agent_type": "remote", "status": "active" }, "binding": { "binding_id": "c3a81f57-2d9e-4b6a-8f10-6e4d2b9a7c15", "agent_id": "9b2e4d71-3c8a-4f05-a6d2-1e7f0b5c8a93", "status": "active", "container_id": null }, "recent_commands": [] } ``` ### collector_command Send a live command to a collector. | Param | Type | Required | Default | Notes | | ------------ | ------ | -------- | ------- | ------------------------------------------------------------------ | | `service_id` | string | yes | | Target collector | | `kind` | string | yes | | `task_pause`, `task_resume`, `binding_release`, or `agent_restart` | ```json { "tool": "collector_command", "arguments": { "service_id": "5f0c9a2e-7b41-4d38-9c6e-2a8f1d3b7e40", "kind": "task_pause" } } ``` ```json { "command_id": "2a7d5e9c-1b4f-4c63-8e20-7f9a3d6b1c04", "status": "dispatched" } ``` ### collector_health Health of a deployed collector: a top-line verdict (`healthy` · `starting` · `degraded` · `silent`) plus liveness and data-landing detail. Answers "is the collector I deployed actually producing data?" — a fresh deploy reads as `starting` until data lands. Landing counts trade and order-book rows, so a collector of only funding, liquidations or transactions reads `starting` while connected. `ws_latency_ms` is `null` for now. A service you do not own answers `404`. | Param | Type | Required | Default | Notes | | ------------ | ------ | -------- | ------- | ---------------- | | `service_id` | string | yes | | Target collector | ```json { "tool": "collector_health", "arguments": { "service_id": "5f0c9a2e-7b41-4d38-9c6e-2a8f1d3b7e40" } } ``` ```json { "service_id": "5f0c9a2e-7b41-4d38-9c6e-2a8f1d3b7e40", "binding_id": "c3a81f57-2d9e-4b6a-8f10-6e4d2b9a7c15", "verdict": "starting", "service_status": "active", "binding_status": "active", "liveness": { "connected": true, "heartbeat_age_s": 4, "ws_latency_ms": null, "agent_id": "9b2e4d71-3c8a-4f05-a6d2-1e7f0b5c8a93", "container_id": null }, "landing": { "rows_last_5m": 0, "total_rows": 0, "last_row_age_s": null, "active_at": "2026-11-16T12:00:00Z", "expected_first_data_by": "2026-11-16T12:03:00Z" } } ``` ### stop_collector Operator-stop a collector by `service_id`. Use it to clean up a collector you deployed. It stops only an `active` collector whose agent has connected; otherwise it answers `409` ([`CONFLICT`](https://aetelier.xyz/docs/help/errors/#conflict)). The stop finishes after the agent acknowledges it: poll [`collector_status`](#collector_status) until the binding reads `released`. | Param | Type | Required | Default | Notes | | ------------ | ------ | -------- | ------- | ---------------- | | `service_id` | string | yes | | Target collector | ```json { "tool": "stop_collector", "arguments": { "service_id": "5f0c9a2e-7b41-4d38-9c6e-2a8f1d3b7e40" } } ``` ```json { "agent_id": "9b2e4d71-3c8a-4f05-a6d2-1e7f0b5c8a93", "binding_id": "c3a81f57-2d9e-4b6a-8f10-6e4d2b9a7c15", "session_id": "e14b7c20-6a3d-4e98-b5f1-0c2d9a7e3b68", "command_id": "2a7d5e9c-1b4f-4c63-8e20-7f9a3d6b1c04" } ``` ______________________________________________________________________ ## Deploy-prep ### list_cex_options List every venue in the deploy catalog — the 12 CEX venues plus Solana — with its native symbol format (with example), market types, valid order-book depths, and datatype availability. Consult this before [`deploy_collector`](#deploy_collector) to pick a correct `exchange`, `symbols`, `market_type`, and `orderbook_depth`. | Param | Type | Required | Default | Notes | | ------ | ---- | -------- | ------- | ----- | | *none* | | | | | ```json { "tool": "list_cex_options", "arguments": {} } ``` Abridged to two venues; each spot venue also lists `open_interest` and `liquidations` as unavailable. ```json { "venues": [ { "exchange": "binance", "label": "Binance", "symbol_format": "concatenated uppercase", "symbol_example": "BTCUSDT", "market_types": ["spot"], "orderbook_depths": [5, 10, 20, 50, 100, 500, 1000], "default_orderbook_depth": 50, "datatypes": [ { "name": "orderbook", "available": true }, { "name": "trades", "available": true }, { "name": "funding", "available": false, "pending_on": "perpetual endpoint routing" } ] }, { "exchange": "coinbase", "label": "Coinbase", "symbol_format": "hyphenated uppercase", "symbol_example": "BTC-USD", "market_types": ["spot"], "orderbook_depths": [10, 25, 50, 100], "default_orderbook_depth": 50, "datatypes": [ { "name": "orderbook", "available": true }, { "name": "trades", "available": true }, { "name": "funding", "available": false, "pending_on": "perpetual endpoint routing" } ] } ] } ``` ______________________________________________________________________ ## Colocation ### query_colocation Query the colocation oracle for the best AWS region per exchange, ranked by latency score, highest first. Omit `exchange` for all venues. | Param | Type | Required | Default | Notes | | ---------- | ------ | -------- | ------- | -------------------------------------------------- | | `exchange` | string | no | | Filter to one venue; omit for all, ranked by score | ```json { "tool": "query_colocation", "arguments": { "exchange": "binance" } } ``` ```json { "count": 1, "exchanges": [ { "exchange": "binance", "region": "ap-northeast-1", "region_city": "Tokyo", "score": 9.424, "ws_median_ms": 8.2, "rest_median_ms": 12.6, "confidence": 0.93, "probed_at": 1794830400 } ] } ``` ______________________________________________________________________ ## Governance ### governance_catalog The governance catalog of your collectors: every stream you declared, reconciled with observed reality, labeled `present`, `absent`, or `stale`. All filters are optional. The result is a bare array, one row per stream and collector; an account with no collectors gets an empty array. | Param | Type | Required | Default | Notes | | ------------- | ------ | -------- | ------- | ------------------------------- | | `exchange` | string | no | | Filter by venue | | `market_type` | string | no | | Filter by market type | | `symbol` | string | no | | Filter by symbol | | `datatype` | string | no | | Filter by datatype | | `presence` | string | no | | `present`, `absent`, or `stale` | ```json { "tool": "governance_catalog", "arguments": { "exchange": "coinbase", "presence": "present" } } ``` Abridged; each row also carries `kind`, `expected_cadence_ms`, `is_active`, `row_count`, `first_seen_us`, `last_seen_us`, `measured_cadence_ms`, `observed_at_us`, `alert`, `staleness_ms` and `reconnect_count`. ```json [ { "exchange": "coinbase", "market_type": "spot", "symbol": "BTC/USDT", "datatype": "orderbook", "binding_id": "c3a81f57-2d9e-4b6a-8f10-6e4d2b9a7c15", "presence": "present" } ] ``` ### stream_scorecard Completeness and quality scorecard for one of your streams. Without `window_secs` it reads the stream's latest completeness run; with it, completeness is recomputed live over a trailing window. Symbols may contain a slash (`BTC/USDT`). `completeness.status` reads `ok`, `degraded`, `critical` or `absent`, and `completeness_pct` is a fraction from 0 to 1, or `-1` when the stream has no expected bucket count. Without `window_secs`, a stream with no completeness run answers `404` with `no completeness run for …`, and an account with no collectors answers `404` with `no collectors deployed`. A `window_secs` past your plan's ceiling answers `400` with `window_secs must be between 1 and {max_secs} for your plan`. | Param | Type | Required | Default | Notes | | ------------- | ------ | -------- | ------- | -------------------------------------------------------------------- | | `exchange` | string | yes | | Venue id | | `market_type` | string | yes | | e.g. `spot` | | `symbol` | string | yes | | As the platform records it, may contain a slash | | `datatype` | string | yes | | `orderbook`, `trades`, `funding`, `open_interest`, or `liquidations` | | `window_secs` | int | no | | Recompute completeness over this trailing window (seconds) | ```json { "tool": "stream_scorecard", "arguments": { "exchange": "coinbase", "market_type": "spot", "symbol": "BTC/USDT", "datatype": "orderbook" } } ``` Abridged; the result also carries `window`, which names the run or trailing window read, and `completeness` also carries the bucket counts, `max_gap_ms` and `rows_in_window`. ```json { "stream": { "exchange": "coinbase", "market_type": "spot", "symbol": "BTC/USDT", "datatype": "orderbook" }, "completeness": { "status": "critical", "completeness_pct": 0.049 }, "quality": { "exception_count": 0, "max_severity": "none", "checks": [] }, "gaps": [] } ``` ### governance_datasets Your recorded parquet datasets in the lake, across all datatypes: one entry per binding, venue, market type, symbol and datatype among your collectors. The result is a bare array; an account with no collectors gets an empty one. `dataset_id` names the entry only; fits take their ids from `list_datasets`. | Param | Type | Required | Default | Notes | | ------ | ---- | -------- | ------- | ----- | | *none* | | | | | ```json { "tool": "governance_datasets", "arguments": {} } ``` ```json [ { "dataset_id": "8c41d07e2b9f3a55", "name": "kraken · spot · ETH-USD · trades", "binding_id": "c3a81f57-2d9e-4b6a-8f10-6e4d2b9a7c15", "venue": "kraken", "market_type": "spot", "symbol": "ETH-USD", "data_type": "trades", "file_count": 12, "size_bytes": 48211904, "mtime": "2026-11-08T17:40:00Z" } ] ``` ______________________________________________________________________ ## Fit & serve ### list_datasets List fittable datasets (venue, symbol, datatype), each with an opaque `dataset_id`. `fit_recommended` marks trades datasets in the size band a fit converges on well; it is advisory, and any dataset can be fitted. | Param | Type | Required | Default | Notes | | ------ | ---- | -------- | ------- | ----- | | *none* | | | | | ```json { "tool": "list_datasets", "arguments": {} } ``` ```json [ { "dataset_id": "3f9a2c71d04be815", "name": "kraken · ETH-USD · trades", "venue": "kraken", "symbol": "ETH-USD", "data_type": "trades", "file_count": 12, "size_bytes": 48211904, "mtime": "2026-11-08T17:40:00Z", "n_events": 701, "fit_recommended": true } ] ``` ### fit_pricing The current price of one Hawkes fit, in compute units, so a client can report the cost before it runs a fit. The server reads it from `action_rates.hawkes_fit_compute` in the public catalog at . A fit is checked against the compute balance before it starts and is charged only when it converges. | Param | Type | Required | Default | Notes | | ------ | ---- | -------- | ------- | ----- | | *none* | | | | | ```json { "tool": "fit_pricing", "arguments": {} } ``` The result holds two fields. Read the price live; this page quotes none. | Field | Type | Holds | | ----------------- | ------ | ------------------------------------- | | `hawkes_fit_cost` | int | Compute units one converged fit draws | | `token_kind` | string | Always `compute` | ### fit_hawkes Fit a univariate Hawkes process (MLE, exponential kernel) to a dataset and persist it. Returns the fitted parameters and diagnostics; the chart series are omitted — fetch them with [`get_fit`](#get_fit). Prefer a trades dataset. | Param | Type | Required | Default | Notes | | --------------- | ------ | -------- | ----------------- | ---------------------------------------------------------------------------------------------------------------- | | `dataset_id` | string | yes | | From `list_datasets` | | `tolerance` | float | no | `50` | Convergence threshold on the gradient infinity-norm, per training event. Raise it after a `Not converged` error | | `max_iter` | int | no | `50000` | Optimizer iteration cap | | `train_ratio` | float | no | `0.8` | Train split fraction | | `learning_rate` | float | no | `1e-2` | Scale of the optimizer's first step | | `seed` | int | no | | Recorded with the fit | | `aggregate` | bool | no | `true` for trades | Aggregate fills into taker orders before fitting; `false` fits the raw fills. Orderbook data is never aggregated | The tool leaves out every optional field you omit, so the platform default in the table applies, and `config` in the result echoes the values used. The `tolerance` description in the tool's schema still names `1e3`; the default that applies is `50`. By default a fit takes at most 1,000,000 events and runs for at most 300 seconds ([Platform limits](https://aetelier.xyz/docs/help/platform-limits/#fits)). A `400` with `Not converged after …` means the fit did not converge and was not charged: refit with a higher `tolerance`. A `402` is not a convergence problem — see [Reading a 402](https://aetelier.xyz/docs/help/mcp-errors/#reading-a-402). ```json { "tool": "fit_hawkes", "arguments": { "dataset_id": "3f9a2c71d04be815", "tolerance": 500 } } ``` Abridged; the result also carries `baseline`, `interarrival`, `derived`, `history_tail_ms` and provenance fields such as `dataset_ref`, `dataset_sha256` and `engine_version`. ```json { "fit_id": "7c21e0d4-5b8a-4f3e-9d61-2a7b0c9e4f15", "model": "hawkes_exponential", "data_type": "trades", "config": { "tolerance": 500.0, "max_iter": 50000, "train_ratio": 0.8, "learning_rate": 0.01, "aggregate": true }, "parameters": { "mu": 0.0021, "alpha": 0.38, "beta": 2.07 }, "diagnostics": { "converged": true, "iterations": 1842, "branching_ratio": 0.184 }, "data": { "n_events_total": 701, "n_events_train": 560, "n_events_test": 141 } } ``` ### list_fits List the caller's fit runs, newest first, up to 200. | Param | Type | Required | Default | Notes | | ------ | ---- | -------- | ------- | ----- | | *none* | | | | | ```json { "tool": "list_fits", "arguments": {} } ``` Abridged; each entry also carries the fit's `config`, `seed`, event counts and provenance fields. ```json [ { "fit_id": "7c21e0d4-5b8a-4f3e-9d61-2a7b0c9e4f15", "dataset_ref": "kraken ETH-USD trades", "data_type": "trades", "status": "converged", "converged": true, "branching_ratio": 0.184, "created_at": "2026-11-08T17:50:00+00:00" } ] ``` ### get_fit Fetch a persisted fit artifact by `fit_id`, including the full chart series (`intensity`, `residual_ecdf`, `residual_qq`). | Param | Type | Required | Default | Notes | | -------- | ------ | -------- | ------- | -------------------------------- | | `fit_id` | string | yes | | From `fit_hawkes` or `list_fits` | ```json { "tool": "get_fit", "arguments": { "fit_id": "7c21e0d4-5b8a-4f3e-9d61-2a7b0c9e4f15" } } ``` Abridged; the artifact carries every field `fit_hawkes` returns, plus `series`. ```json { "fit_id": "7c21e0d4-5b8a-4f3e-9d61-2a7b0c9e4f15", "diagnostics": { "converged": true, "branching_ratio": 0.184 }, "series": { "intensity": [ ], "residual_ecdf": [ ], "residual_qq": [ ] } } ``` ### forecast_fit Forecast event arrivals from a stored fit — median plus a p25/p75 band, as gaps since the end of the training window. Reproducible for a given seed. | Param | Type | Required | Default | Notes | | ------------ | ------ | -------- | ------- | ------------------------------------------------------------------------------------------------- | | `fit_id` | string | yes | | The fit to forecast from | | `n_forecast` | int | no | `50` | Steps to forecast, clamped to 1–5000 | | `mc_paths` | int | no | `500` | Monte-Carlo paths, capped at 5000; `>1` gives a p25/p75 band, `0` or `1` a deterministic forecast | | `seed` | int | no | `42` | Reproducibility seed | ```json { "tool": "forecast_fit", "arguments": { "fit_id": "7c21e0d4-5b8a-4f3e-9d61-2a7b0c9e4f15", "n_forecast": 10 } } ``` ```json { "fit_id": "7c21e0d4-5b8a-4f3e-9d61-2a7b0c9e4f15", "seed": 42, "mc_paths": 500, "deterministic": false, "current_ts_ms": 59921.4, "n_forecast": 10, "points": [ { "index": 0, "gap_ms": 812.5, "gap_p25_ms": 301.2, "gap_p75_ms": 1690.8, "ts_ms": 60733.9, "ts_p25_ms": 60222.6, "ts_p75_ms": 61612.2 } ] } ``` ______________________________________________________________________ ## Clarion Clarion attests one of your completed traces on Solana devnet. Request an attestation, poll it until it is `bound`, then read the server's report or download the record and verify it yourself. Attestations carry no charge during the Solana devnet beta. Traces come from tracing, which is open to selected accounts — see [Feature access](https://aetelier.xyz/docs/help/tiers/index.md). These tools call the platform with your API key. A refused call reads `clarion : …`; a malformed id is refused before any call is made. ### clarion_request Request a Clarion attestation (`trace-completed.v1`) of one of your completed traces. Returns the request; poll [`clarion_status`](#clarion_status) until it is `bound` or `failed`. Asking again for the same trace returns its open or bound request; after a `failed` request, asking again opens a new one. A request for a trace that is still running waits at `requested` until the trace completes. An account holds at most 20 open requests; past that the tool answers `429` with `too many requests: at most 20 open requests`. Wait for an open request to bind or fail, then ask again. | Param | Type | Required | Default | Notes | | ---------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------------------------- | | `trace_id` | string | yes | | Id of one of your completed traces, such as `tr_4ab6b4c50ac9`; 1 to 64 characters of `[A-Za-z0-9_-]` | ```json { "tool": "clarion_request", "arguments": { "trace_id": "tr_4ab6b4c50ac9" } } ``` ```json { "id": "6f1d2c3a-8b4e-4c7a-9e21-5d0b7a3f8c19", "trace_id": "tr_4ab6b4c50ac9", "method": "trace-completed.v1", "status": "requested", "error": null, "requested_at": "2026-11-08T18:02:11.412Z", "updated_at": "2026-11-08T18:02:11.412Z", "cluster": null, "program_id": null, "window_id": null, "record_id": null, "window": null } ``` ### clarion_status Status of a Clarion request by `request_id`, or every request when it is omitted (`{"requests": [...]}`, newest first, up to 100). Status moves `requested`, `built`, `committed`, `revealed`, `bound`; a bound request carries its `record_id` and on-chain `window`. A `failed` request carries `error`: `attestation failed`, or a trace message such as `trace {trace_id} failed` or `trace {trace_id} is not visible to its requester`. | Param | Type | Required | Default | Notes | | ------------ | ------ | -------- | ------- | ---------------------------------------------------------------------- | | `request_id` | string | no | | Request id (a UUID) from `clarion_request`; omit to list every request | ```json { "tool": "clarion_status", "arguments": { "request_id": "6f1d2c3a-8b4e-4c7a-9e21-5d0b7a3f8c19" } } ``` ```json { "id": "6f1d2c3a-8b4e-4c7a-9e21-5d0b7a3f8c19", "trace_id": "tr_4ab6b4c50ac9", "method": "trace-completed.v1", "status": "bound", "error": null, "requested_at": "2026-11-08T18:02:11.412Z", "updated_at": "2026-11-08T18:09:32.725Z", "cluster": "devnet", "program_id": "8GirLY…", "window_id": 1, "record_id": "b2e7c901-4d3a-4f68-8a1c-0e9d4b7f2a63", "window": { "address": "…", "slot_start": 421337600, "slot_end": 421337750, "root": "…", "commit_slot": 421337760, "commit_signature": "…", "reveal_slot": 421337910, "reveal_signature": "…", "status": "revealed", "committed_at": "2026-11-08T18:06:01.118Z", "revealed_at": "2026-11-08T18:09:12.540Z" } } ``` ### clarion_report Server verification report of a bound Clarion record: layer 1 `formulae`, layer 2 `chain`, layer 3 `artifacts`. Each layer reads `pass`, `pass_withheld` (partial, because files are withheld), `fail` or `skipped`, and `passed` is false when any layer fails. The report checks the window snapshot stored when the record bound. It is a convenience; verify independently with [`clarion_download`](#clarion_download). It works for a record you requested or one shared with you. Before the record binds it answers `409` with `conflict: record is not bound yet`. | Param | Type | Required | Default | Notes | | ----------- | ------ | -------- | ------- | ----------------------------------------------------- | | `record_id` | string | yes | | `record_id` of a bound request, from `clarion_status` | ```json { "tool": "clarion_report", "arguments": { "record_id": "b2e7c901-4d3a-4f68-8a1c-0e9d4b7f2a63" } } ``` ```json { "record_id": "b2e7c901-4d3a-4f68-8a1c-0e9d4b7f2a63", "passed": true, "state": "Revealed", "layers": [ { "layer": 1, "name": "formulae", "outcome": "pass", "detail": null }, { "layer": 2, "name": "chain", "outcome": "pass", "detail": null }, { "layer": 3, "name": "artifacts", "outcome": "pass_withheld", "detail": "withheld: tracer_params.v1.json (0 fields and 1 file hash not re-derived)" } ], "window_source": "window.json, read from the chain by the operator at bind" } ``` ### clarion_download Download a bound Clarion record into `//`: the attestation, released artifacts, withheld declaration and window snapshot, each checked against its sha256. Withheld files are not downloaded; their names come back in `withheld`. The result also lists the shell commands that clone and build [aetelier-clarion](https://github.com/aetelierxyz/aetelier-clarion) v0.1.0 next to the record, read its window from a public Solana RPC, and verify it. The tool does not run them; they need `git` and a Rust toolchain. Downloading a record shared with you logs each file for the record's owner. Before the record binds it answers `409` with `conflict: record is not bound yet`. Over the hosted endpoint nothing is written on the server. The result carries `record_id`, `files` (each released file's `filename`, `sha256` and `url`), `withheld`, `fetch` (shell commands that create `/`, download each file with `$AETELIER_API_KEY` and check its sha256) and the same `verify` commands, relative to the directory you run them in. | Param | Type | Required | Default | Notes | | ----------- | ------ | -------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `record_id` | string | yes | | `record_id` of a bound request, from `clarion_status` | | `dir` | string | no | `AETELIER_CLARION_DIR`, else `clarion-records` | Directory that receives `/`; a relative path resolves against the MCP server's working directory. Ignored over the hosted endpoint | ```json { "tool": "clarion_download", "arguments": { "record_id": "b2e7c901-4d3a-4f68-8a1c-0e9d4b7f2a63", "dir": "/work/clarion" } } ``` ```json { "record_id": "b2e7c901-4d3a-4f68-8a1c-0e9d4b7f2a63", "dir": "/work/clarion/b2e7c901-4d3a-4f68-8a1c-0e9d4b7f2a63", "files": [ { "filename": "attestation.json", "sha256": "…", "bytes": 4127, "path": "/work/clarion/b2e7c901-4d3a-4f68-8a1c-0e9d4b7f2a63/attestation.json" }, { "filename": "corrected_ledger.json", "sha256": "…", "bytes": 1893, "path": "/work/clarion/b2e7c901-4d3a-4f68-8a1c-0e9d4b7f2a63/corrected_ledger.json" }, { "filename": "fillrates.json", "sha256": "…", "bytes": 912, "path": "/work/clarion/b2e7c901-4d3a-4f68-8a1c-0e9d4b7f2a63/fillrates.json" }, { "filename": "window.json", "sha256": "…", "bytes": 655, "path": "/work/clarion/b2e7c901-4d3a-4f68-8a1c-0e9d4b7f2a63/window.json" }, { "filename": "withheld.json", "sha256": "…", "bytes": 214, "path": "/work/clarion/b2e7c901-4d3a-4f68-8a1c-0e9d4b7f2a63/withheld.json" } ], "withheld": ["tracer_params.v1.json"], "verify": [ "test -d /work/clarion/aetelier-clarion-v0.1.0 || git clone --quiet --depth 1 --branch v0.1.0 https://github.com/aetelierxyz/aetelier-clarion /work/clarion/aetelier-clarion-v0.1.0", "(cd /work/clarion/aetelier-clarion-v0.1.0 && cargo build --release --locked --workspace --target-dir target)", "/work/clarion/aetelier-clarion-v0.1.0/target/release/clarion-admin --rpc-url https://api.devnet.solana.com --program-id 8GirLY… show --window-id 1 > /work/clarion/b2e7c901-4d3a-4f68-8a1c-0e9d4b7f2a63.window.json", "/work/clarion/aetelier-clarion-v0.1.0/target/release/clarion-formulae verify --attestation /work/clarion/b2e7c901-4d3a-4f68-8a1c-0e9d4b7f2a63/attestation.json --window /work/clarion/b2e7c901-4d3a-4f68-8a1c-0e9d4b7f2a63.window.json --artifacts /work/clarion/b2e7c901-4d3a-4f68-8a1c-0e9d4b7f2a63 --formulae-dir /work/clarion/aetelier-clarion-v0.1.0/formulae" ] } ``` # Worked examples **Server:** `aetelier-mcp` · **Form:** natural-language ask → tool sequence → results Each flow is a full engagement: what you ask the client, the tools it drives to satisfy the ask, and the results it reads back between steps. You speak in natural language; the client picks the tools and chains them, reading each result before the next and adapting as it goes. Results are illustrative and abridged — live values vary. Health first, cleanup last A robust flow opens with `platform_health` and, for a deploy, closes with `stop_collector`. The flows below assume a reachable platform. Errors are results, not failures A backend error comes back as `{"ok": false, "error": "..."}`, with `code` and `docs_url` when the backend sent them — an ordinary tool result the client reads and adapts to in the same loop. Flow 2 shows this: a non-converged fit returns a `400` and becomes a looser-tolerance refit. ______________________________________________________________________ ## Flow 1 — Deploy a collector and confirm data is landing **Ask** — "Stand up a Binance BTC spot collector in a low-latency region and tell me once it's actually producing data." This is a remote bring-your-own deploy: `deploy_collector` registers the service and mints an agent JWT, and **you** run your own agent against the gateway with that JWT. The client drives: `platform_health` → `list_cex_options` → `query_colocation` → `deploy_collector` → `collector_health` → `stop_collector` **Step 1 — confirm the platform answers** ```json { "tool": "platform_health", "arguments": {} } ``` ```json { "overseer": "ok", "api_key": "ok", "overdex_server": "ok", "overwatch": "ok", "overplex": "ok" } ``` **Step 2 — resolve the venue and its native symbol format** The client consults the deployable options before it commits to a symbol string, since each venue names symbols differently. ```json { "tool": "list_cex_options", "arguments": {} } ``` ```json { "venues": [ { "exchange": "binance", "label": "Binance", "symbol_format": "concatenated uppercase", "symbol_example": "BTCUSDT", "market_types": ["spot"], "orderbook_depths": [5, 10, 20, 50, 100, 500, 1000], "default_orderbook_depth": 50, "datatypes": [ { "name": "orderbook", "available": true }, { "name": "trades", "available": true } ] } ] } ``` Binance names BTC spot as `BTCUSDT`, supports `spot`, and offers depth `50`. **Step 3 — pick the region** ```json { "tool": "query_colocation", "arguments": { "exchange": "binance" } } ``` ```json { "count": 1, "exchanges": [ { "exchange": "binance", "region": "ap-northeast-1", "score": 0.96 } ] } ``` **Step 4 — register the remote collector** ```json { "tool": "deploy_collector", "arguments": { "exchange": "binance", "symbols": ["BTCUSDT"], "market_type": "spot", "region": "ap-northeast-1" } } ``` ```json { "service_id": "63060972-4c1e-4b8a-9f2d-7a5e0c3b1d84", "binding_id": "cfb7688a-2d3f-4e91-8b6c-15a9e4f07d23", "gateway_url": "https://gateway.aetelier.xyz", "token": "your-agent-jwt" } ``` The deploy returns the `service_id`, the `binding_id`, the gateway URL, and an agent JWT. Nothing is running yet: this is a bring-your-own collector, so you launch the agent yourself, pointing it at the returned gateway URL and passing the JWT. **Step 5 — run your own agent against the gateway** Set `AETELIER_GATEWAY_URL` to the deploy's `gateway_url` and `AETELIER_TOKEN` to its `token`. The agent reads the binding and service ids from the JWT's claims, so neither is a separate variable. The webapp's fleet view shows this command for the binding, with a freshly minted token: ```bash docker run -d --pull always --restart unless-stopped --name aetelier-agent-binance-orderbook-cfb7 \ -v "$HOME/aetelier-data:/home/agent" \ -e AETELIER_GATEWAY_URL="https://gateway.aetelier.xyz" \ -e AETELIER_TOKEN=your-agent-jwt \ -e RUST_LOG=info \ ghcr.io/aetelierxyz/aetelier-agent:latest ``` The full variable contract is in [`aetelier-agent` → Environment variables](https://aetelier.xyz/docs/operations/agent/#environment-variables). The JWT is a credential scoped to this binding. Treat it like a password: keep it out of shared configs and version control. **Step 6 — confirm data is landing** A fresh deploy has no lake rows for the first few minutes, so `collector_health` leads with liveness and reads `starting` rather than reporting a failure. Just after the agent starts: ```json { "tool": "collector_health", "arguments": { "service_id": "63060972-4c1e-4b8a-9f2d-7a5e0c3b1d84" } } ``` ```json { "service_id": "63060972-4c1e-4b8a-9f2d-7a5e0c3b1d84", "verdict": "starting", "liveness": { "connected": true, "heartbeat_age_s": 4, "ws_latency_ms": null }, "landing": { "rows_last_5m": 0, "total_rows": 0, "expected_first_data_by": "2026-07-04T18:05:00Z" } } ``` A few minutes later, once rows land: ```json { "tool": "collector_health", "arguments": { "service_id": "63060972-4c1e-4b8a-9f2d-7a5e0c3b1d84" } } ``` ```json { "service_id": "63060972-4c1e-4b8a-9f2d-7a5e0c3b1d84", "verdict": "healthy", "liveness": { "connected": true, "heartbeat_age_s": 3, "ws_latency_ms": null }, "landing": { "rows_last_5m": 8421, "total_rows": 33110, "last_row_age_s": 2 } } ``` The verdict flips to `healthy` once fresh rows land, and the client tells you data is flowing. **Step 7 — tear it down** ```json { "tool": "stop_collector", "arguments": { "service_id": "63060972-4c1e-4b8a-9f2d-7a5e0c3b1d84" } } ``` ```json { "agent_id": "5b0e2c71-9a44-4f3e-8d16-c2a7f90b3e58", "binding_id": "cfb7688a-2d3f-4e91-8b6c-15a9e4f07d23", "session_id": "e41d9a03-6c2b-4f87-a5e9-0b3c7d18f246", "command_id": "9d7f3b2e-1a65-4c08-b4f3-6e2a8c05d917" } ``` The stop is accepted at once and returns the release command. The service reads `stopping` until the agent acknowledges the release, then `stopped`. Stop the collector when you are done to release the binding; a running collector draws [data units](https://aetelier.xyz/docs/help/tokens/index.md) once per UTC day. Between deploy and stop you can pause and resume the task with `collector_command` (`task_pause`, `task_resume`). ______________________________________________________________________ ## Flow 2 — Fit and forecast a model **Ask** — "Fit a Hawkes model to Kraken ETH trades and forecast the next 10 events." This flow adapts mid-loop: the first fit does not converge at the default tolerance, so the client reads the error and refits with a looser one. The client drives: `list_datasets` → `fit_pricing` → `fit_hawkes` → `get_fit` → `forecast_fit` **Step 1 — pick a dataset** Hawkes fits want an event stream, so the client picks a trades dataset. `fit_recommended` marks a trades set in the size band a fit converges on well. ```json { "tool": "list_datasets", "arguments": {} } ``` ```json [ { "dataset_id": "9f3a61c2d40b7e85", "venue": "kraken", "symbol": "ETH-USD", "data_type": "trades", "n_events": 702, "fit_recommended": true } ] ``` **Step 2 — check the fit price** A fit draws compute units, and only when it converges. The client reads the price and reports it before it runs one. ```json { "tool": "fit_pricing", "arguments": {} } ``` ```text { "hawkes_fit_cost": {cost}, "token_kind": "compute" } ``` `hawkes_fit_cost` is the price in compute units, the catalog's `action_rates.hawkes_fit_compute`. The balance is checked against it before the fit starts; if it is short, `fit_hawkes` returns a `402` and runs nothing. See [Units and the 402 error](https://aetelier.xyz/docs/help/tokens/#the-402-balance-errors). **Step 3 — first fit (does not converge)** ```json { "tool": "fit_hawkes", "arguments": { "dataset_id": "9f3a61c2d40b7e85" } } ``` ```json { "ok": false, "error": " 400: validation error: estimation did not produce a usable result: Not converged after 50000 iterations (gradient norm = 3.418207e4)" } ``` The `400` is an ordinary result, and nothing was charged. `Not converged after` is the signal to raise `tolerance` above the server default of `50`. A `402` is a different case: no tolerance clears it, so the client stops and reports it ([Reading a 402](https://aetelier.xyz/docs/help/mcp-errors/#reading-a-402)). **Step 4 — refit with a looser tolerance** ```json { "tool": "fit_hawkes", "arguments": { "dataset_id": "9f3a61c2d40b7e85", "tolerance": 500 } } ``` ```json { "fit_id": "7c21e0a4-5b8f-4d0e-9a63-2f1c8b7d4e10", "config": { "tolerance": 500, "max_iter": 50000, "train_ratio": 0.8 }, "parameters": { "mu": 0.00017, "alpha": 0.0042, "beta": 0.0231 }, "diagnostics": { "converged": true, "branching_ratio": 0.182, "iterations": 1843 }, "baseline": { "lr_reject_h0": true }, "data": { "n_events_train": 561 } } ``` The refit converged, so it draws the fit price. `baseline.lr_reject_h0` is `true`: the likelihood-ratio test rejects a plain Poisson model, and a branching ratio of 0.182 says the series is mildly self-exciting. If it still had not converged, the client would raise `tolerance` again. **Step 5 — read the full fit** `fit_hawkes` omits the chart series to keep the result small. The client fetches the full artifact — parameters, diagnostics, and series — with `get_fit`. ```json { "tool": "get_fit", "arguments": { "fit_id": "7c21e0a4-5b8f-4d0e-9a63-2f1c8b7d4e10" } } ``` ```json { "fit_id": "7c21e0a4-5b8f-4d0e-9a63-2f1c8b7d4e10", "diagnostics": { "converged": true, "branching_ratio": 0.182 }, "series": { "intensity": [ ], "residual_ecdf": [ ], "residual_qq": [ ] } } ``` **Step 6 — forecast from the fit** ```json { "tool": "forecast_fit", "arguments": { "fit_id": "7c21e0a4-5b8f-4d0e-9a63-2f1c8b7d4e10", "n_forecast": 10 } } ``` ```json { "fit_id": "7c21e0a4-5b8f-4d0e-9a63-2f1c8b7d4e10", "seed": 42, "mc_paths": 500, "deterministic": false, "n_forecast": 10, "points": [ { "index": 0, "gap_ms": 3920, "gap_p25_ms": 1180, "gap_p75_ms": 6710 }, { "index": 9, "gap_ms": 48183, "gap_p25_ms": 37950, "gap_p75_ms": 59420 } ] } ``` Each point's `gap_ms` is the median cumulative gap since the end of the training data, with `gap_p25_ms` and `gap_p75_ms` as the band; the reply above shows the first and last of the 10 points. The client reports the 10th event near 48 seconds out. The same `seed` gives the same forecast; raise `mc_paths` to cut Monte-Carlo noise in the band. ______________________________________________________________________ ## Flow 3 — Audit an existing stream **Ask** — "How complete is the Coinbase BTC/USDT order book?" A short two-step read: the client resolves the stream in the governance catalog, then scores it. Governance reads draw no units. The client drives: `governance_catalog` → `stream_scorecard` **Step 1 — find the stream** ```json { "tool": "governance_catalog", "arguments": { "exchange": "coinbase", "datatype": "orderbook" } } ``` ```json [ { "exchange": "coinbase", "market_type": "spot", "symbol": "BTC/USDT", "datatype": "orderbook", "presence": "present" } ] ``` **Step 2 — score it** ```json { "tool": "stream_scorecard", "arguments": { "exchange": "coinbase", "market_type": "spot", "symbol": "BTC/USDT", "datatype": "orderbook" } } ``` ```json { "stream": { "exchange": "coinbase", "market_type": "spot", "symbol": "BTC/USDT", "datatype": "orderbook" }, "completeness": { "status": "critical", "completeness_pct": 0.049 }, "quality": { "exception_count": 0, "max_severity": "none", "checks": [] } } ``` Completeness is `critical` (`completeness_pct` is a 0–1 ratio, so 4.9%) while quality shows no exceptions — the stream is sparse, not corrupt. Add `window_secs` to recompute completeness live over a trailing window. ______________________________________________________________________ ## Compose the whole engagement **Ask** — "Stand up a Binance BTC collector in a low-latency region, confirm it's landing data, audit an established stream, fit a Hawkes model to a trades dataset, forecast from it, then tear the collector down." A capable client chains the flows above into one engagement, reading each result before the next and adapting as it goes: ``` flowchart LR H[platform_health] --> L[list_cex_options] L --> Q[query_colocation] Q --> D[deploy_collector] D --> CH[collector_health] CH --> G[stream_scorecard] G --> F[fit_hawkes] F --> FC[forecast_fit] FC --> S[stop_collector] ``` One engagement: check health, resolve the venue and region, deploy a remote collector, watch it land data, audit a stream's governance, fit a Hawkes model, forecast from the fit, and stop the collector. Each arrow is a tool call whose result the client reads before the next, adapting as it goes — a looser tolerance on a non-converged fit, `starting` versus `healthy` on a fresh deploy. # SDK # SDK overview The Aetelier SDK is a Rust workspace of six crates for market-data research on the Aetelier platform: - **`aetelier-types`** — the shared data model: trades, order books, timestamps in UTC epoch microseconds, and the wire types the platform speaks. - **`aetelier-connect`** — venue connectivity: WebSocket clients with reconnect, the worker framework, book reconstruction, and the conformance-certified venue adapters. - **`aetelier-io`** — columnar persistence: Parquet writers and readers for every datatype, filename conventions, and loss accounting artifacts. - **`aetelier-entrepot`** — archive access: an S3 reader for venue archives with integrity verification and cost accounting. - **`aetelier-telemetry`** — metrics and structured telemetry for long-running collectors. - **`aetelier-sdk`** — the facade crate that re-exports the workspace surface behind one dependency. The mental model: connect ingests and validates, types carries the rows, io persists them, entrepot replays archives, telemetry watches the whole thing. ## Adding the SDK to a project ```toml # Cargo.toml [dependencies] aetelier-sdk = { git = "https://github.com/aetelierxyz/aetelier-sdk", tag = "v0.1.0" } ``` The crates are not on crates.io, so the dependency resolves from git. The tag is mutable; pin `rev = ""` for a reproducible build. ## What's documented where - **[API reference](https://aetelier.xyz/docs/sdk/api/index.md)** — auto-generated from the SDK's public Rust API by `scripts/cargo_doc_to_md.py`. Updated on each docs build that runs against a checkout of `aetelier-sdk`. - **[Backend reference](https://aetelier.xyz/docs/backend/index.md)** — the wire contract the SDK speaks to. Read this if you're building a non-Rust client or debugging at the protocol level. - **[Guides](https://aetelier.xyz/docs/guides/index.md)** — task-oriented walkthroughs. ## Source The crate lives at [`aetelierxyz/aetelier-sdk`](https://github.com/aetelierxyz/aetelier-sdk). File issues against the SDK in that repo; file documentation issues against this repo (`aetelier-webdocs`). # Getting started The shortest path through the Aetelier SDK. By the end of this page you will have a Rust project that connects to Bybit, streams a few minutes of live order-book and trade data, and writes a small Parquet file you can read back in any analytics tool. If you want the full runnable variant with logging, error handling, and a multi-worker manifest, jump to [Tutorial 1: Bybit → Parquet](https://aetelier.xyz/docs/guides/01-bybit-to-parquet/index.md). ## Prerequisites - **Rust** 1.88+ (the workspace uses edition 2024). - **A Bybit account** is **not** required — we'll use the public WebSocket endpoint, which doesn't need authentication for market data. ## 1. Create a new crate ```bash cargo new --bin aetelier-quickstart cd aetelier-quickstart ``` ## 2. Add `aetelier-sdk` to `Cargo.toml` The SDK is distributed from GitHub (the core crates are not published on crates.io): ```toml [package] name = "aetelier-quickstart" version = "0.1.0" edition = "2024" [dependencies] aetelier-sdk = { git = "https://github.com/aetelierxyz/aetelier-sdk", tag = "v0.1.0", features = ["parquet"] } tokio = { version = "1", features = ["full"] } anyhow = "1" clap = { version = "4", features = ["derive"] } tracing = "0.1" tracing-subscriber = { version = "0.3", features = ["env-filter"] } ``` `aetelier-sdk` is a facade crate — adding it pulls in the workspace crates you'll touch (`aetelier-types`, `aetelier-connect`, `aetelier-io`) so you don't have to list each one. The `parquet` feature opts into the Parquet sink and the Parquet reader/writer functions in `aetelier-io`. ## 3. Describe the worker in a TOML manifest Collection is manifest-driven: a `MarketWorker` is configured from a TOML file that says which exchange, which symbols, which data types, how to synchronize, and where output goes. Save this as `worker.toml`: ```toml [collect] exchange = "bybit" gap_threshold_secs = 30 [collect.datatypes.orderbook] enabled = true depth = 50 [collect.datatypes.trades] enabled = true [collect.sync] sync_mode = "on_time" flush_threshold = 3000 [collect.sync.update_frequency] value = 200 unit = "Millis" [[collect.output]] type = "parquet" dir = "data/snapshots/" [[collect.output]] type = "terminal" [[workers]] symbol = "BTCUSDT" ``` Two outputs fan out at once — Parquet for persistence, terminal for visibility. The 200 ms grid with `flush_threshold = 3000` means one Parquet flush every 10 minutes of snapshots. ## 4. The minimum viable runner ```rust use std::path::PathBuf; use aetelier_sdk::aetelier_connect::{ config::workers::MarketWorkerManifest, workers::market_worker::MarketWorker, }; use clap::Parser; use tokio::sync::watch; #[derive(Parser)] struct Cli { #[arg(short, long, default_value = "worker.toml")] config: PathBuf, } #[tokio::main] async fn main() -> anyhow::Result<()> { tracing_subscriber::fmt::init(); let cli = Cli::parse(); let manifest = MarketWorkerManifest::from_toml(&cli.config)?; let configs = manifest.resolve_all(); anyhow::ensure!(!configs.is_empty(), "manifest is empty"); let (shutdown_tx, shutdown_rx) = watch::channel(false); tokio::spawn(async move { tokio::signal::ctrl_c().await.expect("ctrl-c handler"); let _ = shutdown_tx.send(true); }); let worker = MarketWorker::from_config(configs.into_iter().next().unwrap())?; let report = worker.run(shutdown_rx).await?; println!( "collected {} events into {} snapshots ({} flushes)", report.ingestion.total_events, report.snapshots_produced, report.flushes, ); Ok(()) } ``` Run it: ```bash cargo run ``` You'll see one terminal line per 200 ms snapshot. Press Ctrl-C to stop; the worker shuts down gracefully and reports what it collected. After a few minutes you'll have a tree like: ```text data/snapshots/ ├── orderbooks/bybit_BTCUSDT_ob_sync_.parquet └── trades/bybit_BTCUSDT_trades_sync_.parquet ``` The filename convention (`{symbol}_{datatype}_{mode}_{ts}`) is documented on the [`aetelier-io`](https://aetelier.xyz/docs/sdk/io/#filename-convention) page. ## What you just learned | Concept | Where it lives | | ------------------------------------- | ------------------------------------------------------------------------------------------- | | Exchange clients with reconnect | [`aetelier-connect`](https://aetelier.xyz/docs/sdk/connect/index.md) | | Workers that synchronize feeds | [`aetelier-connect`](https://aetelier.xyz/docs/sdk/connect/index.md) `MarketWorker` | | TOML worker manifests | [`aetelier-connect`](https://aetelier.xyz/docs/sdk/connect/index.md) `MarketWorkerManifest` | | Output fan-out (parquet, terminal) | `[[collect.output]]` in the manifest | | Parquet readers / writers | [`aetelier-io`](https://aetelier.xyz/docs/sdk/io/index.md) | | The data types this all flows through | [`aetelier-types`](https://aetelier.xyz/docs/sdk/types/index.md) | ## Where to go next - [Tutorial 1: Bybit → Parquet](https://aetelier.xyz/docs/guides/01-bybit-to-parquet/index.md) — the same flow with multi-symbol manifests, proper error handling, and graceful shutdown. - [Tutorial 2: multi-exchange sync](https://aetelier.xyz/docs/guides/02-multi-exchange-sync/index.md) — fanning out across Bybit, Coinbase, Binance, Kraken with a single synchronizer. - [Architecture](https://aetelier.xyz/docs/sdk/architecture/index.md) — how the crates fit together. # Architecture The Aetelier SDK is a Cargo workspace layered so each level depends on the ones below and not on the ones above. The story runs from raw exchange WebSocket traffic at the bottom to per-datatype Parquet at the top, with one canonical schema layer in the middle. Ingestion has two generations that live side by side in `aetelier-connect`: a **legacy per-venue path** and a **framework path**. The framework path is the default for managed order-book and trade streams. Both decode the same wire types and emit the same normalized `Orderbook` and `Trade`, so downstream consumers see one schema regardless of which produced a stream. ## Crate-level dependency graph ``` flowchart TB types["aetelier-types
schema
(no internal deps)"] connect["aetelier-connect
WebSocket clients,
ingestion framework,
workers, sinks"] io["aetelier-io
Parquet / CSV / JSON
readers + writers"] telemetry["aetelier-telemetry
OpenTelemetry
instrumentation"] sdk["aetelier-sdk
umbrella façade
(re-exports)"] types --> connect types --> io telemetry -.->|feature: telemetry| connect io --> connect types --> sdk connect --> sdk io --> sdk ``` *Diagram: `aetelier-types` is the dependency-free schema foundation every other crate builds on. `aetelier-connect` and `aetelier-io` are the connectivity and persistence layers. `aetelier-telemetry` cross-cuts `aetelier-connect` behind its `telemetry` feature. `aetelier-sdk` is an umbrella façade re-exporting `types`, `connect`, and `io`.* `aetelier-types` has zero internal dependencies — it is the foundation every other crate depends on. `aetelier-connect` and `aetelier-io` are the connectivity and persistence layers. `aetelier-telemetry` cross-cuts: behind the `telemetry` feature it instruments `aetelier-connect`'s workers and sinks, and is otherwise absent from the build graph. `aetelier-sdk` is the umbrella crate — depend on it for one import that pulls in the schema, connectivity, and I/O layers. ## The two ingestion generations Both generations decode the same wire types and emit the same normalized `Orderbook` and `Trade`. They differ in where per-venue behaviour lives. | Generation | Per-venue surface | Shared surface | Reconstruction | | -------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------- | | Legacy path | A full per-source `WssClient` + `WssDecoder` + `ExchangeEvent` per venue | Reconnect / backoff plumbing | Ad hoc, per client (`BookInitializer` pipeline) | | Framework path | `ProtocolHooks` + `Normalizer` + a `ReconstructionModel` choice, registered as one `ExchangeAdapter` | `WssTransport`, the drive loop, the reconstruction runtime, the checksum kit, the symbol codec | `SourcedOrderBook` / `SourcedTradeBook`, model-selected | A worker runs the framework path when `framework_ingest = true` is set under `[collect]` in its config and the requested venue resolves in the framework registry; otherwise it runs the legacy path. The framework path is the default for managed order-book and trade streams. The legacy `WssClient` / `DataWorker` / `MarketWorker` surface remains exported for bring-your-own callers and datatypes the framework does not model. The framework path is documented across four pages: - [Ingestion framework](https://aetelier.xyz/docs/sdk/framework/index.md) — the `ExchangeAdapter` model, `ProtocolHooks`, `WssTransport`, `Normalizer`, and the registry. - [Feeds and Books](https://aetelier.xyz/docs/sdk/feeds-books/index.md) — the `Feed` lifecycle and the `SourcedOrderBook` / `SourcedTradeBook` Book lifecycle. - [Reconstruction models](https://aetelier.xyz/docs/sdk/reconstruction/index.md) — `FullRefresh`, `SeqDelta`, `ChecksumDelta`, and `L3`, with their continuity predicates and checksum recipes. - [Venue coverage](https://aetelier.xyz/docs/sdk/venues/index.md) — the coverage matrix for the twelve registered adapters. ## The runtime data path ``` sequenceDiagram autonumber participant Exch as Exchange feed participant Ingest as Ingestion
(framework adapter
or legacy client) participant Worker as DataWorker /
MarketWorker participant Sync as MarketSynchronizer participant Sinks as OutputSinkSet participant IO as aetelier-io
(Parquet) Exch->>Ingest: WebSocket frames Ingest->>Worker: normalized Orderbook / Trade Worker->>Sync: event with timestamp Sync->>Worker: MarketSnapshot at grid tick Worker->>Sinks: MarketSnapshot Sinks->>IO: decomposed per-datatype rows IO-->>IO: per-datatype Parquet files ``` *Diagram: exchange frames enter through either the framework adapter or a legacy client, are normalized, synchronized onto a grid into `MarketSnapshot`s, then decomposed to per-datatype Parquet by the sinks.* Parquet on disk is where the SDK's responsibility ends. Any consumer that reads those files runs as a separate process, on its own schedule, and can run on a separate machine. ## Reading the layers ### Layer 1 — schema (`aetelier-types`) Pure type definitions. `Orderbook`, `Trade`, `MarketSnapshot`, synchronizer modes, error variants. No I/O, no networking, no async. The single source of truth for what a "trade" looks like across the SDK. A change here ripples upward by ordinary type-checking — there is no risk of two crates inventing their own `Trade`. See [`aetelier-types`](https://aetelier.xyz/docs/sdk/types/index.md). ### Layer 2 — connectivity (`aetelier-connect`) Exchange WebSocket clients with reconnect, backoff, and circuit breakers. The ingestion framework: per-venue `ExchangeAdapter`s behind a shared `WssTransport`, normalization, model-selected reconstruction, and a registry. Two worker types: `DataWorker` (raw passthrough) and `MarketWorker` (synchronized snapshots). Output sinks: channel, terminal, Parquet. See [`aetelier-connect`](https://aetelier.xyz/docs/sdk/connect/index.md) for the crate, and [Ingestion framework](https://aetelier.xyz/docs/sdk/framework/index.md) for the framework path in depth. ### Layer 3 — persistence (`aetelier-io`) Readers and writers for every top-level type, primarily Parquet. Three extension traits — `FlushToParquet`, `FlushObSyncToParquet`, `FlushAggregateToParquet` — that workers call into to persist streaming output, gated behind the `connect` + `parquet` features. A filename convention (`{symbol}_{datatype}_{mode}_{ts}.parquet`) that downstream tools parse to locate the right files for a given symbol and time range. See [`aetelier-io`](https://aetelier.xyz/docs/sdk/io/index.md). ### Cross-cutting — telemetry (`aetelier-telemetry`) OpenTelemetry instrumentation, wired into `aetelier-connect` behind the `telemetry` feature. A fixed set of metric names (`MESSAGES_RECEIVED`, `EVENT_LATENCY_MS`, `WORKER_CONNECTION_STATE`, `SINK_QUEUE_DEPTH`) shared across workers and sinks so a single operator dashboard can consume telemetry from anywhere in the SDK. See [`aetelier-telemetry`](https://aetelier.xyz/docs/sdk/telemetry/index.md). ### Umbrella — façade (`aetelier-sdk`) The umbrella crate. Depending on `aetelier-sdk` pulls in `aetelier-types`, `aetelier-connect`, and `aetelier-io` through one import, and forwards the `parquet` and `connect` feature flags to `aetelier-io`. See [SDK overview](https://aetelier.xyz/docs/sdk/index.md). ## Reading paths Most readers want one of: - **"I want to collect live data."** Start with [Getting started](https://aetelier.xyz/docs/sdk/getting-started/index.md), then [Tutorial 1: Bybit → Parquet](https://aetelier.xyz/docs/guides/01-bybit-to-parquet/index.md). - **"I want to integrate or understand a venue."** Read [Ingestion framework](https://aetelier.xyz/docs/sdk/framework/index.md) and [Venue coverage](https://aetelier.xyz/docs/sdk/venues/index.md), then [Tutorial 2: multi-exchange sync](https://aetelier.xyz/docs/guides/02-multi-exchange-sync/index.md). - **"I want to read the data I already collected."** Skip the connectivity layer and read [`aetelier-io`](https://aetelier.xyz/docs/sdk/io/index.md). For everything else, the [API reference](https://aetelier.xyz/docs/sdk/api/index.md) is the exhaustive view, organized by crate. # Ingestion framework **Family:** SDK-crate (`aetelier-connect::framework`) · **Min version:** `aetelier-connect` 0.1.0 The ingestion framework is a set of composable seams that let one shared WebSocket transport and one shared reconstruction runtime serve every exchange. A venue is integrated by filling in the parts that actually differ between exchanges — subscribe framing, heartbeat, symbol spelling, and how a book is kept in sync — behind stable traits; everything else is written once. ## The two generations Two ingestion generations live in `aetelier-connect`. They differ in where per-venue behaviour lives, not in what they produce. | Generation | Per-venue surface | Shared surface | Reconstruction | | -------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------- | | Legacy path | A full per-source WSS client + event enum per venue | Reconnect/backoff plumbing | Ad hoc, per client | | Framework path | `ProtocolHooks` + `Normalizer` + a `ReconstructionModel` choice, registered as one `ExchangeAdapter` | `WssTransport`, the drive loop, the reconstruction runtime, the checksum kit, the symbol codec | `SourcedOrderBook` / `SourcedTradeBook`, model-selected | The framework path collapses the per-venue surface to the pieces that vary and promotes reconstruction into shared, model-selected types. Both generations decode the same wire types and emit the same normalized `Orderbook` and `Trade`, so downstream consumers see one schema regardless of which path produced a stream. Turning the framework on A worker runs the framework path when `framework_ingest = true` is set under `[collect]` in its config. `MarketWorker::run_framework` then resolves the requested venues against the registry and drives them through the shared transport and reconstruction runtime. ## The adapter model A venue adapter is a single `ExchangeAdapter` that composes four seams. The adapter names its venue id, carries a static `ExchangeProfile` (symbol codec, connection budget, version pins), chooses a `ReconstructionModel` per channel, and spawns one connection carrying a set of symbols. ``` flowchart LR A["ExchangeAdapter
(one per venue)"] --> H["ProtocolHooks
subscribe · heartbeat ·
control · codec · prepare"] A --> N["Normalizer
decoded frame →
DomainEvent(s)"] A --> M["ReconstructionModel
per channel"] A --> P["ExchangeProfile
SymbolCodec ·
ConnectionBudget · versions"] H --> T["WssTransport
(shared)"] N --> T T --> D["drive loop
(shared)"] D --> R["SourceRuntime +
SourcedOrderBook /
SourcedTradeBook
(shared)"] M --> R ``` *Diagram: one per-venue `ExchangeAdapter` supplies `ProtocolHooks`, a `Normalizer`, a per-channel `ReconstructionModel`, and an `ExchangeProfile`; the `WssTransport`, drive loop, and reconstruction runtime are shared across every venue.* ### `ProtocolHooks` — the WSS protocol seam `ProtocolHooks` captures the connection behaviour that varies across exchanges. The `WssTransport` calls into it at each stage of the connect → subscribe → read loop. | Hook | Purpose | Default | | -------------------- | ---------------------------------------------------------------- | ---------------- | | `endpoint` | Base WSS URL | required | | `subscribe_frames` | Frames that subscribe a set of symbols on one socket | required | | `heartbeat` | Keep-alive strategy (`None` · `WsPong` · `Text` · `Resubscribe`) | `None` (passive) | | `on_inbound_control` | React to a control frame — `Ignore` or `Reply` | `Ignore` | | `frame_codec` | Frame encoding — `PlainText` or `Gzip` | `PlainText` | | `prepare` | Pre-subscribe bootstrap: token fetch, dynamic URL, login | no-op | `prepare` returns a `Prepared` that may override the endpoint and heartbeat and inject extra frames, covering venues with a dynamic URL or an in-band seed request without special-casing the transport. ### `WssTransport` — the shared connect-and-read loop `WssTransport` is the exchange-agnostic pump, monomorphized per venue over the `ProtocolHooks` `H` and the frame decoder `D`. It runs one lifecycle: bootstrap via `prepare` → resolve the endpoint → connect → send subscribe frames → start the heartbeat → read (inflate → control → decode) → exit. Each inbound frame is inflated per the venue codec, offered to `on_inbound_control`, then decoded to the venue event type and forwarded with its local receipt timestamp. A WS-protocol RTT ping runs independently so the connection round-trip is measured with no per-venue code. The loop returns a `WssExitReason`, which the drive loop maps onto a `TaskExit` (`Completed` · `DrainTimedOut` · `Failed`) that the worker uses to drive the task to its terminal state and to decide reconnection. ### `Normalizer` — decoded frame to `DomainEvent` A per-venue `Normalizer` maps one decoded WSS event into zero or more `DomainEvent`s — `Book(NormalizedDelta)` or `Trade`. Returning a list means a batched-trade frame yields one event per trade rather than dropping all but the first. The normalizer derives the canonical pair from the event's own venue symbol, since a socket is multi-symbol. ### `BookReconstructor` — model-selected sync Reconstruction is not per-venue code; it is a `ReconstructionModel` choice consumed by the shared `SourcedOrderBook` and `SourcedTradeBook`. The adapter picks a model per channel (a venue may run one model on its book channel and another elsewhere), and the shared `apply` path handles seeding, continuity checks, and gap detection. See [Reconstruction models](https://aetelier.xyz/docs/sdk/reconstruction/index.md). ## The registry Every compiled-in venue is listed once in `register_all`, keyed by its stable venue id and resolved into a process-wide registry at boot. `resolve` is a fail-fast self-check: it turns a request for an unknown venue into a startup error listing the missing ids, rather than a silently empty stream. ```rust let adapter = registry() .get("binance") .expect("binance is compiled in"); let model = adapter.book_model("orders"); ``` Adding a venue is one line in `register_all` plus the adapter that implements `ExchangeAdapter` over its `ProtocolHooks`, `Normalizer`, and chosen `ReconstructionModel`. ## Building a venue adapter The steps to integrate a new public order-book + trades venue: 1. Choose the `SymbolCodec` for the venue's wire symbol spelling and set the `ConnectionBudget` on its `ExchangeProfile`. 1. Implement `ProtocolHooks`: `endpoint`, `subscribe_frames`, and only the other hooks the venue needs (heartbeat, control-frame reply, gzip codec, or a `prepare` bootstrap). 1. Implement a frame decoder and a `Normalizer` that maps its events to `DomainEvent`s. 1. Choose a `ReconstructionModel` per channel (see [Reconstruction models](https://aetelier.xyz/docs/sdk/reconstruction/index.md)); provide a `RestSnapshot` seeder if the model needs one. 1. Register the adapter in `register_all`. ```rust impl ProtocolHooks for BinanceHooks { fn endpoint(&self) -> String { "wss://stream.binance.com:9443/ws".to_string() } fn subscribe_frames(&self, symbols: &[String]) -> Vec { vec![subscribe_frame(symbols)] } fn heartbeat(&self) -> Heartbeat { Heartbeat::WsPong { every: Duration::from_secs(15) } } } ``` ## See also - [Feeds and Books](https://aetelier.xyz/docs/sdk/feeds-books/index.md) — the `Feed` and Book lifecycles a running adapter drives. - [Reconstruction models](https://aetelier.xyz/docs/sdk/reconstruction/index.md) — how `apply` keeps a book in sync, per model. - [SDK architecture](https://aetelier.xyz/docs/sdk/architecture/index.md) — where `aetelier-connect` sits in the crate stack. # Governance and data # Data Governance **Governance tag:** overwatch Data Governance lets a tenant govern **their own** artifact streams: the feeds an agent produces (orderbook, trades, funding, open interest, liquidations) are reconciled against what was declared, scored for completeness and quality, and tracked file-by-file with content-addressed lineage. Governance is scoped to the streams a tenant owns — one tenant never sees another's. ## Two surfaces | Surface | What it covers | Where it runs | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | | **Streaming telemetry + lineage** | Stream inventory, freshness, declared-vs-observed reconciliation, completeness and quality scorecards, network placement alerts | Continuously, over the live stream | | **At-rest ingestion** | Parquet-to-ClickHouse ingestion with path-derived lineage, sha256 provenance, and exactly-once landing into a queryable system-of-record | On the tenant's archived Parquet | ## Per-tenant artifact-stream model A **stream** is one `(exchange, market_type, symbol, datatype)` tuple an agent produces. Every governance dimension keys on that tuple. Each stream carries a `binding_id` — the deploy that owns it — so all reconciliation, scoring, and lineage stays isolated to the owning tenant. ``` flowchart LR A[Agent artifact streams] --> D[Declared streams] A --> O[Observed reality] D --> C[Catalog reconciliation] O --> C C --> S[Completeness + Quality scorecards] O --> AL[Network placement alerts] A -.archived Parquet.-> IN[At-rest ingestion] IN --> SOR[Queryable system-of-record] ``` An agent's own streams flow into a declared set and an observed reality; their reconciliation feeds completeness and quality scorecards; observed network latency feeds placement alerts; archived Parquet is separately ingested into a queryable system-of-record. ## Dimensions - **Catalog** ______________________________________________________________________ Stream inventory: declared-vs-observed reconciliation, freshness, presence. [Read catalog →](https://aetelier.xyz/docs/govern/catalog/index.md) - **Completeness** ______________________________________________________________________ Sequence and bucket scoring — how much of the expected stream actually landed. [Read completeness →](https://aetelier.xyz/docs/govern/completeness/index.md) - **Quality** ______________________________________________________________________ Per-datatype check families over the stored records. [Read quality →](https://aetelier.xyz/docs/govern/quality/index.md) - **Alerts** ______________________________________________________________________ Network placement alerts with a debounced firing-to-resolved lifecycle. [Read alerts →](https://aetelier.xyz/docs/govern/alerts/index.md) ## Surfaces | Surface | What it is | Reference | | --------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------- | | **Governance API** | Read the catalog, per-stream scorecards, and resolve a dataset to its files | [api.md](https://aetelier.xyz/docs/govern/api/index.md) | | **At-rest ingestion** | Parquet to ClickHouse with lineage and exactly-once landing | [ingestion.md](https://aetelier.xyz/docs/govern/ingestion/index.md) | ## What a tenant gets for their own streams | Question | Answered by | | ------------------------------------------------- | ------------------------------------------------------------------------ | | Which streams do I own, and are they fresh? | [Catalog](https://aetelier.xyz/docs/govern/catalog/index.md) | | Did every expected bucket arrive? | [Completeness](https://aetelier.xyz/docs/govern/completeness/index.md) | | Is the stored data valid? | [Quality](https://aetelier.xyz/docs/govern/quality/index.md) | | Is a collector deployed in a high-latency region? | [Alerts](https://aetelier.xyz/docs/govern/alerts/index.md) | | Where are the files behind a dataset? | [API — datasets](https://aetelier.xyz/docs/govern/api/index.md) | | Can I query my persisted streams at rest? | [At-rest ingestion](https://aetelier.xyz/docs/govern/ingestion/index.md) | # Dataset catalog The Aetelier platform collects normalized market-microstructure data — trades and Level-2 orderbook snapshots — from multiple cryptocurrency exchanges into a single, exchange-agnostic schema. This page documents what the seed corpus covers, the on-disk convention, the record schema, and how to read it with the SDK. The same data feeds the [research notes](https://aetelier.xyz/docs/research/index.md). Format, not a download This catalog documents the **schema and collection convention**, not a hosted download. You produce your own corpus by running a collector — see [Tutorial 1: Bybit → Parquet](https://aetelier.xyz/docs/guides/01-bybit-to-parquet/index.md) — and read it back with the functions below. Everything here is reproducible from the SDK. ## Coverage (seed corpus) A snapshot of the current collected corpus — **407 Parquet files, ~3.8 MB**, gathered early June 2026 in synchronized (`sync`) mode: | Exchange | Datatype | Files | Notes | | ------------ | ------------------- | ----- | ----------------------------------------------------- | | **Binance** | Orderbook snapshots | 362 | The bulk of the corpus — L2 books across five symbols | | **Coinbase** | Orderbook snapshots | 43 | Second-venue coverage for cross-exchange work | | **Binance** | Trades | 1 | Sample trade stream | | **Bybit** | Trades | 1 | Sample trade stream | **Symbols:** `BTC-USDT`, `ETH-USDT`, `SOL-USDT`, `ALGO-USDT`, `LINK-USDT`. This is a **seed corpus**, deliberately skewed toward Binance L2 books; it is enough to develop and reproduce the published analyses, not a balanced multi-venue panel. Collect more with the SDK as needed. ## File naming Every file follows one convention, which downstream tools parse to locate the right data for a symbol and time range: ```text {exchange}_{symbol}_{datatype}_{mode}_{YYYYMMDD}_{HHMMSS.mmm}.parquet ``` Real examples from the corpus: ```text binance_BTC-USDT_trades_sync_20260602_044413.927.parquet coinbase_BTC-USDT_ob_sync_20260601_195024.176.parquet bybit_BTC-USDT_trades_sync_20260602_044412.022.parquet ``` - `datatype` is `trades` or `ob` (orderbook). - `mode` is `sync` for grid-aligned, synchronized collection. - The trailing timestamp is the collection start (millisecond precision). ## Schema Records use the SDK's exchange-agnostic types — exchange wire formats are normalized into these by the per-exchange decoders. The authoritative definitions live in [`aetelier-types`](https://aetelier.xyz/docs/sdk/types/index.md); the logical shapes are: | Field | Type | Meaning | | -------------------- | ------------- | ------------------------------------------------------ | | `source_trade_ts_us` | `u64` | Trade timestamp, Unix microseconds (exchange-reported) | | `pair` | `TradingPair` | Canonical pair, e.g. `BTC/USDT` | | `side` | `TradeSide` | Taker side | | `amount` | `f64` | Filled quantity, base-currency units | | `price` | `f64` | Execution price, quote-currency units | | `exchange` | `String` | Source exchange | | `id` | `String` | Exchange-assigned trade id | | Field | Type | Meaning | | ----------------- | --------------- | ---------------------------------------------------- | | `orderbook_id` | `u32` | Snapshot id | | `orderbook_ts_us` | `u64` | Snapshot timestamp, Unix microseconds (grid-aligned) | | `pair` | `TradingPair` | Canonical pair | | `exchange` | `String` | Source exchange | | `bids` | price → `Level` | Bid levels (best bid = highest price) | | `asks` | price → `Level` | Ask levels (best ask = lowest price) | Synchronized (`sync`) collection composes these into a `MarketSnapshot` per grid tick — `ts_us` (grid-aligned), the carried-forward `orderbook`, and the `trades`, `liquidations`, `funding_rate`, and `open_interest` observed in that interval. See [Architecture](https://aetelier.xyz/docs/sdk/architecture/index.md) for how the synchronizer builds them. ## Reading it The [`aetelier-io`](https://aetelier.xyz/docs/sdk/io/index.md) crate reads each datatype back into the typed records: ```rust use aetelier_io::trades::read_trades_parquet; use aetelier_io::orderbooks::ob_parquet::load_parquet_to_ob; let trades = read_trades_parquet("…/binance_BTC-USDT_trades_sync_20260602_044413.927.parquet".as_ref())?; let books = load_parquet_to_ob("…/coinbase_BTC-USDT_ob_sync_20260601_195024.176.parquet".as_ref())?; ``` From there the data is ready for whatever analysis you run on top of it. ## Reproduce / extend - **Collect fresh data:** [Tutorial 1: Bybit → Parquet](https://aetelier.xyz/docs/guides/01-bybit-to-parquet/index.md). - **Multi-exchange, synchronized:** [Tutorial 2: multi-exchange sync](https://aetelier.xyz/docs/guides/02-multi-exchange-sync/index.md). # Platform API # Platform API The Aetelier platform separates the **control plane** from the **wire**: | Component | Role | | ------------- | ------------------------------------------------------------------------------------------------------------------ | | Control plane | Serves the REST surface: session, service, and binding lifecycle. Mints the JWT an agent presents at registration. | | Wire | Speaks the gRPC contract to remote agents: registration, commands, telemetry, artifacts, and lifecycle events. | This page documents the **public integration surface** — how an operator brings up a remote agent and how that agent talks to the platform. The agent-facing wire is the gRPC contract in `aetelier-proto`; the agent binary and its handshake are documented on the operations pages. - [Wire protocol](https://aetelier.xyz/docs/proto/proto/index.md) — the `aetelier.v1beta1` `Gateway` service and its message shapes. - [`aetelier-agent`](https://aetelier.xyz/docs/operations/agent/index.md) — the remote-agent binary: CLI flags, environment variables, and the gateway/JWT handshake. - [SDK reference](https://aetelier.xyz/docs/sdk/index.md) — the worker primitives an agent spawns from a manifest. ## Authentication A remote agent presents a **pre-issued JWT** to the Gateway at registration. The Overseer mints the token at deploy time; the agent consumes it and never self-signs. The Gateway verifies the token signature on every connection attempt. The token's claims carry the identities an agent run is scoped to: | Claim | Type | Description | | ------------ | -------------- | -------------------------- | | `sub` | UUID | User ID | | `session_id` | UUID | Session the agent binds to | | `service_id` | UUID | Service the agent serves | | `binding_id` | UUID | Binding minted at deploy | | `exp` | unix timestamp | Token expiration | | `iat` | unix timestamp | Issued-at | The agent extracts `session_id`, `service_id`, and `binding_id` from the token — they are not separate environment variables. The authoritative `agent_id` is allocated by the Gateway and returned in `RegistrationResponse.Accepted`. Where the token comes from Operators copy the token from the webapp's "Deploy agent" response into the agent's `AETELIER_TOKEN` environment variable. See [`aetelier-agent`](https://aetelier.xyz/docs/operations/agent/#where-the-jwt-comes-from). ## The wire — `aetelier.v1beta1` Gateway Every cross-boundary message is a gRPC `Envelope` on the `Gateway` service. The service exposes three RPCs: | RPC | Shape | Carries | | ------------------ | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `CommandChannel` | bidirectional stream of `Envelope` | `Registration` (first frame), then `Manifest` / `Command` and their acks; downstream `Command`s from the platform | | `TelemetryChannel` | client stream of `Envelope` returning `Ack` | `Heartbeat`, `AgentStatus`, `TaskTelemetry`, `ArtifactFrame` | | `EventSubscribe` | `EventSubscribeRequest` returning a server stream of `Envelope` | session-scoped lifecycle `Event`s | The message shapes — `Registration`, `Manifest`, `Command`, telemetry frames, `ArtifactFrame` and its lineage, and the lifecycle `Event` families — are specified in the [wire protocol reference](https://aetelier.xyz/docs/proto/proto/index.md). Package The current contract is `aetelier.v1beta1`. Consumers pin a specific tag or git revision of `aetelier-proto`. ## Lifecycle commands The platform sends lifecycle verbs to a running agent over `CommandChannel`. Each is acked by `command_id`: | Command | Effect | | --------- | -------------------------------------------------------------- | | `pause` | Workers stop emitting events but keep their connections alive. | | `resume` | Workers resume emission. | | `stop` | Workers shut down cleanly; the agent exits. | | `restart` | Workers shut down and respawn from the same manifest. | See [`aetelier-agent` lifecycle](https://aetelier.xyz/docs/operations/agent/#lifecycle) for the full handshake and the operator's view of these commands. ## Agent configuration The remote agent reads a small set of environment variables. The full contract — CLI flags, defaults, and the identity model — is on the [`aetelier-agent`](https://aetelier.xyz/docs/operations/agent/index.md) page. | Env var | Default | Required | Description | | ---------------------- | ------------------------ | -------- | --------------------------------------- | | `AETELIER_GATEWAY_URL` | `http://localhost:50443` | no | Gateway gRPC URL | | `AETELIER_TOKEN` | — | **yes** | Pre-issued JWT from the deploy response | | `AGENT_ALIAS` | auto-generated | no | User-facing label | | `RUST_LOG` | `info` | no | Tracing / logging filter | Dev placeholders Any token or signing secret shown in examples is a **development placeholder**, not a usable credential. Production tokens are minted per deploy by the Overseer and are never checked into source or reproduced in documentation. ## Related material - [Wire protocol](https://aetelier.xyz/docs/proto/proto/index.md) — the `aetelier.v1beta1` message and service contract. - [`aetelier-agent`](https://aetelier.xyz/docs/operations/agent/index.md) — operating the remote-agent binary. - [`aetelier-connect`](https://aetelier.xyz/docs/sdk/connect/index.md) — the worker primitives the agent spawns. - [`aetelier-telemetry`](https://aetelier.xyz/docs/sdk/telemetry/index.md) — the metric vocabulary the agent streams upstream. # Help # Getting help **Support is async and email-only.** There is no live chat, no phone line, and no 24/7 human response. Most answers are faster than an email — the platform is built so that errors are actionable and this knowledge base resolves on the exact string you saw. Work the self-serve path first, then escalate by email. ## 1. Is it down? Check the status page The public status page is external and shows live service state: - **Status:** Check it first for any "is it down / is this an outage" question. If an incident is posted there, the fix is to wait for it to clear — email will not speed it up. ## 2. Search your exact error first Each documented error string is quoted verbatim on its page. Paste the string into the docs search, or fetch the page's Markdown directly (append `.md` to any docs URL). Common ones: | You saw | Start here | | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | | `insufficient DATA token balance` / `insufficient COMPUTE token balance` | [Units and the 402 error](https://aetelier.xyz/docs/help/tokens/index.md) | | `this fit costs {cost} compute tokens` | [Units and the 402 error](https://aetelier.xyz/docs/help/tokens/index.md) | | `managed agents are not included in the {tier} tier` | [Feature access](https://aetelier.xyz/docs/help/tiers/index.md) | | `live reconciliation requires the Pro tier or higher` | [Feature access](https://aetelier.xyz/docs/help/tiers/index.md) | | `concurrent-collector cap reached` | [Feature access](https://aetelier.xyz/docs/help/tiers/index.md) | | `Not converged after {iterations} iterations` (a fit `400`) | [MCP errors are data](https://aetelier.xyz/docs/help/mcp-errors/index.md) | | Deployed but no data landing | [Collector: no data](https://aetelier.xyz/docs/help/collector-no-data/index.md) | | A top-up not credited (top-ups are not open yet) | [Payment not credited](https://aetelier.xyz/docs/help/payment-not-credited/index.md) | | Any API error with a `code` field | [Error-code index](https://aetelier.xyz/docs/help/errors/index.md) | **If a search returns nothing:** we document what is live, so a capability you cannot find most likely does not exist yet — check [Platform limits](https://aetelier.xyz/docs/help/platform-limits/index.md) for the enforced boundaries. Email us and we will say plainly whether it exists, is planned, or is out of scope. ## 3. For agents: platform_health first, then the Markdown An agent should triage before it asks a human: - Call [`platform_health`](https://aetelier.xyz/docs/mcp/tools/#platform_health) first — it reports each backing service as `ok`, or why it is not. - Read errors as data. Every machine-side failure maps to an in-loop action; see [MCP errors are data, not failures](https://aetelier.xyz/docs/help/mcp-errors/index.md). - Fetch the whole documentation set in one request: [`https://aetelier.xyz/docs/llms-full.txt`](https://aetelier.xyz/docs/llms-full.txt). Any single page's source is fetchable by appending `.md` to its URL. ## 4. Ask the community Community links, for usage questions, ideas, and talking to other builders, appear only inside your dashboard under **Settings → Community** (see [Official channels](https://aetelier.xyz/docs/help/official-channels/index.md)). Community channels follow the same async response targets as email (see the [support policy](https://aetelier.xyz/docs/help/support-policy/index.md)). Anything touching your **account, billing, a payment, an API key, or personal data is handled only over email** — we will never resolve those in a community thread. ## 5. Still stuck? Email us If the status page is clear, the error page did not resolve it, and `platform_health` reads `ok` for every service, email support: - **Email:** support@aetelier.xyz — the system of record, and the only channel for account, billing, refund, and data-subject requests. Report a security issue privately, by email or through a public repository's **Security** tab on [GitHub](https://github.com/aetelierxyz), never in a public thread. - **Hours and targets:** Monday–Friday, 09:00–18:00 America/Mexico_City; replies come within business hours. Severity definitions and first-response targets are in the [support policy](https://aetelier.xyz/docs/help/support-policy/index.md). - **Include:** what you did, the exact error string and any `code`, any `service_id` or `fit_id`, and the approximate time (with timezone). Once top-ups open, add a top-up's `memo`, transaction signature and network. - **Never send** your API key, wallet private key or seed phrase. Support never needs them. The more of that you include, the faster a single async round-trip resolves it. ## Related - [Support policy](https://aetelier.xyz/docs/help/support-policy/index.md) · [Official channels](https://aetelier.xyz/docs/help/official-channels/index.md) - [Units and the 402 error](https://aetelier.xyz/docs/help/tokens/index.md) · [Feature access](https://aetelier.xyz/docs/help/tiers/index.md) · [MCP errors are data, not failures](https://aetelier.xyz/docs/help/mcp-errors/index.md) - [My collector deployed but no data is landing](https://aetelier.xyz/docs/help/collector-no-data/index.md) - [I paid but my units are not credited](https://aetelier.xyz/docs/help/payment-not-credited/index.md) - [Aetelier for agents](https://aetelier.xyz/docs/agents/overview/index.md) — the agent-facing orientation # Support policy This page is the single published source for response targets. The Terms of Service reference it; no other page restates these numbers. ## What a response target measures A response target is the time to first human acknowledgment and the start of triage — **not** the time to resolution. We do not commit a resolution time during beta; resolution is best-effort and worked in priority order. Acknowledgment clocks run only during published support hours; a message arriving outside those hours starts its clock at the next opening. ## Support hours Human support operates **Monday–Friday, 09:00–18:00 America/Mexico_City**, excluding Mexican public holidays and any reduced-coverage dates announced on the [status page](https://status.aetelier.xyz). Outside those hours, automated monitoring and the public status page remain live continuously; human replies resume at the next opening. Human support is by email at **support@aetelier.xyz**. What to include is in [Getting help](https://aetelier.xyz/docs/help/getting-help/index.md). ## Severity and response targets Every account shares one table and one queue during beta. | Severity | Definition | First-response target (business hours) | | -------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | | **P0** | Platform-wide outage, data loss, or a security incident | Within 4 business hours; status posted on detection, 24/7 | | **P1** | Major degradation affecting many accounts, or a fault that hard-blocks one account's collectors, fits or swarms | Within 1 business day | | **P2** | Single-account, non-catastrophic: a payment or access question, one silent collector, one non-converging fit | Within 2 business days | | **P3** | General and pricing questions, non-blocking bugs, feature requests, docs feedback | Within 3 business days | ## What runs around the clock 24/7 automated monitoring and a public status page; human response during support hours. ## Expected behavior is not an incident A `402` with `insufficient DATA token balance` or `insufficient COMPUTE token balance`, an access gate such as `live reconciliation requires the Pro tier or higher`, and `concurrent-collector cap reached` are the platform enforcing your unit balance and your account's access — the action was refused, not charged. Top-ups are not open yet, and gated features are open to selected accounts; [Units and the 402 error](https://aetelier.xyz/docs/help/tokens/index.md) and [Feature access](https://aetelier.xyz/docs/help/tiers/index.md) give the next step for each. Once top-ups open, a top-up that stays uncredited is the case that belongs in email: [I paid but my units are not credited](https://aetelier.xyz/docs/help/payment-not-credited/index.md) says when to send it and what to include. ## Payments and refunds - Units are prepaid, non-transferable service credits, not money. - Top-ups are not open yet: the public top-up status reads `disabled`, shown as **OPENS SOON**. They open first on Solana devnet, for listed testers only (**OPEN · DEVNET**); mainnet comes later. Every status word is in [Top-ups over x402](https://aetelier.xyz/docs/help/tokens/#top-ups-over-x402-coming). - Once open, top-ups are paid in USDC on Solana from your own wallet over x402 v2. Coinbase Developer Platform, as facilitator, verifies and settles each payment. Aetelier never receives or stores wallet keys, and support never needs them. - Bundle purchases are final except where the law requires a refund ([Terms of Service](https://aetelier.xyz/terms) §6). Send refund requests to support@aetelier.xyz as described in [Refunds](https://aetelier.xyz/docs/help/payment-not-credited/#refunds). ## How these targets are bounded These response targets are operational objectives, not contractual guarantees, and do not modify the Terms of Service. A missed target earns no service credits during beta ([Terms of Service](https://aetelier.xyz/terms) §9). ## Related - [Getting help](https://aetelier.xyz/docs/help/getting-help/index.md) — the escalation path itself - [Official channels](https://aetelier.xyz/docs/help/official-channels/index.md) — where we are, and where we are not - [Units and the 402 error](https://aetelier.xyz/docs/help/tokens/index.md) — what units fund, and how top-ups will work - [I paid but my units are not credited](https://aetelier.xyz/docs/help/payment-not-credited/index.md) — receipts by memo, and refunds # Official channels Impersonation is the dominant scam vector around crypto-adjacent products. This page is the complete, authoritative list of where we are — anything else that uses our name is not us. Aetelier is operated by Lattice Numerical Systems Limited, registered in England and Wales under company number 17550837. Our only official channels are: - **This website and app:** `aetelier.xyz` and its subdomains - **Documentation:** [aetelier.xyz/docs](https://aetelier.xyz/docs/) - **Status page:** [status.aetelier.xyz](https://status.aetelier.xyz) - **Email:** `support@aetelier.xyz`. Mail from us comes only from an `@aetelier.xyz` address; check the domain letter by letter. - **GitHub:** [github.com/aetelierxyz](https://github.com/aetelierxyz) - **X:** [x.com/aetelierxyz](https://x.com/aetelierxyz) - **Company profiles:** only those linked from the footer of `aetelier.xyz` Community links appear only inside your dashboard, under **Settings → Community**. A Discord or forum invite from anywhere else is not ours. We do **not** operate any Telegram, WhatsApp, or Signal group. ## What we never do - We never DM you first. - We never ask for your password, your API key, or your wallet's private key, keypair file, or seed phrase. - We never ask you to send USDC or any other funds to an address in a message. Top-ups are not open yet (**OPENS SOON**; see [Top-ups over x402](https://aetelier.xyz/docs/help/tokens/#top-ups-over-x402-coming)). Once they open, a payment request comes only as the `402` reply to a top-up you start yourself against `aetelier.xyz`, and you sign it with your own wallet. Every other `402` only refuses work; it is not a payment request. - We do not offer or sell any coin or other cryptocurrency ([Terms of Service](https://aetelier.xyz/terms) §2). Units cannot be sent, exchanged, or resold (§4), so any coin sale, airdrop, or unit resale under the Aetelier name is not us. If anyone claims otherwise under the Aetelier name, it is not us; report it to `support@aetelier.xyz`. ## Related - [Getting help](https://aetelier.xyz/docs/help/getting-help/index.md) · [Support policy](https://aetelier.xyz/docs/help/support-policy/index.md) - [Units and the 402 error](https://aetelier.xyz/docs/help/tokens/index.md) — what units are, and how top-ups will work # Error-code index Platform API error bodies carry three fields: ```json { "error": "payment required: insufficient DATA token balance (0) to deploy a collector", "code": "INSUFFICIENT_DATA_TOKENS", "docs_url": "https://aetelier.xyz/docs/help/errors/#insufficient_data_tokens" } ``` `error` is the human-readable string, `code` is stable and machine-matchable, and `docs_url` lands on this page at the section for that code. Agents should branch on `code` whenever a body carries one, not on the prose. Fit and swarm errors carry `error` only, with no `code` yet; match their message instead. Top-up endpoints answer with their own lowercase codes, such as `topup_disabled`, and no `docs_url`; they are listed in [I paid but my units are not credited](https://aetelier.xyz/docs/help/payment-not-credited/index.md). For the narrative recovery patterns, read [MCP errors are data, not failures](https://aetelier.xyz/docs/help/mcp-errors/index.md). Most errors here are the platform enforcing a balance, access or input rule: **the action was refused, not charged**. A `402` here refuses work; it is not a payment request and carries no x402 headers. Nothing to buy Some messages still say `tokens`, `tier`, `plan` or `upgrade`. Nothing can be bought to open a feature. Gated features are open to selected accounts, and units do not open them. Top-ups are not open yet: the public status reads `disabled`, shown as **OPENS SOON** — see [Top-ups over x402](https://aetelier.xyz/docs/help/tokens/#top-ups-over-x402-coming). ## INSUFFICIENT_DATA_TOKENS HTTP 402. Verbatim: `insufficient DATA token balance ({n}) to deploy a collector`. A collector deploy needs at least one data unit, and the balance is below that. Nothing was charged and nothing was deleted. An account with no units of any kind is on [the floor](https://aetelier.xyz/docs/help/tokens/#the-floor) instead and does not get this code: it can still deploy remote collectors up to the floor's cap. Fix: report the shortfall; top-ups are not open yet — see [Units and the 402 error](https://aetelier.xyz/docs/help/tokens/#the-402-balance-errors). ## INSUFFICIENT_COMPUTE_TOKENS HTTP 402. Verbatim: `insufficient COMPUTE token balance ({n}) to deploy a platform agent`. Only a platform (managed) collector deploy sends this code: it needs at least one compute unit on top of its data unit. Platform collectors are open to selected accounts, so other accounts get [`TIER_TOO_LOW`](#tier_too_low) first. A fit or swarm that is short of compute units answers `402` with no `code`, such as `this fit costs {cost} compute tokens; your balance is {balance}`. Same semantics: refused, not charged. Fix: deploy a remote collector, which draws data units only, or report the shortfall — see [Units and the 402 error](https://aetelier.xyz/docs/help/tokens/#the-402-balance-errors). ## EMAIL_UNVERIFIED HTTP 402, reserved. **Not sent today:** no current `402` message names email verification, so no response carries this code. An account whose email is not verified holds no units, so it is on [the floor](https://aetelier.xyz/docs/help/tokens/#the-floor) and gets the floor's answers instead: a platform collector returns [`TIER_TOO_LOW`](#tier_too_low), a fit returns `this fit costs {cost} compute tokens; your balance is 0` with no `code`, and a collector past the floor's cap returns [`CONCURRENT_CAP_REACHED`](#concurrent_cap_reached). In the webapp, collector deploys and fits stay off until you verify. Fix: open the verification link we emailed you, then load the webapp; the [signup grant](https://aetelier.xyz/docs/help/tokens/#verify-your-email-to-unlock-the-signup-grant) lands then. ## TIER_TOO_LOW HTTP 402. Verbatim: `managed agents are not included in the {tier} tier — upgrade to Base or higher, or deploy a BYO (remote) agent`. Platform (managed) collectors are open to selected accounts, and this account is not one of them. Units do not clear it, and nothing can be bought to clear it. Remote (BYO) collectors are open to every account. Fix: deploy a remote collector — see [Feature access](https://aetelier.xyz/docs/help/tiers/index.md). ## RECONCILE_REQUIRES_PRO HTTP 402. Verbatim: `live reconciliation requires the Pro tier or higher — current tier: {tier}`. Live reconciliation is open to selected accounts. Fix: deploy without `[collect.reconcile]` `enabled = true` — see [Feature access](https://aetelier.xyz/docs/help/tiers/index.md). ## SSE_REQUIRES_PRO HTTP 402. Verbatim: `live collector-state streaming is included from the Pro plan`. The live collector-state stream (`GET /api/collectors/state/stream`) is open to selected accounts. Fix: poll [`collector_status`](https://aetelier.xyz/docs/mcp/tools/#collector_status) or [`collector_health`](https://aetelier.xyz/docs/mcp/tools/#collector_health), which work on every account — see [Feature access](https://aetelier.xyz/docs/help/tiers/index.md). ## TRACER_REQUIRES_PRO HTTP 402. Verbatim: `trace configuration is included from the Pro plan`. Tracing is open to selected accounts. The gate covers every `/api/tracer/` route, reads included, and units do not open it. Fix: none yet; report the code — see [Feature access](https://aetelier.xyz/docs/help/tiers/index.md). ## CONCURRENT_CAP_REACHED HTTP 402. Verbatim: `concurrent-collector cap reached ({in_flight}/{cap}) for the {tier} tier — release a collector or upgrade`. The account's concurrent-collector cap is fully in use. The cap is lower on [the floor](https://aetelier.xyz/docs/help/tokens/#the-floor), where the message reads `for the free tier floor`. Fix: stop a collector you no longer need with [`stop_collector`](https://aetelier.xyz/docs/mcp/tools/#stop_collector), then retry — see [Platform limits](https://aetelier.xyz/docs/help/platform-limits/#collectors). ## PAYMENT_REQUIRED HTTP 402. Fallback code for a `402` message that matches none of the codes above; no current message maps to it. Read the `error` string, report it, and do not retry unchanged. Fit and swarm `402`s carry no `code`; match their message in [Units and the 402 error](https://aetelier.xyz/docs/help/tokens/#the-402-balance-errors) and [Feature access](https://aetelier.xyz/docs/help/tiers/#exact-messages). ## API_KEY_INVALID HTTP 401. Verbatim: `unauthorized`. The request carried no credential, or one that is malformed, expired or revoked. Fix: create a new API key in the webapp (Settings → Security) and retry with it. Keys are revocable; a key that worked yesterday may have been rotated. ## FORBIDDEN HTTP 403. Verbatim prefix: `forbidden:`. The credential is valid but does not own the resource it addressed. Fix: check that the `service_id` / resource id belongs to this account. A platform collector on Solana for an account not on the preset's allowlist is also refused here; deploy a remote collector instead — see [Feature access](https://aetelier.xyz/docs/help/tiers/index.md). ## NOT_FOUND HTTP 404. Verbatim prefix: `not found:`. The id in the request does not exist on this account. Ids are account-scoped; copy them from a list call rather than constructing them. ## CONFLICT HTTP 409. Verbatim prefix: `conflict:`. The request collides with current state (for example, a duplicate deploy of the same resource). Re-read current state with a list call, then retry with the conflict resolved. ## VALIDATION_ERROR HTTP 400. Verbatim prefix: `validation error:`. The request failed admission checks before touching any state. The message names the offending field — one collector runs one symbol, and [Platform limits](https://aetelier.xyz/docs/help/platform-limits/index.md) lists the enforced boundaries. A governance read past the account's `window_secs` ceiling also lands here; retry inside the ceiling the message names. ## RATE_LIMITED HTTP 429. Verbatim prefix: `too many requests:`. Back off and retry with exponential delay. Agents: treat this as pacing feedback, not failure. ## SERVICE_UNAVAILABLE HTTP 503. The message is passed through and names the actionable condition. A backing service is temporarily unreachable or an operator condition (such as a missing agent image) blocks the action. On tracing and the live stream, `entitlement check unavailable` means the access check could not run. Check the [status page](https://status.aetelier.xyz) and [`platform_health`](https://aetelier.xyz/docs/mcp/tools/#platform_health); if both are green, retry with backoff. ## INTERNAL HTTP 500. Verbatim: `internal error`. Also HTTP 503 with `service unavailable` when a backing queue is unreachable. A platform-side fault; detail stays server-side. Retry once with backoff; if it repeats, check the [status page](https://status.aetelier.xyz) and email **support@aetelier.xyz** with the time (and timezone) and what you called — see [Getting help](https://aetelier.xyz/docs/help/getting-help/index.md). ## Related - [MCP errors are data, not failures](https://aetelier.xyz/docs/help/mcp-errors/index.md) — recovery patterns - [Units and the 402 error](https://aetelier.xyz/docs/help/tokens/index.md) · [Feature access](https://aetelier.xyz/docs/help/tiers/index.md) · [Platform limits](https://aetelier.xyz/docs/help/platform-limits/index.md) - [Getting help](https://aetelier.xyz/docs/help/getting-help/index.md) # Platform limits These are the boundaries the platform enforces today. A request that crosses one is refused with a [structured error](https://aetelier.xyz/docs/help/errors/index.md) — that refusal is the rule working, not a malfunction. We document what is live; if a capability is not described in these docs, the platform does not currently provide it. ## Collectors - **One collector runs one symbol.** A manifest with more than one `[[workers]]` entry is rejected with [`VALIDATION_ERROR`](https://aetelier.xyz/docs/help/errors/#validation_error). Run one collector per symbol you want covered. - **Venues are fixed:** spot markets on twelve CEX venues, perpetuals on Hyperliquid, and on-chain transactions for one account address on Solana. Any other venue or market type is rejected at validation. See [Venue coverage](https://aetelier.xyz/docs/sdk/venues/index.md) and [Datasets](https://aetelier.xyz/docs/datasets/index.md). - **Concurrent collectors are capped per account.** An account runs up to nine collectors at once, or three while it holds no units; selected accounts have higher caps. Past the cap, a deploy answers `402` with [`CONCURRENT_CAP_REACHED`](https://aetelier.xyz/docs/help/errors/#concurrent_cap_reached): stop a collector to deploy another. ## Agents - **Remote (BYO) agents work on every account.** You run the container; the dashboard hands you the exact `docker run` command. A deploy needs at least one data unit, or answers `402` with [`INSUFFICIENT_DATA_TOKENS`](https://aetelier.xyz/docs/help/errors/#insufficient_data_tokens). - **With no units of any kind, an account keeps three remote collectors.** It can still deploy and run up to three remote collectors, unmetered. Metering then stops any platform collectors and any remote collectors beyond the oldest three. Running out never closes the account. - **Platform (managed) agents are open to selected accounts.** Elsewhere a platform deploy answers `402` with [`TIER_TOO_LOW`](https://aetelier.xyz/docs/help/errors/#tier_too_low); deploy a remote agent instead. A platform deploy also needs at least one compute unit ([`INSUFFICIENT_COMPUTE_TOKENS`](https://aetelier.xyz/docs/help/errors/#insufficient_compute_tokens)). On Solana, an account not on the provider's list gets `403` with [`FORBIDDEN`](https://aetelier.xyz/docs/help/errors/#forbidden) first. ## Fits - **Checked before, charged on convergence.** A short compute balance answers `402` before any work starts. Only a converged fit is charged; a failed, oversized or timed-out fit is not. Swarms follow the same rule. - **A fit takes at most 1,000,000 events and runs for at most 300 seconds**, by default. Past either limit the fit is refused with `400` (`validation error:`). - **An account has up to nine fits in flight at once**; selected accounts have higher caps. Past the cap, a fit answers `402` with `concurrent-fit cap reached`. A fit may wait for a free run slot before it starts. ## Features open to selected accounts Nothing can be bought to open these, and a top-up does not clear their codes. Each feature in the table answers `402` on an account where it is not open: | Feature | Code | | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Platform (managed) collectors | [`TIER_TOO_LOW`](https://aetelier.xyz/docs/help/errors/#tier_too_low) | | Live reconciliation (`[collect.reconcile]` with `enabled = true`) | [`RECONCILE_REQUIRES_PRO`](https://aetelier.xyz/docs/help/errors/#reconcile_requires_pro) | | Live collector-state stream (`GET /api/collectors/state/stream`) | [`SSE_REQUIRES_PRO`](https://aetelier.xyz/docs/help/errors/#sse_requires_pro) | | Tracing, every `/api/tracer/` route, reads included | [`TRACER_REQUIRES_PRO`](https://aetelier.xyz/docs/help/errors/#tracer_requires_pro) | - **Data governance reads draw no units.** A live-window read spans at most one hour (`window_secs` up to `3600`); longer windows are open to selected accounts. Past the ceiling a read answers `400` with [`VALIDATION_ERROR`](https://aetelier.xyz/docs/help/errors/#validation_error). A seven-day window for every signed-in account is coming. See the [governance API](https://aetelier.xyz/docs/govern/api/index.md). - **Traces are capped per account:** up to 50 by default. Past that, a new trace answers `429` with `trace quota reached`. ## Units - **Work draws prepaid units.** Collectors draw data units once per UTC day for every day they run; a platform collector also draws compute units. Fits and swarms draw compute units. Every rate is in the public catalog, which needs no key: ```bash curl -s https://aetelier.xyz/api/payments/catalog | jq '.action_rates' ``` `action_rates` carries `byo_collector_day_data`, `managed_collector_day_compute`, `hawkes_fit_compute` and `swarm_round_compute`. `tokens_per_usd` is the list rate, `bundles` lists the bundles, and `signup_grant` is what a verified new account starts with. - **Units are prepaid, non-transferable service credits, not money.** Bundle purchases are final except where the law requires a refund ([Terms of Service](https://aetelier.xyz/terms) §4–§6). ## Top-ups - **USDC top-ups are not open yet.** The public status endpoint reads `disabled`, shown as **OPENS SOON**: ```bash curl -s https://aetelier.xyz/payments/topup/status ``` Top-ups open first on Solana devnet, for listed testers only; mainnet comes later. `operational` with a devnet `network` reads **OPEN · DEVNET**. `degraded` reads **DELAYED**: top-ups are running slowly. No answer reads **UNAVAILABLE**: the status could not be read. - **While top-ups are off**, the top-up endpoints answer `503` with code `topup_disabled`. Once devnet opens, an account not on the tester list gets `403` with code `topup_not_allowed`. - **Payments use x402 v2, in USDC on Solana only**, with Coinbase Developer Platform as the facilitator that verifies and settles each payment. The facilitator pays the Solana network fee, so the paying wallet needs USDC only. Aetelier never receives or stores wallet keys. - **Every top-up belongs to an account** and needs its bearer token, such as an API key. - **Once open**, a prepared top-up must be signed and submitted within 25 seconds (`410` with `intent_expired` otherwise), and an account holds at most five prepared top-ups awaiting submission at once (`429` with `too_many_open_intents`). - **A public, signed payer CLI is coming.** ## Support - Support is asynchronous — email **support@aetelier.xyz**, plus the community channels in your dashboard, under the published [support policy](https://aetelier.xyz/docs/help/support-policy/index.md). There is no live chat or phone line. Account, billing and payment questions are handled over email only. ## Related - [Error-code index](https://aetelier.xyz/docs/help/errors/index.md) · [Units and the 402 error](https://aetelier.xyz/docs/help/tokens/index.md) · [Feature access](https://aetelier.xyz/docs/help/tiers/index.md) - [I paid but my units are not credited](https://aetelier.xyz/docs/help/payment-not-credited/index.md) · [Official channels](https://aetelier.xyz/docs/help/official-channels/index.md) # My collector deployed but no data is landing **Applies to:** every collector deployed through `deploy_collector` or the webapp Deploy panel · **First check:** [`collector_health`](https://aetelier.xyz/docs/mcp/tools/#collector_health) The single most common surprise: **`deploy_collector` does not run a collector.** It registers the service and mints an agent JWT — nothing streams until **you run the agent** with that token. This page explains that step and the states you see while data starts (or fails) to land. Bring-your-own, by design `deploy_collector` is remote bring-your-own only. It returns a `service_id`, a `binding_id`, a `gateway_url`, and a `token` (the agent JWT). The overseer never spawns a platform-managed container from this tool. See [`deploy_collector`](https://aetelier.xyz/docs/mcp/tools/#deploy_collector) and [Worked examples → Flow 1](https://aetelier.xyz/docs/mcp/examples/index.md). ## Run the agent The collector produces data only once the `aetelier-agent` process is running against the gateway with the JWT from your deploy result. The two load-bearing variables: | Env var | From | Notes | | ---------------------- | -------------------------------------- | ----------------------------------------------------------------------------- | | `AETELIER_GATEWAY_URL` | the `gateway_url` in the deploy result | Match the scheme exactly — see [TLS vs plaintext](#the-binding-stays-pending) | | `AETELIER_TOKEN` | the `token` in the deploy result | The agent JWT. Required — the agent does not self-sign | The token's claims already carry `binding_id`, `service_id`, and `session_id`, so you do not set those as separate variables — the agent extracts them at startup. Full contract: [`aetelier-agent` → Environment variables](https://aetelier.xyz/docs/operations/agent/#environment-variables). The webapp shows the exact command for your binding, on the Deploy panel or from the fleet's COMMAND button: ```bash docker run -d --pull always --restart unless-stopped --name aetelier-agent--- \ -v "$HOME/aetelier-data:/home/agent" \ -e AETELIER_GATEWAY_URL="" \ -e AETELIER_TOKEN= \ -e RUST_LOG=info \ ghcr.io/aetelierxyz/aetelier-agent:latest ``` The container name is `aetelier-agent-` plus the exchange id, the datatype, and the first four characters of the `binding_id`; see [`aetelier-agent` → Deployment](https://aetelier.xyz/docs/operations/agent/#deployment-docker). Treat the JWT like a password — keep it out of shared configs and version control. ## Starting vs silent — read the verdict Once the agent is up, [`collector_health`](https://aetelier.xyz/docs/mcp/tools/#collector_health) returns a top-line verdict. A fresh, working deploy reads `starting`, not a failure, until the first rows land: | Verdict | Means | Do this | | ---------- | --------------------------------------------------------- | ------------------------------------------------------- | | `starting` | Connected; still inside the first-data grace, no rows yet | Wait out the grace, then re-check | | `healthy` | Connected and fresh rows are landing | Nothing — data is flowing | | `degraded` | Connected but rows stalled past the grace | Check the venue/symbol and the agent logs | | `silent` | Not connected, or no data and past grace | The agent is not running or cannot register — see below | `liveness.connected: false` means the agent never registered with the gateway. `liveness.connected: true` with `landing.rows_last_5m: 0` past the grace means it registered but is not producing — usually a wrong symbol or a paused task. ## The first-data grace (~180s) A new deploy has no lake rows for the first few minutes, so health leads with liveness and reads `starting` rather than reporting a problem. The window is the platform's first-data lag, **180 seconds**; it is what separates `starting` from `degraded`. The health result reports `landing.expected_first_data_by` — do not conclude failure before that timestamp. ## The binding stays pending If the binding never leaves pending and the agent seems stuck connecting, the agent is not registering with the gateway. Common causes: - **TLS vs plaintext mismatch.** The most frequent cause. A gateway served behind a TLS-terminating origin needs an `https://` `AETELIER_GATEWAY_URL`; a plaintext h2c gateway needs `http://`. Pointing a plaintext agent at a TLS origin (or the reverse) leaves the agent connecting with the binding never activating. Match the scheme to how the gateway is actually served. - **Expired or wrong-key token.** A JWT that has expired, or was minted against a signing key the gateway no longer uses, is rejected at registration. Mint a fresh token from the webapp Deploy panel. - **Binding already in use.** The same `binding_id` is already held by another active agent. Stop the other agent or deploy a new collector. The agent's own diagnostics for these are in [`aetelier-agent` → Common operational issues](https://aetelier.xyz/docs/operations/agent/#common-operational-issues). ## One collector, one symbol A collector carries exactly **one symbol**. Deploying with more than one symbol is rejected at admission — deploy a separate collector per symbol. If a deploy you expected to accept several symbols came back refused, this is why. ## Quick checklist 1. Did you actually run the agent? `deploy_collector` alone mints only a JWT. 1. Is `AETELIER_TOKEN` the exact `token` from the deploy result, unexpired? 1. Does `AETELIER_GATEWAY_URL` match the gateway's scheme (`http://` vs `https://`)? 1. Are you inside the ~180s grace? Check `landing.expected_first_data_by`. 1. Is the symbol the venue-native form? Confirm with [`list_cex_options`](https://aetelier.xyz/docs/mcp/tools/#list_cex_options). 1. One symbol per collector. ## Related - [`collector_health`](https://aetelier.xyz/docs/mcp/tools/#collector_health) — the verdict and landing detail - [`aetelier-agent`](https://aetelier.xyz/docs/operations/agent/index.md) — the run contract, JWT handshake, and lifecycle - [Worked examples → Flow 1](https://aetelier.xyz/docs/mcp/examples/index.md) — deploy and watch data land, end to end - [Units and the 402 error](https://aetelier.xyz/docs/help/tokens/index.md) — if the deploy itself was refused for balance - [Getting help](https://aetelier.xyz/docs/help/getting-help/index.md) — when to escalate # Units and the 402 error **Units are prepaid service credits.** They are non-transferable, are not money, and have no monetary value outside the platform. Two kinds are metered today, separately: **data units** and **compute units**. Every rate and bundle price lives in one public [catalog](#where-prices-live); this page quotes none of them. A 402 is a refusal, not a charge When an action would exceed your balance, the platform **refuses it** and returns `402`, almost always before any work starts. Nothing is metered and nothing is drawn down. ## What units fund today | Unit | Funds | Rate field in `action_rates` | | ----------- | ------------------------------------------------------------------------ | ------------------------------- | | **Data** | Each running collector, per UTC day | `byo_collector_day_data` | | **Compute** | Each Hawkes fit | `hawkes_fit_compute` | | **Compute** | Each Convection swarm, per member for every round in its round limit | `swarm_round_compute` | | **Compute** | Each platform (managed) collector, per UTC day, on top of its data units | `managed_collector_day_compute` | Platform collectors are open to selected accounts; other accounts get `TIER_TOO_LOW` and can deploy a remote (bring-your-own) collector instead. Not metered today: - [Data Governance](https://aetelier.xyz/docs/govern/index.md) reads draw no units. - Clarion attestations carry no charge during the Solana devnet beta. - Traces draw no units. Tracing is open to selected accounts (`TRACER_REQUIRES_PRO`), and adding units does not open it. ## How metering works - **Collectors.** An hourly sweep charges each running collector once per UTC day, so a part day costs a full day. A deploy needs at least one data unit unless the account is on [the floor](#the-floor), and a platform collector also needs at least one compute unit. - **Fits.** The balance is checked against the fit price before the fit starts. The fit is charged only when it converges; a fit that fails, times out or does not converge draws nothing. - **Swarms.** The price is `swarm_round_compute` × members × the round limit, fixed when the swarm is admitted. A swarm always runs its full round limit. The balance is checked before it starts, and it is charged once, only when it converges; an aborted swarm draws nothing. ## Where prices live The catalog is public JSON and needs no key: ```bash curl -s https://aetelier.xyz/api/payments/catalog | jq '.action_rates' ``` | Field | Holds | | ---------------- | ------------------------------------------------------------------------------------- | | `tokens_per_usd` | The list rate, in units per USDC | | `action_rates` | The four per-action rates in the table above | | `bundles` | Each bundle's `sku`, `kind`, `units`, `price_atomic`, `price_usdc` and `discount_pct` | | `signup_grant` | The units a new account receives once its email is verified | `bundles` also lists `networking` bundles, but nothing draws networking units. The reply also carries legacy fields such as `plans` and `packs`; nothing in them is for sale. For a fit, [`fit_pricing`](https://aetelier.xyz/docs/mcp/tools/#fit_pricing) returns the current price so a client can report it before running. Every field, with runnable examples: [Pricing and payments](https://aetelier.xyz/docs/pricing/index.md). ## The 402 balance errors Each unit kind refuses independently. Paste either string into search to land back here: ```text insufficient DATA token balance ``` ```text insufficient COMPUTE token balance ``` | `error` contains | `code` | Means | | --------------------------------------------------------------------- | ----------------------------- | --------------------------------------------------------- | | `insufficient DATA token balance ({n}) to deploy a collector` | `INSUFFICIENT_DATA_TOKENS` | Not enough data units to deploy | | `insufficient COMPUTE token balance ({n}) to deploy a platform agent` | `INSUFFICIENT_COMPUTE_TOKENS` | Not enough compute units for a platform collector | | `this fit costs {cost} compute tokens; your balance is {balance}` | none | Not enough compute units for the fit | | `this run costs {cost} compute tokens; your balance is {balance}` | none | Not enough compute units for the swarm | | `this fit costs {cost} compute tokens; balance fell short mid-run` | none | The balance dropped while the fit ran; it was not charged | Collector and fit errors put `payment required:` before the message, so match the substring. Collector errors carry a `code` and a `docs_url` into the [error-code index](https://aetelier.xyz/docs/help/errors/index.md); fit and swarm errors carry no `code` yet. What to do: 1. **New account?** Verify your email; the [signup grant](#verify-your-email-to-unlock-the-signup-grant) lands then. 1. **Balance spent?** Top-ups are not open yet; see [Top-ups over x402](#top-ups-over-x402-coming). 1. **Agents:** report the shortfall to the human and do not retry unchanged. See [MCP errors are data, not failures](https://aetelier.xyz/docs/help/mcp-errors/index.md). Other `402` replies are not balance errors: - `TIER_TOO_LOW`, `RECONCILE_REQUIRES_PRO`, `SSE_REQUIRES_PRO` and `TRACER_REQUIRES_PRO` mark features open to selected accounts. Adding units does not clear them. - `CONCURRENT_CAP_REACHED` means the account's collector cap is in use; stop a collector to deploy another. The cap is lower on [the floor](#the-floor). - A fit `402` containing `concurrent-fit cap reached` means too many fits are running; wait for one to finish. ## The floor An account is **on the floor** when every unit balance is zero or below, unless it is one of the selected accounts. On the floor: - its oldest remote collectors, up to the floor's collector cap, keep running and draw no units; - platform collectors, and remote collectors beyond the cap, are stopped; - new remote collectors can still be deployed up to the cap; past it, a deploy returns `CONCURRENT_CAP_REACHED`; - fits and swarms return `402` until compute units are added. Reaching the floor deletes nothing: collected data, datasets and fits are kept. ## Verify your email to unlock the signup grant A new account receives a one-time signup grant of data and compute units, credited once its email is verified; `signup_grant` in the catalog holds the amounts. Until then the balance reads zero, so the account is on the floor and fits and platform collectors return `402`. Open the verification link; the grant lands the next time the account's balance is read, for example when the webapp loads. Signup units may expire or be adjusted ([Terms of Service](https://aetelier.xyz/terms) §4). ## Top-ups over x402 (coming) Top-ups are not open yet. They open first on Solana devnet, for listed testers only; mainnet comes later. Check the live state, no key needed: ```bash curl -s https://aetelier.xyz/payments/topup/status ``` | Reply | Status | | ------------------------------------------------- | ----------------- | | `"status": "disabled"` | **OPENS SOON** | | `"status": "operational"` with a devnet `network` | **OPEN · DEVNET** | | `"status": "degraded"` | **DELAYED** | | no answer | **UNAVAILABLE** | How a top-up will work: - You buy a bundle from `bundles` in USDC on Solana, over x402 v2. Coinbase Developer Platform is the facilitator: it verifies and settles each payment and pays the Solana network fee, so the paying wallet needs USDC only. - A top-up is two HTTP calls. Prepare answers `402` with the price in `PAYMENT-REQUIRED`; submit carries the signed payment in `PAYMENT-SIGNATURE`, and a settled reply returns `PAYMENT-RESPONSE`. - The payment is signed on your machine. Aetelier never receives or stores wallet keys. - Units are credited once, keyed to the payment's on-chain signature, and the receipt is fetched by memo. See [I paid but my units are not credited](https://aetelier.xyz/docs/help/payment-not-credited/index.md). - Aetelier adds the prepare step before the `402`, so a stock x402 client will not work unchanged. A public, signed payer CLI is coming. Until top-ups open, the prepare, submit and receipt calls answer `503` with code `topup_disabled`, while the status endpoint answers `disabled`. Once devnet opens, an account not on the tester list gets `403` with code `topup_not_allowed`. The top-up `402` asks for a payment. The balance `402`s above only refuse work and carry no x402 headers. Bundle purchases are final except where the law requires a refund ([Terms of Service](https://aetelier.xyz/terms) §6). ## Related - [Error-code index](https://aetelier.xyz/docs/help/errors/index.md) — every code, its verbatim string and its fix - [Feature access](https://aetelier.xyz/docs/help/tiers/index.md) — features open to selected accounts, and their codes - [MCP errors are data, not failures](https://aetelier.xyz/docs/help/mcp-errors/index.md) — how a `402` reads to an agent - [I paid but my units are not credited](https://aetelier.xyz/docs/help/payment-not-credited/index.md) — receipts by memo, and support - [`fit_pricing`](https://aetelier.xyz/docs/mcp/tools/#fit_pricing) — read a fit's compute price before running it # Feature access **Some features are open only to selected accounts today.** Nothing can be bought to open them. Every account can run remote collectors, model fits and Convection swarms, paid for in prepaid units, and read governance data. Metered access by units is coming and replaces most of these gates. ## Open to every account | Feature | Draws | Notes | | -------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Remote (bring-your-own) collectors** | data units, once per collector per UTC day | You run `aetelier-agent` — see [My collector deployed but no data is landing](https://aetelier.xyz/docs/help/collector-no-data/index.md) | | **Model fits** | compute units, charged only when the fit converges | Read the price first with [`fit_pricing`](https://aetelier.xyz/docs/mcp/tools/#fit_pricing) | | **Convection swarms** | compute units, charged only when the swarm converges | The price is fixed when the swarm is admitted — see [How metering works](https://aetelier.xyz/docs/help/tokens/#how-metering-works) | | **Governance reads** | no units | Catalog, completeness and scorecards, up to your account's window ceiling | | **Collector state by polling** | no units | [`collector_status`](https://aetelier.xyz/docs/mcp/tools/#collector_status) and [`collector_health`](https://aetelier.xyz/docs/mcp/tools/#collector_health) | Every rate is in the public catalog, under `action_rates`, at (no key needed). ## Open to selected accounts | Feature | Code (HTTP) | Do this instead | | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | **Platform (managed) collectors** | [`TIER_TOO_LOW`](https://aetelier.xyz/docs/help/errors/#tier_too_low) (402) | Deploy a remote collector | | **Platform collectors on Solana** | [`FORBIDDEN`](https://aetelier.xyz/docs/help/errors/#forbidden) (403) | Deploy a remote collector | | **Live reconciliation** — a manifest with `[collect.reconcile]` `enabled = true` | [`RECONCILE_REQUIRES_PRO`](https://aetelier.xyz/docs/help/errors/#reconcile_requires_pro) (402) | Deploy without that section enabled | | **Live collector-state stream** — `GET /api/collectors/state/stream` | [`SSE_REQUIRES_PRO`](https://aetelier.xyz/docs/help/errors/#sse_requires_pro) (402) | Poll `collector_status` or `collector_health` | | **Tracing** — every `/api/tracer/` route, reads included | [`TRACER_REQUIRES_PRO`](https://aetelier.xyz/docs/help/errors/#tracer_requires_pro) (402) | No fallback yet; report the code | | **Longer governance windows** — `window_secs` | [`VALIDATION_ERROR`](https://aetelier.xyz/docs/help/errors/#validation_error) (400) | Retry inside the ceiling the message names | | **More collectors at once** | [`CONCURRENT_CAP_REACHED`](https://aetelier.xyz/docs/help/errors/#concurrent_cap_reached) (402) | Stop one you no longer need with [`stop_collector`](https://aetelier.xyz/docs/mcp/tools/#stop_collector), then retry | | **More fits at once** | no `code` yet (402) | Wait for a running fit to finish, then retry | The collector and fit caps are lower while an account holds no units — see [The floor](https://aetelier.xyz/docs/help/tokens/#the-floor). ## Exact messages The `error` field starts with `payment required:` (402), `forbidden:` (403) or `validation error:` (400), then the text below. The server fills in the values in braces. `{tier}` is an internal access label, such as `free`. | Code | Message | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `TIER_TOO_LOW` | `managed agents are not included in the {tier} tier — upgrade to Base or higher, or deploy a BYO (remote) agent` | | `FORBIDDEN` | `[collect.grpc] preset '{preset}' is reserved for internal use and this account is not on its allowlist — presets for this account: {presets}` | | `RECONCILE_REQUIRES_PRO` | `live reconciliation requires the Pro tier or higher — current tier: {tier}` | | `SSE_REQUIRES_PRO` | `live collector-state streaming is included from the Pro plan` | | `TRACER_REQUIRES_PRO` | `trace configuration is included from the Pro plan` | | `VALIDATION_ERROR` | `window_secs must be between 1 and {max_secs} for your plan` | | `CONCURRENT_CAP_REACHED` | `concurrent-collector cap reached ({in_flight}/{cap}) for the {tier} tier — release a collector or upgrade` | | none | `concurrent-fit cap reached ({in_flight}/{cap}) for the {tier} tier — wait for a fit to finish or upgrade` | While an account holds no units, the collector cap message reads `for the free tier floor`. Nothing to buy Some messages still name a plan or suggest an upgrade. No plan or upgrade is on sale, and nothing can be bought to open these features. ## What to do **Agents** - Branch on `code`. `FORBIDDEN` and `VALIDATION_ERROR` are shared codes and the fit limit has none, so also match the message text shown above. - The same call gets the same answer until something changes. Take the fallback in the table, or stop and report the code and message to the person you act for. - Do not try to top up. Top-ups are not open yet, and units open none of these features; only the collector and fit caps depend on the balance. - A `503` with code `SERVICE_UNAVAILABLE` and `entitlement check unavailable` on tracing or the live stream means the access check could not run. Retry with backoff. - MCP tools return the same `code` and `docs_url` inside a normal tool result — see [MCP errors are data, not failures](https://aetelier.xyz/docs/help/mcp-errors/index.md). **People** - Use the fallback in the table. Remote collectors, fits, swarms and governance reads stay open on every account. - For questions about access, email **support@aetelier.xyz** with the code, the time (and timezone) and what you called. - After your account's access changes, allow up to a minute before you retry. ## What is coming Metered access by units is coming. When it ships: - **Platform collectors** open to any account whose balance covers one day of both daily rates, which the catalog's `action_rates` lists as `byo_collector_day_data` and `managed_collector_day_compute`. Platform collectors on Solana stay open to selected accounts until their daily cost is measured. - **Tracing** opens to every account. Each new trace draws compute units; reads and resubmits draw none. - **Live reconciliation** opens to every account, included in the collector-day rate. - **The live collector-state stream and governance windows** open to every signed-in account, with the same window ceilings for every account. - **The collector cap** goes. Your unit balance decides how many collectors run, within the [platform limits](https://aetelier.xyz/docs/help/platform-limits/index.md). - **Fits** get one limit on runs in flight for every account, answered with `429` instead of `402`. `TIER_TOO_LOW`, `RECONCILE_REQUIRES_PRO`, `SSE_REQUIRES_PRO`, `TRACER_REQUIRES_PRO` and `CONCURRENT_CAP_REACHED` then stop being sent. A short balance still answers `INSUFFICIENT_DATA_TOKENS` or `INSUFFICIENT_COMPUTE_TOKENS` — see [The 402 balance errors](https://aetelier.xyz/docs/help/tokens/#the-402-balance-errors). Units are prepaid, non-transferable service credits, not money. Top-ups are not open yet: the public status at reads `disabled`, shown as **OPENS SOON**. Top-ups open first on Solana devnet, for listed testers only (**OPEN · DEVNET**); mainnet comes later. Every status word is in [Top-ups over x402](https://aetelier.xyz/docs/help/tokens/#top-ups-over-x402-coming). ## Related - [Error-code index](https://aetelier.xyz/docs/help/errors/index.md) — every code, with its anchor - [Units and the 402 error](https://aetelier.xyz/docs/help/tokens/index.md) — what each unit kind pays for - [MCP errors are data, not failures](https://aetelier.xyz/docs/help/mcp-errors/index.md) — how a gate reads to an agent - [Platform limits](https://aetelier.xyz/docs/help/platform-limits/index.md) — boundaries every account shares - [My collector deployed but no data is landing](https://aetelier.xyz/docs/help/collector-no-data/index.md) — running a remote collector # MCP errors are data, not failures **For agents.** A backend failure from the `aetelier-mcp` server returns as an ordinary result, not a protocol error. Read it and adapt in the same loop. Nothing below is a dead end; each maps to a concrete next action. ```json { "ok": false, "error": " 402: payment required: insufficient DATA token balance (0) to deploy a collector", "code": "INSUFFICIENT_DATA_TOKENS", "docs_url": "https://aetelier.xyz/docs/help/errors/#insufficient_data_tokens" } ``` `error` is the backend message behind a ` :` prefix. `code` and `docs_url` appear when the backend sends them, and `docs_url` lands on the [error-code index](https://aetelier.xyz/docs/help/errors/index.md), the per-code catalog. Branch on `code` when it is present and on the message when it is not. This page is the narrative recovery guide. Health first Call [`platform_health`](https://aetelier.xyz/docs/mcp/tools/#platform_health) before real work. If a service reads anything other than `ok`, that capability is unreachable — retry later rather than hammering it. ## Field guide | Status / signal | Means | Do this | | -------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `401` | API key missing, wrong, revoked or expired | Re-mint the key in the webapp (Settings → Security); set it as `AETELIER_API_KEY` for the local binary, or send it as `Authorization: Bearer ` to the hosted endpoint. Do not retry unchanged | | `402` | Refused, not charged: units short, not open for this account, or a cap reached | Sort it with [Reading a 402](#reading-a-402). Do not retry until the cause changes | | `403` | Authenticated, but not your resource | Do not retry. Confirm the id belongs to the caller; re-list to get a current one | | `429` | Rate limited | Back off and retry with increasing delay. Do not tighten the loop | | `400` with `Not converged after` | The fit did not converge at the given tolerance, and nothing was charged | Raise `tolerance` above the server default of `50` and refit; raise it again if it still fails | | not-found for an id | The collector, fit, or dataset id is wrong or gone | Re-list (`list_collectors`, `list_fits`, `list_datasets`) to get a current id | ## Reading a 402 A `402` from these tools is a refusal, not a payment request. It carries no x402 headers, and the refused action was not charged. Sort it into one of three groups below. Fit 402s carry no `code` yet, so match them on the message; a `code` on them is coming. Every 402 message starts with `payment required:`, so match the rest as a substring. ### Units short | `code` | Message contains | Means | | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------- | | [`INSUFFICIENT_DATA_TOKENS`](https://aetelier.xyz/docs/help/errors/#insufficient_data_tokens) | `insufficient DATA token balance` | Collector deploy refused: data units below one | | [`INSUFFICIENT_COMPUTE_TOKENS`](https://aetelier.xyz/docs/help/errors/#insufficient_compute_tokens) | `insufficient COMPUTE token balance` | Platform collector deploy refused: compute units below one | | none yet | `this fit costs {cost} compute tokens; your balance is {balance}` | Fit refused before it ran | | none yet | `this fit costs {cost} compute tokens; balance fell short mid-run` | Fit ran, but was not charged and returns no fit | `INSUFFICIENT_COMPUTE_TOKENS` comes only from a platform collector deploy over the REST API. `deploy_collector` registers remote collectors only, so it never sends it. **Do this:** stop, and report the shortfall to the human — the action, its cost, and the balance. Read a cost before acting with [`fit_pricing`](https://aetelier.xyz/docs/mcp/tools/#fit_pricing) or the public catalog at `https://aetelier.xyz/api/payments/catalog` (no key): `action_rates` holds the per-action rates and `tokens_per_usd` the list rate in units per US dollar. - An account whose email is not verified holds no units. Verifying the email credits the signup grant the next time the account opens the webapp. - An account with no units at all still deploys remote collectors, up to a lower cap. - Top-ups are not open yet. They open first on Solana devnet for listed testers, in USDC over x402, and mainnet comes later. Read the state at `https://aetelier.xyz/payments/topup/status`: `disabled` reads OPENS SOON, `operational` on a devnet `network` reads OPEN · DEVNET, `degraded` reads DELAYED, and a failed fetch reads UNAVAILABLE. A mainnet `network` still reads OPENS SOON. - The MCP server has no balance or top-up tool yet; both are coming, and so is a public, signed CLI payer. ### Not open for this account These features are open to selected accounts. Adding units does not change that, and nothing can be bought to open them. `{tier}` is a slug the server fills in. The current tools do not trigger these codes: `deploy_collector` registers remote collectors only and asks for no live reconciliation, and no tool opens the live collector stream or tracing. An agent calling the REST API directly can meet them. | `code` | Message contains | Do this | | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`TIER_TOO_LOW`](https://aetelier.xyz/docs/help/errors/#tier_too_low) | `managed agents are not included in the {tier} tier` | Deploy a remote collector instead; [`deploy_collector`](https://aetelier.xyz/docs/mcp/tools/#deploy_collector) always registers one | | [`RECONCILE_REQUIRES_PRO`](https://aetelier.xyz/docs/help/errors/#reconcile_requires_pro) | `live reconciliation requires the Pro tier or higher` | Redeploy without `[collect.reconcile] enabled = true` | | [`SSE_REQUIRES_PRO`](https://aetelier.xyz/docs/help/errors/#sse_requires_pro) | `live collector-state streaming is included from the Pro plan` | Poll [`collector_status`](https://aetelier.xyz/docs/mcp/tools/#collector_status) or [`collector_health`](https://aetelier.xyz/docs/mcp/tools/#collector_health) instead | | [`TRACER_REQUIRES_PRO`](https://aetelier.xyz/docs/help/errors/#tracer_requires_pro) | `trace configuration is included from the Pro plan` | Report it and move on; reading traces is gated too | ### Cap reached | `code` | Message contains | Do this | | ----------------------------------------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [`CONCURRENT_CAP_REACHED`](https://aetelier.xyz/docs/help/errors/#concurrent_cap_reached) | `concurrent-collector cap reached` | Stop a collector you no longer need with [`stop_collector`](https://aetelier.xyz/docs/mcp/tools/#stop_collector), and retry once it has released. The cap is lower at a zero balance | | none yet | `concurrent-fit cap reached` | Wait for a running fit to finish, then retry | | none yet | `the zero-balance floor allows` | The daily fit allowance at a zero balance is used. Retry after 00:00 UTC | [`PAYMENT_REQUIRED`](https://aetelier.xyz/docs/help/errors/#payment_required) is the fallback for any other coded 402. Read `error`, report it, and do not retry unchanged. ## A worked recovery A fit that does not reach the convergence threshold returns a `400`: ```json { "ok": false, "error": " 400: validation error: estimation did not produce a usable result: Not converged after {iterations} iterations (gradient norm = {norm})" } ``` The agent reads it and retries with a looser `tolerance` than the default `50` — the error is the instruction: ```json { "tool": "fit_hawkes", "arguments": { "dataset_id": "ds_9f3a…", "tolerance": 500 } } ``` A `402` on a fit is not a convergence problem: no `tolerance` changes it. Stop the loop and report it as above. A longer recovery is in [Worked examples → Flow 2](https://aetelier.xyz/docs/mcp/examples/#flow-2-fit-and-forecast-a-model). ## No "contact support" is emitted machine-side The server never returns a `contact support` string, a phone number, or a ticket id in a tool result. Every machine-side error is **actionable by the caller** — re-mint, report a shortfall, deploy a remote collector, stop a collector, wait, back off, loosen, or re-list. Escalation to a human is a last resort for a human operator, documented in [Getting help](https://aetelier.xyz/docs/help/getting-help/index.md); it is never part of the agent loop. ## Related - [Error-code index](https://aetelier.xyz/docs/help/errors/index.md) — every code, its verbatim string, and the fix - [Tool reference](https://aetelier.xyz/docs/mcp/tools/index.md) — the result contract per tool - [Worked examples](https://aetelier.xyz/docs/mcp/examples/index.md) — full ask → tool-sequence → recovery flows - [Aetelier for agents](https://aetelier.xyz/docs/agents/overview/index.md) — capability map, gating, identifiers - [Units and the 402 error](https://aetelier.xyz/docs/help/tokens/index.md) · [Feature access](https://aetelier.xyz/docs/help/tiers/index.md) — what `402` gates resolve to # I paid but my units are not credited **USDC top-ups are not open yet.** While the top-up status reads **OPENS SOON**, no top-up can be paid, so there is nothing to credit. Top-ups open first on Solana devnet, for listed testers only; mainnet comes later. The rest of this page describes how a top-up will be credited once they open. ## Check the top-up status The status endpoint is public and needs no key: ```bash curl -s https://aetelier.xyz/payments/topup/status ``` | Reply | Status | Meaning | | ------------------------------------------------- | ----------------- | ---------------------------------------------------- | | `"status": "disabled"` | **OPENS SOON** | Top-ups are off; nothing can be paid | | `"status": "operational"` with a devnet `network` | **OPEN · DEVNET** | Listed testers can top up with devnet test USDC | | `"status": "degraded"` | **DELAYED** | Top-ups are running slowly; payments may settle late | | no answer | **UNAVAILABLE** | The status could not be read; try again shortly | `network` is a CAIP-2 id; devnet is `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1`. While top-ups are off, the prepare, submit and receipt endpoints answer `503` with code `topup_disabled`. Once devnet opens, an account that is not on the tester list gets `403` with code `topup_not_allowed`. ## How a top-up will be credited Top-ups use x402 v2: USDC on Solana, with Coinbase Developer Platform as the facilitator that verifies and settles each payment. The facilitator pays the Solana network fee, so the paying wallet needs USDC only. Aetelier never receives or stores wallet keys. A top-up is two HTTP calls. Prepare answers `402` with the price in `PAYMENT-REQUIRED` and a `memo` that names this top-up. Submit carries the signed payment in `PAYMENT-SIGNATURE`, and its reply says where the payment stands: | Submit reply | `code` | Meaning | What to do | | ------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- | | `200` | `settled` | Settled on-chain and credited once; the reply carries the receipt, a `PAYMENT-RESPONSE` header and, when available, your new balance | Nothing | | `202` | `settling` | Submitted, but settlement is not confirmed yet; the platform keeps rechecking it in the background | Do not pay again; fetch the receipt by memo after the `Retry-After` delay | | `409` | `verify_rejected` | The facilitator rejected the payment; nothing was credited | Start a new top-up | | `409` | `intent_failed` | This memo already failed; the reply carries its receipt | Read `receipt.failure` in the receipt table below | | `410` | `intent_expired` | The signing window closed before the payment was submitted | Start a new top-up | | `503` | `verify_unavailable` | The facilitator could not verify the payment; nothing was credited | Start a new top-up after the `Retry-After` delay | | `503` | `topup_unavailable` | Top-ups are starting or the payment network is unreachable; the payment was not sent | Start a new top-up after the `Retry-After` delay | Each credit is keyed to the payment's on-chain signature, so one payment never credits twice. Repeating a submit for the same memo returns its current receipt, never a second credit. A public, signed payer CLI that waits for settlement and reads the receipt for you is coming. ## Fetch the receipt by memo Read the receipt with the API key of the account that started the top-up. A memo that is unknown or belongs to another account gets `404` with code `memo_not_found`: ```bash curl -s https://aetelier.xyz/api/payments/topups/ \ -H "Authorization: Bearer $AETELIER_API_KEY" ``` The reply is `200` in every state. Read `receipt.state`: | `receipt.state` | Meaning | | ---------------------------------------- | --------------------------------------------------------------------------------------------------- | | `settled` | Credited once; `signature` is the on-chain transaction | | `settling` | Still being checked; `pending_signature`, when present, is the transaction the facilitator reported | | `failed` with `failure: not_landed` | No matching transaction was found yet; the platform keeps rechecking for up to 24 hours | | `failed` with `failure: verify_rejected` | Final; nothing was credited | | `expired` | Final; the payment was never submitted | | `open` | Prepared, not yet submitted | A settled top-up also shows in your ledger history with reason `topup`. ## Still not credited: email support Email **support@aetelier.xyz** if the receipt reads `settled` but your balance has not moved, or if USDC left your wallet and the receipt still reads `failed` after 24 hours. Include: - the `memo`; - the transaction signature, from the receipt or your wallet history; - the network, from `receipt.network`; - the bundle `sku` and the approximate time, with timezone. Never send keys Support never needs your wallet keypair file, private key or seed phrase, or your API key. Do not send them to anyone. See [Official channels](https://aetelier.xyz/docs/help/official-channels/index.md). Response targets are in the [support policy](https://aetelier.xyz/docs/help/support-policy/index.md). ## Refunds Units are prepaid, non-transferable service credits, not money. Bundle purchases are final except where the law requires a refund ([Terms of Service](https://aetelier.xyz/terms) §6). Send refund requests to support@aetelier.xyz with the same memo, signature and network. ## Related - [Units and the 402 error](https://aetelier.xyz/docs/help/tokens/index.md) — what units fund, and what a short balance means - [Getting help](https://aetelier.xyz/docs/help/getting-help/index.md) — the escalation path and the status page - [Error-code index](https://aetelier.xyz/docs/help/errors/index.md) — platform API error codes