From 515d9b7e68e98a570c6c153f42d05f6e90a1f26c Mon Sep 17 00:00:00 2001
From: "yves.gugger" <yves.gugger@gentwo.com>
Date: Mon, 8 Dec 2025 12:04:31 +0100
Subject: [PATCH] docs: Document TLD price consistency strategy in README

---
 README.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/README.md b/README.md
index 2f4e0b6..a8dd71b 100644
--- a/README.md
+++ b/README.md
@@ -254,6 +254,28 @@ npm run dev
 | GET | `/api/v1/tld-prices/{tld}/history` | Get price history |
 | GET | `/api/v1/tld-prices/{tld}/compare` | Compare registrar prices |
 
+#### Price Data Consistency
+
+All TLD price endpoints use a unified pricing strategy:
+
+1. **Static TLDs (18 popular)**: Rich multi-registrar data (5+ registrars per TLD)
+   - .com, .net, .org, .io, .ai, .dev, .app, .xyz, .tech, .online, .store, .me, .info, .biz, .ch, .de, .uk, .co
+   
+2. **Database TLDs (869+)**: Scraped from Porkbun API (single registrar)
+
+**Price Calculation** (consistent across all endpoints):
+```
+avg_price = sum(registrar_prices) / count(registrars)
+min_price = min(registrar_prices)
+max_price = max(registrar_prices)
+```
+
+This ensures identical prices on:
+- Overview table (`/overview`)
+- Detail page (`/{tld}`)
+- Compare page (`/{tld}/compare`)
+- Trending cards (`/trending`)
+
 ### Subscription
 | Method | Endpoint | Description |
 |--------|----------|-------------|