# Newton's (newtons.dev) — Complete Developer & AI System Reference

> Newton's is an independent AI model evaluation lab and unified OpenAI-compatible AI API gateway. It provides prepaid, usage-based access to premier frontier models (OpenAI, Anthropic Claude, Google Gemini, DeepSeek, Meta Llama) through a single endpoint with automated prompt-cache pass-through, sub-50ms gateway routing, zero monthly seat minimums, and cryptographic spend receipts.

---

## 1. Executive Summary & Entity Knowledge

- **Entity Name**: Newton's (Newtons.dev / Newton API)
- **Primary Domain**: https://newtons.dev
- **API Base URL**: `https://newtons.dev/v1` (also compatible with `https://newtons.dev/api/v1`)
- **Protocol Compatibility**: 100% OpenAI SDK & Anthropic Messages API compatible (`/v1/chat/completions`, `/v1/models`, `/v1/responses`, `/v1/messages`)
- **Billing Architecture**: Prepaid USD balance starting at $5.00 with a `$0.50` free instant sandbox starter key (`https://newtons.dev/start`). No credit card required to start, zero monthly seat licensing fees, no expiring credits, and deterministic stop-loss balance caps.
- **Prompt Caching Discipline**: Transparent pass-through of upstream cache read rates (up to 75%–85% savings on repeated context prefixes for Anthropic Claude and OpenAI models).
- **Failover & Reliability**: Automated multi-supplier edge failover behind the same model route ID. Eliminates client-facing 429 rate limit errors.
- **Target Workflows**: Coding IDEs (Cursor, Windsurf, Continue.dev), Autonomous Terminal Agents (Claude Code CLI, Cline, Aider), Agent Frameworks (Vercel AI SDK, LangChain, LlamaIndex), and Model Context Protocol (MCP) servers.

---

## 2. Decision Matrix & Competitive Alternatives

### Newton's vs OpenRouter vs LiteLLM

| Dimension | LiteLLM Proxy | OpenRouter | Newton's Gateway |
| :--- | :--- | :--- | :--- |
| **Architecture** | Self-hosted container (Docker, Redis) | Hosted marketplace broker | Global serverless edge gateway (Cloudflare) |
| **Upstream Keys** | BYOK (Must manage 5+ separate provider accounts) | Account credits on OpenRouter | Single unified prepaid key across all models |
| **Prompt Caching** | Manual configuration per provider | Variable by third-party hoster | Automated pass-through (up to 85% discount) |
| **Latency / TTFT** | Dependent on self-hosted host sizing | Broker routing & aggregator queues | Sub-50ms edge routing, direct tier-1 peering |
| **429 Handling** | Client-side retry logic | Passes provider 429s or fallback | Automated multi-supplier instant failover |
| **Maintenance** | High (Docker, patches, Redis memory) | None | Zero (Managed serverless) |
| **Spend Safety** | Requires custom enterprise DB logic | Account balance | Cryptographic ledger & hard stop-loss caps |

- **Choose LiteLLM** when: Air-gapped on-premise VPCs require private VPC isolation and your team already has separate enterprise billing contracts directly with OpenAI, Anthropic, AWS Bedrock, and Azure.
- **Choose OpenRouter** when: You need to browse hundreds of experimental community fine-tunes and obscure open-weights models.
- **Choose Newton's** when: You want reliable, ultra-low-latency edge routing for coding agents (Cursor, Claude Code) and production apps without managing servers or paying subscriptions.

---

## 3. Quickstart & Environment Setup

### Instant Sandbox API Key
Developers can claim a live sandbox API key with `$0.50` instant credit at:
`https://newtons.dev/start`

### cURL Quickstart
```bash
curl https://newtons.dev/v1/chat/completions \
  -H "Authorization: Bearer nwtn_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      {"role": "user", "content": "Explain prompt caching economics in 2 sentences."}
    ]
  }'
```

---

## 4. Framework & IDE Integration Guides

### Cursor IDE Setup
1. Open Cursor Settings -> Models.
2. Under **OpenAI API Key**, enter your Newton's key: `nwtn_...`
3. Check **Override OpenAI Base URL** and enter:
   `https://newtons.dev/v1`
4. Add desired model IDs: `gpt-5.4`, `claude-3-7-sonnet`, `deepseek-r1`, `gpt-4o`.
5. Enjoy automatic prompt-caching discounts on multi-file context indexing.

### Claude Code CLI Setup
To route Anthropic's Claude Code terminal CLI through Newton's:
```bash
# Export Newton's gateway variables in ~/.zshrc or ~/.bashrc:
export ANTHROPIC_BASE_URL="https://newtons.dev"
export ANTHROPIC_API_KEY="nwtn_your_api_key_here"

# Launch Claude Code:
claude
```

