Coins API for plugins

Game modes pay and charge coins through GateCoins from Gate-Paper. The proxy books everything in the database, so balances stay correct across servers.

Set it up

Add Gate-Paper as a dependency in your plugin.yml and compile against its jar.

depend: [ Gate-Paper ]

Pay a reward once

The idempotency key makes a booking happen at most once for 7 days, so a retry after a timeout never pays twice.

String key = "meetup-" + roundId + "-" + player.getUniqueId();
GateCoins.add(player.getUniqueId(), 50, "Meetup", "Round won", key)
    .thenAccept(result -> {
        if (!result.duplicate()) {
            player.sendMessage("You earned 50 coins. Balance: " + result.balance());
        }
    })
    .exceptionally(error -> {
        getLogger().warning("Coins not booked: " + error.getMessage());
        return null;
    });

Calls return a CompletableFuture and never block the server thread. Check GateCoins.isAvailable() if you need to know whether the proxy connection is up.

Reference

Method What it does

static boolean isAvailable() True when the connection to the proxy coin service is running.

static CompletableFuture<Long> balance(UUID uuid) Current balance, also for offline players.

static CompletableFuture<Long> balance(Player player) Current balance of an online player.

static CompletableFuture<Boolean> has(UUID uuid, long amount) Whether the player has at least the amount.

static OptionalLong cached(UUID uuid) Balance from memory for players online on this server, available after join loading.

static OptionalLong cached(Player player) Same as cached(UUID) for a player.

static CompletableFuture<Result> add(UUID uuid, long amount, String source, String reason) Adds coins; source is the game mode name (max 48 chars), reason optional (max 255).

static CompletableFuture<Result> add(UUID uuid, long amount, String source, String reason, String idempotencyKey) Adds coins; the same key is booked at most once for 7 days.

static CompletableFuture<Result> remove(UUID uuid, long amount, String source, String reason) Removes coins; fails with CoinsException.Reason.INSUFFICIENT if the balance is too low (nothing is removed).

static CompletableFuture<Result> remove(UUID uuid, long amount, String source, String reason, String idempotencyKey) Removes coins with an idempotency key.

record Result(long balance, long delta, boolean duplicate) Result of a booking: new balance, change, and whether the idempotency key was already used.

Reason reason() Failure reason: INSUFFICIENT, INVALID, UNAVAILABLE or TIMEOUT.

long balance() Current balance when the reason is INSUFFICIENT, otherwise 0.

Method	What it does
`static boolean isAvailable()`	True when the connection to the proxy coin service is running.
`static CompletableFuture<Long> balance(UUID uuid)`	Current balance, also for offline players.
`static CompletableFuture<Long> balance(Player player)`	Current balance of an online player.
`static CompletableFuture<Boolean> has(UUID uuid, long amount)`	Whether the player has at least the amount.
`static OptionalLong cached(UUID uuid)`	Balance from memory for players online on this server, available after join loading.
`static OptionalLong cached(Player player)`	Same as cached(UUID) for a player.
`static CompletableFuture<Result> add(UUID uuid, long amount, String source, String reason)`	Adds coins; source is the game mode name (max 48 chars), reason optional (max 255).
`static CompletableFuture<Result> add(UUID uuid, long amount, String source, String reason, String idempotencyKey)`	Adds coins; the same key is booked at most once for 7 days.
`static CompletableFuture<Result> remove(UUID uuid, long amount, String source, String reason)`	Removes coins; fails with CoinsException.Reason.INSUFFICIENT if the balance is too low (nothing is removed).
`static CompletableFuture<Result> remove(UUID uuid, long amount, String source, String reason, String idempotencyKey)`	Removes coins with an idempotency key.
`record Result(long balance, long delta, boolean duplicate)`	Result of a booking: new balance, change, and whether the idempotency key was already used.
`Reason reason()`	Failure reason: INSUFFICIENT, INVALID, UNAVAILABLE or TIMEOUT.
`long balance()`	Current balance when the reason is INSUFFICIENT, otherwise 0.