---
title: "Chat"
method: POST
path: "/v1/chat"
tags: ["chat"]
---

# Chat

`POST /v1/chat`

## Request

- Base URL: `https://api.bitpoort.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.bitpoort.com/v1/chat`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Chat with the blockchain RAG — ask anything about on-chain activity.

Automatically selects the best available LLM provider:
1. Anthropic Claude with native tool calling
2. DeepSeek V3 with RAG context injection (fallback)

Grounding enforcement:
- Report intents trigger mandatory tool calls before LLM generation
- Evidence gate blocks responses with insufficient data
- Numeric claim guard validates dollar amounts and percentages

## Request body

- ChatRequest
  - `message` string, required: The user's question
  - `chain` string, nullable: Filter context to a specific chain (e.g. 'ETH')
  - `history` ChatMessage[]: Previous conversation turns for multi-turn context
    - `role` string, required: 'user' or 'assistant'
    - `content` string, required
  - `conversation_id` string, nullable: Client-generated conversation id. On the bridge engine it maps to a live managed-agent session (true multi-turn: prior tool results stay in the agent's context). The legacy engine ignores it.
  - `max_chunks` integer: Max RAG chunks to retrieve
  - `provider` string, nullable: Force a provider: 'anthropic' or 'deepseek'. None = auto-detect.
  - `model` string, nullable: Per-request model override (e.g. 'claude-sonnet-4-20250514', 'gpt-4o'). If set, takes priority over server config.
  - `llm_api_key` string, nullable: Per-request LLM API key override — bring-your-own-key for hybrid RPC synthesis.

## Response `200`

Successful Response

- ChatResponse
  - `answer` string, required
  - `model` string, required
  - `provider` string, required
  - `chunks_used` integer, required
  - `tools_used` string[]
  - `evidence` EvidenceItem[]
    - `ref_id` integer, nullable
    - `type` string
    - `source_id` string
    - `chain` string, nullable
    - `topic` string, nullable
    - `block_number` integer, nullable
    - `timestamp` string, nullable
    - `confidence` number, nullable
    - `summary` string
    - `etherscan_url` string, nullable
    - `label_source` string, nullable
    - `time_window` string, nullable
  - `citations` object
  - `confidence` string
  - `trace_id` string, nullable
  - `grounding` GroundingMeta: Metadata about the grounding quality of this response.
    - `grounded` boolean
    - `is_report_intent` boolean
    - `tools_called` string[]
    - `rag_chunks_count` integer
    - `tool_rows_returned` integer
    - `evidence_ids_used` integer[]
    - `ungrounded_claims` string[]
    - `evidence_gate_passed` boolean
  - `suggestions` string[]: Suggested follow-up questions based on the response context
  - `rag_time_ms` number, required
  - `llm_time_ms` number, required
  - `total_time_ms` number, required
  - `credits_remaining` number, nullable
  - `low_balance_warning` string, nullable
  - `verification` object[], nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/bitpoort/apis/bitpoort-api.md) · [All operations](https://skmtc.dev/bitpoort/apis/bitpoort-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bitpoort/apis/bitpoort-api/revisions/1a51d8566777?raw)