# HoldAPI client and MCP launcher

Node.js 20.3 or newer. Install the versioned package from HoldAPI:

```sh
npm install --allow-remote=all https://coldboot.pro/downloads/holdapi-client-0.2.0.tgz
```

npm 12 disables URL installs by default. The flag permits this installation only; it does not change your saved npm configuration. Run this inside the project where you want to use the client.

Set `HOLDAPI_API_KEY` privately in your server or launcher environment. The local launcher also accepts `HOLDAPI_API_KEY_FILE`, an absolute path to a small owner-only key file. Configure exactly one key source. Never put dashboard keys in browser bundles, source control, arguments or chat.

```ts
import { HoldApiClient } from '@holdapi/client';

const client = new HoldApiClient({ apiKey: process.env.HOLDAPI_API_KEY!, baseURL: "https://coldboot.pro/v1" });
const catalog = await client.models();
console.log(catalog.data);
const result = await client.createImage({
  model: 'openai/gpt-image-2', prompt: 'A small robot tending a garden',
  size: '1024x1024', n: 1,
}, { maxCreditMicroUsd: 100_000n });
console.log(result.data, result.billing);
```

Discover live IDs and prices before a paid call. `maxCreditMicroUsd` is a positive bigint reservation ceiling, at most 999999999999999, enforced by the gateway before dispatch. Verified provider usage above the reservation may still be charged. A pending charge is `null`, never inferred to be zero. Billing values use exact bigint millionths of a dollar; serialize them as decimal strings. Requests never retry automatically.

Methods include `balance`, `models`, `tools`, `chat`, `createImage`, `editImage`, `speech`, `soundEffects`, `music`, `createVideo`, `nativeMessages`, `nativeResponses`, `pollJob` and `invokeTool`. Jobs use the returned relative poll URL or opaque ID and the same wallet. Poll explicitly while status is 202; retain the handle if interrupted. JSON helpers reject `stream:true` before sending; use a streaming HTTP transport for SSE. Image creation defaults to a five-minute timeout.

## MCP

For hosts that support a manually configured Bearer token, use Streamable HTTP at `https://coldboot.pro/v1/mcp`, with your dashboard key in the private Authorization setting. This server does not provide OAuth discovery or write files on the gateway.

For desktop hosts, install the package above and configure a local stdio server:

```json
{
  "mcpServers": {
    "holdapi": {
      "command": "npx",
      "args": ["--no-install", "holdapi-mcp"],
      "env": { "HOLDAPI_BASE_URL": "https://coldboot.pro/v1" }
    }
  }
}
```

Run the host from the project where you installed the package, or use the absolute path to `node_modules/.bin/holdapi-mcp`. Set `HOLDAPI_API_KEY` in the host's private launcher environment. On Windows hosts that cannot execute npm wrappers, use `node` with the absolute path to `node_modules/@holdapi/client/dist/cli.js`.

Optional `HOLDAPI_INPUT_DIR` allows image edits to read a relative `input_path` and optional `mask_path` within that folder. Paths outside it, symlink escapes and unrecognized files are refused. Source images total at most 8 MiB; edit JSON has a separate 12 MiB ceiling, so a 1.3 MiB PNG fits after base64 encoding. Remote MCP does not expose file-path arguments.

Optional `HOLDAPI_OUTPUT_DIR` is a local project output directory. Completed image, speech, sound-effect, music and video tools accept a plain `filename` such as `hero.png`, `voice.mp3` or `clip.mp4`. Pending jobs retain their handle; pass a filename to `poll_job` when collecting the completed output. Existing files are never overwritten. Downloads validate public HTTPS hosts, type and byte limits without sending your API key. Raw PCM has no reliable container signature and is not saved by this helper. Without an output directory, tools return URLs or inline data.

Optional `HOLDAPI_SESSION_CAP_USD` sets a positive decimal USD reservation budget for one launcher process, for example `1.00`. The shared guard accounts for concurrent calls, settled costs and outstanding holds; repeated polls do not double count. Ambiguous errors retain liability and stop new paid calls; tracked jobs can still be polled. A new process starts a new budget. This is not a wallet-wide or persistent cap, and authoritative provider overruns can exceed reserved amounts. Capped sessions refuse untracked settling jobs and tools with unbounded lifetime charges. Without this setting only per-call limits apply.

Set `HOLDAPI_BASE_URL=https://coldboot.pro/v1` for Coldboot. The shared launcher defaults to a different gateway; the override requires HTTPS or loopback HTTP.

MCP tools discover balance/models/gateway tools, run bounded chat/image/edit/audio/music/video requests, poll owned jobs and invoke registered nonfinancial tools. Paid tools require `maxCreditMicroUsd` as a decimal string. Budgets apply to each invocation, not the whole conversation. Batches are unsupported. Always inspect structured billing and distinguish pending reservations from settled charges. Disconnecting does not guarantee a free call.

Typed MCP search, Exa, read-only Solana RPC and prediction-market tools describe their supported fields. The generic catalog tool remains for other registered contracts.

Image `quality` is available on supported OpenAI models through the account rail, with a live USD maximum-per-image reservation. `background` and `output_format` are not exposed by the current upstream contract and are refused before generation. Transparent brand marks remain unavailable through this route; putting transparency in the prompt does not guarantee alpha output.

The optional `@holdapi/client/media` export saves validated PNG/JPEG/WebP, MP3/WAV/Ogg/M4A and MP4/WebM output locally. Credentials are never sent to media hosts.