diff --git a/docs/web3-eth-net.rst b/docs/web3-eth-net.rst
index 627f966560b..67be0dda87b 100644
--- a/docs/web3-eth-net.rst
+++ b/docs/web3-eth-net.rst
@@ -25,7 +25,7 @@ getNetworkType
 
 Guesses the chain the node is connected by comparing the genesis hashes.
 
-.. note:: This is not a 100% accurate guess as any private network could use testnet and mainnet genesis blocks and network IDs.
+.. note:: It's recommended to use the :ref:`web3.eth.getChainId <eth-chainId>` method to detect the currently connected chain.
 
 -------
 Returns
diff --git a/docs/web3-eth.rst b/docs/web3-eth.rst
index 8b7f9fd3bd4..6b86ab07ffe 100644
--- a/docs/web3-eth.rst
+++ b/docs/web3-eth.rst
@@ -1467,3 +1467,31 @@ Example
 
 
 ------------------------------------------------------------------------------
+
+.. _eth-chainId:
+
+getChainId
+==========
+
+.. code-block:: javascript
+
+    web3.eth.getChainId([callback])
+
+Returns the chain ID of the current connected node as described in the `EIP-695 <https://github.com/ethereum/EIPs/blob/master/EIPS/eip-695.md>`_.
+
+-------
+Returns
+-------
+
+``Promise<Number>`` - Returns chain ID.
+
+-------
+Example
+-------
+
+.. code-block:: javascript
+
+    web3.eth.getChainId().then(console.log);
+    > 61
+
+------------------------------------------------------------------------------