diff --git a/README.md b/README.md
new file mode 100644
--- /dev/null
+++ b/README.md
@@ -0,0 +1,22 @@
+[![Build Status](https://travis-ci.org/Noeda/bet.svg?branch=master)](https://travis-ci.org/Noeda/bet)
+
+This library contains Haskell bindings to the Betfair API.
+
+<https://developer.betfair.com/default/api-s-and-services/sports-api/sports-overview/>
+
+At the moment, the 'Betting API' and 'Heartbeat API' is implemented.
+The 'Accounts API' is not.
+
+See "Network.Betfair".
+
+CAUTION: These are experimental bindings. Because of the financially
+dangerous nature of betting, I advice you to have a contingency plan if
+something in the library breaks down.
+
+In particular, check the Betfair API documentation page for which version
+it is at the moment. This library is written against version 2.0 exactly.
+
+This library enforces limits on the number of calls you can do to Betfair
+API in a second, to help you avoid data charges. See
+"Network.Betfair.Unsafe".
+
diff --git a/bet.cabal b/bet.cabal
--- a/bet.cabal
+++ b/bet.cabal
@@ -1,5 +1,5 @@
 name:                bet
-version:             0.1.1.0
+version:             0.1.2.0
 synopsis:            Betfair API bindings. Bet on sports on betting exchanges.
 description:
     This library contains Haskell bindings to the Betfair API.
@@ -31,6 +31,7 @@
 build-type:          Simple
 stability:           experimental
 cabal-version:       >=1.10
+extra-source-files:  README.md
 
 flag toys
   description:         Build toys; to test if things work
diff --git a/src/Network/Betfair.hs b/src/Network/Betfair.hs
--- a/src/Network/Betfair.hs
+++ b/src/Network/Betfair.hs
@@ -28,6 +28,35 @@
 -- Use `request` to make calls to Betfair. Look at "Network.Betfair.Types" for
 -- commands to use with `request`.
 --
+-- == Examples
+--
+-- This example opens a connection to Betfair and lists all your current bets.
+--
+-- @
+--    {-\# LANGUAGE OverloadedStrings \#-}
+--
+--    import Network.Betfair
+--
+--    -- Use your actual credentials here. You need to see Betfair
+--    -- documentation about that
+--    credentials :: Credentials
+--    credentials = {
+--          _username = "Mr. Example"
+--        , _password = "supersecret"
+--        , _certificatePrivateKeyFile = "ssl/supersecret-client.key"
+--        , _certificateCertificateFile = "ssl/supersecret-client.crt"
+--        , _apiKey = "abcde12345"
+--        }
+--
+--    main = do
+--        bf <- openBetfair credentials
+--        -- Many request types have a default (so you can use 'default'
+--        -- function) but if they don't, you can check Network.Betfair.Types
+--        -- module for the all the data types you can use in request.
+--        results <- request (default { lcoOrderBy = Just ByMatchTime } :: ListCurrentOrders)
+--        print results
+--
+-- @
 
 module Network.Betfair
     (
diff --git a/src/Network/Betfair/Unsafe.hs b/src/Network/Betfair/Unsafe.hs
--- a/src/Network/Betfair/Unsafe.hs
+++ b/src/Network/Betfair/Unsafe.hs
@@ -30,6 +30,6 @@
     | otherwise = atomicModifyIORef' rateLimit $ \_ -> ( nor, () )
 
 -- | Returns the current global rate limit.
-getAPIRateLimit :: IO Double
+getAPIRateLimit :: IO NumberOfRequests
 getAPIRateLimit = readIORef rateLimit