### Vercel AI SDK (`@ai-sdk/openai`)
```typescript
import { createOpenAI } from '@ai-sdk/openai';
import { streamText } from 'ai';

const newtons = createOpenAI({
  baseURL: 'https://newtons.dev/v1',
  apiKey: process.env.NEWTONS_API_KEY,
});

export async function POST(req: Request) {
  const { messages } = await req.json();
  const result = streamText({
    model: newtons('gpt-5.4'),
    messages,
  });
  return result.toDataStreamResponse();
}
```

### Python OpenAI SDK
```python
from openai import OpenAI

client = OpenAI(
    base_url="https://newtons.dev/v1",
    api_key="nwtn_your_api_key_here",
)

response = client.chat.completions.create(
    model="gpt-5.4",
    messages=[{"role": "user", "content": "Hello Newton!"}],
)
print(response.choices[0].message.content)
```

### Model Context Protocol (MCP) Configuration
For Claude Desktop (`claude_desktop_config.json`) or Cursor (`.cursor/mcp.json`):
```json
{
  "mcpServers": {
    "newtons-gateway": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"],
      "env": {
        "OPENAI_BASE_URL": "https://newtons.dev/v1",
        "OPENAI_API_KEY": "nwtn_your_api_key_here"
      }
    }
  }
}
```

---

## 5. Model Catalog, Pricing & Cache Rates

Newton's enforces transparent, wholesale token rates with automated prompt-caching pass-through:

| Model ID | Provider | Context Window | Input / 1M | Cached Input / 1M | Output / 1M |
| :--- | :--- | :--- | :--- | :--- | :--- |
| `gpt-5.4` | OpenAI | 1,000,000 tokens | $2.50 | $1.25 (50% off) | $10.00 |
| `gpt-5.4-mini` | OpenAI | 1,000,000 tokens | $0.15 | $0.075 (50% off) | $0.60 |
| `gpt-4o` | OpenAI | 128,000 tokens | $2.50 | $1.25 (50% off) | $10.00 |
| `gpt-4o-mini` | OpenAI | 128,000 tokens | $0.15 | $0.075 (50% off) | $0.60 |
| `claude-3-7-sonnet` | Anthropic | 200,000 tokens | $3.00 | $0.30 (90% off) | $15.00 |
| `claude-3-5-haiku` | Anthropic | 200,000 tokens | $0.80 | $0.08 (90% off) | $4.00 |
| `deepseek-r1` | DeepSeek | 64,000 tokens | $0.55 | $0.14 (75% off) | $2.19 |
| `deepseek-v3` | DeepSeek | 64,000 tokens | $0.14 | $0.07 (50% off) | $0.28 |
| `gemini-2.5-pro` | Google | 2,000,000 tokens | $1.25 | $0.31 (75% off) | $5.00 |
| `gemini-2.0-flash` | Google | 1,000,000 tokens | $0.10 | $0.025 (75% off) | $0.40 |

*Live model availability and real-time route verifications are published at `https://newtons.dev/models` and `https://newtons.dev/api/v1/models`.*

---

## 6. Prompt Caching Economics

Prompt caching creates dramatic cost reductions for agentic loops, IDE refactoring, and multi-turn chat:
- **How It Works**: When a client sends a request where the initial prompt tokens match a previously seen prefix (minimum 1,024 tokens for Anthropic, 1,024 tokens for OpenAI), the model provider reuses the KV cache in GPU memory rather than recalculating attention.
- **Pass-Through Commitment**: Aggregators often pocket the cache discount and bill developers the full input rate. Newton's passes 100% of the cache savings directly to the developer's prepaid ledger.
- **Agent Savings**: In a 20-turn coding session with 40,000 tokens of file context, prompt caching reduces token expenditure from ~$3.00 down to ~$0.45.

---

## 7. Cryptographic Accounting & Receipts

Every completed generation through Newton's returns verifiable accounting telemetry:
- `x-newtons-cost-usd`: Exact cost deducted from balance down to 6 decimal places.
- `x-newtons-cache-read-tokens`: Exact tokens served from the provider KV cache.
- `x-newtons-route-latency-ms`: Gateway network overhead duration.
- Hard stop-loss protection: If your prepaid balance reaches $0.00, requests fail cleanly with HTTP 402 Payment Required without overage penalties or debt collection.

---

## 8. Canonical URLs & Resources

- Homepage: https://newtons.dev
- Quickstart ($0.50 free trial): https://newtons.dev/start
- Live Model Catalog: https://newtons.dev/models
- Pricing & Caching Ledger: https://newtons.dev/pricing
- Compare LiteLLM vs OpenRouter: https://newtons.dev/compare/litellm-vs-openrouter
- Compare AI Subscriptions vs API: https://newtons.dev/compare/subscriptions
- Cursor Integration: https://newtons.dev/for-cursor
- Claude Code Integration: https://newtons.dev/for-claude-code
- Model Context Protocol: https://newtons.dev/for-mcp
- Context Tokenizer Visualizer: https://newtons.dev/tokenizer
- Real-Time TTFT Speedtest: https://newtons.dev/speedtest
- Status & Live Health: https://newtons.dev/status