diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b1a3b3c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,144 @@
+# MAC Address Vendor Lookup API
+
+A FastAPI service that identifies network device manufacturers from MAC addresses using a three-tier lookup strategy for optimal performance and reliability.
+
+## Features
+
+- **Multi-format MAC address support**: Accepts various formats (with/without separators)
+- **Partial MAC lookup**: Works with full addresses or just the first 6 digits (OUI)
+- **Three-tier lookup strategy**:
+  1. Local file cache (fastest)
+  2. GitHub vendor database fallback
+  3. External API fallback (macvendors.com)
+- **Standardized output**: Returns MAC addresses in dash-separated format
+
+## Supported MAC Address Formats
+
+All of these formats are accepted:
+- `000000` (OUI only)
+- `00:00:01`
+- `00-00-02-AB-CD-EF`
+- `000003ABCDEF`
+- `00 00 04 12 34 56`
+
+## How to Deploy
+
+### Using Docker Compose
+
+```yml
+services:
+  api:
+    image: git.shihaam.dev/shihaam/macvendors
+    ports:
+      - 5000:8000
+```
+
+### Using Docker
+
+```bash
+# Pull and run
+docker run -p 5000:8000 git.shihaam.dev/shihaam/macvendors
+
+# With local MAC vendor file
+docker run -p 5000:8000 -v $(pwd)/mac_list.txt:/app/mac_list.txt git.shihaam.dev/shihaam/macvendors
+```
+
+### Local Development
+
+```bash
+# Install dependencies
+pip install fastapi uvicorn httpx
+
+# Run the server
+uvicorn macvendorapi:app --host 0.0.0.0 --port 8000
+```
+
+## API Usage
+
+### Endpoint
+
+```
+GET /lookup/{mac_address}
+```
+
+### Examples
+
+```bash
+# Basic lookup
+curl http://localhost:5000/lookup/70-22-FE
+
+# Different formats
+curl http://localhost:5000/lookup/7022FE
+curl http://localhost:5000/lookup/70:22:FE
+curl http://localhost:5000/lookup/70-22-FE-12-34-56
+```
+
+### Expected Response
+
+```json
+{
+  "mac_address": "70-22-FE",
+  "vendor": "Apple, Inc."
+}
+```
+
+### Error Responses
+
+**Invalid MAC address:**
+```json
+{
+  "detail": "Invalid MAC address format"
+}
+```
+
+**Unknown vendor:**
+```json
+{
+  "mac_address": "FF-FF-FF",
+  "vendor": "Unknown"
+}
+```
+
+## Local MAC Vendor File
+
+To improve performance, you can provide a local `mac_list.txt` file in the same format as the [IEEE OUI database](https://gist.githubusercontent.com/aallan/b4bb86db86079509e6159810ae9bd3e4/raw/846ae1b646ab0f4d646af9115e47365f4118e5f6/mac-vendor.txt):
+
+```
+000000	Officially Xerox
+000001	SuperLAN-2U
+000002	BBN (was internal usage only, no longer used)
+```
+
+## Lookup Strategy
+
+1. **Local File**: Checks `mac_list.txt` first (fastest, no network calls)
+2. **GitHub Database**: Falls back to the official IEEE OUI database
+3. **External API**: Uses macvendors.com API as final fallback
+4. **Unknown**: Returns "Unknown" if no matches found
+
+## Building from Source
+
+```bash
+# Clone repository
+git clone <repository-url>
+cd macvendors
+
+# Build Docker image
+docker build -t mac-vendor-api .
+
+# Run container
+docker run -p 8000:8000 mac-vendor-api
+```
+
+## Health Check
+
+```bash
+curl http://localhost:5000/
+```
+
+Returns:
+```json
+{
+  "message": "MAC Address Vendor Lookup API"
+}
+```