diff --git a/README.md b/README.md
index 89145ba..f1b3670 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,117 @@
 # aiohttpx
 
-aiohttpx is a HTTP client built on top of the [httpx](https://github.com/encode/httpx) and [aiohttp](https://github.com/aio-libs/aiohttp) libraries.
+## Description
+
+**aiohttpx** is an asynchronous HTTP client that merges the ergonomics and powerful API of [httpx](https://github.com/encode/httpx) with the high-performance transport layer of [aiohttp](https://github.com/aio-libs/aiohttp).
+It also provides optional Redis-powered caching and rate-limiting to enable efficient, production-grade request handling with minimal setup.
 
 ## Features
 
-* Fully asynchronous using aiohttp as the transport
-* Supports caching using Redis as the backend
-* Supports rate limiting using Redis as the backend
+* Fully asynchronous HTTP client using **aiohttp** as the transport.
+* Optional **Redis-based caching** to reduce redundant API calls.
+* Optional **Redis-based rate limiting** to control request throughput.
+* Familiar API interface inspired by **httpx**.
+
+## Requirements
+
+* Python 3.13 or higher
+* Redis server (if using caching or rate limiting)
+
+## Installation
+
+### Using `uv` Tool
+
+This project supports dependency management via the [uv tool](https://github.com/astral-sh/uv).
+To set up the project:
+
+1. **Install uv**
+
+   ```bash
+   curl -LsSf https://astral.sh/uv/install.sh | sh
+   ```
+
+2. **Add to the repository**
+
+   ```bash
+   uv add https://git.meowly.ru/Miwory/aiohttpx.git
+   ```
+
+## Configuration
+
+aiohttpx supports several optional parameters for caching and rate limiting:
+
+### `key` — Redis prefix
+
+A string used as the **Redis key namespace** for all cache and rate-limit entries.
+This allows multiple clients or services to share the same Redis instance without collisions.
+
+### `limit` — Rate limit
+
+The maximum number of requests allowed **per second** for this client.
+This value is enforced using Redis, making it safe to use across distributed systems.
+
+### `X-Cache-TTL` — Enable caching for a request
+
+To enable caching for a specific request, include the header:
+
+```text
+X-Cache-TTL: <seconds>
+```
+
+Example:
+
+```python
+response = await client.get(
+    "/users",
+    headers={"X-Cache-TTL": "60"},  # cache this endpoint for 60 seconds
+)
+```
+
+If this header is present and Redis is configured, the response will be cached for the specified duration.
+
+## Usage
+
+### Basic Example
+
+```python
+from aiohttpx.client import AioHTTPXClient
+
+class TwitchAPIClient(AioHTTPXClient):
+    def __init__(
+        self,
+        redis_url: str,
+        client_id: str,
+        client_secret: str,
+        redirect_uri: str,
+    ):
+        self.base_uri = 'https://api.twitch.tv/helix'
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.redirect_uri = redirect_uri
+
+        super().__init__(
+            base_url=self.base_uri,
+            headers={'Client-Id': self.client_id},
+            redis_url=redis_url,
+            key='twitch',      # Redis prefix
+            limit=10,          # 10 requests per second
+            logger='Twitch API',
+        )
+
+    async def test_endpoint(self):
+        ...
+```
+
+## Linting and Pre-commit Checks
+
+This project uses `pre-commit` and `ruff` for linting and formatting.
+Run the linting process with:
+
+```bash
+poe lint
+```
+
+## License
+
+This project is licensed under the MIT License.
+See `LICENSE` for details.