> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chipipay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat & Streaming

> General-purpose AI chat with 8 models. Synchronous or real-time streaming via SSE.

Base URL: `https://api.chipipay.com/v1`

## When to use each

|                  | `/ai/chat`                                                                                                   | `/ai/chat/stream`                                                            |
| ---------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| **How it works** | Send a prompt, get the full response in one JSON object                                                      | Send a prompt, get tokens one-by-one via Server-Sent Events                  |
| **Best for**     | Backend agents, batch processing, serverless functions, any case where you process the full response at once | Chatbots, real-time UIs, any interface where users watch the response appear |
| **Latency feel** | User waits until the entire response is generated (can be 1-5 seconds)                                       | First token arrives in \~200ms, text streams as it's generated               |
| **Cost**         | Per token                                                                                                    | Same per-token cost, debited when stream completes                           |
| **Complexity**   | Simple — one HTTP request, one JSON response                                                                 | Requires SSE parsing (see examples below)                                    |

### What you can build

* **Customer support bot** — `/chat/stream` for real-time replies, `/chat` for classification/routing behind the scenes
* **Code assistant** — `/chat/stream` so developers see code being written line by line
* **Transaction summarizer** — `/chat` to batch-summarize wallet activity on your backend
* **AI-powered search** — `/chat` to rerank results or generate answers from your data
* **DeFi copilot UI** — `/chat/stream` for the conversational layer, pair with `/think` for portfolio decisions
* **Telegram/Discord bot** — `/chat` for simple Q\&A, `/chat/stream` if the platform supports progressive message edits
* **Content generation** — `/chat` to generate descriptions, emails, or marketing copy

***

## POST /ai/chat

General-purpose AI. Any prompt, any model. Powers chatbots, code assistants, finance apps.

**Cost:** Per token (varies by model — see [Models & Pricing](/services/ai-api/models))

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST https://api.chipipay.com/v1/ai/chat \
    -H "Authorization: Bearer sk_prod_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "haiku",
      "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is USDC?"}
      ],
      "max_tokens": 256
    }'
  ```

  ```json Response (201) theme={null}
  {
    "text": "USDC is a stablecoin pegged 1:1 to the US dollar...",
    "model": "haiku",
    "provider": "anthropic",
    "usage": {
      "inputTokens": 16,
      "outputTokens": 47,
      "totalTokens": 63
    },
    "cost": {
      "charged": 0.000352,
      "currency": "USD"
    },
    "finishReason": "stop",
    "latencyMs": 1422
  }
  ```
</CodeGroup>

### Request body

| Field        | Type   | Default   | Description                                                                                   |
| ------------ | ------ | --------- | --------------------------------------------------------------------------------------------- |
| `model`      | string | `"haiku"` | Any model from [Models & Pricing](/services/ai-api/models).                                   |
| `messages`   | array  | Required  | Array of objects with `role` (`"system"`, `"user"`, or `"assistant"`) and `content` (string). |
| `max_tokens` | number | 4096      | Max output tokens. Capped at the model's limit.                                               |

### Response fields

| Field          | Type   | Description                                                         |
| -------------- | ------ | ------------------------------------------------------------------- |
| `text`         | string | The model's response text.                                          |
| `model`        | string | Model ID used (e.g. `"haiku"`, `"gpt-4o-mini"`).                    |
| `provider`     | string | `"anthropic"`, `"openai"`, or `"google"`.                           |
| `usage`        | object | Token counts: `inputTokens`, `outputTokens`, `totalTokens`.         |
| `cost`         | object | `charged` (USD) and `currency`.                                     |
| `finishReason` | string | `"stop"` (completed), `"length"` (hit max\_tokens), or `"unknown"`. |
| `latencyMs`    | number | Server-side processing time in milliseconds.                        |

***

<h2 id="streaming">
  POST /ai/chat/stream
</h2>

Streaming version of `/ai/chat`. Returns **Server-Sent Events (SSE)** with token-by-token text deltas. Ideal for chatbots and real-time UIs.

**Cost:** Same as `/ai/chat` — per token, debited after stream completes.

Same request body as `/ai/chat`. Same models, same auth.

<CodeGroup>
  ```bash cURL theme={null}
  curl -N -X POST https://api.chipipay.com/v1/ai/chat/stream \
    -H "Authorization: Bearer sk_prod_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{"model": "haiku", "messages": [{"role": "user", "content": "Tell me a short joke"}]}'
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch("https://api.chipipay.com/v1/ai/chat/stream", {
    method: "POST",
    headers: {
      "Authorization": "Bearer sk_prod_YOUR_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "haiku",
      messages: [{ role: "user", content: "Tell me a short joke" }],
    }),
  });

  const reader = response.body!.getReader();
  const decoder = new TextDecoder();
  let buffer = "";

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    buffer += decoder.decode(value, { stream: true });
    const lines = buffer.split("\n");
    buffer = lines.pop() ?? "";

    for (const line of lines) {
      if (!line.startsWith("data: ")) continue;
      const data = JSON.parse(line.slice(6));

      if (data.error) {
        throw new Error(`Stream error: ${data.error}`);
      } else if (data.done) {
        console.log("\nCost:", data.cost.charged, "USD");
        console.log("Tokens:", data.usage.totalTokens);
      } else {
        console.log(data.text); // append to your UI
      }
    }
  }
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.chipipay.com/v1/ai/chat/stream",
      headers={"Authorization": "Bearer sk_prod_YOUR_KEY"},
      json={
          "model": "haiku",
          "messages": [{"role": "user", "content": "Tell me a short joke"}],
      },
      stream=True,
  )

  for line in response.iter_lines():
      if not line or not line.startswith(b"data: "):
          continue
      import json
      data = json.loads(line[6:])
      if data.get("error"):
          raise RuntimeError(f"Stream error: {data['error']}")
      elif data.get("done"):
          print(f"\nCost: ${data['cost']['charged']}")
      else:
          print(data["text"], end="", flush=True)
  ```
</CodeGroup>

### SSE event format

| Event      | Shape                                                                                   | When                         |
| ---------- | --------------------------------------------------------------------------------------- | ---------------------------- |
| Text delta | `data: {"text":"token"}`                                                                | Each token as it's generated |
| Completion | `data: {"done":true,"model":"haiku","provider":"anthropic","usage":{...},"cost":{...}}` | Stream finished              |
| Error      | `data: {"error":"message"}`                                                             | Provider error during stream |

<Note>
  The completion event includes `model`, `provider`, `usage`, and `cost` — same fields as the synchronous response. Credits are debited when this event fires.
</Note>

***

## Error handling

| HTTP Status | Meaning                                               |
| ----------- | ----------------------------------------------------- |
| 201         | Success (chat)                                        |
| 200         | Success (stream — SSE follows)                        |
| 400         | Invalid request (missing messages, unsupported model) |
| 401         | Invalid, inactive, or expired API key                 |
| 402         | Insufficient credits                                  |
| 429         | Rate limit exceeded                                   |
| 502         | Provider error (model returned an error)              |