> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toolken.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Anthropic SDK

> Use Claude models through Toolken with the native Anthropic SDK. One base URL change, no protocol translation needed.

**The Anthropic SDK connects to Claude's native Messages API.** Set the base URL to `https://gateway.toolken.ai` (no `/v1` suffix -- the SDK appends `/v1/messages` itself) and add `X-Toolken-Key` as a default header.

<Note>The base URL for the Anthropic SDK is `https://gateway.toolken.ai` with no `/v1` at the end. The SDK appends `/v1/messages` automatically. Adding `/v1` yourself will cause routing errors.</Note>

<Steps>
  <Step title="Get your keys">
    You need two keys:

    | Key           | Where to get it           | Looks like    |
    | ------------- | ------------------------- | ------------- |
    | Toolken key   | Dashboard, under API Keys | `tk_live_...` |
    | Anthropic key | Your Anthropic account    | `sk-ant-...`  |

    Toolken forwards your Anthropic key verbatim and never stores it.
  </Step>

  <Step title="Configure the client">
    <CodeGroup>
      ```python Python theme={null}
      import anthropic

      client = anthropic.Anthropic(
          base_url="https://gateway.toolken.ai",  # no /v1 -- SDK appends /v1/messages
          api_key="sk-ant-...",                   # your Anthropic key, forwarded untouched
          default_headers={
              "X-Toolken-Key": "tk_live_...",
              "X-Toolken-Metadata-Agent": "my-agent",  # tag this client's traffic
          },
      )

      message = client.messages.create(
          model="claude-3-5-sonnet-20241022",
          max_tokens=1024,
          messages=[{"role": "user", "content": "Hello"}],
      )
      print(message.content[0].text)
      ```

      ```javascript Node theme={null}
      import Anthropic from "@anthropic-ai/sdk";

      const client = new Anthropic({
        baseURL: "https://gateway.toolken.ai",  // no /v1 -- SDK appends /v1/messages
        apiKey: process.env.ANTHROPIC_API_KEY,  // forwarded untouched
        defaultHeaders: {
          "X-Toolken-Key": "tk_live_...",
          "X-Toolken-Metadata-Agent": "my-agent",  // tag this client's traffic
        },
      });

      const message = await client.messages.create({
        model: "claude-3-5-sonnet-20241022",
        max_tokens: 1024,
        messages: [{ role: "user", content: "Hello" }],
      });
      console.log(message.content[0].text);
      ```
    </CodeGroup>

    <Tip>`X-Toolken-Metadata-Agent` takes any string. Use one value per agent or workflow you want to track separately in the dashboard. Any `X-Toolken-Metadata-*` header becomes a groupable dimension automatically.</Tip>
  </Step>

  <Step title="Attribute by customer (optional)">
    Add `X-Toolken-Metadata-Customer-Id` to track spend per end-user or organization:

    <CodeGroup>
      ```python Python theme={null}
      client = anthropic.Anthropic(
          base_url="https://gateway.toolken.ai",
          api_key="sk-ant-...",
          default_headers={
              "X-Toolken-Key": "tk_live_...",
              "X-Toolken-Metadata-Agent": "support-agent",
              "X-Toolken-Metadata-Customer-Id": "org_abc123",
          },
      )
      ```

      ```javascript Node theme={null}
      const client = new Anthropic({
        baseURL: "https://gateway.toolken.ai",
        apiKey: process.env.ANTHROPIC_API_KEY,
        defaultHeaders: {
          "X-Toolken-Key": "tk_live_...",
          "X-Toolken-Metadata-Agent": "support-agent",
          "X-Toolken-Metadata-Customer-Id": "org_abc123",
        },
      });
      ```
    </CodeGroup>
  </Step>

  <Step title="See your cost">
    Within seconds your request appears in the dashboard, grouped by agent and customer. The response body is identical to calling Anthropic directly -- Toolken is a transparent proxy.
  </Step>
</Steps>

## Streaming

The Anthropic SDK's streaming API works without any changes:

<CodeGroup>
  ```python Python theme={null}
  with client.messages.stream(
      model="claude-3-5-sonnet-20241022",
      max_tokens=1024,
      messages=[{"role": "user", "content": "Count to five."}],
  ) as stream:
      for text in stream.text_stream:
          print(text, end="", flush=True)
  ```

  ```javascript Node theme={null}
  const stream = await client.messages.create({
    model: "claude-3-5-sonnet-20241022",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Count to five." }],
    stream: true,
  });
  for await (const event of stream) {
    if (
      event.type === "content_block_delta" &&
      event.delta.type === "text_delta"
    ) {
      process.stdout.write(event.delta.text);
    }
  }
  ```
</CodeGroup>

## How the two keys travel

The Anthropic SDK injects your key as `x-api-key`. Toolken reads `X-Toolken-Key` separately and forwards `x-api-key` unchanged.

| Header                                | Who reads it    | What happens after                                    |
| ------------------------------------- | --------------- | ----------------------------------------------------- |
| `X-Toolken-Key: tk_live_...`          | Toolken gateway | Stripped before forwarding                            |
| `x-api-key: sk-ant-...`               | Anthropic       | Forwarded untouched                                   |
| `X-Toolken-Metadata-Agent: ...`       | Toolken gateway | Recorded as metadata key `agent`, then stripped       |
| `X-Toolken-Metadata-Customer-Id: ...` | Toolken gateway | Recorded as metadata key `customer_id`, then stripped |

## Provider detection

Any request to `/v1/messages` routes to Anthropic automatically. A model name starting with `claude-` also triggers auto-detection. You do not need an `X-Toolken-Provider` header.

## Next

<CardGroup cols={2}>
  <Card title="Custom Properties" icon="tag" href="/features/observability/custom-properties">All attribution headers and how metadata keys become dashboard dimensions.</Card>
  <Card title="OpenAI SDK" icon="wand-magic-sparkles" href="/integrations/openai-sdk">Use OpenAI and OpenAI-compatible models through Toolken.</Card>
  <Card title="Gemini SDK" icon="sparkles" href="/integrations/gemini-sdk">Use Gemini models through Toolken via the OpenAI-compatible path.</Card>
  <Card title="Anthropic and Gemini" icon="route" href="/features/providers-routing/anthropic-gemini">Provider routing details for Anthropic and Gemini.</Card>
</CardGroup>