# Sonar

> Sonar is the independent reliability and routing layer for agent commerce.

Before an agent spends money on an x402 API, Sonar helps it identify which provider is most likely to work, what it costs, and why.

## What Sonar does

- Aggregates x402 service listings from multiple discovery sources.
- Deduplicates services by canonical HTTP method and URL.
- Runs controlled, unpaid HTTP 402 probes from a private worker.
- Measures liveness, handshake validity, latency, price drift, and schema coverage.
- Computes transparent status and ranking signals from observed history.
- Exposes explainable recommendations through REST and MCP.
- Never acts as a provider proxy and never pays a service during normal recommendations.

## Primary URLs

- Homepage: /
- Service catalog: /services
- Recommendation UI: /services#recommend
- Documentation: /docs
- REST API documentation: /docs#rest
- MCP documentation: /docs#mcp
- Machine-readable API overview: /api/docs
- MCP endpoint: /api/mcp
- REST stats: /api/v1/stats
- REST catalog: /api/v1/endpoints?limit=100&offset=0
- REST recommendations: /api/v1/route?capability=weather&prefer=reliable&n=3

## Recommendation API

`GET /api/v1/route` ranks measured services for an agent task.

Query parameters:

- `capability`: keyword, category, or use case.
- `prefer`: `balanced`, `reliable`, `fastest`, or `cheapest`.
- `max_price`: optional maximum advertised USD price.
- `n`: number of recommendations, from 1 to 10.

Results include endpoint identity, description, documentation URL, price, score, uptime, p90 latency, price drift, schema completeness, and probe count.

## Catalog API

`GET /api/v1/endpoints` supports `limit` up to 100 and offset pagination. Each result includes URL, method, name, description, category, status, advertised price, probe statistics, and score.

`GET /api/v1/endpoints/:id` returns full service details.

`GET /api/v1/endpoints/:id/history` returns recent probe outcomes.

## MCP

Connect an MCP client to `POST /api/mcp`.

Available tools:

- `search_services`: search the measured catalog by capability, category, status, or price.
- `get_service_health`: inspect one service, evidence, and probe history.
- `recommend_service`: rank services for a capability and preference.

Sonar MCP returns context and recommendations. It does not invoke providers or make payments on behalf of the caller.

## Evidence and status

Sonar maintains independent measurements rather than copying source-directory badges. Status is based on the 24-hour measurement window:

- `unknown`: no probes yet.
- `live`: handshake uptime at least 95%.
- `degraded`: lower uptime, high latency, or material price drift.
- `down`: low uptime with a recent success.
- `dead`: no success for seven days after enough measurement history.

Services with fewer than five probes are marked `confidence: low` in API responses and in the UI. Their status is provisional.

Scores combine observed success, latency, price, price drift, schema completeness, and freshness. Treat scores as evidence-backed comparisons, not guarantees.

## Sources

The private ingester currently supports Coinbase Bazaar, x402 List, and local JSON sources. Source listings are normalized and deduplicated before Sonar probes them independently.

## Safety

Free probes are unpaid and restrict unsafe URLs, private networks, and mutating unattended requests. Paid probing is disabled by default and requires separate operator configuration, budget caps, and payment controls.

## Crawler guidance

This file is intended for language models, search agents, MCP clients, and documentation crawlers. Prefer the JSON endpoints above over scraping rendered HTML. Respect HTTP caching, pagination, and rate limits.