How to start an ICO on Ethereum

Let’s face it – blockchain projects and smart contracts are hot news. New coins, new events are cropping up every week. So what do you need to do when you meet someone that wants to utilize this hype and start an ICO? I’ll give you a developer’s perspective. I’ll walk you through the process of creating a coin and the landing page using the Ethereum blockchain platform.

How to launch an ico on ethereum – our agenda:

  1. Specifications
  2. Smart contract
  3. Tools
  4. Specifications continued
  5. Implementation
  6. Deployment
  7. Testing
  8. ICO status page
  9. What if I need to change the contract?
  10. Wrapping up
  11. Create an ICO  …or get a team to do it


So, first things first…

It’s best to start an ICO (initial coin offering) with a good plan (this article by Chris McCann offers good suggestions). However, it all really starts with a business idea. It should (of course) include creating a cryptocurrency (coin) that has a strong and unique selling point. You need to cooperate with the founder to agree on a specification (which can be later used as a part of a whitepaper) and then proceed to development with thorough testing. Last but not least, you need to create a landing page that displays the ICO status. After your client rolls out a marketing campaign, you’re ready to go.

The specification

At Espeo, we highly value an agile approach to software development. Just as the agile manifesto tells you, we’d rather spend time developing working software than writing comprehensive documentation. However, with Ethereum smart contracts it’s just not that simple. You need to get the code absolutely right from the very beginning, because once the contract goes live – it’s final. There’s no going back. There are strategies for updating your coin or ICO code, which we’ll cover later on in the article. However, bear in mind that each change might decrease community trust in your coin, and this can be reflected in coin price at exchanges. That’s why it’s best that you all agree on a specification which makes all the details absolutely clear to all parties.

So, what do you need to discuss with the founder?

Usually you start with an ERC20 token. You’ll need to know the token name, its symbol and whether it allows decimal fractions. And if so, how many. There’s also the decision on how many tokens can be created (total supply) and when they’re created. You can mint tokens all at once after deployment, or make each ether payment create them. Consider incorporating some inflation or deflation mechanisms if it fits the idea. Other currency parameters are highly dependent on the particular business idea, so we’re not going to discuss this in depth.
To start an ICO you need to consider a few basic parameters:

  • start date,
  • end date,
  • minimum and maximum caps
  • and the currency they’re expressed in.

Let’s say you want to start an ICO that needs to raise a minimum of 1,000 ETH and maximum of 20,000 ETH (4 weeks). But you need to have all the corner cases covered in your code – the ICO may need to end early because you run out of tokens. It’s also highly advised to add a failsafe mechanism – a possibility of halting the ICO completely in case of any security bugs or other problems. Customizing the ICO doesn’t end at defining its duration.
You can offer lots of other possibilities. Here are just a few ideas:

  • Tokens can be accessible immediately after transaction or only after the ICO ends,
  • The ICO can be preceded by a closed presale for invited people,
  • The ICO can offer a bonus scheme for early buyers,
  • Raised funds may be returned if the goal is not met,
  • Founders may get some of the initial token supply,
  • Funds raised during the ICO may be released during some vesting periods or under particular circumstances,
  • Raised ether may be stored in the contract or transferred immediately to some wallet (the difference is in the gas costs, accessibility of the funds and the security if you choose to store them on some particular hardware or multisignature wallet).


Smart contract & Ethereum blockchain

Alright, so you’ve got the specification. Both you – the dev – and the business founder fully understand how the coin and the ICO should behave. What’s next?

Proceed to implementation, testing and deployment.

The importance of unit testing the contracts can’t be stressed enough. When dealing with the delicate matter of people’s money (and possibly a lot of it!) you need to be sure that no line of code goes untested. Provide tests for all scenarios and corner cases you can think of. You have to produce a bug-free product and that requires exceptional unit testing skills. Your attention to detail should outdo NASA! It’’s a task in some ways similar to programming the Mars Rover. You don’t get a chance to fix any bugs after the code goes live. Ethereum utilizes the immutable nature of blockchain and applies it to smart contracts.
Another crucial part of smart contract development are the code reviews. Each line of code should be checked by your peers before it’s committed to the repository. Static code analysis can help discover incorrect implementation, inconsistent contract behaviour, inconsistent requirements or security issues. You can even hire security experts such as OpenZeppelin to audit your code.

Tools to start an ICO

As an example, we’re going to develop a very basic Ethereum smart contract that represents a coin with a simple ICO. For that, we’re going to use:


Specification – continued

