Go to PolySwarm

Participating in the PolySwarm Marketplace

Once you've thoroughly tested your participant, you'll want to put it to work in the real PolySwarm marketplace!

At a high level, plugging into the PolySwarm marketplace is a simple matter of:

  1. determining which Community(ies) you'd like to join
  2. pointing your participants to the hosted instance of polyswarmd for those Communities

There are a few items to be aware of when doing this; we discuss below.

Wallets & Keyfiles

PolySwarm is built on top of Ethereum, a programmable world computer fueled by a native cryptocurrency called Ether (ETH). When an Ethereum user executes a transfer of ETH or conducts a call into an Ethereum "smart contract" (e.g. PolySwarm's Relay contracts), the user must pay the Ethereum network to carry out this transaction in the form of "Gas". Gas is deducted from the user's ETH balance.

PolySwarm operates on Nectar (NCT) - an application-layer cryptocurrency token built on top of Ethereum. NCT is essential for participating in the PolySwarm marketplace.

Your participant, acting as your representative on the PolySwarm marketplace, must have access to both ETH and NCT.

Cryptocurrency Wallets

As with all cryptocurrencies (e.g. Bitcoin), funds are maintained in "wallets". Technically, a wallet is simply a cryptographic keypair and some metadata that describes the keypairs' usage. Wallets are uniquely identified by a cryptographic hash of the public portion of this cryptographic keypair. Possession / control of a wallet (and all funds contained therein) is analogous to possession of the private portion of the wallet's keypair.

In PolySwarm, as with all cryptocurrency applications, an attacker with access to your wallet's private key can steal all your cryptocurrency (ETH & NCT) and impersonate you in the marketplace.

It is absolutely essential that you protect the secrecy of your wallet's private key.

Means to secure your private key are outside of the scope of this document. In order for your participant to participate in the PolySwarm marketplace (and place transactions on your behalf), your participant must have the ability to sign transactions with your wallet's private key. This means the participant must either have direct access to the key (less secure) or have the ability to request signatures of a device / process that has access to the key (more secure). The direct keyfile access method is supported by polyswarm-client today. Support for offloading transaction signing to another device will arrive in a future polyswarm-client release.

Wallet Usage in PolySwarm

During integration testing, we told our participants where to find a "keyfile" that contains our encrypted private key via the --keyfile argument to the polyswarm-client programs (i.e. microengine and balancemanager). All keyfiles distributed with polyswarm-client (and other PolySwarm projects) are encrypted with a trivial password: password, specified via the --password argument. The keyfile's path and password are stored in test-integration.yml.

Production / marketplace keyfiles must be treated differently than keyfile used for testing.

Never use any keyfile included in any public PolySwarm project (e.g. keyfile_microengine found in polyswarm-client) when connecting to the PolySwarm marketplace.

Never fund a wallet that may have had its private key disclosed to untrusted parties or devices. The aformentioned keyfiles in polyswarm-client certainly match this requirement; their private keys are available for all to see.

Wallets holding real NCT and/or ETH and are used when participating to the PolySwarm marketplace ("Production" or "Marketplace" wallets) must be securely generated and must be unique among participants.

Production wallets' private keys must be protected at rest and in use against external and insider threats.

The official Ethereum client (go-ethereum or geth for short) has instructions for securely generating a keyfile. See Managing your accounts in geth.

Follow this guide on a trustworthy device to create a new keyfile that you'll use to connect to the PolySwarm marketplace.

Funding Your Wallet

Once you've generated your own keyfile, you'll need to fund your wallet with ETH and NCT.

Generally, there are three funding avenues available:

  1. Purchase ETH and NCT on a cryptocurrency exchange and transfer them to the address corresponding to your participant's wallet. Methods to purchase & transfer cryptocurrencies are outside the scope of this document.
  2. Subscribe to PolySwarm Direct - an upcoming service with configurable auto-refills that ensure your participant is funded. This service is in development, stay tuned!
  3. Initial partners have received a NCT seedling in their production wallet per our published distribution schedule.

Finding Your Community(ies)

The PolySwarm marketplace is made up of a patchwork of Communities. Communities are groups of individuals and corporations that share a particular malware interest or mutually agree to maintain the confidentiality of artifacts exchanged within the Community.

Unless overridden, participants based on polyswarm-client will connect to the current default public community. To connect to a different community, use the --polyswarmd-addr argument or associated environment value to override this default.

The default public community is a "proving ground" of sorts for security experts to build a reputation via their participant(s). Once security experts build a reputation, they may want to engage in additional Communities.

As more communities come online, they'll appear in on the PolySwarm Communities page:

polyswarm-client based participants currently only support communicating with a single Community at a given time.

Support for multiple Communities will be included in a future release.

In the interim, please run a distinct instance of your participant (and supporting services like balancemanager) per Community.

Customize marketplace.env

We will customize your participant's docker/marketplace.env file and then use your participant's docker/marketplace.yml file to connect to the PolySwarm marketplace.

marketplace.yml and marketplace.env were added to participant-template on Oct 12th, 2019.

If your participant lacks these files, you will need to rebase your participant on a more recent participant-template.

marketplace.yml is responsible for launching everything you need to connect to the marketplace: your participant's frontend, redis middleware, worker backend and balancemanager. This YAML relies on values contained within marketplace.env, which we'll customize now.

marketplace.yml relies on marketplace.env for the following information:

  1. The in-container file path of your participant's marketplace keyfile.
  2. The password used to decrypt your participant's marketplace keyfile.
  3. A valid API key for the community you wish to join.


Place your newly generated production keyfile in a location that will be accessible to containers launched from your participant's Docker image. For simplicity, we'll assume you place this keyfile in the root of your participant's directory: /path/to/your/participant/production_keyfile.

Launch your favorite text editor and edit marketplace.env's KEYFILE= variable to point to the container-accessible path you chose for your participant's keyfile.

Variables in marketplace.env must not be enclosed in single or double quotations.

Do this: KEYFILE=production_keyfile

Don't do this: KEYFILE="production_keyfile"


Customize the PASSWORD= variable with the encryption password you chose when creating your keyfile.


To obtain your API key for the default public community, sign up at PolySwarm, click your name in the top right corner and select Settings. Your API key(s) will be displayed in the API Keys tab.

Customize the API_KEY= variable with your API key.

Connecting to the Marketplace

With your marketplace.env configured, connecting to the marketplace is as simple as running the following from the root directory of your participant:

$ docker-compose -f docker/marketplace.yml up

You should see various log output indicating connection to the marketplace.

If you're running a microengine, check that everything is running smoothly by uploading an artifact to the marketplace and looking for your engine's keyfile address in the scan results set. If you haven't already, you'll want to claim your microengine so that you can name it.

Congratulations, you're connected to the PolySwarm marketplace!

Notes on Relaying NCT to Your Community(ies)

Recall that each community has a distinct sidechain where PolySwarm transactions occur. In order to participate, you'll need to maintain a balance of NCT (ETH not required) on the Community's sidechain.

We've made this easy: you can use polyswarm-client's balancemanager utility. You'll need to run both your participant and a balancemanager to maintain a balance of NCT on the Community sidechain. Windows users will recall running balancemanager from the integration testing instructions. Linux users had balancemanager handled for them by Docker transparently.

balancemanager can be run in three modes:

  1. deposit: deposit the configured amount of NCT onto the Community and exit
  2. withdraw: withdraw the configured amount of NCT from the Community and exit
  3. maintain: continually ensure a configurable balance of NCT in the Community

Most users will want to simply maintain a balance - we'll dive into using this functionality below. Advanced users may want to manually deposit and withdraw funds.