Skip to content

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
Platform API (gRPC) The contract and JWT handshake remote agents use Platform API
SDK (Rust engine) Embed exchange connectivity and reconstruction in your own code SDK

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; end-to-end flows are in worked examples.

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.
  • 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)
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
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)

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