# Vindex API

Vehicle Intelligence for AI agents. Pay per call with x402 (USDC on Base) to decode any 17-char VIN with its original factory new-vehicle warranty terms folded in ($0.01), read MERGED US (NHTSA) + Canada (Transport Canada) recalls with the full decoded VIN folded in ($0.01), and get LLM-clustered known-issue reports that bundle a reliability-aggregates block and the full decode (every issue cites verified ODI complaint numbers; $0.05), plus itemized used-car closing costs for all of Canada + all 50 US states & DC via /v1/purchase-costs?country=CA|US ($0.02). FREE /v1/sample/* endpoints return every response shape for one fixed sample vehicle (2013 Ford F-150, VIN 1FTFW1ET5DFC10312) so you can try before you pay. Every JSON object response carries a legal `disclaimer` field. Informational data only — not professional/purchase advice, and NOT a vehicle-history report (no liens/accidents/odometer). Contains information licensed under the Open Government Licence – Canada.

- **Base URL**: https://api.vindexapi.dev
- **Docs (agent-facing)**: https://api.vindexapi.dev/llms.txt · https://api.vindexapi.dev/llms-full.txt
- **OpenAPI 3.1**: https://api.vindexapi.dev/openapi.json
- **Discovery (JSON)**: https://api.vindexapi.dev/discovery
- **x402 manifest**: https://api.vindexapi.dev/.well-known/x402
- **Agent card (A2A)**: https://api.vindexapi.dev/.well-known/agent-card.json
- **Terms**: https://api.vindexapi.dev/terms.txt

Informational vehicle data only — NOT professional, legal, or purchase advice, and NOT a
vehicle-history report (no liens/accidents/odometer). Contains information licensed under the Open Government Licence – Canada.

## Free (no auth, no payment)

| Method | Path | What |
|--------|------|------|
| GET | /health | Liveness + payment mode |
| GET | /.well-known/hexanon | Catalog of all products in the Hexanon family (x402 data & intelligence APIs for AI agents) — names, taglines, API base URLs, docs, MCP packages. Same catalog on every Hexanon product; canonical copy at https://api.moltalyzer.xyz/.well-known/hexanon. (rate limit: 5/min) |
| GET | /v1/sample/decode | Free, no payment. Normalized NHTSA vPIC decode for the fixed sample vehicle. Same shape as paid GET /v1/decode plus `sample: true` and `note`. (rate limit: 5/min) |
| GET | /v1/sample/recalls | Free, no payment. Merged NHTSA (US) + Transport Canada (CA) recalls + full decoded vehicle for the fixed sample vehicle. Same shape as paid GET /v1/recalls plus `sample: true` and `note`. (rate limit: 5/min) |
| GET | /v1/sample/known-issues | Free, no payment. LLM-clustered known-issues + reliability-aggregates block + full decoded vehicle for the fixed sample vehicle. Same shape as paid GET /v1/known-issues plus `sample: true` and `note`. A non-'ok' synthesis status is served as-is with 200 (samples never 503), still carrying the decode + reliability block. (rate limit: 2/min) |
| GET | /v1/sample/purchase-costs | Free, no payment. Returns `{ sample: true, note, ca, us }`: `ca` is the Ontario $25,000-private result (same shape as paid GET /v1/purchase-costs?country=CA) and `us` is the California $25,000-private result (same shape as paid GET /v1/purchase-costs?country=US). (rate limit: 10/min) |
| GET | /terms.txt · /terms.json | Terms of Service |

## Paid (x402 V2 — USDC on eip155:8453, per-call)

| Method | Path | Price | What |
|--------|------|-------|------|
| GET | /v1/decode | $0.01 | Paid ($0.01 USDC via x402). Decodes a 17-char VIN through NHTSA vPIC and returns the normalized decoded vehicle (make/model/year/engine/body/…) with fetch provenance, PLUS a `warranty` block giving the ORIGINAL factory new-vehicle warranty terms (basic/powertrain/corrosion/roadside/EV-battery) keyed off the decoded make + model-year. Warranty terms are the manufacturer's original coverage as sold — NOT warranty-remaining, and NOT extended-warranty campaigns, recalls, or emissions warranties. The cheapest call when you only need the decode — the same `vehicle` object is also folded into /v1/recalls and /v1/known-issues. Compute-first / settle-after. Free fixed-sample preview of this exact shape: GET /v1/sample/decode. |
| GET | /v1/recalls | $0.01 | Paid ($0.01 USDC via x402). Decodes the VIN and returns the FULL decoded vehicle (the same payload as /v1/decode is folded in here), then merges NHTSA (US) and Transport Canada (CA) recalls into one response — the only API combining both. 24h cache per source; stale served on failure. Canadian detail capped at the 25 most-recent recalls. OGL–Canada attribution. Compute-first / settle-after. Free fixed-sample preview of this exact shape: GET /v1/sample/recalls. |
| GET | /v1/known-issues | $0.05 | Paid ($0.05 USDC via x402). Clusters NHTSA owner complaints into named failure modes; EVERY cited ODI number is programmatically validated against the input complaint set (hallucination-gated) and every issue carries ≥2 verified citations. Severity signals per issue are summed from the CITED complaints only. The response also bundles a `reliability` aggregates block (top components, severity signals, US/Canada recall counts incl. Canadian units affected — reliability was merged into known-issues on 2026-07-07), the full decoded `vehicle` (same payload as /v1/decode), and `complaintsAnalyzed`, the size of the recent-weighted stratified sample the LLM actually saw (vs `complaintCount`, the total). Refuses UNCHARGED below 15 complaints (returns 200 status:insufficient_data) — but still returns the decode + reliability block for free. 90-day cache. Compute-first / settle-after. Free fixed-sample preview of this exact shape: GET /v1/sample/known-issues. |
| GET | /v1/purchase-costs | $0.02 | Paid ($0.02 USDC via x402). Government-imposed closing costs of buying a used passenger vehicle, unified across both countries via `country=CA|US`. CA: any of Canada's 10 provinces + 3 territories (BC, AB, SK, MB, ON, QC, NB, NS, PE, NL, YT, NT, NU) — provincial/territorial sales tax (PST/RST/QST/HST or GST-only) plus transfer/registration/plate fees and inspection; tax is flat on the whole price at the highest bracket whose threshold the price meets (BC private 12% → 15% ≥ $125,000 → 20% ≥ $150,000); Alberta + the three territories levy no private-sale tax; dealer sales add 5% GST except in HST provinces (ON/NB/NS/PE/NL). US: any of the 50 states or DC — sales/use/excise tax, title, first-year registration, inspection, and (for dealer sales) a dealer documentation fee; special regimes handled automatically (DC tiered title-excise range, IL flat RUT-50 private-party table, SC 5% IMF capped at $500, and AK/AZ/HI/MT/NV/NH/OR no private-party sales tax). Each line carries a source URL and confidence. Figures verified 2026-07-04. Compute-first / settle-after. Free fixed-sample preview of this exact shape: GET /v1/sample/purchase-costs. |
| GET | /v1/prepurchase | $0.25 | Whole-job bundle for agents advising a vehicle purchase. One payment returns the normalized VIN decode, safety recalls, known-issue/reliability summary, and CA/US purchase+ownership cost estimate for the decoded vehicle. Equivalent to 4 separate paid calls. Composed in-process from the same data as /v1/decode, /v1/recalls, /v1/known-issues and /v1/purchase-costs (no extra upstream fan-out beyond those). The decode is computed FIRST — an invalid VIN or decode failure returns UNCHARGED (no settle). The response then settles only if the decode succeeded AND at least 2 of the 3 secondary sections (recalls, known-issues, purchase-costs) are available; otherwise it returns UNCHARGED { error: 'insufficient_sections', sections: {…} }. A section that failed but was still charged appears as sections.<name>:'unavailable' with the rest of the report intact. The cost section is a jurisdiction-level estimate (the bundle takes no price/province/state) — call GET /v1/purchase-costs for an exact itemized figure. Compute-first / settle-after. Each section carries its own fetch provenance. |

Prices are USD, settled as USDC (6 decimals). Compute-first / settle-after: you are never
charged for errors or below-threshold answers.

## Quickstart — pay per call (x402, USDC)

```
# 1) Call a paid route with no payment → 402 challenge
curl -s "https://api.vindexapi.dev/v1/decode"
# → { "x402Version": 2, "accepts": [ { "scheme": "exact", "network": "eip155:8453",
#     "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
#     "amount": "10000", "payTo": "0x…" } ], "terms": "https://api.vindexapi.dev/terms.txt" }

# 2) Sign an x402 'exact' USDC authorization for one accepts[] rail, then retry.
#    Standard @x402 V2 clients send PAYMENT-SIGNATURE; legacy clients send X-PAYMENT.
curl -s "https://api.vindexapi.dev/v1/decode?vin=1FA6P8TH5J5100000" -H "PAYMENT-SIGNATURE: <payload>"
# → 200 { …, "charged": true }
```

## Links
- Docs: https://api.vindexapi.dev/llms.txt
- Full: https://api.vindexapi.dev/llms-full.txt
- OpenAPI: https://api.vindexapi.dev/openapi.json
- Discovery: https://api.vindexapi.dev/discovery
- Agent card: https://api.vindexapi.dev/.well-known/agent-card.json
- Changelog: https://api.vindexapi.dev/changelog