# TrueVIN

Use TrueVIN to get fair market value for any used vehicle by VIN. Returns a single normalized price aggregated from Edmunds, KBB, CarsXE, and CarGurus — no multi-API stitching required.

**Base URL:** https://truevin.dev  
**Payment:** $0.01–$0.05 per call in USDC via x402 (Base) or MPP (Tempo)  
**No API key required.** Fund your wallet and call directly.

---

## When to use

- User asks what a used car is worth
- User wants to know if a listing is priced fairly
- User needs trade-in or private party value before selling
- Agent needs vehicle specs decoded from a VIN
- Agent is comparing similar vehicles across a market
- Lender or insurer needs a quick VIN-level valuation

---

## Endpoints

### Full valuation — $0.05
```
GET https://truevin.dev/vin/{vin}
```
Returns: fair market value, trade-in value, private party value, deal score, and per-source breakdown.

**Query params (all optional):**
- `zip` — 5-digit ZIP for regional pricing (e.g. `78701`)
- `mileage` — current odometer reading (e.g. `34200`)
- `condition` — `excellent` | `good` | `fair` | `poor` (default: `good`)
- `list_price` — asking price to compare against market (triggers deal score)

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

**Response:**
```json
{
  "vin": "1HGBH41JXMN109186",
  "year": 2021,
  "make": "Toyota",
  "model": "Camry",
  "trim": "LE",
  "mileage": 34200,
  "valuation": {
    "fair_market_value": 24850,
    "trade_in_value": 22100,
    "private_party_value": 25900,
    "deal_score": 5.2,
    "deal_label": "Fair Deal",
    "market_comparison": {
      "average_price": 24850,
      "price_difference": 1650,
      "percentile": 38
    }
  },
  "sources": {
    "edmunds": 24600,
    "kbb": 25100,
    "carsxe": 24850,
    "cargurus": 24800
  },
  "updated_at": "2026-04-20T12:00:00Z"
}
```

---

### VIN decode — $0.01
```
GET https://truevin.dev/vin/{vin}/decode
```
Returns year, make, model, trim, engine, body style, drivetrain, fuel type. No pricing.

**Use when:** User just needs to know what a vehicle is, not what it's worth.

---

### Price history — $0.05
```
GET https://truevin.dev/vin/{vin}/history
```
Returns a 90-day price trend for this vehicle's make/model/trim, with weekly data points and a direction signal (`rising` | `falling` | `stable`).

**Use when:** User wants to know if now is a good time to buy or if prices are trending down.

---

### Market average — $0.03
```
GET https://truevin.dev/market?make=Toyota&model=Camry&year=2021
```
Returns average, low, and high prices for a make/model/year without a specific VIN.

**Optional:** `zip` for regional pricing.

**Use when:** User asks "what are [make/model] going for?" without a specific car.

---

## Deal score interpretation

| Score | Label | Meaning |
|-------|-------|---------|
| 9–10 | Great Deal | Priced 5%+ below market |
| 7–8 | Good Deal | Priced at or slightly below market |
| 5–6 | Fair Deal | Near market average |
| 3–4 | High Price | Priced above market |
| 1–2 | Overpriced | Significantly above market |

---

## Payment

Pays automatically via x402 (Base/USDC) or MPP (Tempo). Set up your wallet before first call:

**AgentCash:**
```bash
npx agentcash onboard
npx agentcash try https://truevin.dev
npx agentcash add https://truevin.dev
```

**Privy:**
```
Set up https://agents.privy.io/skill.md
```

**Tempo Wallet:**
```
Read https://tempo.xyz/SKILL.md and set up a Tempo Wallet. Fund it with USDC.
```

---

## Agent chain example

**Prompt:** "Is this Craigslist car a good deal? VIN 1HGBH41JXMN109186, asking $26,500 in Austin TX."

1. `GET /vin/1HGBH41JXMN109186?zip=78701&list_price=26500` → FMV $24,850, deal score 5.2 ("Fair Deal"), priced $1,650 above market
2. `GET /vin/1HGBH41JXMN109186/history` → price falling 3% over 90 days
3. Synthesize: "Priced above market. Similar Camry LEs average $24,850 in Austin. The trend is falling — negotiate down or wait."

`truevin.dev` · 2 calls · $0.10

---

## Pricing

| Endpoint | Price |
|----------|-------|
| `/vin/{vin}` | $0.05 |
| `/vin/{vin}/decode` | $0.01 |
| `/vin/{vin}/history` | $0.05 |
| `/market` | $0.03 |

All prices in USDC. No subscription. No free tier.

---

## Resources

- OpenAPI: https://truevin.dev/openapi.json
- LLM context: https://truevin.dev/llms.txt
- x402scan: https://x402scan.com
- MPP scanner: https://mppscan.com
- AgentCash: https://agentcash.dev