diff --git a/API/swarm/README.md b/API/swarm/README.md
new file mode 100644
index 00000000..9def0edc
--- /dev/null
+++ b/API/swarm/README.md
@@ -0,0 +1,144 @@
+Swarm API
+=========
+
+#### `addrs`
+
+> List of known addresses of each peer connected.
+
+##### `Go` **WIP**
+
+##### `JavaScript` - ipfs.swarm.addrs([callback])
+
+`callback` must follow `function (err, addrs) {}` signature, where `err` is an error if the operation was not successful. `addrs` will be an array of multiaddrs.
+
+If no `callback` is passed, a promise is returned.
+
+Example:
+
+```JavaScript
+ipfs.swarm.addrs(function (err, addrs) {})
+```
+
+#### `connect`
+
+> Open a connection to a given address.
+
+##### `Go` **WIP**
+
+##### `JavaScript` - ipfs.swarm.connect(addr, [callback])
+
+Where `addr` is of type [multiaddr](https://github.com/multiformats/js-multiaddr)
+
+`callback` must follow `function (err, res) {}` signature, where `err` is an error if the operation was not successful. 
+
+If no `callback` is passed, a promise is returned.
+
+Example:
+
+```JavaScript
+ipfs.swarm.connect(addr, function (err) {
+  // if no err is present, connection is now open
+})
+```
+
+#### `disconnect`
+
+> Close a connection on a given address.
+
+##### `Go` **WIP**
+
+##### `JavaScript` - ipfs.swarm.disconnect(addr, [callback])
+
+Where `addr` is of type [multiaddr](https://github.com/multiformats/js-multiaddr)
+
+`callback` must follow `function (err) {}` signature, where `err` is an error if the operation was not successful. 
+
+If no `callback` is passed, a promise is returned.
+
+Example:
+
+```JavaScript
+ipfs.swarm.disconnect(addr, function (err) {})
+```
+
+#### `peers`
+
+> List out the peers that we have connections with.
+
+##### `Go` **WIP**
+
+##### `JavaScript` - ipfs.swarm.peers([callback])
+
+`callback` must follow `function (err, peerInfos) {}` signature, where `err` is an error if the operation was not successful. `peerInfos` will be an array of [PeerInfo]().
+
+If no `callback` is passed, a promise is returned.
+
+Example:
+
+```JavaScript
+ipfs.swarm.peers(function (err, peerInfos) {})
+```
+
+------------------------------
+
+> NOT IMPLEMENTED YET
+
+#### `filters`
+
+> Display current multiaddr filters. Filters are a way to set up rules for the network connections established.
+
+##### `Go` **WIP**
+
+##### `JavaScript` - ipfs.swarm.filters([callback])
+
+`callback` must follow `function (err, filters) {}` signature, where `err` is an error if the operation was not successful. `filters` is an array of multiaddrs that represent the filters being applied.
+
+If no `callback` is passed, a promise is returned.
+
+Example:
+
+```JavaScript
+ipfs.swarm.filters(function (err, filters) {})
+```
+
+#### `filters.add`
+
+> Add another filter.
+
+##### `Go` **WIP**
+
+##### `JavaScript` - ipfs.swarm.filters.add(filter, [callback])
+
+Where `filter` is of type [multiaddr]()
+
+`callback` must follow `function (err) {}` signature, where `err` is an error if the operation was not successful. 
+
+If no `callback` is passed, a promise is returned.
+
+Example:
+
+```JavaScript
+ipfs.swarm.filters.add(filter, function (err) {})
+```
+
+#### `filters.rm`
+
+> Remove a filter
+
+##### `Go` **WIP**
+
+##### `JavaScript` - ipfs.swarm.filters.rm(filter, [callback])
+
+Where `filter` is of type [multiaddr]()
+
+`callback` must follow `function (err, res) {}` signature, where `err` is an error if the operation was not successful. `res` will be an array of:
+
+If no `callback` is passed, a promise is returned.
+
+Example:
+
+```JavaScript
+ipfs.swarm.filters.rm(filter, function (err) {})
+```
+
+
diff --git a/package.json b/package.json
index f11947b3..9bf33e7a 100644
--- a/package.json
+++ b/package.json
@@ -34,7 +34,8 @@
     "concat-stream": "^1.5.1",
     "detect-node": "^2.0.3",
     "ipfs-merkle-dag": "^0.6.2",
-    "readable-stream": "1.1.13"
+    "readable-stream": "1.1.13",
+    "run-series": "^1.1.4"
   },
   "devDependencies": {
     "aegir": "^6.0.0"
@@ -47,4 +48,4 @@
     "greenkeeperio-bot <support@greenkeeper.io>",
     "nginnever <ginneversource@gmail.com>"
   ]
-}
\ No newline at end of file
+}
diff --git a/src/index.js b/src/index.js
index 62cfa057..f9ad0c53 100644
--- a/src/index.js
+++ b/src/index.js
@@ -5,3 +5,4 @@ exports.files = require('./files')
 exports.config = require('./config')
 exports.pin = require('./pin')
 exports.generic = require('./generic')
