# $coldboot

> Hold $coldboot to receive eligible creator-fee rewards in SOL, or opt in to AI credits worth 1.5x the USD value of your reward share. Spend available credits through an OpenAI-compatible gateway.

This is the product guide for AI assistants helping a user get started. Holding tokens does not automatically configure a client or guarantee available credits. The default reward election is SOL. Credit rewards require opting in, meeting eligibility rules, and a completed allocation. Fees and payouts depend on trading activity. The target allocation interval is 10 minutes, not a guarantee.

## Start here

- [Agent skill](https://coldboot.pro/skills/holdapi/SKILL.md): Setup workflow for Claude, Codex, and other coding agents. Can be read directly; installing it is optional.
- [Reward guide](https://coldboot.pro/docs): Eligibility, SOL versus credits, payout timing, and common questions.
- [Developer guide](https://coldboot.pro/developers): Supported endpoints, setup examples, billing, and error handling.
- [Dashboard](https://coldboot.pro/dashboard): The user signs in with a wallet message, or, for a wallet inside an app like fomo that cannot sign for other sites, by withdrawing an exact USDC amount ($1.01 to $1.99, credited back as AI credit) to the treasury; then selects AI credits and creates or revokes keys.

## Gateway

Base URL: https://coldboot.pro/v1
Authentication: Authorization: Bearer followed by the user's full api_ key. This dashboard key is for coldboot.pro/v1, not for the OpenAI or BlockRun origin.

## MCP and reusable clients

Streamable HTTP MCP endpoint: https://coldboot.pro/v1/mcp. Configure a dashboard Bearer key privately in a host that supports manual Authorization headers. No OAuth discovery is provided. For desktop hosts, install https://coldboot.pro/downloads/holdapi-client-0.2.0.tgz and launch holdapi-mcp over stdio with HOLDAPI_BASE_URL=https://coldboot.pro/v1 and HOLDAPI_API_KEY in the private process environment. See https://coldboot.pro/developers#mcp for configuration. Optional HOLDAPI_OUTPUT_DIR enables local image saving with plain filenames, validation and no overwrites. Remote MCP never reads or writes server files.

TypeScript: npm install --allow-remote=all https://coldboot.pro/downloads/holdapi-client-0.2.0.tgz, then import HoldApiClient from @holdapi/client. Requires Node.js 20.3+. Python: python -m pip install https://coldboot.pro/downloads/holdapi_client-0.1.0-py3-none-any.whl, then from holdapi import HoldApiClient. Requires Python 3.10+. Explicitly set baseURL (TypeScript) or base_url (Python) to https://coldboot.pro/v1; the shared clients default to a different gateway. Read https://coldboot.pro/downloads/client-readme.md and https://coldboot.pro/downloads/python-readme.md. Checksums: https://coldboot.pro/downloads/SHA256SUMS.txt.

Paid MCP tools require maxCreditMicroUsd as a positive decimal string. SDK options use bigint maxCreditMicroUsd in TypeScript or integer max_credit_micro_usd in Python. These set x-api-max-credit-micro-usd, a per-call reservation ceiling between 1 and 999999999999999. The gateway rejects an excessive reservation before dispatch; authoritative provider usage above the reservation can still be charged. There is no aggregate conversation budget and MCP batches are unsupported. Exact billing uses integer microUSD; pending charges are null/None, not zero. Paid requests never retry automatically. JSON SDK helpers reject stream:true before dispatch; use a streaming HTTP client for SSE.

## Verified live setup

The 0.2.0 local launcher supports HOLDAPI_API_KEY_FILE as an alternative to HOLDAPI_API_KEY, never both. Key files must be small regular owner-only files, with an absolute path. HOLDAPI_INPUT_DIR enables relative input_path/mask_path for local edits; decoded image inputs total at most 8 MiB and edit JSON at most 12 MiB. HOLDAPI_OUTPUT_DIR enables validated image/audio/video saving with a plain filename; completed owned jobs can be saved through poll_job. Remote MCP exposes no local file paths. Output type and signature must match; raw PCM is not saved by the helper.

HOLDAPI_SESSION_CAP_USD sets an optional cumulative reservation cap per local launcher process, using decimal USD with at most six fractional digits. Concurrent holds count immediately. Unknown charges stop new paid calls; tracked jobs remain pollable. Repeated polls are accounted once, including later known cost corrections. A restart resets the cap. This is not wallet-wide or persistent, and provider overruns may exceed a reservation. Capped sessions refuse untracked settling jobs and unbounded lifetime tools. Without the setting, only per-call limits apply. Use session_budget to inspect the local guard.

MCP provides typed search, Exa, read-only Solana RPC and prediction-market tools. Image quality is supported for verified account-rail OpenAI image models with live USD per-size maximum pricing; never discount a reservation based on quality. background and output_format are unsupported by the upstream contract and are refused before generation. Transparent brand marks remain unavailable through this route.

Discover current models, rates and tool readiness from this gateway before making a paid request.

For a first image request, verify openai/gpt-image-2 and 1024x1024 in GET /v1/models, then send this JSON to POST /v1/images/generations with the user's privately loaded Bearer key:

```json
{"model":"openai/gpt-image-2","prompt":"A simple green pixel duck on a dark background. No text.","size":"1024x1024","n":1}
```

This is a paid request. A completed response provides the image in data[0].url or data[0].b64_json. Inspect x-api-cost-micro-usd and x-api-cost-pending before reporting a final charge. The default request waits; allow up to five minutes for image generation. For recovery, add async:true or Prefer: respond-async and follow the returned gateway poll_url when the response is 202. Do not retry creation automatically after a timeout.

Use GET /v1/tools for the current audio, search, Exa, read-only RPC, prediction-market data, price feeds, DeFiLlama, Decisions, portrait/RealFace enrollment, sandbox and phone-lookup contracts. Their methods, required ownership and rail readiness matter as well as their existence. A dashboard key must never be sent to api.openai.com or a BlockRun origin.

Supported authenticated endpoints:
- GET /v1/models: Discover current provider/model IDs and pricing. Each row carries a type: chat rows are priced per million tokens, image estimates per image/size, video rates per second, audio rates by pricing.basis. Missing prices are unavailable, not zero. Do not guess model IDs.
- GET /v1/balance: Read the current credit balance.
- POST /v1/chat/completions: Chat Completions, including supported streaming requests.
- POST /v1/images/generations: Image generation with a verified supported image model. Choose type:image and read pricing.is_estimate and pricing.sizes. Published reservation estimates are not a guaranteed final charge.
- POST /v1/images/edits: Edit with a supported model using JSON inline image data or multipart image files.
- GET /v1/images/generations/{id}: Recover an asynchronous image job using the gateway-returned poll_url and a key for the same wallet.
- GET /v1/tools: Discover the registered non-model tools and native protocol readiness.
- POST /v1/audio/speech and /v1/audio/sound-effects: Return JSON audio URLs for supported priced models.
- POST /v1/audio/generations and GET /v1/audio/generations/{id}: Create music and poll a wallet-owned job.
- POST /v1/messages and /v1/responses: Stateless native Anthropic and OpenAI requests, subject to the constraints below.
- POST /v1/videos/generations: Start a video job with a video model from /v1/models and a prompt. Answers 202 with a job id and a poll_url. Priced per second of clip.
- GET /v1/videos/generations/{id}: Poll that job with the same key. 202 while it renders, 200 with the clip URL when it completes. Polling is free. Credits are charged on the completing poll and released if the job fails.
- POST /v1/data/solana/rpc: One Solana JSON-RPC read, forwarded to a read-only node. Standard account, token, block and transaction methods, the DAS asset reads (getAsset, getAssetsByOwner, searchAssets, getTokenAccounts, getAssetProof), getPriorityFeeEstimate, getTransactionsForAddress, getProgramAccountsV2 and getTokenAccountsByOwnerV2, with the parameters Helius defines. Spends no credits, but the key's wallet must hold a credit balance above zero. One request per call: writes, simulateTransaction and methods off the allowlist answer 400 rpc_method_not_allowed, and a JSON-RPC batch array answers 400 invalid_json.
- GET /v1/data/feeds/{path}: Free crypto, fx and commodity price feeds: crypto/list, crypto/price/BTC-USD, crypto/history/BTC-USD and the fx and commodity equivalents.
- GET /v1/data: The data catalog. Rows with served: true answer on this deployment; inspect each row rather than assuming priced endpoints are served. An unavailable data endpoint answers 503 data_endpoint_unavailable without charging.

Data calls are limited per key and by one ceiling shared by every key; GET /data reports the current figures under limits. The shared ceiling answers 429 data_capacity_exceeded with a retry-after header.

GET /v1/tools discovers registered tool endpoints, methods, pricing policy, payment-rail readiness and ownership requirements. Paid pricing must be validated per request. POST /v1/audio/speech returns JSON audio URLs, not raw audio bytes. POST /v1/audio/generations may return 202 with a gateway id and poll_url; GET /v1/audio/generations/{id} is scoped to the creating wallet and cached after completion. Music duration is a hint, not a cost cap. Resource IDs for jobs, sandboxes and enrollment are gateway-issued and wallet-owned. Assistants, embeddings, audio transcription and general file uploads are not implemented. For chat clients, configure a custom OpenAI base URL and Chat Completions mode. Audio and other tools use their explicit routes. This gateway is not a replacement for the Claude or Codex account running the setup agent.

## Setup boundaries

The user handles purchases, wallet approval, reward election, and key creation in the dashboard. Never ask for a seed phrase or private key. Store API keys in a local ignored environment file or a server secret, never public browser code, a commit, logs, or chat. Read balance and models before requesting a paid test. Confirm a paid test's model and output limit with the user unless their existing request already authorizes it. Do not retry uncertain paid requests automatically.

Registered phone reads are POST /phone/lookup and /phone/lookup/fraud with phoneNumber in E.164 format, subject to validated quoted pricing. Direct registered free feeds include /crypto, /fx and /commodity list/price/history paths, /usstock/list and /stocks/{market}/list. Consult GET /tools for rail readiness and supported contracts.

Full native endpoints are https://coldboot.pro/v1/messages and https://coldboot.pro/v1/responses. Anthropic SDKs append /v1/messages, so their base is https://coldboot.pro; OpenAI clients use https://coldboot.pro/v1. Keys belong only to this gateway. On the account rail, POST /messages supports Anthropic-native sync/stream requests with qualified anthropic/model IDs and max_tokens; POST /responses supports OpenAI-native sync/stream requests with qualified openai/model IDs and max_output_tokens. Omitted output caps default to 8192 or the model's lower maximum; choose a small explicit cap. Only currently priced, configured models are accepted. Native exchanges are stateless: store:false, no background jobs, previous_response_id, conversation, stored prompt references or hosted tools. Caller function tools are supported but the caller executes them. Messages accepts the dashboard key in x-api-key only when Authorization is absent; Bearer also works. Caller credentials are not forwarded to the provider. Messages use anthropic-version:2023-06-01; beta headers/context_management are unsupported. Gemini native is unavailable on this rail, use Chat Completions. Conservative reservations include image inputs; authoritative account usage settles the final charge. Pending or zero cost headers before settlement do not prove a free call.

Image editing uses POST /images/edits (provider image2image): JSON image as an inline base64 data URI or array, or multipart image/image[] files, with model, prompt, size and n. The default generation call waits. On supported rails, async:true in JSON or Prefer: respond-async returns 202 with a gateway opaque id and poll_url. GET /images/generations/{id} is scoped to the creating wallet and caches completed results. Pending quotes and reservations are not final charges. Never infer unsupported model, size or rail capabilities.

## Billing

Requests reserve estimated or quoted cost before execution. Available credit must cover the reservation and requests must fit the per-call spending ceiling. Settlement can release a difference or record an unpaid usage shortfall. Future earned credits first repay that shortfall. A timeout does not prove a request was free. See the developer guide for error meanings and current behavior.