📖 Version: @polymathnetwork/sdk - v3.0.0

🤔 Purpose

The Polymath SDK's main goal is to provide external developers a set of tools to build powerful applications that interact with the Polymath protocol. It focuses on abstracting away the complexities of smart contracts (and the blockchain itself) and expose a simple but complete interface. The result is a feature-rich, user-friendly Node.js library.

Setup your Project

The SDK works equally well on browsers and Node.js applications. For simplicity, we're going to setup a Node.js project. Any steps specific to browser environments will be highlighted.

First, create a new Node.js project:

mkdir sdk-demo && cd sdk-demo
npm init

Follow the npm init wizard to initialize your project. Then, install the SDK, which is the only dependency we need to build a simple application.

npm add @polymathnetwork/sdk@2.0.1-beta.24

Finally, add an entry js file such as index.js, which imports the SDK API as well as some browser utils that we're going to use later.

import { Polymath, browserUtils } from '@polymathnetwork/sdk';

🐂 Instantiate and Initialize the Polymath client

Before we use the Polymath SDK, we need to connect to the deployed smart contracts on the desired Ethereum network.

const privateKey = process.env.PRIVATE_KEY;
const networkId = 1; // Or you can detect the current network in browser environments via browserUtils.getNetworkId()
const networkConfigs = {
1: {
polymathRegistryAddress: '0xdfabf3e4793cd30affb47ab6fa4cf4eef26bbc27',
providerUrl: '[INFURA_PRODUCT_ID]',
42: {
polymathRegistryAddress: '0x5b215a7d39ee305ad28da29bf2f0425c6c2a00b3',
providerUrl: '[INFURA_PRODUCT_ID]',
const config = networkConfigs[networkId];
const polyClient = new Polymath();
await polyClient.connect(config);

PolyClient.connect() accepts three parameters:

  • polymathRegistryAddress is the address of the main registry that keeps track of core components of the system, including the addresses of other registries.

  • httpProviderUrl is an URL pointing to an Ethereum node that enables you to view and interact with the blockchain, via HTTP. Said node can be a local geth or parity node, or a 3rd-party provider such as Infura.

  • privateKey is the private key used to sign transactions sent from the SDK.

On browsers, some plugins such as Metamask automatically inject a Web3 instance onto the browser for your webpage to use. If using such plugins, you can omit passing httpProviderUrl and privateKey. The SDK will use the injected provider behind the scenes.

You may detect the currently selected network using browserUtils.getNetworkId(), which returns the network's ID (e.g., 1 for mainnet).

🏳 Prerequisites

Familiarity with Polymath smart contracts

Make sure you understand the purpose of the ST-20/ERC-1400 standard. Polymath's Smart Contract Github repo is a great resource to get started.

Familiarity with React and Redux

The tutorial applications referenced throughout Polymath's SDK documentation are composed of pure React components and use React hooks to manage state.

Metamask Browser Plugin

Using a dApp requires an Ethereum account/wallet to sign transactions and pay for fees. Metamask is a browser wallet that also exposes a provider connected to an Ethereum node so you don't have to run your own.

  • Make sure to install Metamask on a browser.

  • Follow initialization steps in order to create your account.

  • In these tutorial applications, we're going to interact with Polymath's smart contracts on the Kovan test network. Make sure to obtain some Kovan ETH (KETH) beforehand. 1 KETH should be sufficient.

Obtaining POLY

POLY is an ERC20 token required to conduct certain paid operations on the Polymath network. For example, reserving a token symbol or attaching additional modules to your security token requires a predetermined amount of POLY. The manner in which POLY tokens are obtained varies depending on the Ethereum network in use.

  • Kovan: you can obtain Kovan POLY, for free, from the deployed PolyTokenFaucet contract. The SDK will obtain POLY from the faucet on Kovan (or local testnets) whenever it's needed for certain SDK functions (e.g. symbol reservation).

  • Mainnet: you can buy POLY tokens on Mainnet using one of these markets.

👨🏫 Tutorials

The Polymath SDK documentation is segmented into tutorials to help you understand how to use the SDK to create, manage, and distribute your security tokens.

Each tutorial features a standalone application that showcases a specific set of functionalities that the SDK provides. You can find documentation on how each tutorial was built on its Github page. This documentation will focus solely on the components interacting with the SDK.

We recommend visiting Github and launching each tutorial application while working through the documentation.