diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000000000000000000000000000000000000..cd7436bb9b1d8e3085e2127c8bdfd8d327c18b6f
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,34 @@
+oxrlib
+======
+
+Introduction
+------------
+
+oxrlib provides a Python library and CLI tool to query the `Open Exchange Rates API <https://openexchangerates.org/>`_.  It emphasizes support for rich data types throughout, and supports caching API results to the filesystem.
+
+It currently only supports OXR's "historical" API.
+
+Getting started with the CLI tool
+---------------------------------
+
+oxrlib includes an `oxrquery` tool to access the OXR API directly from the command line.  By default, it reads your OXR credentials and other common configuration from `~/.config/oxrlib.ini`.  Copy `oxrlib_example.ini` from the source to `~/.config/oxrlib.ini`, then edit that file following the instructions in the comments.
+
+Run `oxrquery --help` for instructions to use the tool.
+
+Getting started with the library
+--------------------------------
+
+Here's an example of using the Python library, complete with caching results:
+
+  from oxrlib import cache, loaders, rate
+
+  filename_format = '{date}_{base}_rates.json'
+  cache_writer = cache.CacheWriter(DIR_PATH, historical=filename_format)
+  loader = loaders.LoaderChain()
+  loader.add_loader(loaders.FileCache(DIR_PATH, historical=filename_format))
+  loader.add_loader(loaders.OXRAPIRequest(APP_ID_STRING))
+  with loader.historical(DATE, BASE_CODE_STRING) as json_response:
+      hist_rate = rate.Rate.from_json_file(json_response)
+  if loader.should_cache():
+      cache_writer.save_rate(hist_rate)
+  # Rates are available from the hist_rates.rates dict.
diff --git a/oxrlib_example.ini b/oxrlib_example.ini
new file mode 100644
index 0000000000000000000000000000000000000000..7bf1fedc5f1bd26a464cb8d505b070c168ca19ac
--- /dev/null
+++ b/oxrlib_example.ini
@@ -0,0 +1,25 @@
+[OXR]
+# This section includes settings to query the Open Exchange Rates API directly.
+
+# An App ID provided by OXR.
+app_id = abcd1234...
+
+[Cache]
+# This optional section includes settings to read and write a cache of API
+# results on the filesystem.  If you omit these settings, results won't be
+# cached.
+
+# The directory to save cache files under.  This directory must already exist.
+directory = /home/YOU/.cache/oxrlib
+
+# Save data from the historical API using this filename pattern.
+# The pattern must include `{date}` and `{base}`, where API parameters are
+# filled in.
+historical = {date}_{base}_rates.json
+
+[Historical]
+# This optional section can specify default parameters for historical API calls.
+
+# Set the base currency.
+# Note that setting a base other than USD requires a paid OXR account.
+base = USD