Update README.md

Author: ford26321works003

README.md

@@ -1,2 +1,161 @@
 # sora2API
 SORA v2 API Wrapper — Python interface for the SORA decentralized economy platform, providing balance queries, token swaps via Polkaswap DEX, liquidity pool inspection, and network status monitoring
+<div align="center">
+
+# SORA v2 API Wrapper
+
+[![Python](https://img.shields.io/badge/Python-3.9+-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/)
+[![License](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](LICENSE)
+[![SORA](https://img.shields.io/badge/SORA-v2-e6007a?style=for-the-badge)](https://sora.org/)
+[![Polkaswap](https://img.shields.io/badge/Polkaswap-DEX-e6007a?style=for-the-badge)](https://polkaswap.io/)
+
+**Python interface for the SORA v2 decentralized economy platform — balance queries, token swaps, liquidity pools, and network monitoring.**
+
+[Features](#features) · [Getting Started](#getting-started) · [Configuration](#configuration) · [Architecture](#architecture)
+
+</div>
+
+---
+
+## Overview
+
+SORA v2 is a decentralized economic system built on Substrate, featuring:
+
+- **Polkaswap DEX** — a non-custodial decentralized exchange with multiple liquidity sources (XYK pools, multi-collateral bonding curve, order book)
+- **XOR** — the native utility and governance token with a token bonding curve supply mechanism
+- **VAL** — validator reward token for SORA network validators
+- **PSWAP** — liquidity provision incentive token
+
+This wrapper provides a Python API client and interactive TUI for querying balances, executing swaps, inspecting liquidity pools, and monitoring network state.
+
+---
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| Balance queries | Fetch asset balances for any SORA account |
+| Token swaps | Get quotes and execute swaps via Polkaswap DEX |
+| Liquidity pools | List pools with reserve and liquidity data |
+| Network info | Chain metadata, block height, peer count |
+| Well-known assets | Built-in resolution for XOR, VAL, PSWAP, DAI, ETH, XSTUSD |
+| Multi-source routing | XYK Pool and bonding curve routing support |
+| Data models | Typed dataclasses for assets, pools, quotes, results |
+| Rich TUI | Interactive terminal menu for all operations |
+| Configurable | JSON config with interactive setup wizard |
+
+---
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.9+
+- Network access to a SORA node or API endpoint
+
+### Installation
+
+```bash
+git clone https://github.com/example/sora2api-wrapper.git
+cd sora2api-wrapper
+
+pip install -r requirements.txt
+
+python main.py
+```
+
+### Quick Setup
+
+1. Run `python main.py` and select **Install dependencies**
+2. Select **Configure API** to set endpoint URLs
+3. Use **Query balances** to check account holdings
+4. Use **Swap tokens** to get quotes and execute trades
+5. Use **Liquidity pools** to browse available pools
+
+---
+
+## Configuration
+
+Configuration is stored in `config.json`. Edit directly or use the interactive setup.
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `api_url` | `https://mof.sora.org` | SORA REST API base URL |
+| `substrate_url` | `wss://mof2.sora.org` | Substrate WebSocket endpoint |
+| `network` | `mainnet` | Network (mainnet or testnet) |
+| `default_dex_id` | `0` | Default DEX ID for Polkaswap |
+| `timeout` | `30` | Request timeout in seconds |
+
+---
+
+## Architecture
+
+```
+sora2api/
+├── main.py              # TUI entry point (Rich-based menu)
+├── client.py            # SORA API client (balances, swaps, pools, network)
+├── config.py            # Configuration load/save/interactive setup
+├── models.py            # Data models (Asset, Pool, SwapQuote, SwapResult, etc.)
+├── config.json          # Runtime configuration
+├── requirements.txt     # Python dependencies
+└── README.md
+```
+
+### API Client
+
+The `SoraClient` class handles all communication with the SORA network API:
+
+- **Balance queries** via `/accounts/{address}/balances`
+- **Swap quotes** via `/dex/quote` with configurable liquidity sources
+- **Swap execution** via `/dex/swap` with slippage tolerance
+- **Pool listing** via `/dex/pools`
+- **Network info** via `/network/info`
+
+### Data Models
+
+All API responses are mapped to typed Python dataclasses:
+
+- `Asset` — registered token with ID, symbol, precision
+- `Pool` — liquidity pool with reserves and fee data
+- `SwapQuote` — price quote with route and impact information
+- `SwapResult` — executed swap with transaction hash and status
+- `AccountBalance` — per-asset balance breakdown (free, reserved, frozen)
+- `NetworkInfo` — chain state snapshot
+
+---
+
+## Well-Known Assets
+
+| Symbol | Description |
+|--------|-------------|
+| XOR | Native utility token, bonding curve supply |
+| VAL | Validator reward token |
+| PSWAP | Polkaswap liquidity incentive token |
+| DAI | Bridged MakerDAO stablecoin |
+| ETH | Bridged Ether |
+| XSTUSD | SORA synthetic USD stablecoin |
+
+---
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `rich` | Terminal UI, tables, panels, prompts |
+| `requests` | HTTP client for REST API calls |
+| `websockets` | WebSocket connection to Substrate nodes |
+| `substrate-interface` | Substrate RPC and storage queries |
+
+---
+
+## Disclaimer
+
+This tool is provided for **informational and development purposes**. Always verify swap parameters and slippage settings before executing trades. The authors accept no responsibility for financial losses from incorrect usage or API changes.
+
+---
+
+<div align="center">
+
+**MIT License** · Contributions welcome
+
+</div>