--- name: holdapi description: Set up a user's app or compatible client to spend $coldboot AI credits through the coldboot.pro OpenAI-compatible gateway. Use when the user asks to connect their credits, configure the gateway, or make a first API request. --- # Set up $coldboot credits Help the user connect available AI credits to the app or tool they choose. Read https://coldboot.pro/llms.txt and https://coldboot.pro/developers for the maintained product reference. Reward rules are at https://coldboot.pro/docs. ## 1. Establish what the user wants Inspect the chosen app's existing client and configuration. Use its existing stack. For chat, it must support a custom OpenAI-compatible base URL and Chat Completions. Audio and tools use their explicit gateway routes. For a Responses client, verify its stateless request shape and account-rail support before configuring it. Claude or Codex can help set this up, but their own subscription or native account is not replaced by this gateway. If the user has not started, direct them to https://coldboot.pro/dashboard. They connect their wallet, approve a sign-in message, opt in to AI credits, and create an API key. SOL is the default election. Holding alone does not create a spendable balance; eligible rewards must be allocated first. Existing credits remain usable after selling or switching future rewards to SOL. The user handles token purchases and wallet approvals. Do not request wallet secrets or sign transactions on their behalf. Read the reward guide instead of promising returns or immediate credits. ## 2. Configure the chosen client For an MCP agent, use https://coldboot.pro/v1/mcp with a privately configured Bearer dashboard key if its host supports manual Authorization headers. Remote OAuth discovery is unavailable. For desktop hosts install the versioned TypeScript package from 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 launcher environment. Follow https://coldboot.pro/developers#mcp. Optional HOLDAPI_OUTPUT_DIR enables validated local image output with plain filenames and no overwrites; remote MCP does not access gateway files. Never pass keys as command arguments or tool inputs. Reusable TypeScript and Python clients are documented at https://coldboot.pro/developers#sdk, with versioned downloads and SHA-256 checksums. TypeScript imports HoldApiClient from @holdapi/client and sets baseURL to https://coldboot.pro/v1; Python imports HoldApiClient from holdapi and sets base_url to https://coldboot.pro/v1. Paid MCP tools require a positive decimal-string maxCreditMicroUsd. SDK options use bigint maxCreditMicroUsd or integer max_credit_micro_usd. This caps the per-call reservation before dispatch, not guaranteed final provider usage or total conversation spending. Unknown pending charges remain null/None. Do not resubmit a paid call on timeout. JSON helpers refuse streaming before dispatch; use a streaming HTTP transport when needed. For OpenAI-compatible clients, set the base URL to https://coldboot.pro/v1, including /v1. This dashboard key authenticates coldboot.pro/v1, not OpenAI or BlockRun directly. It begins with api_ and is shown once. Ask the user to put it directly into an ignored local environment file, their tool's private settings, or a server secret. Do not ask them to paste it into chat. Never print it, commit it, or expose it in browser bundles. Use OPENAI_BASE_URL and OPENAI_API_KEY if the app supports them. Otherwise use the client's equivalent settings. Read only those required variables and report missing variable names without values. A missing key is a setup prerequisite, not a reason to fabricate a key. ## 3. Verify without spending The 0.2.0 local MCP launcher can read HOLDAPI_API_KEY_FILE instead of HOLDAPI_API_KEY. Use exactly one source, and require a small owner-only regular key file with an absolute path. HOLDAPI_INPUT_DIR permits input_path/mask_path relative to a selected folder, with containment and image checks; image inputs total at most 8 MiB and edit JSON at most 12 MiB. HOLDAPI_OUTPUT_DIR permits validated local saving for completed images, speech, sound effects, music and video. Use a plain filename and preserve returned jobs until poll_job can save the completed output. Never regenerate merely because a download failed. Raw PCM is not saved by the helper. Set HOLDAPI_SESSION_CAP_USD when the user wants a cumulative local-process reservation budget. Values are exact positive decimal USD, up to six fractional digits. Concurrent calls reserve immediately; known final costs replace holds, repeated polls do not double count and upward corrections count. Unknown charges stop new paid calls but tracked jobs remain pollable. Restarting resets the cap, so do not present it as a persistent wallet limit or guaranteed maximum final charge. Capped sessions refuse untracked settling jobs and unbounded lifetime tools. Without this setting only per-call limits apply. Typed MCP tools describe search, Exa, read-only Solana RPC and prediction-market reads. Image quality is supported only on verified OpenAI account-rail image models with live maximum pricing. background and output_format are unavailable in the provider contract and must fail before generation. Do not promise a transparent brand mark, infer alpha support from a prompt, or switch providers silently. With the user's key loaded privately, GET https://coldboot.pro/v1/models, https://coldboot.pro/v1/balance and https://coldboot.pro/v1/tools using Authorization: Bearer . These are read-only checks. Select a full provider/model ID and endpoint for the user's task, rather than always selecting chat. Image rows have type:image and published reservation estimates by size. Audio rows have type:speech, music or sound_effect and rates by pricing.basis. Never infer a nonchat ID from a chat model, or treat a missing price as zero. Do not hardcode a display name or an invented model ID. Review current prices, rail readiness and the available balance. Supported paths are GET /models, GET /balance, POST /chat/completions, POST /images/generations, POST /videos/generations, GET /videos/generations/{id}, POST /data/solana/rpc, GET /data/feeds/{path} and GET /data relative to the base URL. GET /tools discovers additional registered audio, search, data and resource tool routes with payment-rail readiness and ownership requirements. Paid pricing is validated per request before submission; discovery does not make every provider capability callable. Assistants, embeddings, audio transcription and general file uploads are not implemented. Solana reads spend no credits. POST /data/solana/rpc takes one JSON-RPC request (the standard reads, the DAS asset methods such as getAsset and searchAssets, getPriorityFeeEstimate, getTransactionsForAddress) and refuses writes and simulations with 400 rpc_method_not_allowed, and a JSON-RPC batch array with 400 invalid_json. GET /data/feeds/crypto/price/BTC-USD is a free price read. GET /data lists the data endpoints with served: true on the ones this deployment answers; do not call one marked served: false. Data calls are limited per key and by one shared ceiling that answers 429 data_capacity_exceeded with a retry-after header. Video is two steps: POST /videos/generations answers 202 with a job id and a poll_url, then GET /videos/generations/{id} with the same key answers 202 while it renders and 200 with the clip URL when it completes. Polling is free, credits are charged on the completing poll, and a failed job is not charged. Video models are priced per second; read the id, usd_per_second and max_duration_seconds from /models rather than guessing them. Speech POST /audio/speech returns JSON with an audio URL, not raw MP3 bytes. Music POST /audio/generations may return 200 inline or 202 with a gateway id and poll_url. Poll GET /audio/generations/{id} using a key for the same wallet: pending 202, completed 200 with audio URLs. Finished polls use the cached result without another charge. Music duration is a hint, not a guaranteed length or final cost cap. Use gateway-returned IDs for owned music jobs, sandboxes, portraits and enrollment. Upstream IDs or another wallet's resource do not authorize access. Sandboxes can accrue lifetime charges and require explicit termination. GET /tools lists discovery contracts; each request must also fit this deployment's configured model and method allowlists. 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. ## 4. Make a bounded first call when authorized If the user has already authorized a paid test, use that scope. Otherwise ask before spending credits, naming the model and output limit. For chat, start with one non-streaming request, a short message, max_tokens: 256 and automatic retries disabled. If a model rejects that parameter, consult its supported configuration before retrying. For images, first verify an image model and size from a supported gateway source. If none is available, stop and explain that limitation. Use one image and disclose that it is a paid request. GPT Image 2 was successfully tested through this gateway on 2026-10-12 with model openai/gpt-image-2, size 1024x1024 and n:1. Verify those choices against the live catalog before reusing them. The test's $0.00598 final charge was an observation, not a promised price. Image creation may take up to five minutes; use async:true or Prefer: respond-async for recoverable jobs, then poll only the returned gateway path. Never treat the reservation as the final charge or issue another creation call merely because the first response was slow. A request must fit both available credit and the per-call spending ceiling. Do not raise limits or switch to a more expensive model to bypass a rejection. An interrupted request may still be charged; check balance before considering a retry. ## 5. Explain the result Report the configured app, base URL, model ID, whether the read-only checks passed, and whether a paid request was actually tested. Keep keys redacted. If setup is blocked, give the next concrete step: - 401: verify the full, unrevoked dashboard key. - 402 insufficient credits: wait for earned credit or reduce the reservation. - 402 quote_over_limit: reduce the requested output or image count; more balance does not lift the ceiling. - 429: reduce request rate or concurrency. On a data call, data_capacity_exceeded is the shared ceiling, not the user's key; wait for retry-after. - 503 data_endpoint_unavailable: that data endpoint is priced and not served on this deployment. Nothing was charged. Use GET /data to see what is served. - 502/503 or timeout: check balance and explain the uncertain charge before retrying. ## Optional installation Reading this URL directly is enough for a one-time setup. If the user asks to install the skill, save this file as SKILL.md inside a holdapi folder in their existing agent skill directory. Follow that agent's current installation instructions and preserve its other skills. Do not modify agent configuration just because this document was linked.