diff --git a/auction/README.md b/auction/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..d80f59e087cef8315d3453a6f5b0f304f0708a49
--- /dev/null
+++ b/auction/README.md
@@ -0,0 +1,5 @@
+# Auction module
+
+### Overview
+
+Auction module provides a way to open auction and place bids on-chain. You can open an auction by specifying a `start: BlockNumber` and/or an `end: BlockNumber`, and when the auction becomes active enabling anyone to place a bid at a higher price. Trait `AuctionHandler` is been used to validate the bid and when the auction ends `AuctionHandle::on_auction_ended(id, bid)` gets called.
diff --git a/oracle/README.md b/oracle/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..a63e569ab3c6e23d53dc3aeeacdfebfeabf7860d
--- /dev/null
+++ b/oracle/README.md
@@ -0,0 +1,12 @@
+# Oracle module
+
+### Overview
+
+Oracle module can be used to feed the system with off-chain data. e.g. a bot can query off-chain data from other sources and submit it into on-chain storage by calling oracle module.
+
+It uses a trait called `OperatorProvider::can_feed_data(who)` to ensure someone have permission to submit data otherwise it will fail with error `NoPermission`.
+You can only submit updates once per block otherwise oracle will call `OnRedundantCall::multiple_calls_per_block(&who)` and fail with error `UpdateAlreadyDispatched`. The trait `OnRedundantCall` can be implemented to slash those who don't play by the roles, by default it does nothing.
+
+Oracle module provides 2 public methods to submit data. Method `feed_value` is used to provide a single update and `feed_values` for batch updates. Keep in mind that you can call only one of them per block otherwise it will be a redundant call and fail. Both those methods are weight zero and dispatch class operational with a high priority, which means they can be misused to DoS the system, so be careful who you allow to call them and make sure to use `CheckOperator` to prevent multiple calls per block.
+
+Module provides additional methods to read raw or combined data. `CombineData` provides a default implementation which finds a median from an array of valid values, but you can provide a custom implementation as well.
diff --git a/prices/README.md b/prices/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..d529325f8cb130658aef90ce7d9d4bba6e4e0c82
--- /dev/null
+++ b/prices/README.md
@@ -0,0 +1,6 @@
+# Prices module
+
+### Overview
+
+This module is been used to get the prices from a source `DataProvider` i.e. Oracle module, and calculate the price for a given `CurrencyId` pair.
+`fn get_price(base_currency_id: CurrencyId, quote_currency_id: CurrencyId) -> Option<Price>`