Title: AI.Bitcoin.com LLM Guide
Audience: Coding assistants helping devs integrate AI.Bitcoin.com
Last updated: 2025-10-31

GOAL
Help developers embed AI.Bitcoin.com’s OpenAI-compatible APIs for chat, embeddings, audio, and add-ons without guesswork.

STYLE FOR ANSWERS
- Favor TypeScript (Node 18+) examples that import the official `openai` SDK with `baseURL: 'https://ai.bitcoin.com/api'`.
- Show concise, runnable snippets; highlight required headers, model names, and toggle flags explicitly.
- Mention balance requirements and add-on costs when advising on Linkup search, Memory, scraping, or YouTube transcripts.
- Surface limitations honestly; if unsure about a model or feature, say so and point to the reference links below.

REQUIRED PACKAGES AND VERSIONS
- npm install openai@^5.8.0
- Optional for manual SSE parsing: npm install eventsource-parser@^1.0.0

CORE CONCEPTS
- OpenAI compatibility: `POST /api/v1/chat/completions`, `/api/v1/messages`, `/api/v1/embeddings`, and `/api/v1/audio/speech` mirror OpenAI payloads and responses.
- Authentication: send either `Authorization: Bearer <NANOGPT_API_KEY>` or `x-api-key: <NANOGPT_API_KEY>`; both headers are accepted.
- Balances: Bitcoin.com tenants spend verse-funded `usd_credits` first, then `usd_balance` or crypto holdings. Insufficient funds return HTTP 402.
- Add-ons: model suffixes (`:online`, `:online/linkup-deep`, `:memory`, `:memory-30`) or payload flags (`scraping: true`, `youtube_transcripts: false`) toggle paid services.
- Pricing metadata: final non-stream or SSE chunks include `x_nanogpt_pricing` with `amount` and `currency` so clients can show exact spend.
- Tooling: function/tool calling follows OpenAI's schema (functions array, `tool_choice`). Anthropic-compatible `/v1/messages` adapter handles tool_use/tool_result mapping automatically.
- Prompt caching and memory: prompt_caching/cache_control toggles 5m or 1h cache TTLs, and memory compression replaces prior turns before dispatch.
- BYOK: bring-your-own-key mode activated with x-use-byok: true or byok.enabled: true to forward requests using stored provider credentials.

GLOSSARY
- Linkup: First-party web search add-on. Standard search costs $0.006 per call; deep search costs $0.06 and yields richer results.
- Memory: Lossless conversation compression via Polychat. Enabled with `:memory` or `memory: true`; replaces message history and charges the actual compression cost.
- Scraping: HTML/PDF fetch when `scraping: true` (max 5 URLs per turn by default, ~$0.001 per URL). Requires sufficient balance.
- YouTube transcripts: Auto-fetches up to 3 transcripts from the latest turn when `youtube_transcripts` is omitted or true. Each transcript costs $0.01.
- x_nanogpt_pricing: JSON object returned in responses/streams detailing model spend and add-on charges.
- Verse credits: Monthly credits allocated to Bitcoin.com staking wallets; visible as `usd_credits` and consumed before cash balance.
- Prompt caching: reusable prompt segments activated by prompt_caching/cache_control or anthropic-beta headers with optional cutAfterMessageIndex.
- Reasoning stream: delta.reasoning text emitted by reasoning-enabled models; reasoning_details provides structured metadata when available.

HARD RULES AND GOTCHAS
- Always send a `model` and at least one user message. Omitted `messages` or unsupported models return HTTP 400.
- Do not request add-ons without balance; Linkup, scraping, memory, and transcripts all run a preflight balance check and will short-circuit with 402 if funds are low.
- Disable transcripts explicitly (`youtube_transcripts: false`) when copying prompts that include YouTube links but should not incur transcript fees.
- Scraping only activates on non-YouTube URLs in the latest user turn when `scraping: true`; exceeding the URL cap or requesting unsupported schemes throws 400.
- Memory replaces the entire conversation with a single compressed system message; retain the server-issued conversation id if you rely on recall across requests.
- Expect the final SSE event (or non-stream JSON) to carry `x_nanogpt_pricing`; do not parse legacy `<NanoGPT>` tags.
- Tool calls must respect OpenAI function signatures. If a provider cannot execute tools, the platform returns an error with `finish_reason: 'tool_calls'` absent.

QUICKSTART MINIMAL
client.ts
```ts
import OpenAI from 'openai';

export const aiBitcoin = new OpenAI({
  apiKey: process.env.NANOGPT_API_KEY,
  baseURL: 'https://ai.bitcoin.com/api',
});
```

