# LLM Consensus API
> One API call orchestrates multiple frontier LLMs into superior answers through patent-pending consensus technology.

## API
- Base URL: https://llmconsensus.io/v1
- OpenAPI Spec: https://llmconsensus.io/openapi.json
- Interactive Docs: https://llmconsensus.io/docs
- Authentication: X-API-Key header (get one at https://llmconsensus.io/account/)

## Main Endpoint
POST /v1/orchestrate
- Sends a prompt to multiple frontier LLMs simultaneously
- Models collaborate, evaluate each other, and converge on a consensus answer
- Returns a single superior response with quality score and metadata

## Request Example
```json
{
  "prompt": "Your question here",
  "mode": "balanced",
  "domain": "auto",
  "stream": false
}
```

## Modes
- fast: 3 models, ~10s, 1 credit (GPT-5.4 Mini, Claude Haiku 4.5, Gemini 2.5 Flash)
- balanced: 3 models with iterative refinement, ~25s, 3 credits (GPT-5.4, Claude Sonnet 4.6, Gemini 3 Pro)
- deep: 5 frontier models with full convergence, ~90s, 20 credits (GPT-5.4, Claude Opus 4.6, Gemini 3.1 Pro, Mistral Large 2, Llama 3.3 70B)

## All Endpoints (28 methods, 24 paths)

### Orchestration
- POST /v1/orchestrate — Main consensus endpoint (API key or x402)
- POST /v1/batch — Submit 1-20 prompts for async processing
- GET /v1/batch/{batch_id} — Poll batch status

### Authentication
- POST /v1/auth/register — Create account (5 free credits)
- POST /v1/auth/login — Get JWT token
- POST /v1/auth/api-keys — Generate additional API key (Bearer JWT)
- GET /v1/auth/me — User profile + keys (Bearer JWT)

### Billing
- GET /v1/billing/packs — Available credit packs (no auth)
- POST /v1/billing/checkout — Stripe checkout session (Bearer JWT)
- POST /v1/billing/crypto-checkout — NOWPayments USDC invoice (Bearer JWT)
- POST /v1/billing/webhook — Stripe webhook handler
- GET /v1/billing/usage — Usage history (Bearer JWT)
- GET /v1/billing/history — Credit ledger (Bearer JWT)
- GET /v1/billing/discount-tier — Volume discount info (Bearer JWT)
- GET /v1/billing/spend-limit — Daily spend limit + today's spend (Bearer JWT)
- PUT /v1/billing/spend-limit — Set daily spend limit (Bearer JWT)
- GET /v1/billing/auto-topup — Auto top-up config (Bearer JWT)
- PUT /v1/billing/auto-topup — Configure auto top-up (Bearer JWT)

### Webhooks
- GET /v1/webhooks/config — Webhook configuration (Bearer JWT)
- PUT /v1/webhooks/config — Set webhook URL (Bearer JWT)
- DELETE /v1/webhooks/config — Remove webhook (Bearer JWT)
- POST /v1/webhooks/test — Send test webhook (Bearer JWT)

### OpenAI Compatible
- POST /v1/chat/completions — Drop-in replacement for OpenAI API (models: consensus-fast, consensus-balanced, consensus-deep)

### System
- GET /v1/health — System status + model availability
- GET /v1/metrics — Prometheus metrics

## Payment Methods

### 1. x402 Protocol (AI Agents — RECOMMENDED)
- Pay per request with USDC on Base L2
- NO account, NO API key, NO registration required
- Send USDC to 0xB0FdC6030B9f30652e8B221B8090d443Dd3C6381
- Base64-encode JSON: {"txHash":"0x...","from":"0xYourWallet"}
- Set header: X-Payment: <base64>
- 0% platform fee
- Pricing: fast $0.05, balanced $0.35, deep $4.50
- Spec: https://x402.org

### 2. Credit Card (Stripe) — for human developers
- Register at POST /v1/auth/register (5 free credits)
- Buy credit packs via POST /v1/billing/checkout
- Packs: Starter €49 (200cr), Pro €149 (700cr), Business €399 (2000cr)

### 3. USDC Top-Up (NOWPayments) — for crypto-native humans
- Register first, then POST /v1/billing/crypto-checkout
- Lower fees (0.5% vs 2.9%) and higher credit bonuses
- Packs: €50 (165cr), €100 (350cr), €200 (750cr), €500 (2200cr)

## Volume Discounts
- Bronze: 5% bonus at 500+ credits spent
- Silver: 10% bonus at 2000+ credits spent
- Gold: 15% bonus at 5000+ credits spent

## Features
- SSE streaming for real-time progress
- Conversation history (24h context)
- Domain detection (legal, medical, financial, technical, creative)
- Language detection and response matching
- Cross-hallucination verification
- Multi-dimensional quality evaluation
- Idempotent requests via Idempotency-Key header
- Webhook callbacks for async results

## For AI Agents
- x402 permissionless payments — no account needed
- Pure REST API — no browser required
- Structured JSON responses with quality scores
- 402 Payment Required response includes x402 spec-compliant payment instructions
- Batch endpoint for parallel processing (POST /v1/batch)
- Webhook delivery for async workflows
- Idempotent requests via Idempotency-Key header
- Machine-readable error codes
- Agent discovery: /.well-known/ai-plugin.json
- x402 Bazaar: 402 responses include extensions.bazaar metadata for CDP facilitator indexing

## Integrations
- OpenAI-compatible: POST /v1/chat/completions (models: consensus-fast, consensus-balanced, consensus-deep)
- MCP Server: mcp_server.py with tools (consensus_query, consensus_batch, check_balance) and resources (status, pricing)
- Any OpenAI SDK works by setting base_url="https://llmconsensus.io/v1"

## Benchmark
LLM Consensus Expert-Domain Evaluation Benchmark v1.0
100 expert questions across financial, legal, medical, and technical domains.
Results: 100% non-inferiority, 44.9% win rate, 0% loss rate.
Methodology: 3-judge multi-vendor blind evaluation.
Dataset: https://llmconsensus.io/benchmark/dataset-v1.json
Full results: https://llmconsensus.io/benchmark/

## Contact
- Website: https://llmconsensus.io
- API Docs: https://llmconsensus.io/docs
- Terms: https://llmconsensus.io/terms.html
- Privacy: https://llmconsensus.io/privacy.html