# Getting Started - Tokpum for Agents

This page walks an LLM agent through the four steps needed to make a
first successful call to the Tokpum gateway.

## 1. Connect a wallet & create an API key

Tokpum uses wallet-based authentication. There is no email/password
signup - sign in with a wallet, then create an API key from the console:

1. Visit the Tokpum console at https://tokpum.com
2. Click "Connect Wallet" and approve the SIWE (Sign-In With Ethereum)
   signature request
3. From the console, navigate to API Keys -> Create Key
4. Copy the key (`sk-xxxx`) into your environment

The wallet signature is the only login - agents holding a private key can
perform SIWE programmatically via the same flow.

## 2. Discover available models

Before writing a request, fetch the live model catalog. It is public and
unauthenticated:

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

The response is a flat JSON array of model entries (truncated):

    [{"model_name": "gpt-4o", "channel_name": "...", "provider_name": "openai", "kind": "chat", "final_pricing": {...}}, ...]

The `kind` field is `"chat"`, `"image"`, or `"video"`. For text-to-video
models, also inspect `video_resolutions` (present only on video models)
to confirm the resolution you want is supported. Optional query
parameters `?provider=` and `?model=` filter the list.

## 3. Make your first chat call

OpenAI SDK - change only the base URL:

    import OpenAI from "openai";
    const client = new OpenAI({
      baseURL: "https://tokpum.com/v1",
      apiKey: process.env.TOKPUM_API_KEY,
    });
    const res = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [{ role: "user", content: "Hello" }],
    });

Anthropic SDK - the Messages API is served at `/v1/messages`. The gateway
authenticates the `Authorization` header only, so pass the key as a Bearer
token (the SDK's default `x-api-key` header gets a 401):

    import Anthropic from "@anthropic-ai/sdk";
    const client = new Anthropic({
      baseURL: "https://tokpum.com",
      defaultHeaders: { Authorization: `Bearer ${process.env.TOKPUM_API_KEY}` },
    });
    const res = await client.messages.create({
      model: "claude-sonnet-4-6",
      max_tokens: 256,
      messages: [{ role: "user", content: "Hello" }],
    });

`curl` form:

    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"}]}'

Errors come back as `{"error": {"message": "...", "type": "..."}}` -
the `type` field is stable per condition (e.g. `rate_limit_exceeded`,
`monthly_budget_exceeded`) so you can branch on it without parsing
prose.

## 4. Stream responses

Set `stream: true` to receive the response as a Server-Sent Events
stream. See [`/agents/patterns/sse-streaming.md`](/agents/patterns/sse-streaming.md)
for the OpenAI vs Anthropic SSE shape differences.

## Next steps

- Browse per-endpoint pages under `/agents/` for full request/response shapes
- Read `/agents/patterns/error-recovery.md` to handle rate limits and 5xx errors
- For async video, read `/agents/patterns/async-video.md` for the poll/webhook patterns