#Sonar AI Gateway API (xtnd-sonar-api)

Repository: XTND-DYNAMICS/xtnd-sonar-api
Production Route: https://api.sonar.vantage.xgi.io
Runtime: Cloudflare Worker (nodejs_compat)

#1. Overview

xtnd-sonar-api acts as a transparent reverse proxy and metering gateway positioned between client applications and frontier LLM providers (OpenAI, Anthropic, Google Gemini).

It allows applications to point their standard SDKs or HTTP clients directly through the gateway without rewriting request payloads:

Client App ──> api.sonar.vantage.xgi.io/v1/proxy/openai/v1/chat/completions ──> api.openai.com

#2. Supported Target Providers

The gateway dynamically routes requests based on the first URL path segment after /v1/proxy/:

#3. Telemetry Extraction Lifecycle

sequenceDiagram
    autonumber
    actor App as Client Application
    participant Proxy as xtnd-sonar-api
    participant LLM as Upstream LLM (Anthropic / OpenAI)
    participant Central as Central Vantage API (api.vantage.xgi.io)

    App->>Proxy: POST /v1/proxy/anthropic/v1/messages (API Key & Body)
    Note over Proxy: Record start timestamp
    Proxy->>LLM: Forward untouched request to api.anthropic.com
    LLM-->>Proxy: Stream response tokens & HTTP headers
    Note over Proxy: Calculate durationMs = performance.now() - start
    Proxy-->>App: Stream response immediately to client (0ms added delay)
    
    rect rgb(20, 30, 45)
        Note over Proxy,Central: Non-blocking background worker (ctx.waitUntil)
        Proxy->>Proxy: Extract rate-limit headers & token metrics
        Proxy->>Proxy: calculateTokenCost(model, tokens)
        Proxy->>Central: POST /v1/events/batch (ai:anthropic:inference)
    end

#3.1 Rate Limit Header Extraction

Upstream headers are extracted automatically:

• OpenAI: x-ratelimit-remaining-tokens, x-ratelimit-remaining-requests, x-ratelimit-reset-tokens.
• Anthropic: anthropic-ratelimit-tokens-remaining, anthropic-ratelimit-tokens-reset.

#3.2 Token & Cache Economics

• Computes exact dollar burn rate using cost-matrix.ts.
• Quantifies prompt cache savings (e.g. Anthropic 90% cache read discount).
• Tracks reasoning/thinking tokens for o1, o3-mini, gemini-2.0-flash-thinking, and Claude 3.7.

#4. Environment Variables & Configuration

In wrangler.jsonc:

{
  "name": "xtnd-sonar-api",
  "main": "src/index.ts",
  "compatibility_date": "2025-04-01",
  "compatibility_flags": ["nodejs_compat"],
  "routes": [
    { "pattern": "api.sonar.vantage.xgi.io", "custom_domain": true }
  ],
  "vars": {
    "ENVIRONMENT": "production",
    "CENTRAL_VANTAGE_API": "https://api.vantage.xgi.io"
  },
  "observability": { "enabled": true }
}

#5. Usage Examples

#5.1 Using Official Anthropic TypeScript SDK

import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
  baseURL: 'https://api.sonar.vantage.xgi.io/v1/proxy/anthropic'
});

const message = await anthropic.messages.create({
  model: 'claude-3-7-sonnet-20250219',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Explain quantum computing in one sentence.' }]
});

#5.2 Using Official OpenAI Node.js SDK

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: 'https://api.sonar.vantage.xgi.io/v1/proxy/openai/v1'
});

const completion = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Analyze this revenue model.' }]
});