---
name: savetoken
description: Reduce the token count of large machine-generated text before sending it to an LLM. SaveToken is an HTTP API that trims and compresses tool and function results, MCP and tool schemas, JSON arrays, and stack traces / tracebacks, then returns a verdict saying whether the reduction was verified safe (structural round-trip or a reference-model check) or whether it left the text unchanged. Typical reduction is 15-50% on the inputs it handles, and nothing on prose, source code, or already-compact text. Use this skill when a tool result, schema, or JSON payload is too big for the context window or is inflating cost, or when you want to compress or trim repeated tool output in an agent loop. It never calls a model and never summarizes.
license: Proprietary. See https://savetoken.org/terms
compatibility: Requires network access to https://api.savetoken.org and a shell with curl (or any HTTP client).
metadata:
  author: savetoken
  homepage: "https://savetoken.org"
  api_base: "https://api.savetoken.org"
---

# SaveToken

SaveToken reduces the number of input tokens in machine-generated text before you
send it to an LLM provider. It runs deterministic, programmatically-verified
transforms — it never calls a model, never summarizes, and never invents text. It
returns the reduced string plus a `verdict` telling you whether the reduction was
proven equivalent to the input.

You send the reduced text to Claude, OpenAI, or any provider **with your own key**.
SaveToken never sees your provider key.

## When to use this skill

Call SaveToken **before** putting any of these into the model's context:

- a **tool or function result** over ~500 tokens (web-search payloads, API JSON responses, file dumps)
- a **tool / MCP schema** or function-definition block
- a **JSON array** of records
- a **stack trace** or error dump

It pays off most in **agent loops**, where the same tool schemas and tool outputs
are re-sent on every turn.

## When NOT to use it

SaveToken does nothing useful on prose, prompts, source code, or short/already-tight
text — it returns `verdict: "NEUTRAL"` and `dollars_saved: 0`. Don't route plain
conversation or instructions through it.

Note: a `NEUTRAL` verdict does **not** always mean the text came back byte-identical.
It can also mean SaveToken *did* reduce the text but could not verify the reduction
was safe for this exact input. Either way, on `NEUTRAL` you use the original text —
see Step 3.

## Step 1 — Get a free key (one time, no account, no card)

```bash
curl -sX POST https://api.savetoken.org/v1/keys/free
```

Response:

```json
{
  "key": "tsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "api_key": "tsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "key_id": "…",
  "daily_quota": 100,
  "note": "store this now — it is never shown again (hashed at rest)"
}
```

Save `api_key`. Free keys allow **100 calls/day**. Store the key on the machine
running the agent — never embed a `tsk_` key in client-side or browser code.

## Step 2 — Optimize the text

```bash
curl -sX POST https://api.savetoken.org/v1/optimize \
  -H "Authorization: Bearer tsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"text": "<the tool output / schema / json / traceback>"}'
```

- Authenticate with `Authorization: Bearer tsk_…` **or** `X-Api-Key: tsk_…`.
- Send **exactly one** of `text` (a string) or `messages` (an array of
  `{"role", "content"}` objects). Sending both or neither returns `400`.
- For a conversation, pass `messages` and set
  `stable_prefix_message_count` to the number of leading messages to leave
  byte-identical (keeps a provider prompt-cache prefix intact).

Response:

```json
{
  "request_id": "…",
  "optimized": "<the reduced text>",
  "mode": "schema",
  "tokens_in": 1234,
  "tokens_out": 634,
  "dollars_saved": 0.0012,
  "verdict": "WIN",
  "warnings": []
}
```

## Step 3 — Use the result according to `verdict`

| `verdict` | Meaning | What to do |
|---|---|---|
| `WIN` | `optimized` is smaller than the input and was verified equivalent to it. | **Use `optimized`** in place of the original text. |
| `NEUTRAL` | No reduction was verified safe for this input. | **Use the original text.** SaveToken couldn't help here. |
| `PASS_THROUGH` | There was nothing to reduce (e.g. the whole input was a stable prefix). | Use the original text. |

Only `WIN` has `dollars_saved > 0`. Never send `optimized` downstream when the
verdict is `NEUTRAL` — fall back to what you had.

Check `warnings` for notes such as an auto-redacted secret in the input.

## Other endpoints

| Method | Path | Auth | Purpose |
|---|---|---|---|
| `POST` | `/v1/keys/free` | none | Mint a free key (20 per IP per day). |
| `POST` | `/v1/optimize` | key | Reduce a block of text or a message array. |
| `GET` | `/v1/usage` | key | Per-call history: `tokens_in`, `tokens_out`, `dollars_saved`, `verdict`, `mode`. |
| `GET` | `/v1/savings` | key | `lifetime_dollars_saved` for your key (a single USD figure — no token total). |
| `GET` | `/v1/health` | none | Liveness check. |
| `POST` | `/v1/support` | none | File an issue directly — see below. |

## Errors

| Status | `code` | Cause |
|---|---|---|
| `400` | `BAD_REQUEST` | Both or neither of `text` / `messages`, or a malformed body. |
| `401` | `UNAUTHORIZED` | Missing, invalid, or revoked key. |
| `429` | `RATE_LIMIT` | 300 calls/min burst cap, or the free-tier 100/day cap. Back off and retry. |
| `500` | `INTERNAL` | Server-side failure. File it (below) with `request_id`. |

## Filing an issue

If a call fails and retrying doesn't help, report it directly — no key needed:

```bash
curl -sX POST https://api.savetoken.org/v1/support \
  -H "Content-Type: application/json" \
  -d '{"message": "getting 500 on every call today", "request_id": "<from the error response>"}'
```

`message` is required (1-4000 chars). `request_id` and `contact` (an email to
reply to) are optional. 10 requests/hour/IP.

## Honest scope

SaveToken reduces three input shapes today — tool/MCP schemas, flat JSON arrays,
and stack traces. In a 19-fixture internal benchmark it engaged on 5 of them and
cut those by 33-49%; a typical live call using default options lands lower (one
real tool-schema test reduced 16%). Everything else comes back as `NEUTRAL`,
unchanged. The lossless transforms (JSON re-encoding, low-level schema compaction)
are proven safe by structural round-trip; the more aggressive schema levels are
checked against a reference model, not guaranteed byte-lossless. If you need
general prose or code compression, this is not the right tool.

Because of the `verdict` contract you can still call it defensively on any
candidate input: the worst case is a wasted request, never corrupted context.

Full reference: https://savetoken.org/docs