Skip to main content

1. Intro to Chialisp

Chialisp is a language based on Lisp that is used on the Chia blockchain to dictate how and when coins can be spent. It's designed to be as simple and efficient as possible, but still provide broad functionality and Turing Completeness.

Throughout this guide you will learn the basics of Chialisp, and by the end you should have the skills required to write working programs using it. No prior knowledge of Lisp is required.


You can follow the Chia Dev Tools installation guide to install and use Chia Dev Tools. You will be using these tools and a simple text editor of your choice to write and run snippets of code.

Once you have it set up, run the following command:

run "test"

The run command compiles Chialisp code. In this case, we are compiling a simple string to make sure it is installed properly.

If it is working correctly, it should output "test". You can now follow along with any of the code in the coming sections.


An atom can represent an integer, string, or hexadecimal number. However, the difference is only known before the code is compiled, and every atom is stored directly as bytes.

For example, these atoms all have the same value:

SymbolANames and operators
String"A"Used to represent text
Integer65Whole numbers, positive or negative
Hexadecimal0x41Raw byte representation

If you are interested in learning more about how atoms are represented, see the CLVM guide.


A list is a nested chain of cons pairs used to represent a set of values, which are also either atoms or lists. While you can manually create these pairs, and it is a good thing to know how to do, we will focus on the higher-level concept of lists for now, since they are easier to use and more practical.

The first item in an unquoted list is the operator, and the rest are its operands. The same goes for functions or macros and their arguments. If you want to express a list of values, you either have to use the list operator or quote the list.

This creates a list of values:

run '(list 1 2 3)'

And here is an operator:

run '(+ 2 3)'

As you can see, just about everything in this language is based on lists, hence the name Lisp (an abbreviation for List Processor). You can see a full list of built-in operators.


Lets try a more complex example:

run '(* (if (> 3 2) 10 5) 10)'

If 3 is greater than 2, it's 10, otherwise 5. Then multiply it by 10. The result here is as you would expect, 100.


Hopefully this guide has been a good introduction into the world of Chialisp. There is a lot more to learn, but this is the foundation that everything else is built on top of.

If you really want to get started with using it, the best way is to try out these examples yourself, and play around a little yourself. Feel free to ask questions on our Discord that come up along the way. We are always happy to help you learn.