TrexAPI

TokenZip Protocol (TZP) Reference API Gateway — Edge cache, pointer management & access control

TokenZip 协议 (TZP) 参考 API 网关 — 边缘缓存、指针管理与访问控制

Official site 官网: tokenzip.org · Contact 联系: [email protected]

English

What is TZP?

TokenZip Protocol (TZP) is an open standard for semantic shared memory between heterogeneous AI agents. It cuts multi-agent communication cost by pass-by-reference: instead of sending full context (thousands of tokens), agents exchange short pointers (TrexID) and fetch compressed semantic payloads from the edge.

• ~80%+ smaller payload size (vector quantization)
• ~95%+ lower latency and API cost vs. full-token transfer
• Model-agnostic: GPT, Claude, Llama, Gemini, etc. share one 384-d Interlingua space

What is TrexAPI?

TrexAPI is the reference implementation of the TZP edge gateway: it accepts semantic payloads (POST), stores them, returns TrexID pointers, and serves payloads on GET. Use it to run your own TZP-compliant edge node.

Design principles (TZP)

1. Map, don’t translate — One 384-d Interlingua space (e.g. all-MiniLM-L6-v2), no cross-model full-dimension translation.
2. Pass by reference, not value — Send [TZP: tx_us_8f9A2bXr7] instead of 10,000 tokens.
3. Open-first, security built-in — AES-256-GCM at rest, HMAC-signed tokens, optional E2EE.

Quick start

# Clone and install
git clone https://github.com/tokenzip/trex-api.git && cd trex-api
npm install

# Configure (copy .env.example to .env; set PORT, TZP_REGION; for dev, set DEV_API_KEY)
cp .env.example .env

# Build and run
npm run build && npm start

Default: http://localhost:3000. See Deployment below for production.

Deployment / 部署

Production checklist: Remove DEV_API_KEY; use HMAC auth (see Deployment: EN | 中文); put behind HTTPS (e.g. Nginx/Caddy).

部署速览： 复制 .env.example 为 .env，配置 PORT、TZP_REGION；开发可设 DEV_API_KEY=testkey。开发用 npm run dev，生产用 npm run build && npm start。Docker 构建后 -p 3000:3000 并传入环境变量即可。生产环境务必去掉 DEV_API_KEY、启用 HMAC 鉴权并配置 HTTPS，详见 部署文档 EN | 中文。

API overview

All requests require Authorization: Bearer <hmac_signed_token>. See TZP v1.0 Specification for payload schema, TrexID format, and error codes.

Security

• TLS 1.3+ for transport.
• AES-256-GCM for payloads at rest.
• HMAC-SHA256 Bearer tokens; optional E2EE and receiver allowlists (allowed_receivers).
• Nonce and timestamp checks to mitigate replay.

Compliance & spec

• Implements TZP-Network: push/pull API, TrexID generation, edge storage, access control.
• Full protocol: TZP v1.0 Specification.
• Official SDKs: tokenzip-python, tokenzip-ts.

License

Apache 2.0. TZP specification: Apache 2.0 / CC-BY-SA 4.0 (dual-licensed).

中文

TZP 是什么？

TokenZip 协议 (TZP) 是一套面向异构 AI 代理的语义共享内存开放标准。通过传指针而非传全文，将多智能体协作时的通信带宽与成本大幅降低：代理之间只交换短指针 TrexID，再从边缘节点拉取压缩后的语义载荷。

• 约 80% 以上的载荷体积压缩（向量量化）
• 约 95% 以上的延迟与 API 成本降低（相对全量 Token 传输）
• 与模型无关：GPT、Claude、Llama、Gemini 等共用同一 384 维 Interlingua 空间

TrexAPI 是什么？

TrexAPI 是 TZP 边缘网关的参考实现：接收语义载荷（POST）、落库、返回 TrexID 指针，并通过 GET 按 TrexID 返回载荷。可用于自建符合 TZP 的边缘节点。

设计原则（TZP）

1. 不翻译，只映射 — 统一 384 维 Interlingua 空间（如 all-MiniLM-L6-v2），不做跨模型全维度翻译。
2. 传指针，不传值 — 只传 [TZP: tx_us_8f9A2bXr7]，不传上万 Token。
3. 开放优先，安全内建 — 静态加密 AES-256-GCM、HMAC 签名令牌，可选端到端加密。

快速开始

# 克隆并安装
git clone https://github.com/tokenzip/trex-api.git && cd trex-api
npm install

# 配置（复制 .env.example 为 .env；设置 PORT、TZP_REGION；开发可设 DEV_API_KEY）
cp .env.example .env

# 构建并运行
npm run build && npm start

默认监听：http://localhost:3000。生产部署与步骤见 Deployment / 部署（上文已含中英双语速览；完整文档 EN | 中文）。

API 概览

所有请求需携带 Authorization: Bearer <hmac_signed_token>。载荷结构、TrexID 格式与错误码见 TZP v1.0 规范。

安全

• TLS 1.3+ 传输。
• AES-256-GCM 静态加密载荷。
• HMAC-SHA256 Bearer 令牌；可选 E2EE 与接收方白名单（allowed_receivers）。
• Nonce 与时间戳校验，降低重放风险。

合规与规范

• 实现 TZP-Network：推送/拉取 API、TrexID 生成、边缘存储与访问控制。
• 完整协议：TZP v1.0 规范。
• 官方 SDK：tokenzip-python、tokenzip-ts。

许可证

Apache 2.0。TZP 规范：Apache 2.0 / CC-BY-SA 4.0（双许可）。

TokenZip Protocol is an open standard. Website 官网: tokenzip.org · Contact 联系: [email protected] · Contributions: tzp-spec | trex-api.