We’re going to use the specification mentioned before – with some added requirements:

  • REQ001: Basic ERC20 “Espeo Token” with symbol of “ESP”, 18 decimals (reflecting ether’s smallest unit – wei) and total supply of 1,000,000 units created at contract deployment and assigned to a specific wallet,
  • REQ002: The ICO is going to last 4 weeks, trying to raise a minimum of 1,000 ETH and maximum of 20,000 ETH; if the goal is not met the ICO continues until the payments reach the min cap
  • REQ003: Raised ether is going to be transferred to a specific wallet after each payment,
  • REQ004: Tokens are going to be available for transfers only after the ICO ends,
  • REQ005: The tokens are going to be sold at a flat rate of 1 ETH : 50 ESP, with added +50% bonus during the first week.



I’ll skip setup and installation instructions for brevity and jump straight to development. Smart contracts possibly deal with huge amounts of money. So, the recommended way of starting is test-first (TDD).
Let’s start small, with a test that checks whether the total supply is correct and it’s assigned to a given wallet.

As you can see, we create an instance of our contract and check its properties by accessing the fields and calling functions.
The tests will fail at this moment. They should! There is no implementation for them to test.

This simple token is based on OpenZeppelin’s StandardToken to reuse a trusted implementation of ERC20 token functionality.
Continue with writing tests and then implementation to meet all requirements. I’ve already done a simple set of tests with basic implementation of the requirements and placed it in espeo/token-ico-example repository. It’s still missing some stuff, e.g. negative scenario tests or extensive input validation, but it’s good enough for now. Feel free to implement the missing parts and send a pull request.


We’ve got our implementation with a comprehensive suite of unit tests. Now we’re going to compile it using truffle and deploy it to the test Ethereum blockchain using (MEW). For deployment we could also use the Truffle Framework’s migrations but for the sake of simplicity let’s stick to MEW.
For easier creation of multiple token contracts with different parameters, I’ve created a Factory contract. That’s what I’m deploying.

How do you deploy a smart contract?

Firstly, go to MEW Contracts and make sure to select the test network node (Ropsten) in upper right corner. Then click the “Deploy contract” heading, paste the contract’s bytecode compiled using truffle compile command, provide your Ethereum account, sign the transaction, click “Deploy contract” button, confirm it and voila! After the transaction is mined the contract is live. Mine got the address 0x110FC34F504694FfE34A351B1594F84aa61D07cc.

How to create a smart contract

Manual smart contract testing

The code is tested by unit tests, but you should also test your code against a working blockchain. Use the Factory contract to create token contracts with various parameters. Remember to test your contracts extensively on the test network before you go live because at that time you still can introduce bugfixes and changes easily. Provide your client with instructions on how to test the contract as well so that they can get the feeling on how to control it.

To create a token contract you need to interact with the Factory contract. For that, visit the same MEW Contracts page. Again, make sure you’re using the test network’s Ropsten node. Then provide the contract address and its Application Binary Interface (ABI) you got after compilation. Of course, for the Factory contract you need the Factory ABI and for EspeoTokenIco contracts created by the Factory you need the EspeoTokenIco ABI.
When you provide this data, you can already read fields and run read-only functions using the dropdown below. For operations that need to write data to the blockchain you’re going to need to authorize yourself as well.

how to create an ico

I’ve created a test token contract that started at 26 Jul 2017 16:00:00 GMT with min cap at 3 ETH and max cap at 5 ETH. It got deployed at 0xA292375e9343f1684e36a03b56bCe6E0664aD1f9.
Now we’ve got a working contract at the Ropsten test network which is same Proof of Work network as the main Ethereum blockchain. However, it uses Ropsten Ether. You can get it easily for free, e.g. using the MetaMask faucet. Test it until you’re sure that it works exactly according to specification. Let your client test it, employ a QA specialist and do it by yourself as well.

There’s one more thing you should know about custom tokens and MEW.

To observe the balance of your coin, please add it to observed token balances under MEW Wallet Info. This is where the ERC20 standard comes in handy. That’s the interface MEW is using to read token balances.

start an ico

For the sake of this post, I’ve made a few transactions to check how the token contract works. I’ve sent 1 ETH during the first week and got 75 ESP which is correct with the rate and bonus requirement. I’ve then sent 4.18 ETH to check if it deals correctly with decimals and whether it closes the ICO after reaching the max cap. The transfers of tokens should now be possible. So, I’ve tested this as well. These are just very simple scenarios from the top of my head. The testing should be much more thorough!
After all of the unit testing, code reviews and manual tests there’s still a way to check your code for even more bugs. Deploy a fresh instance of the token contract (or publish your Factory contract ABI) and offer a bug bounty. It’s a common practice in the blockchain community, so there’s a chance some experienced blockchain developers will take a look at your code.

