> ## 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))

```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
}
```

### 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. |

***

## POST /ai/chat/stream

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.

```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)
```

### 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.

***

## 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) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.