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

# Chat Completions

`POST /v1/chat/completions`

Produces a model reply for a conversation. Requests and responses use the exact shape of the OpenAI Chat Completions API.

***

## Request

```
POST https://api.robinmesh.com/v1/chat/completions
Authorization: Bearer rmesh_live_your_key_here
Content-Type: application/json
```

### Request body

| Field               | Type            | Required | Description                                                                       |
| ------------------- | --------------- | -------- | --------------------------------------------------------------------------------- |
| `model`             | string          | Yes      | ID of the model that should handle the request. See \[Models]\().                 |
| `messages`          | array           | Yes      | The conversation so far, as an ordered array of message objects.                  |
| `stream`            | boolean         | No       | Pass `true` to receive SSE chunks as tokens are generated. Default `false`.       |
| `max_tokens`        | integer         | No       | Upper bound 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 end generation when produced.                          |
| `frequency_penalty` | number          | No       | Discourages tokens in proportion to how often they have appeared (-2.0 to 2.0).   |
| `presence_penalty`  | number          | No       | Discourages any token that has appeared at least once (-2.0 to 2.0).              |
| `seed`              | integer         | No       | Requests reproducible sampling. Best effort only, 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-robinmesh-job-id: job_8fx2kp3m9qrstvwxyz
x-robinmesh-tx-hash: 0x8c2f41ab9e07d3565f18c4ba20d97e631a5c08f2be49d176e0a3b58c917d24f0
x-robinmesh-settlement-tx: 0x3a91d5c07f26e8b4915dc3a08e67f21b49c0d8a35e7612fb08d94ce5a172b36d
x-robinmesh-worker: 0x9d24ab7e315f68c0d1b2fa4c8e0973d65a1cbe48
x-robinmesh-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 whatever content was 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 preceding `[DONE]`. Once the stream has closed, inspect the response object again to read the `x-robinmesh-settlement-tx` header.

### Streaming example

```bash
curl https://api.robinmesh.com/v1/chat/completions \
  -H "Authorization: Bearer rmesh_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

A request's credits go into escrow the moment it arrives, and the worker collects them only once the job has settled.

| 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 that run past roughly 500 output tokens are billed per 1,000 output tokens instead of at the flat rate. The escrow locks an estimate up front; produce fewer tokens than estimated and the difference comes back 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` | Nobody on the network is hosting this model right now. Carries `retry_after` in seconds.       |
| `504`  | `job_timeout`          | The 120-second window elapsed with no worker finishing. The escrowed credits came back to you. |

The full error envelope is documented 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.robinmesh.com/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.