# TrueVIN

> One VIN. One price. One API.

TrueVIN is a pay-per-call REST API that returns a single fair market value for any used vehicle by VIN. It aggregates pricing data from Edmunds, KBB, CarsXE, and CarGurus into one normalized JSON response, eliminating the need to manage multiple automotive data APIs.

Payments settle in USDC via x402 (Base network) or MPP (Tempo). No API key or subscription required.

**Base URL:** https://truevin.dev
**Price:** $0.01–$0.05 per call in USDC

---

## Endpoints

### GET /vin/{vin} — Full valuation ($0.05)

Returns fair market value, trade-in value, private party value, deal score, and per-source price breakdown for a specific vehicle.

Parameters:
- `vin` (path, required) — 17-character Vehicle Identification Number
- `zip` (query, optional) — 5-digit ZIP code for regional pricing
- `mileage` (query, optional) — current odometer reading in miles
- `condition` (query, optional) — excellent | good | fair | poor (default: good)
- `list_price` (query, optional) — asking price to compare against market; activates deal_score

Example: GET https://truevin.dev/vin/1HGBH41JXMN109186?zip=78701&mileage=34200&list_price=26500

Response fields:
- valuation.fair_market_value — weighted average across all sources
- valuation.trade_in_value — estimated dealer offer (~89% of FMV)
- valuation.private_party_value — peer-to-peer estimate (~104% of FMV)
- valuation.deal_score — 0–10 score (10 = great deal), only present when list_price provided
- valuation.deal_label — "Great Deal" | "Good Deal" | "Fair Deal" | "High Price" | "Overpriced"
- valuation.market_comparison.price_difference — how much list_price differs from FMV (positive = overpriced)
- sources — individual prices from Edmunds, KBB, CarsXE, CarGurus

### GET /vin/{vin}/decode — VIN decode ($0.01)

Lightweight endpoint returning vehicle identity: year, make, model, trim, engine, body style, drivetrain, fuel type. No pricing data. Use when you only need to identify a vehicle, not value it.

### GET /vin/{vin}/history — 90-day price trend ($0.05)

Returns weekly price data points over the past 90 days for this vehicle's make/model/trim. Includes trend direction (rising | falling | stable) and percentage change. Use to help a user decide whether to buy now or wait.

### GET /market — Market average ($0.03)

Returns average, low, and high prices for a make/model/year combination without a specific VIN. Supports ZIP code for regional adjustment.

Required parameters: make, model, year
Optional: zip

Example: GET https://truevin.dev/market?make=Toyota&model=Camry&year=2021&zip=78701

### GET /health — Free

Returns server status and timestamp. No charge.

---

## Deal Score Guide

10 — Great Deal: priced 10%+ below market
9 — Great Deal: priced 5–10% below market
8 — Good Deal: priced 2–5% below market
7 — Good Deal: at or slightly below market
6 — Fair Deal: within 0–3% of market
5 — Fair Deal: 3–6% above market
4 — High Price: 6–10% above market
3 — High Price: 10–15% above market
2 — Overpriced: 15–20% above market
1 — Overpriced: 20%+ above market

---

## Payment setup

Before making your first call, fund a USDC wallet on Base:

AgentCash (recommended for AI agents):
  npx agentcash onboard     — creates wallet, shows deposit address
  npx agentcash try https://truevin.dev   — test call for $0.05
  npx agentcash add https://truevin.dev   — register in your agent config

Privy (no CLI):
  Set up https://agents.privy.io/skill.md

Tempo Wallet (MPP):
  Read https://tempo.xyz/SKILL.md and fund with USDC

---

## Example agent workflow

User: "Is this Craigslist listing a good deal? VIN 1HGBH41JXMN109186, asking $26,500, Austin TX."

Step 1: GET /vin/1HGBH41JXMN109186?zip=78701&mileage=34200&condition=good&list_price=26500
Result: FMV $24,850 · Deal score 5.2 "Fair Deal" · $1,650 above market

Step 2: GET /vin/1HGBH41JXMN109186/history
Result: Price falling 3% over 90 days

Agent response: "This 2021 Toyota Camry LE is priced $1,650 above the Austin market average of $24,850. The trend is falling — prices for this model have dropped 3% in the past 90 days. You could likely negotiate to $24,500–$25,000, or wait a few weeks for prices to continue falling."

Cost: 2 calls · $0.10

---

## Data sources

- Edmunds — pricing, VIN specs, trade-in values (official API)
- KBB (Kelley Blue Book) — Blue Book value, private party (pilot program)
- CarsXE — market value, VIN decode, vehicle history (official API)
- CarGurus — deal rating, market comparison, listing prices (IMV API)
- NHTSA — free government VIN decode fallback

---

## Resources

- Full API spec: https://truevin.dev/openapi.json
- Agent skill file: https://truevin.dev/skill.md
- x402 listings: https://x402scan.com
- MPP listings: https://mppscan.com
- AgentCash directory: https://agentcash.dev