diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0454786
--- /dev/null
+++ b/README.md
@@ -0,0 +1,85 @@
+# StackIt Smart Contracts
+
+Open-source smart contracts powering the StackIt treasury and liquidation protection system on Arbitrum.
+
+---
+
+## Contracts
+
+### `Stack.sol`
+The main registry contract. Creates and tracks user wallets, manages token allowlists, and controls the system's swapper and pool addresses.
+
+- Deploys a new `Wallet` proxy for each user
+- Maintains the list of supported tokens (BTC, ETH, USDC)
+- Controls access roles (owner, operators)
+
+### `Wallet.sol`
+A minimal proxy contract created per user. Delegates all logic calls to `WalletImplementation.sol`. Each user owns exactly one wallet — nobody else can touch it.
+
+### `WalletImplementation.sol`
+The core logic contract. Handles all treasury operations:
+
+- **Deposit** — accepts USDC and allocates to BTC/ETH via Aave
+- **Borrow** — borrows USDC against BTC/ETH collateral, enforcing LTV safety limits
+- **Repay** — repays outstanding debt to restore health factor
+- **Liquidation protection** — automatically repays debt using collateral when health factor approaches unsafe levels, using flash loans to re-leverage as markets recover
+
+**Key on-chain safety rules enforced by this contract:**
+- Health factor cannot drop below the configured minimum after a borrow
+- Per-transaction and daily borrow caps enforced on-chain
+- Nonce replay prevention — transactions cannot be replayed
+- Cooldown period between executions
+- Only the wallet owner can authorize transactions — StackIt never holds or controls user keys
+
+---
+
+## Architecture
+
+```
+User Wallet (EOA)
+    │
+    └── Wallet.sol (proxy, per user)
+            │
+            └── WalletImplementation.sol (logic)
+                    │
+                    ├── Aave (lending/borrowing)
+                    ├── Uniswap V2 (swaps)
+                    └── Stack.sol (registry + access control)
+```
+
+**Custody model:** StackIt uses a wallet-sovereign architecture. The system constructs and simulates transactions, but returns them **unsigned** to the user (or agent). The user signs and submits. StackIt never holds private keys.
+
+---
+
+## Deployment
+
+Deployed on **Arbitrum One**.
+
+| Contract | Address |
+|----------|---------|
+| Stack.sol | *(add Arbiscan link)* |
+| WalletImplementation.sol | *(add Arbiscan link)* |
+
+---
+
+## Open Source Scope
+
+The smart contracts — where your funds actually move — are fully open source and auditable here.
+
+The liquidation protection rules engine and backend orchestration are proprietary. This is by design: the on-chain contracts are the trust layer. You can verify that your funds only move with your wallet's authorization, health factor limits are enforced on-chain, and no transaction can be replayed or front-run by the system.
+
+---
+
+## Development
+
+```bash
+yarn install
+yarn hardhat compile
+yarn hardhat test
+```
+
+---
+
+## License
+
+GPL-3.0