{
  "openapi": "3.1.0",
  "info": {
    "title": "TrueVIN API",
    "description": "One VIN. One price. One API. Fair market value for any used vehicle, aggregated from Edmunds, KBB, CarsXE, and CarGurus. Pay per call in USDC via x402 (Base) or MPP (Tempo).",
    "version": "1.0.0",
    "contact": { "url": "https://truevin.dev" }
  },
  "servers": [{ "url": "https://truevin.dev", "description": "Production" }],
  "x-payment": {
    "protocol": "x402",
    "network": "base",
    "currency": "USDC",
    "facilitator": "https://x402.org/facilitator"
  },
  "paths": {
    "/vin/{vin}": {
      "get": {
        "operationId": "getValuation",
        "summary": "Full vehicle valuation",
        "description": "Returns fair market value, trade-in value, private party value, deal score, and per-source price breakdown for a specific VIN. $0.05 per call.",
        "x-payment-price": "$0.05",
        "parameters": [
          {
            "name": "vin",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "pattern": "^[A-HJ-NPR-Z0-9]{17}$" },
            "description": "17-character Vehicle Identification Number"
          },
          {
            "name": "zip",
            "in": "query",
            "schema": { "type": "string", "pattern": "^\\d{5}$" },
            "description": "5-digit ZIP code for regional pricing"
          },
          {
            "name": "mileage",
            "in": "query",
            "schema": { "type": "integer", "minimum": 0, "maximum": 999999 },
            "description": "Current odometer reading in miles"
          },
          {
            "name": "condition",
            "in": "query",
            "schema": { "type": "string", "enum": ["excellent", "good", "fair", "poor"] },
            "description": "Vehicle condition (default: good)"
          },
          {
            "name": "list_price",
            "in": "query",
            "schema": { "type": "number", "minimum": 0 },
            "description": "Listing price to compare against market — activates deal_score and market_comparison"
          }
        ],
        "responses": {
          "200": {
            "description": "Valuation result",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ValuationResult" },
                "example": {
                  "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"
                }
              }
            }
          },
          "400": { "description": "Invalid VIN or query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "402": {
            "description": "Payment required",
            "headers": {
              "X-Payment-Price": { "schema": { "type": "string" }, "description": "Amount owed (e.g. '0.05 USDC')" },
              "X-Payment-Network": { "schema": { "type": "string" }, "description": "Payment network (base)" }
            },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } }
          },
          "404": { "description": "VIN not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/vin/{vin}/decode": {
      "get": {
        "operationId": "decodeVin",
        "summary": "VIN decode — specs only",
        "description": "Returns vehicle identity: year, make, model, trim, engine, body style, drivetrain, and fuel type. No pricing. $0.01 per call.",
        "x-payment-price": "$0.01",
        "parameters": [
          {
            "name": "vin",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "pattern": "^[A-HJ-NPR-Z0-9]{17}$" }
          }
        ],
        "responses": {
          "200": {
            "description": "Vehicle specs",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/DecodeResult" }
              }
            }
          },
          "400": { "description": "Invalid VIN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } },
          "404": { "description": "VIN not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/vin/{vin}/history": {
      "get": {
        "operationId": "getPriceHistory",
        "summary": "90-day price trend",
        "description": "Returns weekly price data points over the past 90 days for this vehicle's make/model/trim. Includes trend direction and percentage change. $0.05 per call.",
        "x-payment-price": "$0.05",
        "parameters": [
          {
            "name": "vin",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "pattern": "^[A-HJ-NPR-Z0-9]{17}$" }
          }
        ],
        "responses": {
          "200": {
            "description": "Price history",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/HistoryResult" }
              }
            }
          },
          "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } },
          "404": { "description": "VIN not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/market": {
      "get": {
        "operationId": "getMarket",
        "summary": "Market average by make/model/year",
        "description": "Returns average, low, and high prices for a make/model/year without a specific VIN. Supports ZIP code for regional pricing. $0.03 per call.",
        "x-payment-price": "$0.03",
        "parameters": [
          { "name": "make", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "model", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "year", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1980 } },
          { "name": "zip", "in": "query", "schema": { "type": "string", "pattern": "^\\d{5}$" } }
        ],
        "responses": {
          "200": {
            "description": "Market pricing data",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/MarketResult" }
              }
            }
          },
          "400": { "description": "Missing required parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }
        }
      }
    },
    "/health": {
      "get": {
        "operationId": "healthCheck",
        "summary": "Health check",
        "description": "Returns server status. Free — no payment required.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "ok" },
                    "timestamp": { "type": "string", "format": "date-time" },
                    "version": { "type": "string", "example": "1.0.0" }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ValuationResult": {
        "type": "object",
        "required": ["vin", "year", "make", "model", "trim", "mileage", "valuation", "sources", "updated_at"],
        "properties": {
          "vin": { "type": "string" },
          "year": { "type": "integer" },
          "make": { "type": "string" },
          "model": { "type": "string" },
          "trim": { "type": "string" },
          "mileage": { "type": ["integer", "null"] },
          "valuation": {
            "type": "object",
            "properties": {
              "fair_market_value": { "type": "integer", "description": "Weighted average across all sources (USD)" },
              "trade_in_value": { "type": "integer", "description": "Estimated dealer offer (USD)" },
              "private_party_value": { "type": "integer", "description": "Peer-to-peer sale estimate (USD)" },
              "deal_score": { "type": ["number", "null"], "minimum": 0, "maximum": 10, "description": "Deal quality score — only present when list_price provided" },
              "deal_label": { "type": ["string", "null"], "enum": ["Great Deal", "Good Deal", "Fair Deal", "High Price", "Overpriced", null] },
              "market_comparison": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "average_price": { "type": "integer" },
                      "price_difference": { "type": "integer", "description": "list_price minus FMV (positive = overpriced)" },
                      "percentile": { "type": "integer", "minimum": 1, "maximum": 99, "description": "Price percentile (lower = better deal)" }
                    }
                  },
                  { "type": "null" }
                ]
              }
            }
          },
          "sources": {
            "type": "object",
            "properties": {
              "edmunds": { "type": ["integer", "null"] },
              "kbb": { "type": ["integer", "null"] },
              "carsxe": { "type": ["integer", "null"] },
              "cargurus": { "type": ["integer", "null"] }
            }
          },
          "updated_at": { "type": "string", "format": "date-time" }
        }
      },
      "DecodeResult": {
        "type": "object",
        "properties": {
          "vin": { "type": "string" },
          "year": { "type": "integer" },
          "make": { "type": "string" },
          "model": { "type": "string" },
          "trim": { "type": "string" },
          "engine": { "type": "string" },
          "bodyStyle": { "type": "string" },
          "drivetrain": { "type": "string" },
          "fuelType": { "type": "string" },
          "plant": { "type": "string" }
        }
      },
      "HistoryResult": {
        "type": "object",
        "properties": {
          "vin": { "type": "string" },
          "make": { "type": "string" },
          "model": { "type": "string" },
          "trim": { "type": "string" },
          "year": { "type": "integer" },
          "trend_90d": {
            "type": "object",
            "properties": {
              "start_price": { "type": "integer" },
              "end_price": { "type": "integer" },
              "change_pct": { "type": "number" },
              "direction": { "type": "string", "enum": ["rising", "falling", "stable"] }
            }
          },
          "data_points": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "date": { "type": "string", "format": "date" },
                "average_price": { "type": "integer" },
                "sample_size": { "type": "integer" }
              }
            }
          }
        }
      },
      "MarketResult": {
        "type": "object",
        "properties": {
          "make": { "type": "string" },
          "model": { "type": "string" },
          "year": { "type": "integer" },
          "zip": { "type": ["string", "null"] },
          "average_price": { "type": "integer" },
          "low_price": { "type": "integer" },
          "high_price": { "type": "integer" },
          "sample_size": { "type": "integer" },
          "updated_at": { "type": "string", "format": "date-time" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string" }
        }
      },
      "PaymentRequired": {
        "type": "object",
        "properties": {
          "error": { "type": "string", "example": "Payment required" },
          "x402Version": { "type": "integer", "example": 1 },
          "accepts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "scheme": { "type": "string", "example": "exact" },
                "network": { "type": "string", "example": "base" },
                "maxAmountRequired": { "type": "string", "example": "50000" },
                "resource": { "type": "string" },
                "description": { "type": "string" },
                "mimeType": { "type": "string", "example": "application/json" },
                "payTo": { "type": "string", "description": "Recipient address on Base" },
                "asset": { "type": "string", "description": "USDC contract address on Base" }
              }
            }
          }
        }
      }
    }
  }
}