diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a111351
--- /dev/null
+++ b/README.md
@@ -0,0 +1,26 @@
+[![status-badge](https://ci.batsense.net/api/badges/107/status.svg)](https://ci.batsense.net/repos/107)
+
+---
+
+# mcaptcha-api-rs: Library to interact with with mCaptcha API
+
+This library provides a convenient interface to validate [mCaptcha authorization
+tokens](https://mcaptcha.org/docs/webmasters/terminology#authorization-token) presented by
+Visitors against your mCaptcha instances. It uses [reqwest](https://crates.io/crates/reqwest),
+and `native-tls` under the hood to communicate with the API.
+
+## Install
+
+```bash
+cargo add mcaptcha-api-rs
+```
+
+## Example
+
+```rust,no_run
+use url::Url;
+use mcaptcha_api_rs::MCaptcha;
+
+let mcaptcha = MCaptcha::new("sitekeyfromdashboard", "secretfromdashboadr", Url::parse("https://mcaptcha.example.com").unwrap());
+assert!(mcaptcha.verify("authorizationtokenfromvisitor").await.unwrap());
+```
diff --git a/src/lib.rs b/src/lib.rs
index 82e3b0b..8373603 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,7 +1,14 @@
+//! # mcaptcha-api-rs: Library to interact with with mCaptcha API
+//! 
+//! This library provides a convenient interface to validate [mCaptcha authorization
+//! tokens](https://mcaptcha.org/docs/webmasters/terminology#authorization-token) presented by
+//! Visitors against your mCaptcha instances. It uses [reqwest](https://crates.io/crates/reqwest),
+//! and `native-tls` under the hood to communicate with the API.
 use reqwest::Client;
 use serde::{Deserialize, Serialize};
 use url::Url;
 
+/// API Client class
 pub struct MCaptcha {
     client: Client,
     sitekey: String,
@@ -10,6 +17,21 @@ pub struct MCaptcha {
 }
 
 impl MCaptcha {
+    /// Create new instance of API client
+    ///
+    /// Parameters:
+    /// - [`sitekey`](https://mcaptcha.org/docs/webmasters/terminology#sitekey):  unique identifier of
+    /// captcha configuration. Available on mCaptcha dashboard. 
+    /// - `account_secret`: used for authentication. Available on the settings page of mCaptcha dashboard
+    /// - `instance_url`: the URL of your mCaptcha instance
+    ///
+    ///
+    /// ```rust
+    /// use url::Url;
+    /// use mcaptcha_api_rs::MCaptcha;
+    ///
+    /// let mcaptcha = MCaptcha::new("sitekeyfromdashboard", "secretfromdashboadr", Url::parse("https://mcaptcha.example.com").unwrap());
+    /// ```
     pub fn new(sitekey: String, account_secret: String, instance_url: Url) -> Self {
         let mut verify_path = instance_url.clone();
         verify_path.set_path("/api/v1/pow/siteverify");
@@ -21,6 +43,16 @@ impl MCaptcha {
         }
     }
 
+    /// Verify authorization token presented by visitor against mCaptcha server
+    ///
+    ///
+    /// ```rust,no_run
+    /// use url::Url;
+    /// use mcaptcha_api_rs::MCaptcha;
+    ///
+    /// let mcaptcha = MCaptcha::new("sitekeyfromdashboard", "secretfromdashboadr", Url::parse("https://mcaptcha.example.com").unwrap());
+    /// assert!(mcaptcha.verify("authorizationtokenfromvisitor").await.unwrap());
+    /// ```
     pub async fn verify(&self, token: &str) -> Result<bool, reqwest::Error> {
         let payload = CaptchaVerfiyPayload::from_ctx(self, token);
         let res: CaptchaVerifyResp = self