> For the complete documentation index, see [llms.txt](https://docs.robincompute.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.robincompute.org/api-reference/completions.md).

# Chat Completions

`POST /v1/chat/completions`

Sends a conversation to a model and returns its reply. Requests and responses match the OpenAI Chat Completions API shape exactly.

***

## Request

```
POST https://api.robincompute.org/v1/chat/completions
Authorization: Bearer rcompute_live_your_key_here
Content-Type: application/json
```

### Request body

| Field               | Type            | Required | Description                                                                   |
| ------------------- | --------------- | -------- | ----------------------------------------------------------------------------- |
| `model`             | string          | Yes      | ID of the model to run. See \[Models]\().                                     |
| `messages`          | array           | Yes      | The conversation so far: an ordered array of message objects.                 |
| `stream`            | boolean         | No       | Set `true` to receive SSE chunks as tokens are generated. Default `false`.    |
| `max_tokens`        | integer         | No       | Cap on generated tokens.                                                      |
| `temperature`       | number          | No       | Sampling temperature, 0.0 through 2.0.                                        |
| `top_p`             | number          | No       | Nucleus sampling cutoff.                                                      |
| `stop`              | string or array | No       | One or more sequences that stop generation when produced.                     |
| `frequency_penalty` | number          | No       | Penalizes tokens in proportion to how often they have appeared (-2.0 to 2.0). |
| `presence_penalty`  | number          | No       | Penalizes any token that has appeared at least once (-2.0 to 2.0).            |
| `seed`              | integer         | No       | Requests reproducible sampling. Best effort, since inference is distributed.  |

### Message object

```json
{
  "role": "user",
  "content": "Explain how Robinhood Chain achieves 100ms block times."
}
```

Valid roles: `system`, `user`, `assistant`.

### Example request

```json
{
  "model": "qwen3-8b",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant. Keep answers concise."
    },
    {
      "role": "user",
      "content": "What is an ERC-4337 smart account?"
    }
  ],
  "stream": false,
  "max_tokens": 512,
  "temperature": 0.7
}
```

***

## Response (non-streaming)

```json
{
  "id": "chatcmpl-job_8fx2kp3m...",
  "object": "chat.completion",
  "created": 1750000000,
  "model": "qwen3-8b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "An ERC-4337 smart account is a smart contract wallet that can sponsor gas, batch transactions, and support social recovery..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 48,
    "completion_tokens": 214,
    "total_tokens": 262
  }
}
```

### Response headers (non-streaming)

```
x-robincompute-job-id: job_8fx2kp3m9qrstvwxyz
x-robincompute-tx-hash: 0x8c2f41ab9e07d3565f18c4ba20d97e631a5c08f2be49d176e0a3b58c917d24f0
x-robincompute-settlement-tx: 0x3a91d5c07f26e8b4915dc3a08e67f21b49c0d8a35e7612fb08d94ce5a172b36d
x-robincompute-worker: 0x9d24ab7e315f68c0d1b2fa4c8e0973d65a1cbe48
x-robincompute-credits-remaining: 1412
```

***

## Streaming response

With `stream: true`, the API replies with Server-Sent Events in the OpenAI chunk format. Each event carries a `delta` object holding the content just produced.

```
data: {"id":"chatcmpl-job_8fx2kp3m...","object":"chat.completion.chunk","created":1750000000,"model":"qwen3-8b","choices":[{"index":0,"delta":{"role":"assistant","content":"A "},"finish_reason":null}]}

data: {"id":"chatcmpl-job_8fx2kp3m...","object":"chat.completion.chunk","created":1750000000,"model":"qwen3-8b","choices":[{"index":0,"delta":{"content":"Program "},"finish_reason":null}]}

data: {"id":"chatcmpl-job_8fx2kp3m...","object":"chat.completion.chunk","created":1750000000,"model":"qwen3-8b","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]
```

`finish_reason` arrives on the last chunk before `[DONE]`. After the stream closes, read the `x-robincompute-settlement-tx` header off the response object; that is your settlement receipt.

### Streaming example

```bash
curl https://api.robincompute.org/v1/chat/completions \
  -H "Authorization: Bearer rcompute_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.3-70b",
    "messages": [{"role": "user", "content": "Write a haiku about Robinhood Chain."}],
    "stream": true
  }'
```

***

## Credit charges

Your credits go into escrow the moment the request arrives. The worker collects them only after the job settles on-chain.

| Charge point      | Timing                                                                 |
| ----------------- | ---------------------------------------------------------------------- |
| Escrow lock       | On arrival, before the request is routed anywhere                      |
| Escrow release    | Once the proof-of-completion passes on-chain verification              |
| Credit deduction  | When settlement is confirmed                                           |
| Refund on failure | Automatic whenever 120 seconds pass without a worker finishing the job |

Completions past roughly 500 output tokens bill per 1,000 output tokens instead of the flat rate. The escrow locks an estimate up front; generate fewer tokens than estimated and the difference returns to your balance.

***

## Errors

| Status | Code                   | Meaning                                                                                       |
| ------ | ---------------------- | --------------------------------------------------------------------------------------------- |
| `400`  | `invalid_request`      | The body failed to parse or omits a required field                                            |
| `400`  | `model_not_found`      | No model matches the requested ID                                                             |
| `402`  | `insufficient_credits` | Your balance cannot cover the model's tier                                                    |
| `503`  | `no_workers_available` | No worker is hosting this model right now. Carries `retry_after` in seconds.                  |
| `504`  | `job_timeout`          | The 120-second window closed with no worker finishing. The escrowed credits came back to you. |

The full error envelope lives in \[Errors]\(

).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.robincompute.org/api-reference/completions.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.