diff --git a/README.md b/README.md
index c51b9d1..3a72b32 100644
--- a/README.md
+++ b/README.md
@@ -1,61 +1,71 @@
-# HaloPay API
+
+HaloPay API
-The dedicated transaction settlement engine and anchor integration gateway for the HaloPay offline-first payment protocol.
+
+ The dedicated settlement backend for HaloPay — a self-custodied Point-of-Sale and merchant settlement protocol built for crisis zones and offline environments where traditional digital banking infrastructure does not exist.
+
-[](https://github.com/HaloPaye/halopay-api/actions)
-[](LICENSE)
-[](https://nodejs.org)
-[](https://www.typescriptlang.org)
+
+ 
+ 
+ 
+ 
+
---
-## Overview
+## Core Architecture
-HaloPay API serves as the high-throughput settlement backend connecting offline point-of-sale terminals, decentralized mesh relays, and on-chain liquidity rails. It bridges transactions conducted in network-constrained environments to digital asset settlement and local fiat off-ramping.
+1. **SEP-10 Web Authentication**: Standardized Stellar challenge-response flow issuing JWTs for secure merchant interactions.
+2. **SEP-12 KYC Ingestion**: Ingests merchant verification fields and binary government ID photos (`multipart/form-data`) to transmit to Stellar anchors (e.g. MoneyGram).
+3. **SEP-24 Fiat Off-Ramp Orchestration**: Programmatically converts aggregated USDC daily sales into local fiat via anchor off-ramp quotes and withdrawals.
+4. **On-Chain Webhook & WebSocket Broadcaster**: Listens to Stellar Horizon payment streams for incoming USDC aid payments and broadcasts instant payment confirmations to merchant POS devices over WebSockets.
-The backend orchestrates non-custodial merchant authentication, KYC identity ingestion for regulated off-ramps, automated quote locking, and resilient WebSocket event broadcasting for incoming payments.
-
----
-
-## System Architecture
+### Architecture Diagram
```mermaid
graph TD
- Client[HaloPay POS Client] -->|Authentication| API[HaloPay API]
- Relay[Mesh Gateway] -->|Batched Vouchers| API
- API -->|KYC & Off-Ramp| Anchor[Banking Anchor / MoneyGram]
- Horizon[Ledger RPC / Horizon] -->|Payment Stream| API
- API -->|WebSocket Confirmation| Client
+ Client[HaloPay POS Client] -->|SEP-10 Auth| API[HaloPay API]
+ API -->|KYC & Settlement| Anchor[Stellar Anchor / MoneyGram]
+ Horizon[Stellar Horizon] -->|Webhook| API
+ API -->|WebSocket| Client
```
-### Core Responsibilities
+### How the Settlement Engine Works
+
+The HaloPay backend is entirely focused on providing a seamless bridge between a merchant who may have intermittent connectivity and the robust Stellar on-chain ecosystem.
-1. **Cryptographic Session Authentication:** Verifies client challenge signatures to issue short-lived JWTs, ensuring the backend only processes actions authorized by valid account keys.
-2. **KYC Document Ingestion:** Handles secure `multipart/form-data` uploads for merchant identification files, validating MIME types and sizes before passing payloads to compliance partners.
-3. **Fiat Off-Ramp Orchestration:** Coordinates automated conversions from digital settlement balances (e.g. USDC) into local fiat currency bank transfers and mobile money payouts.
-4. **Resilient Event Streaming:** Maintains active event listeners on the settlement ledger, pushing real-time confirmation receipts to merchant terminals via WebSockets the instant connectivity is active.
-5. **Auditing & Telemetry:** Records tamper-evident cryptographic audit logs with SHA-256 hash chaining and exports Prometheus metrics for latency and throughput monitoring.
+1. **Authentication (SEP-10):** Merchants sign an authentication challenge using their private Stellar key. The API verifies this signature and issues a JWT. This ensures that the backend only orchestrates fiat withdrawals for verifiable wallet owners.
+2. **KYC Uploads (SEP-12):** To comply with local regulations and anchor requirements, merchants must upload their government ID. Since these files are often large binary images, the API implements a secure `multipart/form-data` ingestion route that validates file sizes and MIME types before forwarding the payload directly to a secure storage bucket and the Anchor.
+3. **Fiat Off-Ramp (SEP-24):** When a merchant chooses to settle their USDC balance to local fiat (e.g., to their bank account or mobile money wallet), the API initiates the SEP-24 interactive withdrawal flow with an anchor like MoneyGram, abstracting away the complex Stellar network fees and reserve requirements.
+4. **Resilient WebSocket Delivery:** Since POS terminals can drop connection at any time, the API maintains a constant listener on the Stellar Horizon network. When it detects a payment to a registered merchant, it broadcasts it. If the merchant reconnects later, the system will instantly push any missed payments so the UI always reflects the true ledger state.
---
-## Technology Stack
+## Stellar & Soroban Architecture Integration
-- **Runtime**: Node.js 20+ (TypeScript)
-- **Web Framework**: Express.js
-- **Settlement SDK**: `@stellar/stellar-sdk`
-- **Real-Time Layer**: `ws` (WebSockets)
-- **Data & Telemetry**: Winston, Prometheus, Zod
-- **Testing**: Jest, Supertest
+HaloPay API implements the gold standard for Stellar Ecosystem Proposals (SEPs) and Soroban RPC settlement:
+
+* **SEP-10 (Web Authentication):** Cryptographically binds merchant sessions using challenge-transaction signatures verified against Stellar Horizon.
+* **SEP-12 (KYC Client API):** Manages merchant customer identity data collection and secure forwarding to licensed Stellar anchors.
+* **SEP-24 (Hosted Deposit & Withdrawal):** Orchestrates interactive fiat off-ramping flows with global anchors (e.g., MoneyGram), turning digital USDC revenue into local physical cash.
+* **SEP-38 (Anchor RFQ Quotes):** Provides programmatic access to real-time indicative and firm price quotes between stellar assets and fiat currencies.
+* **Soroban RPC & Horizon Stream Listeners:** Real-time event streaming of payment ledger entries, broadcasting instant cryptographic confirmation to offline POS terminals the moment internet connectivity is restored.
---
-## Quick Start
+## Tech Stack
+
+- **Language**: TypeScript (Node.js 20+)
+- **Framework**: Express.js
+- **Blockchain Core**: `@stellar/stellar-sdk`
+- **File Ingestion**: `multer` (handling multipart binary government ID images)
+- **Real-Time Communication**: `ws` (WebSockets)
+- **Validation & Auth**: Zod, JSON Web Tokens
-### Prerequisites
-- Node.js v20 or higher
-- npm v9 or higher
+---
-### Installation & Local Run
+## Setup & Quick Start
```bash
# Clone the repository
@@ -65,32 +75,23 @@ cd halopay-api
# Install dependencies
npm install
-# Configure environment variables
-cp .env.example .env
-
-# Run development server with live reload
+# Run dev environment
npm run dev
-# Run comprehensive test suite
+# Run unit tests
npm test
-
-# Build for production
-npm run build
```
----
-
-## API Overview
+## Maintainers & Contact
-| Method | Endpoint | Description |
+| Maintainer | Contact / Telegram | Role |
| :--- | :--- | :--- |
-| `GET` | `/health` | Service liveness and dependency status |
-| `GET` | `/api/v1/auth/challenge` | Generate authentication challenge transaction |
-| `POST` | `/api/v1/auth/token` | Exchange signed challenge for session JWT |
-| `POST` | `/api/v1/kyc/customer` | Ingest merchant verification data and documents |
-| `POST` | `/api/v1/offramp/initiate` | Initiate interactive fiat withdrawal flow |
-| `GET` | `/api/v1/quotes` | Retrieve indicative and firm exchange rate quotes |
-| `WS` | `/events` | Real-time payment confirmation stream |
+| HaloPay Team | [@HaloPayDev](https://t.me/HaloPayDev) | Core Protocol Engineering |
+| Lead Engineer | security@halopay.io | Security & Operations |
+
+## Contributors
+
+[](https://github.com/HaloPaye/halopay-api/graphs/contributors)
---