chat.ts
```ts
import { aiBitcoin } from './client';

const completion = await aiBitcoin.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [
    { role: 'system', content: 'You are an assistant that answers in concise bullet points.' },
    { role: 'user', content: 'Give me two ideas for a Bitcoin wallet onboarding flow.' },
  ],
});

console.log(completion.choices[0].message);
console.log(completion.x_nanogpt_pricing); // total cost metadata
```

STREAMING EXAMPLE
```ts
import { aiBitcoin } from './client';

const stream = await aiBitcoin.chat.completions.create({
  model: 'gpt-4o',
  stream: true,
  reasoning: { enabled: true },
  messages: [
    { role: 'user', content: 'Summarize the latest Bitcoin.com wallet release notes.' },
  ],
});

for await (const event of stream) {
  const delta = event?.choices?.[0]?.delta;
  if (!delta) continue;
  if (delta.reasoning) process.stdout.write(`[thinking] ${delta.reasoning}`);
  if (delta.content) process.stdout.write(delta.content);
  if (event.x_nanogpt_pricing) console.log('\nCost:', event.x_nanogpt_pricing);
}
```

ADD-ON EXAMPLES
- Linkup web search:
```ts
await aiBitcoin.chat.completions.create({
  model: 'gpt-4o:online',
  messages: [{ role: 'user', content: 'Compare current Bitcoin.com wallet promo campaigns.' }],
});
```
- Deep search and Memory together:
```ts
await aiBitcoin.chat.completions.create({
  model: 'claude-3-5-sonnet:online/linkup-deep:memory-30',
  messages: history, // include prior turns; server compresses and retains 30 days
});
```
- Disable transcripts and enable scraping:
```ts
await aiBitcoin.chat.completions.create({
  model: 'gpt-4o-mini',
  youtube_transcripts: false,
  scraping: true,
  messages: [
    { role: 'user', content: 'Summarize https://news.bitcoin.com and https://blog.bitcoin.com/latest.' },
  ],
});
```

ENDPOINT REFERENCE
- GET https://ai.bitcoin.com/api/v1/models — list models; supports `?detailed=true`.
- POST https://ai.bitcoin.com/api/v1/chat/completions — primary chat interface (stream via `stream: true`).
- POST https://ai.bitcoin.com/api/v1/messages — Anthropic-compatible adapter for Claude SDKs.
- POST https://ai.bitcoin.com/api/v1/embeddings — OpenAI embeddings drop-in (float or base64 outputs).
- POST https://ai.bitcoin.com/api/v1/audio/speech — Text-to-speech; supply `model`, `input`, and optional `voice`.
- POST https://ai.bitcoin.com/api/v1/memory — Manage persisted context (create, read, delete by `conversation_id`).

IMAGE GENERATION URLS AND RETENTION
Return hosted URLs instead of base64 and know how long they live.

```ts
const img = await client.images.generate({
  model: 'gpt-image-1',
  prompt: 'a small cabin in the woods at sunrise',
  size: '1024x1024',
  response_format: 'url', // uploads to temporary public storage
});

// img.data => [{ url: 'https://.../generated.png' }]
```

- Inputs: image-to-image/edit accepts `imageDataUrl` (data URI) or an https URL; https inputs are fetched and normalized to data URLs server-side. Vision chat also accepts `{ type: 'image_url', image_url: { url: 'data:image/png;base64,...' } }`.
- Outputs: `response_format: 'url'` uploads generated images to our object storage and returns short-lived links; if upload fails you get `b64_json` instead.
- Retention: generated image files are kept for 24 hours and then permanently deleted; use the URL only for short-term fetches, not archival.

PROMPT CACHING
Enable prompt reuse with prompt_caching or cache_control, and set Anthropic beta headers when required.

COMMON TROUBLESHOOTING
- 401 or 403: verify the API key is active, spelled correctly, and passed via either `Authorization` or `x-api-key` (not both with different values).
- 402: user lacks balance or add-on credits; prompt them to top up or disable paid extras.
- 429: requests exceed per-key or per-IP limits (see `/api/v1/models?detailed=true` for model-specific rate hints); apply exponential backoff.
- Missing transcripts or scraped data: confirm flags (`youtube_transcripts`, `scraping`) and ensure URLs are in the most recent user message.
- Tool call regressions: ensure every tool response includes `role: 'tool'` and a `tool_call_id` that matches the assistant’s request.

LINKS
- API explorer: https://ai.bitcoin.com/api
- Models list: https://ai.bitcoin.com/api/v1/models
- Status updates: https://nano-gpt.com/status (mirrors AI.Bitcoin.com backend uptime)
- Support: mailto:support@ai.bitcoin.com