diff --git a/rpc/core/README.md b/rpc/core/README.md
new file mode 100644
index 000000000..7dff4dfca
--- /dev/null
+++ b/rpc/core/README.md
@@ -0,0 +1,15 @@
+# Tendermint RPC
+
+## Generate markdown for [Slate](https://github.com/tendermint/slate)
+
+We are using [Slate](https://github.com/lord/slate) to power our RPC
+documentation. If you are changing a comment, make sure to copy the resulting
+changes to the slate repo and make a PR
+[there](https://github.com/tendermint/slate) as well. For generating markdown
+use:
+
+```shell
+go get github.com/melekes/godoc2md
+
+godoc2md -template rpc/core/doc_template.txt github.com/tendermint/tendermint/rpc/core | grep -v -e "pipe.go" -e "routes.go" -e "dev.go" | sed 's$/src/target$https://github.com/tendermint/tendermint/tree/master/rpc/core$'
+```
diff --git a/rpc/core/doc.go b/rpc/core/doc.go
new file mode 100644
index 000000000..7902ade25
--- /dev/null
+++ b/rpc/core/doc.go
@@ -0,0 +1,107 @@
+/*
+# Introduction
+
+Tendermint supports the following RPC protocols:
+
+* URI over HTTP
+* JSONRPC over HTTP
+* JSONRPC over websockets
+
+Tendermint RPC is build using [our own RPC library](https://github.com/tendermint/tendermint/tree/master/rpc/lib). Documentation and tests for that library could be found at `tendermint/rpc/lib` directory.
+
+## Configuration
+
+Set the `laddr` config parameter under `[rpc]` table in the `$TMHOME/config.toml` file or the `--rpc.laddr` command-line flag to the desired protocol://host:port setting.  Default: `tcp://0.0.0.0:46657`.
+
+## Arguments
+
+Arguments which expect strings or byte arrays may be passed as quoted strings, like `"abc"` or as `0x`-prefixed strings, like `0x616263`.
+
+## URI/HTTP
+
+```bash
+curl 'localhost:46657/broadcast_tx_sync?tx="abc"'
+```
+
+> Response:
+
+```json
+{
+	"error": "",
+	"result": {
+		"hash": "2B8EC32BA2579B3B8606E42C06DE2F7AFA2556EF",
+		"log": "",
+		"data": "",
+		"code": 0
+	},
+	"id": "",
+	"jsonrpc": "2.0"
+}
+```
+
+The first entry in the result-array (`96`) is the method this response correlates with. `96` refers to "ResultTypeBroadcastTx", see [responses.go](https://github.com/tendermint/tendermint/blob/master/rpc/core/types/responses.go) for a complete overview.
+
+## JSONRPC/HTTP
+
+JSONRPC requests can be POST'd to the root RPC endpoint via HTTP (e.g. `http://localhost:46657/`).
+
+```json
+{
+	"method": "broadcast_tx_sync",
+	"jsonrpc": "2.0",
+	"params": [ "abc" ],
+	"id": "dontcare"
+}
+```
+
+## JSONRPC/websockets
+
+JSONRPC requests can be made via websocket. The websocket endpoint is at `/websocket`, e.g. `localhost:46657/websocket`.  Asynchronous RPC functions like event `subscribe` and `unsubscribe` are only available via websockets.
+
+
+## More Examples
+
+See the various bash tests using curl in `test/`, and examples using the `Go` API in `rpc/client/`.
+
+## Get the list
+
+An HTTP Get request to the root RPC endpoint shows a list of available endpoints.
+
+```bash
+curl 'localhost:46657'
+```
+
+> Response:
+
+```plain
+Available endpoints:
+/abci_info
+/dump_consensus_state
+/genesis
+/net_info
+/num_unconfirmed_txs
+/status
+/unconfirmed_txs
+/unsafe_flush_mempool
+/unsafe_stop_cpu_profiler
+/validators
+
+Endpoints that require arguments:
+/abci_query?path=_&data=_&prove=_
+/block?height=_
+/blockchain?minHeight=_&maxHeight=_
+/broadcast_tx_async?tx=_
+/broadcast_tx_commit?tx=_
+/broadcast_tx_sync?tx=_
+/commit?height=_
+/dial_seeds?seeds=_
+/subscribe?event=_
+/tx?hash=_&prove=_
+/unsafe_start_cpu_profiler?filename=_
+/unsafe_write_heap_profile?filename=_
+/unsubscribe?event=_
+```
+
+# Endpoints
+*/
+package core
diff --git a/rpc/core/doc_template.txt b/rpc/core/doc_template.txt
new file mode 100644
index 000000000..896d0c271
--- /dev/null
+++ b/rpc/core/doc_template.txt
@@ -0,0 +1,8 @@
+{{with .PDoc}}
+{{comment_md .Doc}}
+{{example_html $ ""}}
+
+{{range .Funcs}}{{$name_html := html .Name}}## [{{$name_html}}]({{posLink_url $ .Decl}})
+{{comment_md .Doc}}{{end}}
+{{end}}
+---