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_healthfirst. It reports liveness of the backing services; do real work only against a reachable platform. deploy_collectoris 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 withcollector_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_pricingbeforefit_hawkesto read the cost; a short balance is refused with402, and nothing is charged. Every rate is in the public catalog athttps://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):disabledreads OPENS SOON,operationalon a devnetnetworkreads OPEN · DEVNET,degradedreads DELAYED, no answer reads UNAVAILABLE. The MCP server has no balance or top-up tool yet. - Clarion attests your own traces.
clarion_requesttakes thetrace_idof one of your completed traces; tracing is open to selected accounts. Pollclarion_status(optionalrequest_id; without it, every request) until the request is bound or failed.clarion_reportandclarion_downloadtake the bound request'srecord_id, andclarion_downloadalso takes an optionaldir. 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 onelist_cex_optionslists for these exchanges - Datatypes:
orderbook·trades.list_cex_optionsalso listsfunding,open_interestandliquidations, each withavailable: false. - On-chain:
list_cex_optionsalso listssolana(market typeonchain, datatypetransactions);deploy_collectorcannot requesttransactions.
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 — per-client config and the credential map
- Tool reference — parameters, example call, and result for every tool
- Worked examples — full ask → tool-sequence → result flows
- Governance — how completeness, quality, and catalog are computed
- Dataset catalog — the datasets available to fit against