+exports.swarm = require('./swarm')
diff --git a/src/swarm.js b/src/swarm.js
new file mode 100644
index 00000000..aab7b16a
--- /dev/null
+++ b/src/swarm.js
@@ -0,0 +1,123 @@
+/* eslint-env mocha */
+/* eslint max-nested-callbacks: ["error", 8] */
+
+'use strict'
+
+const expect = require('chai').expect
+const series = require('run-series')
+
+module.exports = (common) => {
+  describe('.swarm', () => {
+    let ipfsA
+    let ipfsB
+
+    before(function (done) {
+      // CI takes longer to instantiate the daemon,
+      // so we need to increase the timeout for the
+      // before step
+      this.timeout(20 * 1000)
+
+      common.setup((err, factory) => {
+        expect(err).to.not.exist
+        series([
+          (cb) => {
+            factory.spawnNode((err, node) => {
+              expect(err).to.not.exist
+              ipfsA = node
+              cb()
+            })
+          },
+          (cb) => {
+            factory.spawnNode((err, node) => {
+              expect(err).to.not.exist
+              ipfsB = node
+              cb()
+            })
+          }
+        ], done)
+      })
+    })
+
+    after((done) => {
+      common.teardown(done)
+    })
+
+    describe('callback API', () => {
+      it('.connect', (done) => {
+        ipfsB.id((err, id) => {
+          expect(err).to.not.exist
+          const ipfsBAddr = id.addresses[0]
+          ipfsA.swarm.connect(ipfsBAddr, done)
+        })
+      })
+
+      it('.peers', (done) => {
+        ipfsA.swarm.peers((err, multiaddrs) => {
+          expect(err).to.not.exist
+          expect(multiaddrs).to.have.length.above(0)
+          done()
+        })
+      })
+
+      it('.addrs', (done) => {
+        ipfsA.swarm.addrs((err, multiaddrs) => {
+          expect(err).to.not.exist
+          expect(multiaddrs).to.have.length.above(0)
+          done()
+        })
+      })
+
+      it('.localAddrs', (done) => {
+        ipfsA.swarm.localAddrs((err, multiaddrs) => {
+          expect(err).to.not.exist
+          expect(multiaddrs).to.have.length.above(0)
+          done()
+        })
+      })
+
+      it('.disconnect', (done) => {
+        ipfsB.id((err, id) => {
+          expect(err).to.not.exist
+          const ipfsBAddr = id.addresses[0]
+          ipfsA.swarm.disconnect(ipfsBAddr, done)
+        })
+      })
+    })
+
+    describe('promise API', () => {
+      it('.connect', () => {
+        return ipfsB.id()
+          .then((id) => {
+            const ipfsBAddr = id.addresses[0]
+            return ipfsA.swarm.connect(ipfsBAddr)
+          })
+      })
+
+      it('.peers', () => {
+        return ipfsA.swarm.peers().then((multiaddrs) => {
+          expect(multiaddrs).to.have.length.above(0)
+        })
+      })
+
+      it('.addrs', () => {
+        return ipfsA.swarm.addrs().then((multiaddrs) => {
+          expect(multiaddrs).to.have.length.above(0)
+        })
+      })
+
+      it('.localAddrs', () => {
+        return ipfsA.swarm.localAddrs().then((multiaddrs) => {
+          expect(multiaddrs).to.have.length.above(0)
+        })
+      })
+
+      it('.disconnect', () => {
+        return ipfsB.id()
+          .then((id) => {
+            const ipfsBAddr = id.addresses[0]
+            return ipfsA.swarm.disconnect(ipfsBAddr)
+          })
+      })
+    })
+  })
+}