Skip to content
A fully reactive / async Discord API wrapper for the JVM, built on vert.x - Fork moved to
Branch: master
Clone or download
Pull request Compare This branch is 170 commits behind mewna:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


CircleCI powered by potato GitHub tag (latest by date)

A Discord API wrapper in Java. Fully async / reactive, built on top of vert.x. catnip tries to map roughly 1:1 to how the Discord API works, both in terms of events and REST methods available.

Join our Discord server!

Licensed under the BSD 3-Clause License.


Get it on Jitpack

Current version: GitHub tag (latest by date)

Can I just download a JAR directly?

No. Use a real build tool like Maven or Gradle.


Get them here.


Basic usage

This is the simplest possible bot you can make right now:

final Catnip catnip = Catnip.catnip("your token goes here");
catnip.on(DiscordEvent.MESSAGE_CREATE, msg -> {
    if(msg.content().startsWith("!ping")) {"pong!");

catnip returns CompletionStages from all REST methods. For example, editing your ping message to include time it took to create the message:

final Catnip catnip = Catnip.catnip("your token goes here");
catnip.on(DiscordEvent.MESSAGE_CREATE, msg -> {
    if(msg.content().equalsIgnoreCase("!ping")) {
        final long start = System.currentTimeMillis();"pong!")
                .thenAccept(ping -> {
                    final long end = System.currentTimeMillis();
                    ping.edit("pong! (took " + (end - start) + "ms)");

You can also create a catnip instance asynchronously:

Catnip.catnipAsync("your token here").thenAccept(catnip -> {
    catnip.on(DiscordEvent.MESSAGE_CREATE, msg -> {
        if(msg.content().startsWith("!ping")) {

Also check out the examples for Kotlin and Scala usage.

Modular usage

catnip supports being used in REST-only or shards-only configurations. The nice thing about catnip is that using it like this is exactly the same as using it normally. The only difference is that to use catnip in REST-only mode, you don't call catnip.connect() and use instead.

Custom event bus events

Because vert.x is intended to be used in clustered mode as well as in a single-node configuration, emitting events over the built-in event bus requires registering a codec for the events that you want to fire. If you have an event class MyEvent, you can just do something to the effect of

eventBus().registerDefaultCodec(MyEvent.class, new JsonPojoCodec<>(this, MyEvent.class));

where JsonPojoCodec is com.mewna.catnip.util.JsonPojoCodec and is safe to use.

Useful extensions

Why write a fourth Java lib?

  • JDA is very nice, but doesn't allow for as much freedom with customizing the internals; it's more / less "do it this way or use another lib" in my experience.
  • Discord4J is built on Project Reactor; I wanted to be able to choose a reactive™️ implementation to use with the lib and not be stuck with just one.
  • I didn't want ten billion events for every possible case. catnip maps more/less 1:1 with the Discord API, and any "extra" events on top of that need to be user-provided via extensions or other means. I guess really I just didn't want my lib to be as "high-level" as other libs are.
  • I wanted to try to maximize extensibility / customizability, beyond just making it modular. Things like being able to intercept raw websocket messages (as JSON), write custom distributed cache handlers, ... are incredibly useful.
  • I like everything returning CompletionStages instead of custom classes. I do get why other libs have them, I just wanted to not.
  • I wanted to make a lib built on vert.x.
  • To take over the world and convert all Java bots. :^)

Why vert.x?

  • vert.x is nice and reactive and async. ™️
  • You can use callbacks (like we do), but vert.x also provides support for reactive streams, Rx, and kotlin coroutines.
  • There's a lot of vert.x libraries and documentation for just about anything you want.
  • The reactive, event-loop-driven model fits well for a Discord bot use-case.

Real-world numbers?

With a bot in ~35k guilds, catnip used ~1.5GB of RAM and <10% CPU on a 2c/4gb VM. Sorry, I lost the screenshots :<

You can’t perform that action at this time.