Token

The Token Developer Hub

Welcome to the Token developer hub. You'll find comprehensive guides and documentation to help you start working with Token as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Creating a Token App

Creating a new Token app can be accomplished in as little as 5 minutes. This guide will help you through the process.

1. Fork the starter app

Fork the javascript sample app and git clone it to your local computer.

$ cd code
$ git clone git@github.com:tokenbrowser/token-app-js.git
$ mv token-app-js my-app
$ cd my-app
$ git remote rename origin upstream
$ # create an empty repository on your github account
$ git remote add origin git@github.com:YOUR-GITHUB-USERNAME/my-app.git
$ git push

The starter app will format all messages properly using the SOFA Protocol and end-to-end encrypt them with Signal so you can focus on the bot logic.

2. Generate a 12 word seed

Visit our seed generator page. This generates an app ID, payment address, and random 12 word phrase that forms the basis of the Ethereum wallet behind your app.

3. Get your app running locally

Now we're going to use Docker to boot up a local instance. First, make sure that you have the latest version of Docker installed.

You'll need to create a docker-compose.yml file and enter the environment variables from the seed generator.

$ cp docker-compose.yml.sample docker-compose.yml
# open docker-compose.yml with your favorite editor and add the env variables
$ docker-compose up

4. Connect to your app

Your Token Android or iOS client should now be able to chat with the Token app running locally on your computer.

Open the Token app on your phone, and search for the username of your new app from the contacts screen. Alternatively, you can scan the QR code on the seed generator page from above to add your app as a contact.

You can now start chatting with your app!

5. Customize your app

You are now ready to start modifying your app and adding your own logic. Try changing one of the text responses in the sample app and save the file (docker should automatically restart the bot.js process on your machine when it detects a change).

For example, you can try adding a new response option with something like this:

function onMessage(session, message) {
  session.reply("Hello Token!")
}

If you're going to install any new Node packages, you'll need to rebuild the bot container.

$ docker-compose build bot # or docker-compose up --build

If you want to pull down changes from the original token-app-js repository in the future, you can do so like this.

$ git pull upstream master
$ # if there are any database changes in new versions, you may need to drop/rebuild the local database
$ docker-compose down -v # v flag will destroy the anonymous volume that holds your postgres db
$ docker-compose up

What's Next

Learn about the various components of a Token app.

App Components

Creating a Token App