Skip to content
Java based client for checking if an account is MCLeaks.
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.


Type Name Latest commit message Commit time
Failed to load latest commit information.


Amount of names

Java based client for checking if an account is MCLeaks.

Allows you to interact with my MCLeaks account checker through a RESTful service.


Java 8 is required in order to use the Java API. If you'd rather implement your own API (in whatever language), head here for the REST API specifications.


Q: Why isn't there an extension?
A: There is an extension for the service, however, it's private to me and a friend. The reason being that where MCLeaks able to view its source, they would be able to discern how I bypass their anti-bot security.

Due to the latest changes in MCLeaks, crowd-sourcing is no longer possible, meaning existing public extensions will no longer function.

Q: How are accounts obtained for the service?
A: As stated above, there is a private extension that grabs tokens and submits them through a private channel.

Q: Why should I use this service?
A: Should someone retrieve their account and want to play on your server, you wouldn't want to deal with manually proving they've recovered their account.

The way I store alts is unique, in that I can check if an alt is still usable, and if it is, I know the account is still susceptible to a malicious user logging in it.

Q: How reliable is the service?
A: The server is implemented using Spark Framework as the backbone. A secondary server runs as failover in the event of the first server going down. This allows seamless updates with no down-time, as your traffic is automatically rerouted by nginx to the backup server.

As a precaution, I have money on stand-by in order to upgrade the servers should I see the server is under heavy-load.

Q: How should MCLeaks accounts be handled?
A: You should only kick the account; banning removes the benefit of someone being able to recover their account.

If you ban the user, then they'll both have to be removed from my database and be unbanned on your server. Kicking simplifies this, and allows you to easily keep and up-to-date state with who is and isn't an MCLeaks account.

Q: _I'm frequently hitting your rate limit/my server has large influxes of players A: Contact me at my email with the subject line MCLeaks - Rate limit increase request, describe what server this is for and how many players the server generally gets. I'll then give you an API token which you then have to use when building the API (or in the request header API-Key)

How to use

As a dependency



In your projects

First, you need to get an instance of the API. To do this, use the builder provided.

final MCLeaksAPI api = MCLeaksAPI.builder()
                .expireAfter(10, TimeUnit.MINUTES).build();

The thread count specifies how many concurrent requests may be running at one time. If you have a lot of requests going at once, you may increase this accordingly. You may also use the API synchronously, which will block the thread executing the method.

The expireAfter parameter describes how long to cache data after fetching. It is recommended to keep this value high as the status of an account being MCLeaks or not is unlikely to change.

If you don't require cache'd results (implementing your own cache), instead of calling

.expireAfter(10, TimeUnit.MINUTES)

You would instead call


which will instead directly retrieve results instead of querying the cache.

API Keys

If you've received an API key, use it by calling the method apiKey


An API key isn't required, but it is used in order to determine your rate limit. Without an API key, you'll be at the default rate limit.

You must have a valid API key in order to use this service. If you would like an API key, contact me at with the subject API Key Request. Please describe why you want an API key and what you plan to use it with. As of 3/27/2017, an API key is no longer required.

Checking if an account is MCLeaks


Uses a callback and a separate (pooled) thread in order to ensure the calling thread never blocks.

Using usernames (not recommended)
api.checkAccount(playerName, isMCLeaks ->
                System.out.println("Got: " + isMCLeaks), Throwable::printStackTrace);

The first parameter denotes the account username to check. Following that, a Consumer is used as a callback for your result. If an error was thrown, the second Consumer acts as an error handler.

You aren't recommended on using this method as names can change, causing a MCLeaks account to be flagged as a real account.

Using UUIDs (recommended)
api.checkAccount(playerUUID, isMCLeaks ->
                System.out.println("Got: " + isMCLeaks), Throwable::printStackTrace);

Using the previous format, the first parameter now represents the account uuid to check. The same results will be returned as with the other method, however this method likely to be more consistent in the event that a player changes their username.


Blocks the thread calling the method until either the account has been checked or an error has occurred checking the account. Regarding the Bukkit API, blocking thread within the AsyncPlayerPreLoginEvent can be useful to delay the players' login until the API has finished its request.

Using usernames (not recommended)
final MCLeaksAPI.Result nameResult = api.checkAccount(playerName);

Checks an account by its username, blocking the main thread until finishing its execution. As stated above, this method may return inconsistent results.

Using UUIDs (recommended)
final MCLeaksAPI.Result uuidResult = api.checkAccount(playerUUID);

Blocks the main thread until it has finished checking the account by its uuid.

Interacting with the MCLeaksAPI.Result is simple, using its 3 respective methods. Use #isMCLeaks to, as the name implies, see if the account was MCLeaks. If an error has occurred, #getError can be used to handle it appropriately. As a convenience method, #hasError is provided to check if an error has occurred. #getError will return null if no error has arisen.

Using the cache'd result

The API provides a method to retrieve a username/uuid's mcleaks status without causing a request to be sent. This is useful in circumstances where you would like to check if a username/uuid is cache'd.

Getting cache'd username result (not recommended)
final Optional<Boolean> cachedName = api.getCachedCheck(playerName);
Getting cache'd UUID result (recommended)
final Optional<Boolean> cachedUUID = api.getCachedCheck(playerUUID);

Cleaning up


After your project (plugin or otherwise) has shut down, call the shutdown method to gracefully end lingering threads from the executor service. Any attempts to request something from the API will now result in an error.

The full example can be viewed here.


Build with mvn clean install. Get the jar out of the /target folder

The latest version can be found here.


For a full run down of all the methods, the JavaDocs can be seen here.

REST API Endpoints

Interested in making your own client or want to know all the available methods? Documentation of all the REST API Endpoints can be found here.

Rate Limiting

The API is limited to 8 requests a second with a burst allowance of 50 requests in cases of going above the rate limit for a short period of time. Implementation uses the token bucket algorithm. Should you exceed the limit there is currently no penalty besides having to wait 1 second before your next request. If you are exceeding this limit, use the contact below for an increase in your rate limit.


You can contact me regarding questions such as an increase in your rate limit or request an account be removed from the database. To contact me, use my email and please state what you are contacting me about in the subject line (either Question - *summarization of question* or Account Removal Request - *account name*) If you are contacting me regarding removing an account, you must make sure to have changed the password before doing so. I will not remove an account if I am still able to log in as it.


This project is licensed under the MIT License.

You can’t perform that action at this time.