API Quickstart

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

TrexAPI is built around 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, Anthropic, or OpenRouter key in the dashboard, then point your client base URL to Trex through the single OpenAI-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 / Anthropic / OpenRouterSubscriber 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 Semantic Edge Dynamic Optimization, a TrexID memory layer, and Semantic Edge routing in one surface.

Semantic Edge Dynamic Optimization, 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

The steps below show the shortest integration path. Move to the advanced sections only if you need direct payload lifecycle control or custom signing.

Create one Trex key

The free tier already includes one production API key. Create it in the dashboard first 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, Anthropic, or OpenRouter 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. Trex acts here as the routing, optimization, and managed-proxy layer.

Your separate relationship with the upstream provider, including account status, billing, usage policies, outputs, and service availability, remains governed by that provider.

If you bind OpenRouter, you still use the same `/v1` compatible interface. When needed, you can pass vendor-prefixed model names like `openai/gpt-5-mini` or `anthropic/claude-sonnet-4` directly.

Replace the compatible URL and key

Point the client base URL to `https://api.trexapi.com/v1`, replace the `apiKey` with your Trex proxy key, and traffic starts flowing through the Trex managed proxy. Trex handles the OpenAI vs Anthropic adaptation inside the Worker.

Default mode: only two changes

If you already use the OpenAI SDK or any OpenAI-compatible client, the default mode only needs two code changes: point `baseURL` at Trex and replace `apiKey` with a Trex proxy key. Your actual provider credential moves out of code into the dashboard, where it is bound one-to-one to the current Trex key.

Replace the client `baseURL` with the Trex-compatible endpoint.
Replace the client `apiKey` with a Trex proxy key.
Start with the included production Trex key on the free tier, then bind your own OpenAI, Anthropic, or OpenRouter key to it in the dashboard.
Keep the original request body almost unchanged and start routing through Trex immediately.

Drop-in replacement example

// Before: direct provider call
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY!,
});

const response = await client.responses.create({
  model: 'gpt-5-mini',
  input: 'Summarize the latest deployment notes for the team.',
});

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

const trexResponse = await trexClient.responses.create({
  model: 'gpt-5-mini',
  input: 'Summarize the latest deployment notes for the team.',
});

Official Node SDK

If you do not want to hand-build `trex_accounting`, signature headers, and upstream adaptation parameters yourself, use the `trexapi` SDK. It automates Trex proxy keys, model-based OpenAI, Anthropic, or OpenRouter adaptation, and HMAC signing for payload routes.

The unified OpenAI-compatible 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 optimized 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: only needed for direct payload or TrexID control

If you need direct `/v1/payloads` control, want to manage the TrexID payload lifecycle yourself, or need custom signing, the Worker still supports the advanced `Authorization: Bearer <agent_id>:<timestamp>:<nonce>:<signature>` mode. If you only want to route model traffic through Trex via the single compatible interface, you can read this section later.

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 unified compatible entry point. Once your provider key is stored in the dashboard, Trex resolves it one-to-one for the current Trex key, forwards the request, parses exact usage, and applies official pricing. For the standard monthly Pro Edge plan, those savings are also credited into the renewal-promise guarantee cycle. Trex provides the routing, optimization, and managed-proxy layer, but it is not responsible for the underlying third-party provider service itself.

POST /v1/responses

The unified Responses-compatible entry point. Keep using the OpenAI request shape; when the model is Claude, Trex adapts it to Anthropic Messages inside the Worker.

POST /v1/chat/completions

The unified Chat Completions-compatible entry point. Trex separates cached prompt tokens before pricing and adapts Claude models to Anthropic upstreams when needed.

Upstream adapter layer

Trex exposes only the OpenAI-compatible surface to users. Request mapping, response shaping, and streaming conversion for OpenAI, Anthropic, and OpenRouter are handled by Trex Worker adapters.

Default proxy authentication

`Authorization` uses a standard `Bearer <trex_proxy_key>` token.
Your provider key is read from the dashboard by default and matched one-to-one to the current Trex key instead of being resent on every request.
Trex is responsible for the routing, optimization, and proxy layer; upstream provider account status, billing, outputs, and availability remain the responsibility of that provider.
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.

The actual copy-paste minimal example

This is the most common setup: only change `baseURL` and `apiKey` on an existing OpenAI-compatible client while keeping the rest of the request structure nearly unchanged. `trex_accounting` is an enhancement, not a prerequisite for adopting Trex.

import OpenAI from 'openai';

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

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: 6184,
      output_tokens: 380,
    },
    trex: {
      original_input_tokens: 6184,
      request_bytes_before: 18342,
    },
  },
});

console.log(response.output_text);

Python minimal example

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["TREX_PROXY_KEY"],
    base_url="https://api.trexapi.com/v1",
)

response = client.responses.create(
    model="gpt-5-mini",
    input="Summarize the latest deployment notes for the team.",
)

print(response.output_text)

What the default mode does not require

You do not need to start with HMAC.
You do not need to send `X-Upstream-Api-Key` on every request.
You do not need to start with the payload or TrexID lifecycle APIs.
You do not need to rewrite your existing OpenAI-compatible request shape.

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/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: 6184,
        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": 6184,
      "output_tokens": 380
    },
    "actual_usage_override": {
      "input_tokens": 1887,
      "cached_input_tokens": 143
    },
    "cache_write_ttl": "5m",
    "trex": {
      "original_input_tokens": 6184,
      "optimized_input_tokens": 1973,
      "request_bytes_before": 18417,
      "request_bytes_after": 6084
    }
  }
}

Current limits

Streaming responses are now supported. For streamed calls, usage and savings reconciliation finalize asynchronously after the stream completes, so the first response bytes do not include final reconciliation headers.
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 the unified compatible interface without a stored dashboard provider key and without an `X-Upstream-Api-Key` override.

`Streaming reconciliation note`

When you send `stream: true`, Trex forwards the upstream SSE stream immediately and finalizes usage plus savings reconciliation asynchronously after the stream closes. The streamed response does not wait for that step, so the final usage event appears in the dashboard shortly afterwards.

Need help getting unstuck?

Start in the dashboard for API key provisioning, then work from this quickstart. For account, access, or rollout issues, contact [email protected].

Open dashboard Review legal docs