API Quickstart

The simplest path: replace the compatible URL, switch to a Trex key, and bind your own API in the dashboard.

TrexAPI is the first platform built for the TokenZip Protocol. Most teams no longer need to start with custom HMAC signing or per-request upstream keys. Create one Trex key, bind your own OpenAI or Anthropic key in the dashboard, then point your client base URL to the Trex-compatible endpoint.

Create an account Review plans

Production target: https://api.trexapi.comLocal default: http://127.0.0.1:8787Supported TZP version: 1.0Managed proxy: OpenAI / AnthropicSubscriber TrexID cache pulls: permanently unlimited + free

How TrexAPI actually works

At the documentation level, TrexAPI is not only a payload API and not only a provider proxy. It is a production interface that combines context distillation, a TrexID memory layer, and Semantic Edge routing in one surface.

Context distillation, not blunt compression

TrexAPI extracts the facts, constraints, and conclusions a task actually depends on before compacting low-signal narrative instead of just cutting context down.

A TrexID memory layer, not one-off text

Processed context is organized as a TokenZip payload and stored behind a TrexID so downstream systems can pass it by reference and expand it on demand.

A reconciled Semantic Edge route

When you proxy your own model traffic through Trex, the Worker reconciles original tokens, actual upstream billed tokens, and savings in one place.

Quickstart flow

This is the default integration path we recommend. Switch to the advanced sections below only if you need direct payload lifecycle control or custom signing.

Create one Trex key

Create an API key in the dashboard and copy the returned `Trex Proxy Key`. That is the value you paste into the `apiKey` field of OpenAI-compatible clients.

Bind your own upstream API once

Save your OpenAI or Anthropic key in the dashboard. Trex will automatically use it on proxy requests so you do not need to send `X-Upstream-Api-Key` every time.

Replace the compatible URL and key

Point the client base URL to `https://api.trexapi.com/v1/proxy/openai` or `.../anthropic`, replace the `apiKey` with your Trex proxy key, and traffic will start flowing through the Trex managed proxy.

Official Node SDK

If you do not want to hand-build `trex_accounting`, signature headers, and provider passthrough parameters yourself, use the `trexapi` SDK. It automates Trex proxy keys, OpenAI / Anthropic passthrough headers, and HMAC signing for payload routes.

OpenAI / Anthropic proxy calls automatically carry your Trex proxy key.
Can automatically inject baseline `trex_accounting` metadata.
Directly wraps HMAC signing for `/v1/payloads`.

Install and call

const { createTrexClient } = require('trexapi');

const trex = createTrexClient({
  baseUrl: 'https://api.trexapi.com',
  proxyKey: process.env.TREX_PROXY_KEY,
  openai: {
    apiKey: process.env.OPENAI_API_KEY,
    organization: process.env.OPENAI_ORG,
    project: process.env.OPENAI_PROJECT,
  },
});

const response = await trex.openai.responses.create(
  {
    model: 'gpt-5-mini',
    input: 'Summarize the latest deployment notes.',
  },
  {
    originalInput: fullPromptBeforeTrex,
  }
);

console.log(response._trex);

TrexID memory-layer flow

Whether you are pushing a payload or reconciling baseline usage inside the managed proxy, the underlying job is the same: turning long context into a reusable TrexID semantic object.

Extract task-bearing context

Identify the semantic material that actually changes model behavior.

Protect high-risk spans

IDs, amounts, clauses, code, and structured fields move through an exact-preservation path.

Package as a TokenZip payload

Organize the distilled result into a signable, storable, reusable semantic payload.

Reuse it through a TrexID

Systems pass the TrexID and expand only when needed instead of resending full long context every time.

TrexID cache retrieval promise

For any active subscriber, retrieval of existing cached content through TrexID is permanently unlimited and free. TrexAPI is designed so you do not keep paying to re-read the same semantic memory once it has already settled behind a TrexID.

Applies to content that already exists in TrexAPI behind a TrexID.
Applies to active subscribers.
The goal is to encourage stable context to settle into a reusable TrexID memory layer.

What this means in practice

High-value context is better settled into a TrexID and then passed by reference between systems.
Repeated reads of existing TrexID cache avoid the repeated input-cost pattern of resending full prompts.
The metered part is new upstream model traffic and new context processing, not repeated retrieval of existing cached memory.

Advanced mode: HMAC authentication

If you need direct `/v1/payloads` control or custom signing, the Worker still supports the advanced `Authorization: Bearer <agent_id>:<timestamp>:<nonce>:<signature>` mode. Requests outside a 5-minute clock window or reusing a nonce are rejected.

Canonical string

POST
/v1/payloads
2026-03-12T10:30:00.000Z
nonce_demo_123

HMAC validation rules

Signature algorithm: HMAC-SHA256 with base64url output.
Timestamp skew tolerance: plus/minus 5 minutes.
Nonce replay protection: nonce is single-use and stored for 10 minutes.
Inactive or suspended API keys are rejected with `401`.

Trex-managed upstream proxy

This is the default entry point we recommend. Once your provider key is stored in the dashboard, Trex forwards the request, parses exact usage, applies official pricing, and credits saved input tokens plus saved token cost into your guarantee cycle.

POST /v1/proxy/openai/responses

Pass through the OpenAI Responses API with the original provider body plus an optional `trex_accounting` object.

POST /v1/proxy/openai/chat/completions

Supports Chat Completions requests; cached prompt tokens are split from standard input tokens before pricing.

POST /v1/proxy/anthropic/messages

