Installation

Get CoinsX running on your server in under a minute.

• 1
  Download the latest CoinsX.jar from the AERIUMSTUDIO resource page.
• 2
  Drop the jar into your server's /plugins/ folder.
• 3
  Restart your server. CoinsX will generate its config files at plugins/CoinsX/.
• 4
  (Optional) Install PlaceholderAPI to enable %coinsx_..% placeholders.
• 5
  Open a port (default 8765) in your firewall if you want to use the Web API / leaderboard website.

Configuration

Main settings are in plugins/CoinsX/config.yml. Every option is commented inline.

config.yml

# Default currency when none is specified
default-currency: coins

database:
  type: sqlite          # sqlite | mysql
  mysql:
    host: localhost
    port: 3306
    database: coinsx
    username: root
    password: ''

web-api:
  enabled: true
  port: 8765
  secret-token: 'change_me_please'  # for POST endpoints
  cors-origin: '*'             # your website origin or *
  leaderboard-cache-seconds: 30

economy:
  default-starting-balance: 0.0
  max-balance: 0            # 0 = no limit
  allow-negative: false
  min-pay-amount: 1.0
  pay-tax: 0.0              # percentage, 0 = no tax

leaderboard:
  entries-per-page: 10
  refresh-interval: 60     # seconds

Currency Config (Currency/coins.yml)

name: '<gradient:#f5a623:#f9d05e>Coins</gradient>'
name-plain: Coins
symbol: ⛃
symbol-position: before    # before | after
decimal-places: 0
starting-balance: 0
compact-format: true       # 1500 → 1.5K
payable: true
show-in-leaderboard: true
placeholder-enabled: true

Commands

All commands support tab-completion. <required> · [optional]

Player Commands

Admin Commands

Permissions

All permissions follow the coinsx.* namespace. OP players inherit all permissions by default.

PlaceholderAPI

Replace <currency> with your currency ID (e.g. coins, tokens). Replace <rank> with a number like 1, 2, 3…

Player Balance

Leaderboard (by Rank)

Player Rank & Stats

Web API — Overview

CoinsX ships with a built-in HTTP server. No extra software needed — just open the port and start making requests.

Web API — Endpoints

All public GET endpoints require no authentication.

GET /api/currencies

Returns a list of all registered currencies.

GET /api/leaderboard/{currency}

Returns the top 100 players for a currency. Supports pagination via query params.

GET /api/player/{uuid}/{currency}

Returns the balance of a specific player by UUID.

GET /api/stats

Returns live server and economy stats.

Web API — Protected Endpoints

These POST endpoints modify balances. They require a Bearer token set in your config.yml.

Request Format

POST /api/give
Authorization: Bearer your_secret_token
Content-Type: application/json

{
  "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
  "name": "Notch",
  "currency": "coins",
  "amount": 500
}

Tutorial — Setup API Server

Before building your website, make sure CoinsX's Web API is reachable from outside your server.

• 1
  In config.yml, set web-api.enabled: true and choose a port that is allocated in your panel.
• 2
  Make sure the port is allocated in Pterodactyl (or open in your VPS firewall: ufw allow PORT/tcp).
• 3
  Change secret-token to a strong random string — this protects your POST endpoints.
• 4
  Upload coinsx_proxy.php + coinsx_config.php to your website's backend/ folder to bypass HTTPS restrictions.
• 5
  Test the proxy: visit https://yoursite.com/backend/coinsx_proxy.php?path=/api/stats — you should see JSON.

Tutorial — Build a Leaderboard Page

A complete working leaderboard page using vanilla HTML + JavaScript + PHP proxy. No frameworks needed.

leaderboard.html// Call your PHP proxy instead of the MC server directly
const PROXY = 'backend/coinsx_proxy.php';

async function fetchJson(path) {
  const [cleanPath, qs] = path.split('?');
  let url = PROXY + '?path=' + encodeURIComponent(cleanPath);
  if (qs) url += '&' + qs;
  const r = await fetch(url);
  return r.json();
}

async function loadLeaderboard() {
  const data = await fetchJson('/api/leaderboard/coins?per_page=10');
  const tbody = document.getElementById('lb');
  tbody.innerHTML = '';
  for (const entry of data.entries) {
    tbody.innerHTML += `<tr>
      <td>#${entry.rank}</td>
      <td>${entry.name}</td>
      <td>${entry.formattedCompact}</td>
    </tr>`;
  }
}
loadLeaderboard();
setInterval(loadLeaderboard, 30000); // refresh every 30s

Tutorial — Player Balance Lookup

Let players look up their own balance (or any player's) by UUID on your website.

balance.htmlasync function lookupBalance() {
  const uuid     = document.getElementById('uuid').value.trim();
  const currency = document.getElementById('currency').value.trim();
  if (!uuid || !currency) return;

  const data = await fetchJson(`/api/player/${uuid}/${currency}`);

  if (data.success) {
    document.getElementById('result').textContent =
      `${data.name ?? uuid}: ${data.formattedCompact} (${data.formatted})`;
  } else {
    document.getElementById('result').textContent = 'Player not found.';
  }
}

Tutorial — Admin Panel (Give/Take/Set)

Use the protected POST endpoints from a server-side backend — never call these from the browser directly as that would expose your secret token.

PHP Example

admin.php<?php
require_once 'coinsx_config.php';

function coinsx_give($uuid, $name, $currency, $amount) {
  $ch = curl_init(COINSX_URL . '/api/give');
  curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
      'Content-Type: application/json',
      'Authorization: Bearer ' . COINSX_KEY
    ],
    CURLOPT_POSTFIELDS => json_encode([
      'uuid' => $uuid, 'name' => $name,
      'currency' => $currency, 'amount' => $amount
    ])
  ]);
  $r = json_decode(curl_exec($ch), true);
  curl_close($ch);
  return $r;
}

// Usage
$r = coinsx_give('069a79f4-...', 'Notch', 'coins', 500);
echo "New balance: " . $r['newBalance'];
?>

Java Developer API

Hook into CoinsX from your own plugins using the CoinsXAPI class.

MyPlugin.java// Get the API instance
CoinsXAPI api = CoinsX.getInstance().getAPI();

// Check balance
double balance = api.getBalance(player, "coins");

// Give coins
api.give(player, "coins", 500);

// Take coins (returns false if not enough)
boolean success = api.take(player, "coins", 100);

// Set exact balance
api.setBalance(player, "coins", 1000);

// Check if player has enough
boolean hasEnough = api.has(player, "coins", 250);

// Get top 10 leaderboard
List<LeaderboardEntry> top = api.getLeaderboardPage("coins", 1, 10);
for (LeaderboardEntry entry : top) {
    plugin.getLogger().info("#" + entry.getRank() + " " + entry.getName()
        + ": " + entry.getBalance());
}

Currency Config Reference

Each file in plugins/CoinsX/Currency/ defines one currency. The filename (without .yml) is the currency ID.