Getting started with SETHER Blockchain API

Develop smart marketing applications using Blockchain and SETHER.


Let's imagine you represent a marketing agency team and you want to inform your client about a running campaign's status, leveraging transparency offered by blockchain.

First off, we need to define our business target. Let's assume that the client targeted 1000 likes at the end of a Facebook campaign.

This tutorial will guide you step by step on how to use the Sether Blockchain API.


You will need the following configurations before starting up:

  1. An up and running ethereum node. We strongly recomend using Infura on the Rinkeby test network;
  2. Basic knowledge of Solidity programming language;
  3. Basic knowledge of Ethereum smart contract deployment. We recommend using Truffle. Get started here;
  4. For ease of Ethereum accounts management we recommend using MetaMask. Get started here
  5. .

Getting Started #back to top

After you have the geth configuration up and running, download or clone the following repositores: Example and Client API.

As you can see, we have three components:

  1. The client api contract code and configuration;
  2. A NodeJS server that makes calls to Blockchain using web3.js library;
  3. A sample Angular application that communicates with the sample sever through simple REST calls.

Blockchain configuration#back to top

Infura provider - #back to top

Follow the instructions here to obtain an Infura provider, which will later be used in our Truffle configuration. Make sure you select the Rinkeby test network for the Infura provider, otherwise you will have to spend real ethereum!

Ethereum account - #back to top

Create a Rinkeby account. You will need the mnemonic for our Truffle configuration and the private key for the server configuration. We recommend using MetaMask

To add some test ETH in your account follow the instructions here.

Truffle configuration - #back to top

Open the blockchain/truffle.config file and edit the mnemonic and the Infura provider in the "rinkeby" section, like shown bellow:

									rinkeby: {
									provider: () => new HDWalletProvider("weird mnemonic text generated for the ethereum account",
									network_id: "*",
									gas:  6994071,
									gasPrice: 100000000000
* Please be careful about who do you share the mnemonic with, since it's a secret that can be used to access your account.

Developing the smart contract #back to top

Derive from one of SETHER interfaces

Based on your needs, you will derive from one of the available SETHER interfaces.

See the available interfaces here

In our scenario we'll need a Facebook KPI. We'll have to derive from the FacebookSetherAPI interface, like so:

                        pragma solidity ^0.5.0;

                        import "../../sether-interface/contracts/FacebookSetherAPI.sol";

                        contract MyContract is FacebookSetherAPI

Define the "target" of you campaign

Allegedly your campaign is successful when the targeted Facebook Page achieved 1000 likes.
Define state parameters and initialize them as so:

	                    uint64 targetLikes;

	                    constructor() public
		                    targetLikes = 1000;
One can add a function to control the target from outside, but that is trivial and beyond the scope of this tutorial.

Implement a business function

Now we get to the fun stuff.
After we defined our business logic, we'll call a function to query the SETHER platform about the value of a certain KPI ; in this case get_facebook_page_likes For a complete list of available methods, please see the documentation
To do so, you'll need to implement a function as simple as this:

                        function checkFacebookLikesTarget(
                            bytes32 setherToken,
                            bytes32 date,
                            bytes32 targetId,
                            uint8 level,
                            bytes32 requestID) public
                            super.get_facebook_page_likes(setherToken, "", date, targetId, level, requestID);
Note: The parameters can be cached in the contract, and the meaning of each one can be found in the docs.

Implement the callback function

When the Sether Platform successfully retrieves the needed KPI, it will call the callback function, that any contract based on a Sether Interface needs to implement: callback
Now, there are two ways to check the result:

  1. Poll the contract from outside to check the result;
  2. Issue a blockchain event on which you can listen from a client application.

We recommend the latter, and this can be implemented as so:

                        // define the event //
	                    event MyEvent(
		                    bool targetAchieved,
		                    bytes32 requestID

                        function callback(uint64 setherMetric, bytes32 requestID) public
                            // emit a event to notify any listeners about the result //
                            emit MyEvent(setherMetric >= targetLikes, requestID);


You now have implemented a contract based on FacebookSetherAPI interface. Great job!

Deploy the contract #back to top

After the steps above, we're ready to deploy our newly created contract.
Since we're using Truffle for this, it's a one liner, so open a bash/command line and just write this:

                        truffle migrate --network rinkeby --reset
Yep, that's is!
Now you can go on etherscan and check that your contract has been deployed, by searching the contract address that you'll see in the output of the command above.

Reference SETHER API #back to top

Before any calls to the Sether API functions, one needs to setup the corresponding Sether API address for the platform you want to base yor contract on.

To do so, call the put_sether_address, available in every SetherAPI interface.

						function put_sether_address(address _setherAddress) public onlyOwner
							setherAddress = _setherAddress;

As you can see, this method is only available for the account that deployed the contract, so make sure that you call this method before making calls to the API.

Rinkeby test network:

After you have finished deployment and are ready to go on the main network!

Main network:

API access key #back to top

As you noticed above, the sether methods require a setherToken param ...

For this you need to generate an API access key. Please go to Sether Dashboard

If you don't have an account, you can create one for free here.

Once you generate a new key, Sether will create an "_API" prefixed project for you on Sether Control Panel . On this project you can manage your Social Network connections.

Error handling#back to top

The errors that occur in this process can be handled only by using the error URL that you configure in your API key section in your dashboard.

You need to provide a REST API endpoint that will be called in case an error will occur.

There are two types of errors that can occur:

•  Blockchain error, e.g. incorrect contract deployment: the deployed contract does not correctly implement an interface of the Sether API.
•  SetherAPI specific error, e.g. fail to retrieve the requested KPI.

See it in action #back to top

Finally, you can just call checkFacebookLikesTarget method from a geth console or use the example web application provided with this tutorial.

Please feel free to contact us at if you need support, or join a discussion on