# Vindex — Canada-aware vehicle intelligence API for AI agents (v0.1.0)

> Vehicle Intelligence for AI agents — Canada-aware, per-call, no signup. Pay per call with x402
> (USDC on Base or Solana) to decode any 17-char VIN, read MERGED US (NHTSA) + Canada (Transport
> Canada) recalls, and get reliability stats, LLM-clustered known-issue reports (every issue cites
> verified ODI complaint numbers), and itemized used-car closing costs for all of Canada (10 provinces
> + 3 territories) + all 50 US states & DC. FREE /v1/sample/*
> endpoints return every response shape for one fixed sample vehicle so you can try before you pay.
> Informational data only — NOT professional/purchase advice, and NOT a vehicle-history report.

<!-- prices below: keep in sync with src/pricing.ts (decode 0.01 / recalls 0.01 / reliability 0.05 / known-issues 0.25 / purchase-costs 0.02 / us-purchase-costs 0.02) -->

## Base URL
- API: https://api.vindexapi.dev
- This document: https://api.vindexapi.dev/llms.txt  ·  Extended: https://api.vindexapi.dev/llms-full.txt
- Discovery (JSON): https://api.vindexapi.dev/discovery
- OpenAPI 3.1: https://api.vindexapi.dev/openapi.json
- 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

## What Vindex is
Vindex aggregates free, public-domain vehicle-safety data and sells thin intelligence layers on
top, priced per call. It is the ONLY API that merges US (NHTSA) and Canada (Transport Canada)
recalls in one response, with Open Government Licence – Canada attribution. VINs are used only as
cache keys (up to 90 days), never linked to a person; no owner/registrant data is collected or
returned. Vindex is NOT a vehicle-history report — it makes no liens/accidents/odometer claims.

Every JSON object response also carries a `disclaimer` string.

## Free endpoints (no auth, no payment)
Every /v1/sample/* endpoint always serves the SAME fixed sample vehicle (2013 Ford F-150,
VIN 1FTFW1ET5DFC10312), computed live through the normal pipeline — identical response shape to its
paid per-VIN twin, plus top-level `sample: true`. Use them to learn every shape before paying.

| Method | Path | Description |
|--------|------|-------------|
| GET | /health | Liveness + configured payment mode (live\|mock) |
| GET | /v1/sample/decode | FREE sample VIN decode (same shape as paid /v1/decode) |
| GET | /v1/sample/recalls | FREE sample merged US + Canada recalls (same shape as paid /v1/recalls) |
| GET | /v1/sample/reliability | FREE sample reliability stats (same shape as paid /v1/reliability) |
| GET | /v1/sample/known-issues | FREE sample known-issues (same shape as paid /v1/known-issues; served as-is, never 503) |
| GET | /v1/sample/purchase-costs | FREE sample closing costs for BOTH countries — `ca` (Ontario $25,000 private) + `us` (California $25,000 private) |
| GET | /terms.txt · /terms.json | Terms of Service (also sets X-Terms-URL) |

## Paid endpoints (x402 V2, USDC on Base or Solana, per-call)
Vindex is strictly pay-per-call: no bundles, no entitlements. Each paid call answers a 402
challenge; sign an x402 `exact` USDC authorization for one advertised rail and retry. Standard
@x402 V2 clients send the `PAYMENT-SIGNATURE` header; legacy clients send `X-PAYMENT` — both are
accepted in live mode. Compute-first / settle-after: you are NEVER charged for an error or a
below-threshold answer.

| Method | Path | Price | Description |
|--------|------|-------|-------------|
| GET | /v1/decode?vin=VIN | $0.01 | NHTSA vPIC normalized decode (make/model/year/engine/…). 90-day cache |
| GET | /v1/recalls?vin=VIN | $0.01 | MERGED NHTSA (US) + Transport Canada (CA) recalls + counts. OGL–Canada attribution. 24h cache |
| GET | /v1/reliability?vin=VIN | $0.05 | Complaint stats (top components; severity: crashes/fires/injuries) + US & Canada recall counts incl. Canadian units affected. v0 returns raw counts (not fleet percentiles) |
| GET | /v1/known-issues?vin=VIN | $0.25 | LLM-clustered named failure modes from NHTSA complaints; EVERY issue cites verified ODI complaint numbers (validated against the source set — hallucination-gated). Refuses (uncharged) below 15 complaints. 90-day cache |
| GET | /v1/ca/purchase-costs?province=BC&price=25000&sale_type=private\|dealer | $0.02 | Itemized Canadian used-vehicle closing costs for any of the 10 provinces + 3 territories (BC/AB/SK/MB/ON/QC/NB/NS/PE/NL/YT/NT/NU): provincial tax (PST/RST/QST/HST or GST-only) + transfer/registration/plate fees + inspection, per-line sourceUrl + confidence. Flat-on-whole bracket tax (e.g. BC 12/15/20%); AB + YT/NT/NU have no private-sale tax |
| GET | /v1/us/purchase-costs?state=CA&price=25000&sale_type=private\|dealer | $0.02 | Itemized US used-vehicle closing costs for any of the 50 states + DC (sales/use/excise tax, title, first-year registration, inspection, dealer doc fee), per-line sourceUrl + confidence |

Optional CA purchase-costs params: `&buyer_has_plates=true` (selects plate-dependent fee lines where a
jurisdiction distinguishes them, e.g. Ontario permit only $32 vs permit + plate $59), `&family_gift=true`
(applies the jurisdiction's family/related-individual gift exemption, $0 tax, private sales only). Tax
base uses the greater of price and book value where a floor exists — a caveat flags this.

Optional US purchase-costs params: `&trade_in=5000` (deducted from the tax base only where the state
grants a FULL dealer trade-in credit), `&local_rate=1.5` (exact county/city surtax %; when omitted the
sales-tax line carries a range up to the state's max local rate). Special regimes handled automatically:
DC has NO percentage sales tax — a tiered title EXCISE (1.5–11% of FMV by weight × MPG) is returned as a
`market_estimate` range; IL private-party sales use a flat RUT-50 fee table (returned as a null-amount
`market_estimate`, 6.25% + local applies to IL DEALER sales only); SC charges a 5% IMF CAPPED at $500;
and AK/AZ/HI/MT/NV/NH/OR levy NO state sales tax on private-party sales ($0 tax line). Registration is
first-year only; value-based recurring taxes (AZ VLT, AL ad valorem, etc.) are noted under registration.

Prices are USD, settled as USDC (6 decimals). A mock mode exists for testing (`x-mock-payment`
header); the flow described here is live x402.

## Paid flow (x402)
1. `GET /v1/known-issues?vin=1FA6P8TH5J5100000` with no payment → **402** PaymentRequired:
   ```json
   {
     "x402Version": 2,
     "accepts": [
       { "scheme": "exact", "network": "eip155:8453", "asset": "USDC", "price": "$0.25",
         "payTo": "0x…", "description": "Vindex known-issues for one VIN", "mimeType": "application/json" },
       { "scheme": "exact", "network": "solana", "asset": "USDC", "price": "$0.25",
         "payTo": "…", "description": "Vindex known-issues for one VIN", "mimeType": "application/json" }
     ],
     "terms": "https://api.vindexapi.dev/terms.txt"
   }
   ```
2. Pick one `accepts[]` rail and sign an x402 `exact` USDC authorization (EIP-3009 on Base, or an
   SPL TransferChecked on Solana). Retry the SAME request with the payment header
   (`PAYMENT-SIGNATURE` for V2 clients, or legacy `X-PAYMENT`).
3. Server flow is compute-first: it computes the answer, and only settles + charges if the answer
   is billable. Errors and below-threshold refusals are returned **uncharged**. On success → **200**
   with the endpoint's JSON body.

## Volume tiers
None. Vindex is flat per-call: decode $0.01, recalls $0.01, reliability $0.05, known-issues $0.25,
CA purchase-costs $0.02, US purchase-costs $0.02. The /v1/sample/* endpoints are always free.

## Errors
- 400 — invalid VIN (must be 17 chars, no I/O/Q) or bad params (e.g. missing province/price/sale_type)
- 402 — payment required / verification or settlement failed (you were NOT charged)
- 422 — vPIC could not resolve make/model/year for this VIN (`vpicErrorText` explains)
- 502 — an upstream public-data source was unavailable (served stale where possible)
- known-issues below 15 complaints → **200** `{ "status": "insufficient_data", … }` (uncharged, not an error)

## Data sources & attribution
- NHTSA vPIC + api.nhtsa.gov (US federal, public domain) — decode, recalls, complaints
- Transport Canada vehicle-recall-database — Canadian recalls; Contains information licensed under
  the Open Government Licence – Canada.

## Disclaimer
Informational vehicle data aggregated from public sources; not professional, legal, or purchasing
advice; provided as-is without warranty. NOT a vehicle-history report (no liens/accidents/odometer).
Recall/complaint data reflects the source databases at fetch time. Terms: https://api.vindexapi.dev/terms.txt