ICO status page

Another crucial part of the ICO is the status page. You need to inform the potential token buyers of basic ICO parameters like start and end dates, the minimum and maximum caps, the rates and bonuses etc. I’m going to show you how to create an ICO status page using just a Bootstrap theme, web3.js library for Ethereum blockchain integration and INFURA as a publicly accessible Ethereum blockchain node. I’m not going deep into design best practices or the contents. I’ll leave that up to you and the client. What I want to show you is how easy it is to display data straight from Ethereum blockchain on a website.

ethereum blockchain
As you can see in the screenshot above, the website is very simple. It’s just a static HTML file with some JavaScript on top of it.

Now, let’s talk code.


To start small in the snippet above, we’re just displaying the total amount raised. I’ve omitted the HTML structure and styling for brevity. With some crude utility methods reading and displaying a value from a smart contract is a one-liner! Of course web3.js library offers you much more possibilities. Feel free to read the docs.

With the rich toolset that web3.js library is offering and INFURA Ethereum nodes already in place, you can kick-off the frontend development of your ICO status page in minutes. Starting with a static HTML page with simple JavaScript that requires little-to-none infrastructure you can go further. Add cool progress bars, pretty designs, with some backend work a user registration page and more.

What if I need to change the contract?

The token is live and the ICO is in progress. However, you’ve noticed a serious bug and you need to fix it ASAP. I’ve said before that once you deploy it the smart contract’s code is final and can’t be changed. That’s true but fortunately there are ways to update your token – even after it goes live. Be aware that you’re changing a contract that people may have already agreed upon. It’s not a decision you should make lightly!

There are two popular strategies to updating contracts. Here’s the first one.

It’s essentially uploading a new one and informing people about it. But there’s a little more to it. The process starts in a similar way as it did before. Agree with your client on the bugfix scope or any other requirements, change the code and unit tests and test the contract again. The next thing is to plan a data migration from the previous contract if you haven’t planned to store your data in a separate contract.
There are many ways to do it.
Let’s say you want to migrate token balances from the bugged contract. The easiest way to do it is to prepare a smart contract that will call the standard ERC20 balanceOf() function to read token balance for a particular address. Then, assign the token balance to the new contract. When you’ve got both the fixed token and the migration contracts ready and tested you can proceed to deployment.
Firstly, publish informative community announcements explaining what, when and why you’re going to change with the token contract. Then, use the failsafe mechanisms in your contract. Halt the fundraising and pause all token transfers so that the contract is frozen and no token balances can change. Get the list of token buyers for the data migration, e.g. from and deploy it. Update the smart contract address on all your pages and you’re done.

There’s also another way.

You can organize your contracts in an object-oriented-like structure, where the main contract with publicly announced address is a Proxy which refers to other contracts for the actual work execution. This is how you plan for modifiability in your Ethereum blockchain code. However, having that modifiable Proxy lowers the trustworthiness of the contract because the owner can change the work delegates at any moment. This is a delicate balance between blockchain’s trustlessness and systems that require one to trust the owner. Having said all that, ERC20 tokens are rather simple contracts, so they should not use the Proxy pattern.
As you can see, updating an Ethereum smart contract is not that easy. You need to either prepare the community for the change and perform data migration, or plan any contract modifications upfront. That’s why developing contracts is hard, especially if you try to get the contract 100% right from the start.

Wrapping up

With this lengthy article, I’ve tried to introduce you to the world of Ethereum smart contracts and ICOs. We started from the importance of a good specification, went through the development of smart contracts, put extra stress on automated and manual testing. Then we saw how easy it is to build a simple ICO status page and finished with the hardships of introducing changes to your smart contracts.
Now you know how to start an ICO on Ethereum – how to build the token contract, get the ICO status page up and running. So you’ve got the development part pretty much covered. There’s more to a successful ICO. You need a whitepaper describing the business idea, technical execution and a marketing strategy to reach potential buyers. But that’s a whole different story, worth another article.

Start an ICO yourself!

ICOs and smart contracts are what we’re (me, the CTO, included) working on at Espeo Blockchain. Last year, we held developer workshops on how to start an ICO, build tokens and deploy Ethereum ICO smart contracts. We hold out own blockchain meetup. With all that expertise we can share insights like this article with you, so don’t forget to follow us on Twitter 🙂

And if you’re planning to start an ICO – we provide top-notch development services: create an ICO of your own!