A Programmable Bitcoin Push Notifications API

This week 4 different BitDBs were born.

Each has its own distinct trait, and can be extremely useful when used in combination. All BitDB nodes are HTTP[s] endpoints. They are “Pull” APIs.

Today, I present the “PUSH” counterpart.

Meet Bitsocket.

For every single BitDB.

  1. Genesis:
  2. Babel:
  3. Chronos:
  4. Meta:

As of today, for each of these BitDB nodes, you will find an additional button named Socket on the home page:

What Is It?

Bitsocket is a realtime programmable Bitcoin push notifications API. If BitDB is a “pull” API, Bitsocket is the “push” counterpart. With BitDB you use HTTP[s] requests to fetch from the database, but with Bitsocket you subscribe to an SSE (Server Sent Events) endpoint and listen to incoming realtime events, straight from Bitcoin, based on various filters you set up with your Bitquery.

Both Bitdb and Bitsocket use Bitquery. Instead of using the query language to fetch from the database, it structurally filters the realtime Bitcoin Zeromq event stream and delivers the filtered stream to the API endpoint via SSE (Server Sent Events)

There’s zero learning curve if you already know how to use BitDB. And all BitDBs use the same Bitquery query language, so you just need to learn one query language to be able to do everything.

How Bitsocket Works for Each BitDB

Each Bitsocket API emits an event equivalent to each object stored on the corresponding BitDB instance. And of course you can filter the event stream in realtime using Bitquery.

And the API endpoint for the SSE (Server Sent Events) is very similar to the BitDB endpoint, except the path looks like this:[BASE64_ENCODED_STRING]

You can also find out the endpoint URLs on the socket explorer,

Case Studies

CASE 1. Bitcoin → Application

You can build applications that listen to and run on various Bitcoin events. Thanks to Bitquery’s ease of use, you can treat Bitcoin like any other JavaScript event source, subscribe to various patterns, and trigger actions in your app 100% based on Bitcoin events.

Let’s take a look at a web app called “Bitcoin plays Pokemon”, created by

It’s a remote controlled game device you can control using Bitcoin transactions. And the game device is livestreamed through Twitch. You can check it out here:

In the past there have been primitive ways of listening to and acting upon realtime Bitcoin transactions, but none had the capability to handle sophisticated filters like Bitsocket.

Bitquery — the stream filtering language of Bitsocket — is a Turing complete query language, a combination of MongoDB query language and JQ. This means you can create all kinds of map/filter queries to program your push notifications.

Anyway, the way this Pokemon game works is:

  1. You make a Bitcoin transaction using Moneybutton.
  2. The game controller is replaced with Moneybutton, so if you pay to an address, the game device recognizes it and makes a move.
  3. The app listens to Bitsocket for incoming transactions, filters and inspects the OP_RETURN. If the OP_RETURN output contains the string “left”, it moves the character to the left, and so on.

CASE 2. Application 1 → Bitcoin → Application 2

Not only can you listen to Bitcoin one way, but you can also “send” an event to another application that’s listening to the Bitcoin transaction event. It’s like an IPC (Inter Process Calls) of sorts.

This way you can create autonomous apps that communicate with one another through Bitcoin transactions.

Let’s take a look at an interesting event that happened recently which is a perfect example of this.

Act 1: The @_opreturn Bot Lives

I wrote and operate a Twitter bot named @_opreturn. Here’s what it does:

  1. Listens to transactions from Bitcoin
  2. Parses the message from the transaction and post it to Twitter

This is effectively the “Bitcoin → App” use case from the last section. You can check out the bot here:

Act 2: The @amritabithi Bot Enters the Scene

Then something interesting happened. A developer named @amritabithi built another bot that does the opposite. Instead of turning Bitcoin transactions into Twitter posts, this bot:

  1. listens to all replies to @amritabithi Twitter account
  2. and sends a Bitcoin transaction

Basically it’s the opposite of @_opreturn. It’s is a case of “App → Bitcoin” (whereas @_opreturn was Bitcoin → App). It’s pretty amazing as you can see below:

Here’s what’s going on:

  1. I have Twitter open on the left side, and Bitsocket explorer on the right side, listening to Live Bitcoin events.
  2. The Bitsocket explorer is listening to a Bitquery for all transactions that send to an address out.e.a, and applies a JQ filter .[] | .out[0].s2 to filter the stream down to the push data we want to display.
  3. Then on Twitter, I reply to @amritabithi, triggering the bot.
  4. This twitter post triggers a Bitcoin transaction on the Bitcoin SV chain, and immediately shows up on Bitsocket.
Act 3: The two bots talk to each other forever, through Bitcoin

So now we have two independent autonomous bots. Guess what happened next.

The two bots started interacting through Bitcoin as a message bus, and in certain cases, went into an infinite loop.

amritabithi eventually updated the bot to ignore certain patterns so the infinite loop wouldn’t happen and bankrupt him as a result.

However it was the first instance of two autonomous bots communicating through Bitcoin.

This is just a fun example, but should be enough to inspire many developers and entrepreneurs to come up with something very useful.

CASE 3. Bitcoin → App → Bitcoin

Lastly, you can build apps that listen to certain patterns of transactions, and then trigger another bitcoin transaction in response. Create a looping program on Bitcoin.

This one will be very interesting, but no project on Bitcoin SV, as far as I know, has been built with this approach yet. If you have built something like this, please let me know, I will check it out and share. Otherwise, someone go build one.


Not many people have yet realized the power of Bitsocket, especially when used in conjunction with BitDB. I hope some of the case studies I mentioned above helps.

Also, now that all BitDB nodes support Bitsocket, you should be able to build all kinds of creative mix and match event driven applications.

Looking forward to it!


To learn more about Bitsocket, check out the official page:

Also, you should learn Bitquery first if you don’t know it yet. Bitquery drives everything in both BitDB and Bitsocket:

If you have any questions or just want to meet other Bitcoin developers, join the Atlantis Slack:

To stay updated on the progress of BitDB and Bitsocket, follow the creator: