# Tokpum

> Tokpum (tokpum.com) is an LLM gateway with OpenAI- and Anthropic-compatible APIs.
> Membership is on-chain: a TokpumPass NFT discounts the merchant's platform commission (levels 1-5 give 10-50% off the take rate). Holders spend TKPM to level up - 100k / 300k / 1M / 3M cumulative TKPM reaches L2 / L3 / L4 / L5 per NFT (3M cap). All contracts live on Base (chain ID 8453).
> API base URL: https://<host>/v1, where <host> is the host you fetched this
> file from (production: https://tokpum.com). The curl examples below use the
> production host; on another deployment, substitute the host you fetched this
> file from. Create API keys in the console on the same host (wallet connect).
> Human-readable guides live at /docs on the same host.

## API

### Authentication

All inference endpoints take an API key as a Bearer token:

    Authorization: Bearer sk-xxxx

Create keys in the Tokpum console on the same host (connect a wallet, then
Console -> API Keys).

### Drop-in usage

The gateway speaks the OpenAI and Anthropic wire protocols and authenticates
every request with a Bearer token (Authorization header).

OpenAI SDK - change only the base URL:

    baseURL: 'https://tokpum.com/v1'

Anthropic SDK - the gateway does not accept the SDK's default x-api-key
header, so pass the key as a Bearer token:

    baseURL: 'https://tokpum.com',
    defaultHeaders: { Authorization: 'Bearer sk-xxxx' }

### Chat

#### POST /v1/chat/completions - OpenAI Chat Completions

```bash
curl -X POST https://tokpum.com/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}]}'
```

Set `"stream": true` for an SSE stream of chunks (same shape as OpenAI streaming).

#### POST /v1/messages - Anthropic Messages

```bash
curl -X POST https://tokpum.com/v1/messages \
  -H "Authorization: Bearer sk-xxxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-3-5-sonnet-20241022","max_tokens":100,"messages":[{"role":"user","content":"Hello"}]}'
```

### Images

#### POST /v1/images/generations - text-to-image, synchronous

Request body: `model`, `prompt`, `n` (default 1, max 9), `size` (default
`"1024x1024"`; each dimension 512-2048 and a multiple of 8), `response_format`
(only `"url"`; `"b64_json"` is rejected).

```bash
curl -X POST https://tokpum.com/v1/images/generations \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"minimax-image-01","prompt":"A neon koi fish swimming through clouds","n":1,"size":"1024x1024"}'
```

Response (truncated):

```json
{"created": 1725000000, "data": [{"url": "https://..."}]}
```

### Video - async task API

#### POST /v1/video/generations - submit

Request body: `model`, `prompt`, `negative_prompt?`, `image_url?`,
`end_image_url?`, `aspect_ratio` (one of `"16:9"`, `"9:16"`, `"1:1"`),
`duration` (1-60 seconds), `resolution` (one of `"480p"`, `"720p"`,
`"768p"`, `"1080p"`, `"2k"`, `"4k"`), `camera_control?`, `webhook_url?`.
Not every model serves every resolution - the public pricing catalog
(`GET /api/v1/public/pricing`) lists the supported set per model in
`video_resolutions`; submitting an unsupported resolution is a 400 naming
the supported values.

```bash
curl -X POST https://tokpum.com/v1/video/generations \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"minimax-h3","prompt":"A timelapse of a city skyline at sunset","aspect_ratio":"16:9","duration":5,"resolution":"768p"}'
```

Response (truncated):

```json
{"task_id": "task_abc123", "status": "PROCESSING", "provider": "minimax", "model": "minimax-h3", "created_at": 1725000000}
```

#### GET /v1/video/tasks/{task_id} - poll

```bash
curl https://tokpum.com/v1/video/tasks/task_abc123 \
  -H "Authorization: Bearer sk-xxxx"
```

Status flows `SUBMITTING` -> `PROCESSING` -> `SUCCESS` or `FAILED`. Response
(truncated):

```json
{"task_id": "task_abc123", "status": "SUCCESS", "progress": 100,
 "result": {"video_url": "https://...", "cover_image_url": "https://...", "duration": 5.0, "resolution": "768p"}}
```

`result` is null until SUCCESS; `error` holds the failure message on FAILED.
Tasks are scoped to the API key's merchant - a task id from another key is a 404.

### Other endpoints

- `GET /v1/models` - model list from the routed upstream.
- `POST /v1/responses` - OpenAI Responses API.
- `POST /v1/images/edits` - image edit; `multipart/form-data` with fields
  `model`, `prompt`, `image` (file), `size`, `response_format`.
- `POST /v1/video/tasks/{task_id}/cancel` - cancel a task; the upstream only
  accepts cancellation while the task is still queued (otherwise 409 and the
  task keeps running). An accepted cancellation refunds the reservation in
  full.

### MCP

- `POST /mcp` - MCP server (Streamable HTTP, stateless, JSON-RPC 2.0). Tools for agent self-onboarding and account management: `get_login_challenge`, `complete_login`, `get_gateway_config`, `whoami`, `get_balance`, `get_deposit_info`, `list_deposits`, `create_withdrawal_challenge`, `submit_withdrawal`, `list_withdrawals`, `get_withdrawal`, `cancel_withdrawal`, `list_api_keys`, `create_api_key`, `delete_api_key`, `list_models`, `get_strategies`, `set_strategy`, `list_channels`. Authenticate with `Authorization: Bearer <sk- key>`; obtain a key by completing `get_login_challenge` -> `complete_login`. Inference is NOT served over MCP - use `/v1/chat/completions` (OpenAI-compatible) or `/v1/messages` (Anthropic-compatible) with the same key.

### Models and pricing

Example models by kind - chat: `gpt-4o`, `claude-3-5-sonnet-20241022`;
image: `minimax-image-01`; video: `minimax-h3`.

The live catalog (models, providers, per-kind pricing) is a public endpoint
with no authentication - fetch it instead of relying on cached model lists:

```bash
curl https://tokpum.com/api/v1/public/pricing
```

Each entry includes `model_name`, `provider_name`, `channel_name`, `kind`
(`"chat"`, `"image"`, or `"video"`), and `final_pricing`.

## Documentation index
<!-- AUTO-GENERATED-LINK-TABLE-START -->
### Full reference

- [/llms-full.txt](/llms-full.txt) - all pages concatenated, one fetch for large-context agents
- [/llms-full.json](/llms-full.json) - machine-readable manifest of the page tree

### Endpoints

- [chat-completions](/agents/chat-completions.md) - POST /v1/chat/completions
- [images-edits](/agents/images-edits.md) - POST /v1/images/edits
- [images-generations](/agents/images-generations.md) - POST /v1/images/generations
- [messages](/agents/messages.md) - POST /v1/messages
- [models](/agents/models.md) - GET /v1/models
- [public-pricing](/agents/public-pricing.md) - GET /api/v1/public/pricing
- [responses](/agents/responses.md) - POST /v1/responses
- [video-cancel](/agents/video-cancel.md) - POST /v1/video/tasks/{task_id}/cancel
- [video-generations](/agents/video-generations.md) - POST /v1/video/generations
- [video-poll](/agents/video-poll.md) - GET /v1/video/tasks/{task_id}
- [whitepaper.md](/whitepaper.md) - Tokpum 白皮书

### Getting started

- [getting-started](/agents/getting-started.md) - Getting Started - Tokpum for Agents

### Patterns

- [async-video](/agents/patterns/async-video.md) - Async Video
- [error-recovery](/agents/patterns/error-recovery.md) - Error Recovery
- [key-rotation](/agents/patterns/key-rotation.md) - Key Rotation
- [rate-limits](/agents/patterns/rate-limits.md) - Rate Limits
- [sse-streaming](/agents/patterns/sse-streaming.md) - SSE Streaming

### Contracts

- [contracts.md](/contracts.md) - Tokpum Contracts - Full Reference
- [contracts.txt](/contracts.txt) - Tokpum Contracts
<!-- AUTO-GENERATED-LINK-TABLE-END -->

## Contracts

On-chain membership and contract addresses (TokpumPass NFT, TKPM token,
treasury, governor) are maintained in a dedicated file on this host:
/contracts.txt - and on the human-readable page /contracts.

## Notes

- The documentation index above is generated from the agent page tree by
  `npm run docs:build:index` in the tokpum repository; per-endpoint pages are
  drift-tested against the gateway route table in CI.