Supports Anthropic Messages and uses `cache_write_ttl` to distinguish 5-minute vs 1-hour prompt cache write pricing.

Default proxy authentication

`Authorization` uses a standard `Bearer <trex_proxy_key>` token.
Your provider key is read from the dashboard by default instead of being resent on every request.
OpenAI optionally forwards `OpenAI-Organization` / `OpenAI-Project`.
Anthropic optionally forwards `Anthropic-Version` / `Anthropic-Beta`.

Advanced override mode

If you do not want to use the stored binding for one call, send `X-Upstream-Api-Key` to override it.
You can also fall back to the HMAC mode when you need to control the signing format yourself.
X-Trex-Usage-Event-Id still returns the reconciliation event ID.
X-Trex-Guarantee-Status still returns the current guarantee state.

OpenAI-compatible minimal example

This is the most common setup: create a Trex proxy key, replace the base URL, and keep the rest of your OpenAI request structure intact.

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.TREX_PROXY_KEY!,
  baseURL: 'https://api.trexapi.com/v1/proxy/openai',
});

const response = await client.responses.create({
  model: 'gpt-5-mini',
  input: 'Summarize the latest deployment notes for the team.',
  trex_accounting: {
    baseline_usage: {
      input_tokens: 6200,
      output_tokens: 380,
    },
    trex: {
      original_input_tokens: 6200,
      request_bytes_before: 18342,
    },
  },
});

console.log(response.output_text);

Advanced / manual override example

If you want to temporarily bypass the stored dashboard binding or explicitly override the provider key in a script, use this pattern.

const proxyResponse = await fetch('https://api.trexapi.com/v1/proxy/openai/responses', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: authorization,
    'X-Upstream-Api-Key': process.env.OPENAI_API_KEY!,
  },
  body: JSON.stringify({
    model: 'gpt-5-mini',
    input: 'Summarize the latest deployment notes for the team.',
    trex_accounting: {
      baseline_usage: {
        input_tokens: 6200,
        output_tokens: 380,
      },
    },
  }),
});

trex_accounting structure

`baseline_usage` tells the Worker what the provider would have consumed without Trex, while `actual_usage_override` is available for edge cases where you need to explicitly override the provider usage split.

{
  "trex_accounting": {
    "baseline_usage": {
      "input_tokens": 6200,
      "output_tokens": 380
    },
    "actual_usage_override": {
      "input_tokens": 1900,
      "cached_input_tokens": 120
    },
    "cache_write_ttl": "5m",
    "trex": {
      "original_input_tokens": 6200,
      "optimized_input_tokens": 2020,
      "request_bytes_before": 18342,
      "request_bytes_after": 6021
    }
  }
}

Current limits

Only non-streaming JSON responses are supported right now.
If the provider/model pair does not match the pricing catalog, the Worker returns `PRICING_RULE_NOT_FOUND`.
For active subscribers, retrieval of existing TrexID cache is permanently unlimited and free.
Automatic free-month grants finalize inside Trex billing state first, while external billing execution can be added later.

Copy-paste example

This example matches the current Worker signature implementation and the `/v1/payloads` request schema.

import crypto from 'node:crypto';

const agentId = 'agent_xxx';
const secret = 'tsk_xxx';
const timestamp = new Date().toISOString();
const nonce = 'nonce_demo_123';
const path = '/v1/payloads';
const canonical = ['POST', path, timestamp, nonce].join('\n');
const signature = crypto.createHmac('sha256', secret).update(canonical).digest('base64url');
const authorization = `Bearer ${agentId}:${timestamp}:${nonce}:${signature}`;

const response = await fetch('http://127.0.0.1:8787/v1/payloads', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: authorization,
  },
  body: JSON.stringify({
    tzp_version: '1.0',
    payload: {
      vector_seq_b64: ['AAECAwQ='],
      quant_params: { min: -1, max: 1, method: 'uniform' },
      dimensions: 384,
      chunk_count: 1,
      summary: 'demo payload',
    },
    metadata: {
      ttl_seconds: 86400,
      allowed_receivers: ['agent_xxx'],
    },
  }),
});

Available payload endpoints

The same HMAC authorization format applies across the full TokenZip payload lifecycle.

POST /v1/payloads

Push a new payload and receive `trex_id`, `expires_at`, and checksum metadata.

GET /v1/payloads/:trex_id

Retrieve the payload and metadata if the record exists, is active, and your agent is allowed.

HEAD / DELETE

Check payload metadata headers or revoke a payload when the sender needs to invalidate it.

Common error responses

The Worker returns structured JSON errors for most failure cases.

`TREX_UNAUTHORIZED`

Missing signature, invalid HMAC, expired timestamp, reused nonce, or inactive credentials.

`TREX_VERSION_UNSUPPORTED`

Your payload declared a TZP version other than `1.0` or `1.0.0`.

`TREX_FORBIDDEN`

Your agent is not included in `allowed_receivers`, or you are trying to revoke a payload you did not send.

`TREX_NOT_FOUND`

The payload does not exist, has expired, or was revoked before your request.

`PROVIDER_BINDING_REQUIRED`

You called `/v1/proxy/...` without a stored dashboard provider key and without an `X-Upstream-Api-Key` override.

`STREAMING_NOT_SUPPORTED`

Streaming is not yet supported on the managed proxy because usage reconciliation requires the final JSON response body.

Need help getting unstuck?

Start in the dashboard for API key provisioning, then work from this quickstart. For account, access, or rollout issues, contact support@trexapi.com.

Open dashboard Review legal docs