# Pioneer Server API

> OpenAI- and Anthropic-compatible inference relay with smart provider routing.
> Built with Bun. Zero framework overhead.

## Base URL

```
https://alpha.pioneers.dev
```

All API paths below are relative to this base. The OpenAI-compatible root is
`https://alpha.pioneers.dev/api/v1`.

## Authentication

Inference requires an API key. Send it either way:

```
Authorization: Bearer sk-pioneer-<64 hex chars>     # OpenAI convention
x-api-key: sk-pioneer-<64 hex chars>                # Anthropic SDK convention
```

Get a key at https://alpha.pioneers.dev/keys (sign in with your wallet).
Keys spend credits; fund your address at https://alpha.pioneers.dev/leaderboard,
or create a company for funded seats at https://alpha.pioneers.dev/companies/create.

Public, no-auth endpoints: `GET /api/v1/chat/health`, `GET /health`, `GET /`,
`GET /metrics`, `GET /llms.txt`, `GET /docs`, the leaderboard, and metrics.

---

## Agent Handoff — wire Pioneers as a provider

Pioneers is OpenAI-compatible, so any agent runtime that accepts a custom
OpenAI base URL can use it. Given only a `sk-pioneer-...` key, an agent should:

1. **Validate the key first** (expect HTTP 200; do not edit config on non-200):
   ```bash
   curl -sS -o /dev/null -w "%{http_code}" \
     https://alpha.pioneers.dev/api/v1/chat/completions \
     -H "Authorization: Bearer $PIONEERS_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"model":"auto","messages":[{"role":"user","content":"ping"}]}'
   ```

2. **Configure the provider** with:
   - `baseUrl`: `https://alpha.pioneers.dev/api/v1`
   - `apiKey`: the `sk-pioneer-...` key (from env `PIONEERS_API_KEY`, never on disk)
   - `api`: `openai-completions`
   - model id: `auto` (Pioneers routes to the best backend internally)

3. **Verify** with a one-shot completion asking the model to echo a sentinel
   string, and confirm the sentinel appears in the response.

OpenClaw users: the full step-by-step installer (env, openclaw.json, auth
profiles, gateway restart) lives in the **Pioneers Installer** agent skill.

---

## Chat Completions

### POST /api/v1/chat/completions

OpenAI-compatible chat completions with smart routing across providers.
Auth + credits required. Supports streaming (SSE), tool calling, and
reasoning/thinking token passthrough.

**Request:**
```json
{
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "Hello" }
  ],
  "model": "auto",
  "max_tokens": 1000,
  "temperature": 0.7,
  "stream": false,
  "tools": [],
  "tool_choice": "auto"
}
```

**Response (non-streaming):**
```json
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "Qwen3.5-27B.Q4_K_M.gguf",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Hello! How can I help?",
      "reasoning_content": "The user said hello..."
    },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 12, "completion_tokens": 8, "total_tokens": 20 }
}
```

**Response (streaming):** Server-Sent Events (SSE)
```
data: {"object":"chat.completion.chunk","choices":[{"delta":{"reasoning_content":"thinking..."}}]}

data: {"object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello!"}}]}

data: [DONE]
```

**Thinking/Reasoning Tokens:** Models that support chain-of-thought (Qwen,
DeepSeek) emit `reasoning_content` on the message delta, passed through
transparently.

**Model Resolution:** `"auto"` (or omitted) routes to the first healthy
provider's default model. OpenAI/HuggingFace model names are mapped to the
active backend.

---

### POST /api/v1/code/chat/completions

Same OpenAI spec as `/chat/completions`, but injects Pioneer's coding-agent
system prompt before relaying. Auth + credits required.

---

### GET /api/v1/chat/models

List available models across configured providers. Auth required.
(`/api/v1/models` and `/api/v1/code/models` are aliases.)

```json
{
  "object": "list",
  "data": [
    { "id": "Qwen3.5-27B.Q4_K_M.gguf", "provider": "vllm", "created": 1700000000 },
    { "id": "deepseek-v3.2", "provider": "venice", "created": 1700000000 }
  ]
}
```

---

### GET /api/v1/chat/health

Provider health status (public).

```json
{ "status": "ok", "name": "pioneer-server", "version": "2.0.0", "uptime": 3600.5 }
```

---

## Anthropic-Compatible Messages

### POST /v1/messages  (alias: POST /api/v1/messages)

Anthropic Messages API shape, translated to the relay. Auth via `x-api-key`
or `Authorization: Bearer`. `GET /v1/models` returns an Anthropic-shaped model
list (used by the Claude Code SDK to probe the server).

---

## MCP (Model Context Protocol)

### GET /api/v1/mcp/tools

Discovery list of alpha-hosted MCP tools.

### POST /api/v1/mcp

JSON-RPC executor for MCP tool calls. Per-company tools are routed through the
company's Mini server.

---

## Account & Companies (auth required)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/account` | Account info, credits, alias |
| GET | `/api/v1/account/companies` | Companies you belong to |
| POST | `/api/v1/companies/create` | Create a company (funded seats) |
| POST | `/api/v1/companies/join` | Request to join a company |
| GET | `/api/v1/companies/{addr}/info` | Company slug, name, plan |
| GET | `/api/v1/companies/{addr}/members` | Member list |

Manage keys and credits in the browser at `/keys` and `/leaderboard`.

---

## Atlas (Assets & Networks)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/atlas/assets/{limit}/{skip}` | Paginated crypto assets |
| GET | `/api/v1/atlas/network/{chainId}` | RPC nodes by EVM chain ID |
| GET | `/api/v1/atlas/networks/{start}/{stop}/{limit}` | Nodes across major EVM networks |

---

## Apps (Dapp Store)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/apps/spotlight` | Featured dapp (or `null`) |
| GET | `/api/v1/apps/version/{minVersion}/{limit}/{skip}` | Dapps by min client version |
| GET | `/api/v1/apps/version/{version}/asset/{asset}/{limit}/{skip}` | Dapps by asset + version |

---

## Health & Server Info

| Method | Path | Description |
|--------|------|-------------|
| GET | `/health` | Kubernetes health check → `{ "status": "ok" }` |
| GET | `/` | Server metadata and status |
| GET | `/metrics` | Live metrics dashboard (SSE) |

---

## Technical Details

- **Runtime:** Bun (`Bun.serve`, hand-rolled router — no framework)
- **Auth:** wallet challenge → JWT, or `sk-pioneer-*` API keys
- **Provider chain:** vLLM → Venice → OpenAI (env-configured failover)
- **Streaming:** SSE with `reasoning_content` passthrough
- **Database:** MongoDB Atlas; Redis for keys/metrics
- **Docs:** this page (`/docs`) and `/llms.txt`