# Heimdallm

> An inference marketplace: independent providers serve models behind one OpenAI-compatible API, each at their own published prices, billed on measured usage.

This is Heimdallm at https://staging.impossiblecarrot.cc. Use this origin and the API below rather than another
product with the same name. Everything here is described in the documentation at more length.

## Agent skill and CLI

Read [the versioned CLI skill](https://staging.impossiblecarrot.cc/SKILL.md) for customer and provider workflows,
installation, credential reuse, and task recovery. [Agent setup](https://staging.impossiblecarrot.cc/docs/agents.md)
explains installation into Hermes, OpenClaw, Claude Code, and Codex.

An MCP server exposes the marketplace as tools: hosted over Streamable HTTP at
`https://api-staging.impossiblecarrot.cc/api/mcp` with the API key as `Authorization: Bearer`, or run locally with
`heimdall-staging mcp`. [MCP server](https://staging.impossiblecarrot.cc/docs/mcp.md) lists the tools and client setup.

The staging CLI is installed with `npm install -g @staging-heimdall/cli` and invoked as
`heimdall-staging`. Set `HEIMDALL_STAGING_BASE_URL=https://api-staging.impossiblecarrot.cc/api/v1` and
`HEIMDALL_STAGING_WEB_URL=https://staging.impossiblecarrot.cc`. Public catalogue reads need no login.
The [CLI reference](https://staging.impossiblecarrot.cc/docs/cli.md) names each command's flags.
The [OpenAPI document](https://staging.impossiblecarrot.cc/api/openapi.json) describes the public API.

## The API

The base URL is `https://api-staging.impossiblecarrot.cc/api/v1`.

Chat completions, completions, embeddings and transcriptions keep OpenAI's request and response
shapes, so an OpenAI SDK reaches the marketplace by changing `baseURL` and the key. The fields added
on top, `usage.cost` and `provider` among them, are extensions a client that does not know them can
ignore. Image generation is served at `POST /images` on the reference Image API, in a shape of its
own. Video generation is an asynchronous job: `POST /videos` accepts it, `GET /videos/{jobId}` polls
it or a `callback_url` is told when it finishes, and `GET /videos/{jobId}/content` downloads the clip.
Meshes use `POST /meshes` and their own job and download contract. Reranking and speech synthesis
have dedicated API references. Responses and Messages use their own events and supported features;
read [compatibility](https://staging.impossiblecarrot.cc/docs/migration.md) before configuring a client.

`GET https://api-staging.impossiblecarrot.cc/api/v1/models` is the catalogue and needs no credential. Resolve a model id against
it before sending a request. Which models exist, which providers serve them and what each charges
all change without notice, and that endpoint answers all three.

## Keys

An inference request carries `Authorization: Bearer <key>`. A key starts with `sk-hd-v1-`, is shown
once when it is created, and spends the credit balance of the account it belongs to. That header is
the whole of the authentication. The browser session cookie reaches the site and never the API.

## What a request costs

Every request is billed in the unit it is sold in: per token for most models, per second of audio
for a transcription, per image or megapixel for image generation. Each provider sets its own prices per
endpoint and publishes them as exact decimal strings. The listed price is the billed price. There is
no subscription and no markup on inference. Chat responses carry the exact charge in `usage.cost`;
other protocols expose accounting as described in their references and generation receipts. Charges use measured usage and published prices.

Two rules keep that honest:

- A unit consumed at a price the endpoint never published is **never billed at zero**. It is
  recorded as unpriced and flagged.
- A measurement with no samples behind it reads as absent, not as zero. Throughput, time to first
  token and uptime are measured from real traffic, never taken from a provider's own claim, and a
  figure nothing observed is published as nothing at all.

## Reading the documentation as markdown

Every documentation page is served as markdown at the address it is served as HTML, two ways:

- Append `.md` to the path: `https://staging.impossiblecarrot.cc/docs/quickstart.md`
- Send `Accept: text/markdown` to the ordinary path: `https://staging.impossiblecarrot.cc/docs/quickstart`

Both answer `content-type: text/markdown`. Every response from a documentation address names
`Accept` in `Vary`, because the address alone does not decide which of the two comes back.

The markdown is the source the page is rendered from, with the components on the page expanded to
the content they show, so nothing on the page is missing from it.

`https://staging.impossiblecarrot.cc/llms.txt` indexes every page, each with its own description.

## Funding with a signed authorization (x402)

An account already holding a key can be topped up without leaving the API. `GET
https://api-staging.impossiblecarrot.cc/api/v1/deposits/x402` describes the rail — the asset, the networks, the receiving address
and the amount bounds — or answers `{"enabled": false}` on a deployment that has not configured
it. `POST` the amount and network; the 402 that comes back carries the payment requirements, and
resubmitting the same request with a `PAYMENT-SIGNATURE` header holding the signed EIP-3009
authorization settles it. Send your API key with the request and the credit lands on your account;
a wallet already bound to an account credits that account without a key. Neither names an account,
and the request is refused with the authorization unused.

The balance appears once the transfer confirms on chain, at the same confirmation depth every
crypto deposit waits for; the response states the wait.

## Starting without an account

Reuse an existing CLI login or securely supplied API key. If authorized Google/GitHub access or
a browser session is available, complete normal sign-in and CLI login with it. Otherwise:

1. Give the human this URL: `https://staging.impossiblecarrot.cc/login`.
2. They sign in or create an account, then connect the installed CLI using its normal login flow.
3. Wait for access, then check `heimdall-staging key --json`. Public discovery can continue meanwhile.

`heimdall-staging login --manual` supports a browser on another computer: keep the terminal open
and enter the short-lived code from the approval page. A website login alone does not connect the CLI.
Do not ask for passwords or long-lived API keys in chat. [Authentication](https://staging.impossiblecarrot.cc/docs/authentication.md)
describes existing key import and browser authorization options.