Blog Article

Tokens on Stellar


Jed McCaleb

Publishing date


Asset issuance

Everyone is talking about tokens these days. At this past Consensus conference I was at a dinner and someone from Poloniex was there. People were asking him how they decided what new coins to list and how they were going to keep up with the accelerating number of new tokens and coins that are being created. The answer was basically that they can't. No one can. It will become an increasing challenge for exchanges to not only list all the tokens and coins people are asking for but to also create the multitude of pairs between all of them.

This is another reason we hope people start moving to a more decentralized exchange model. Instead Poloniex could be a Stellar anchor for the tokens and coins it does support and these could then be traded freely with the tokens other anchors choose to support. But even better would be to avoid all that and just create your token directly on Stellar skipping the need for an anchor altogether.

There is clearly a lot of hype around these things now and although many will surely fall by the wayside a lot of them make sense and are moving things forward. What is great is that Stellar is built to keep track of any arbitrary token. It makes it very easy to issue a new token out into the world. There are a lot of benefits to using Stellar for this:

  • Quick settlement. 3-5 seconds for a token holder to send the token to someone else.
  • Cheap transactions
  • Built in exchange with any other token, asset or currency in the network.
  • Optionally control of who can hold your token.
  • Ability to do voting, dividends or awards all in the same network.
  • Unify how exchanges and others can deal with your token. If an exchange supports Stellar than it can easily list all other tokens issued on Stellar.

Let's issue a token

It is trivial to create assets on Stellar. It was built to keep track of any arbitrary asset, or currency so can also be easily used for all these new tokens that are popping up. Here I'll walk you through how you do this technically by creating an example token... Let's say I want to make a HUG token. Anyone can send me one of these HUG tokens and I'll hug them. I want to create 5000 of these and want to ensure the world that no more are ever created so no one has to be concerned with hug inflation. There are wallets that provide an easier interface for many of these steps but I'll just use the Stellar laboratory.

Step 1 - Create issuing account

You can use the laboratory to generate the key pair. You must now send lumens to this public key to create the account inside the network. From any Stellar wallet Send 31 lumens to the new public key you just generated. Issuing account:



You can also do this step programatically.

Step 2 - Create distribution account.

Use the same method as above to create the account but create it with at least 41 lumens. HUG distribution:


Step 3 - Trust the issuing account.

Here is the change trust operation that we need to use in the laboratory. In your case, change the parameters to the accounts you created in steps 1 and 2 and the token you want to create. Also remember to click the button to fetch the correct sequence number for your distribution account.

Step 4 - Create tokens

Now that the distribution account trusts the issuing account the HUG tokens can be created. This is done by simply sending a payment from the issuing account to the distribution account as done here. See the Stellar docs for more details about issuing assets.

Step 5 - Publish information about your token

Ideally there will be a more formalized protocol around this so that clients can programmatically display details about each token. Here I've created a simple doc describing the HUG token, the conditions it can be redeemed under, etc.

 "code": "HUG",
 "name": "hug token",
 "desc": "1 HUG token entitles you to a hug from Jed McCaleb.",
 "conditions": "You must travel to Jed to receive your hug. You must be in a reasonably clean condition before receiving your hug."

In order to prove that I'm the one that created this token, I'm also signing the doc with my keybase public key. I take this doc and publish it to IPFS. You can see the full document here here. Now we want to attach the IPFS hash of the token description to the issuing account. We do this with the manage data operation. Here is this transaction in the laboratory.

Step 6 - Limit the supply

Great! Your token exists and you have told people what it is all about. Now you likely want to prove to the world that you won't flood the market with your tokens. The simplest way to do this is to lock the issuing account so that it can no longer make transactions. You can do this with the multi-sig features of Stellar. You simply change the weight of the master signer on the account. Now that the account is locked you can be sure that there will only ever be 5000 HUGs in the world. You can see that the issuing account is locked here and I posted the secret key above so feel free to try it to make sure it can't issue more tokens.

Step 7 - Distribute your Token

Ok now your token exists and everything is setup. The final step is to get them in the hands of the people. There are many ways to do this of course. One of the great features of Stellar is that it has a built in decentralized exchange. So a natural way to get the HUGs out into the world is simply to put an offer out for them. Here in the laboratory I create an offer selling HUG tokens You can see the live active HUG market here. As you can see hugs are cheap, only 30 XLM. Feel free to buy one and I look forward to you redeeming it! This was a simple example of what is possible. There are a lot of ways you can extend this basic idea to for more complicated use cases. A few ideas are:

  • Inflating token supply in a predefined schedule using pre-authorized transactions
  • Limit who can hold your token
  • Issue a dividend
  • Conducting an auction for your tokens