crypto-comp public API

Version 1.0.0 · /api/v1/openapi.json (OpenAPI 3.1, public, no key required) · mint a key

Quickstart

First, mint a key in your panel. It is shown once and cannot be recovered — store it before closing the dialog. Then set two variables and work down this page:

Every command below uses only these variables plus $STRATEGY_ID and $RUN_ID, which come out of steps 3 and 4. They are executed verbatim by this project's end-to-end suite against a real installation, so a stale example fails a build rather than your afternoon.

Endpoints

Scopes

A key carries a subset of these, chosen when you mint it. Each endpoint requires exactly one. There is no implication: strategies:write does not grant strategies:read, and a key that needs both must say both. A key missing a scope gets 403 insufficient_scope naming the scope to add.

Rate limits

Counted in a fixed 60-second window, against two ceilings on the same number: one per key and one per account. Minting a second key therefore does not raise your quota — the account ceiling is the real one, and a 429's detail says which of the two you hit.

Every response — successes included — carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the window resets), so you can pace yourself before you are ever refused. A refusal adds Retry-After.

The fixed window has a boundary property worth knowing. A fixed window admits up to 2x the limit across a boundary. Documented property, not a defect. If you send your whole allowance in the last instant of one window and again in the first instant of the next, both are served. It is bounded at twice the limit and it is the price of not storing a record of every request you make.

This API is not metered against AI credit. Calls here cost nothing from your credit balance; the rate limit is the only bound. Credit is spent by the in-app AI assistant, which is a different surface.

Errors

Every error body has exactly two keys: {"error": "<code>", "detail": "…"}. Branch on error, which comes from the closed list below; detail is prose for a human and may change wording at any time. Anything machine-readable beyond the code is a header, so it can be added without changing the shape.

The full code list: bad_request unauthorized tier_limit insufficient_scope not_found spec_invalid rate_limited internal unavailable

Two are worth a note. 404 also means "not yours" — deliberately the same answer as "does not exist", so this API can never confirm that another account's id is real. 422 does not carry the validator's errors , because the body is two keys — send the spec to POST /api/v1/specs/validate, which answers 200 with the structured errors, fix them, and try again.

Money

Every monetary and statistical value crosses this API as a decimal string — "10000.00000000", never 10000. Parse them with a decimal type, not a float: 0.00000001 round-trips through a double as 1e-8, which this API will reject on the way back in. Sending a JSON number where a decimal string belongs is a 400.

The exceptions are the fields that are genuinely counts, not amounts: trade_count, bar_count, max_drawdown_duration_bars and the base_timeframe label.

Versioning

Within /api/v1, changes are additive only. Fields may be added to a response; none will be removed, renamed, or have its type narrowed, and no endpoint will move. A change that would break a working client ships as /api/v2, alongside this one.

So: ignore fields you do not recognise rather than failing on them, and branch on the error code rather than on detail or on a status alone.

Paths outside /api/v1 — everything under /api/ that this page does not list — are internal to the web application, are not versioned, and change without notice. Please do not build against them.

Keys

A key looks like mcpk_<12 hex>_<secret>. The middle segment identifies which credential you presented and proves nothing; the last segment is the secret. They travel together as one bearer token, so there is nothing to pair up.

We store only a hash, so the key is shown exactly once and we cannot recover it for you — a lost key is revoked and replaced. Revocation takes effect immediately on the next request. The mcpk_ prefix exists so a leaked key is findable by a secret scanner: if one lands in a public repository, revoke it in the panel.

Variables used by the examples on this page: $CRYPTO_COMP_BASE_URL $CRYPTO_COMP_API_KEY $STRATEGY_ID $RUN_ID