# Voice Quality API

![status](https://img.shields.io/badge/status-live-brightgreen)
![MCP](https://img.shields.io/badge/MCP-server-blue)
![x402](https://img.shields.io/badge/x402-pay--per--call-blue)
![model](https://img.shields.io/badge/MOS-ITU--T%20G.107%20E--model-informational)
![G.113](https://img.shields.io/badge/Ie%2FBpl-G.113%20verified-brightgreen)
![SSRF](https://img.shields.io/badge/SSRF-guarded-brightgreen)

**Measure the network path quality to a voice/VoIP destination and get an
estimated MOS (1–5) — live, from an API.** Built for AI voice agents. Available
as REST and as an **MCP tool**, paid per call via
**[x402](https://github.com/coinbase/x402)** (USDC on Base).

🌐 **Live:** [voice-quality.com](https://voice-quality.com) · REST
`api.voice-quality.com` · MCP `mcp.voice-quality.com`

---

## Try it

```bash
curl https://api.voice-quality.com/health          # {"status":"ok"}

curl -s https://api.voice-quality.com/v1/voice-quality \
  -H 'content-type: application/json' \
  -d '{ "target": "your-voice-endpoint.example", "target_port": 10000, "codec": "G711" }'
```

You get an **estimated MOS** + live **RTT / jitter / packet loss**. Point it at an
endpoint that answers media — your own voice infra, or a tiny reflector you run
([`probe-agent/cmd/reflector`](./probe-agent/cmd/reflector)). **20 free/day**;
beyond that it's pay-per-call via x402 (no account needed).

```jsonc
{
  "request_id": "vq_2ibc6qqq",
  "target": "your-voice-endpoint.example",
  "codec": "G711",
  "measured_at": "2026-07-01T10:15:13.795Z",
  "summary": { "mos_estimate": 4.38, "mos_class": "excellent", "r_factor": 91.8 },
  "by_probe": [ /* per-probe metrics + R-factor + MOS */ ],
  "methodology": {
    "model": "ITU-T G.107 E-model",
    "confidence": "estimate",
    "assumptions": ["owd = rtt/2 (symmetric path)", "adaptive jitter buffer = 2x jitter"]
  },
  "credits_used": 0
}
```

## Why it exists

Free network-measurement platforms (Globalping, RIPE Atlas) measure
ping/traceroute/DNS/HTTP — they do **not** measure RTP media quality or estimate
MOS. The tools that do (Cyara, Spearline) are enterprise sales motions. This
fills the gap: **voice path quality as a clean, self-serve, agent-native API** —
check it before you route a call, or monitor the path to your voice endpoints.

## Trustworthy by design

- **Honest metric.** An *objective* G.107 E-model estimate from measured network
  metrics — never sold as a perceptual (PESQ/POLQA) score. Every response carries
  `methodology.confidence: "estimate"` and its assumptions.
- **Verified constants.** The codec `Ie`/`Bpl` values are verified against
  **ITU-T G.113 (09/2024), App. I, Table I.4** — rows matched to the probe profile
  (no PLC, no VAD/DTX). Not "representative"; cited.
- **SSRF-guarded.** ~36.7% of public MCP servers ship SSRF issues — this one
  blocks internal/private targets by default (orchestrator **and** probe), plus a
  per-target allowlist and rate limit.
- **Hardened.** TLS/mTLS on the probe channel, non-root containers,
  `pnpm audit` clean, structured machine-readable errors, `Idempotency-Key`,
  Prometheus `/metrics`, per-identity API keys.

## Pricing

| Tier | What you get |
|------|--------------|
| **Free** | 20 measurements/day per identity (`credits_used: 0`). |
| **Pay-per-call** | Beyond that, a sub-cent–cents micropayment per call via **x402** (USDC on Base). Unpaid → `402` with the payment requirements; pay and retry. Agents pay transparently. |

## Agent-native (MCP + x402)

One MCP tool, `measure_voice_quality`. The server wraps the REST API and pays
x402 transparently from a configured wallet once the free tier is exhausted — no
human in the loop.

```jsonc
{
  "mcpServers": {
    "voice-quality": {
      "url": "https://mcp.voice-quality.com/",
      "env": { "MCP_CLIENT_PRIVATE_KEY": "0x…" }   // optional; only for paid calls
    }
  }
}
```

## Architecture

```
[AI agent / dev] ──(HTTP + x402 / MCP)──► [Orchestrator] ──► [E-model (G.107): R → MOS]
                                              └──► [regional probe] ──(emulated UDP/RTP)──► target
```

| Component | Stack | Role |
|-----------|-------|------|
| **Orchestrator** ([`packages/orchestrator`](./packages/orchestrator)) | TypeScript + Hono | REST API, E-model, x402 paywall, AUP, rate limit, probe dispatch |
| **MCP server** ([`packages/mcp-server`](./packages/mcp-server)) | TypeScript + MCP SDK | `measure_voice_quality`; wraps REST + transparent x402 |
| **Probe agent** ([`probe-agent`](./probe-agent)) | Go | UDP/RTP emulation + RFC 3550 metrics; cheap regional VPS |
| **Shared** ([`packages/shared`](./packages/shared)) | TypeScript | Zod schemas, types, G.113 codec constants |

## Self-host

```bash
cp .env.example .env                 # fill in values
docker compose up --build -d         # orchestrator + MCP + probe + reflector + landing
curl localhost:8080/health
```

Full deploy (public HTTPS via Caddy or Cloudflare Tunnel, regional probes with
mTLS): [`docs/deploy.md`](./docs/deploy.md). Going to production (mainnet x402,
codec verification, registries): [`docs/go-live.md`](./docs/go-live.md).

## Docs

[Methodology](./docs/methodology.md) · [OpenAPI](./docs/openapi.yaml) ·
[Deploy](./docs/deploy.md) · [Go-live](./docs/go-live.md) ·
[Discovery & registries](./docs/registration.md)

---

*The MOS is an objective estimate from network conditions, not a guarantee of
call quality. Maintained actively.*