> For the complete documentation index, see [llms.txt](https://warmania.gitbook.io/paperx-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://warmania.gitbook.io/paperx-documentation/api-reference/paperx-api.md).

# PaperX API

## PaperX API

#### Install the jar <a href="#install-the-jar" id="install-the-jar"></a>

\*Make sure to change the path to the jar, and the jar name if needed.

```
mvn install:install-file -Dfile=pathtoyourjar\PaperX.jar -DgroupId=com.paperx -DartifactId=PaperX -Dversion=1.3 -Dpackaging=jar
```

#### Add the maven dependency <a href="#add-the-maven-dependency" id="add-the-maven-dependency"></a>

```
<dependency>
    <groupId>com.paperx</groupId>
    <artifactId>PaperX</artifactId>
    <version>1.3</version> <!-- Latest version here -->
    <scope>provided</scope>
</dependency>
```

#### Add PaperX to the plugin.yml <a href="#add-playerconsole-to-the-plugin.yml" id="add-playerconsole-to-the-plugin.yml"></a>

```
depend: [PaperX]
```

### Basic Usage

#### Check a balance

```java
// Normal Balance
double dollars = PaperXAPI.getDollars(player);

// Gems
double gems = PaperXAPI.getGems(player);

// Crafts
int crafts = PaperXAPI.getCrafts(player);

// Any custom currency by id
double tokens = PaperXAPI.getBalance(player, "tokens");
```

#### Give currency to a player

```java
// Give 500$
PaperXAPI.depositDollars(player, 500.0);

// Give 100 gems
PaperXAPI.addGems(player, 100.0);

// Give 50 crafts
PaperXAPI.addCrafts(player, 50);

// Give any custom currency ( In this example, tokens )
PaperXAPI.deposit(player, "tokens", 200.0);
```

#### Take currency from a player

```java
// Returns false if player doesn't have enough of the currency
boolean success = PaperXAPI.withdrawDollars(player, 250.0);

boolean success = PaperXAPI.removeGems(player, 50.0);

boolean success = PaperXAPI.removeCrafts(player, 10);

boolean success = PaperXAPI.withdraw(player, "tokens", 100.0);
```

#### Check if a player has enough

```java
boolean canAfford = PaperXAPI.hasDollars(player, 1000.0);
boolean hasGems   = PaperXAPI.hasGems(player, 50.0);
boolean hasCrafts = PaperXAPI.hasCrafts(player, 20);
boolean hasTokens = PaperXAPI.has(player, "tokens", 100.0);
```

#### Set a balance directly

```java
PaperXAPI.setBalance(player, "dollar",  5000.0);
PaperXAPI.setGems(player,   250.0);
PaperXAPI.setCrafts(player, 100);
PaperXAPI.setBalance(player, "tokens",  999.0);
```

### Custom Currencies

#### Register a currency

java

```java
// registerCurrency(id, displayName, symbol, decimals, boosterEnabled)
PaperXAPI.registerCurrency("tokens", "Tokens", "🪙", true, false);

// Shorter version | decimals=true, boosterEnabled=false by default
PaperXAPI.registerCurrency("tokens", "Tokens", "🪙");
```

#### Get currency info

```java
import com.paperx.CurrencyManager.Currency;

Currency tokens = PaperXAPI.getCurrency("tokens");
if (tokens != null) {
    String name   = tokens.getDisplayName(); // "tokens"
    String symbol = tokens.getSymbol();      // "<symbol>"
    boolean dec   = tokens.hasDecimals();    // true / false
}
```

#### List of all currencies

```java
for (Currency c : PaperXAPI.getAllCurrencies()) {
    String id   = c.getId();
    String name = c.getDisplayName();
}
```

#### Unregister a currency

```java
boolean removed = PaperXAPI.unregisterCurrency("tokens");
```

### Leaderboard Example

```java
import java.util.List;
import java.util.Map;
import java.util.UUID;

// ( Gets the top 10 people by gems )
List<Map.Entry<UUID, Double>> top = PaperXAPI.getTopBalances("gems", 10);

for (int i = 0; i < top.size(); i++) {
    UUID   uuid    = top.get(i).getKey();
    double balance = top.get(i).getValue();
    String name    = Bukkit.getOfflinePlayer(uuid).getName();
    Bukkit.getLogger().info("#" + (i + 1) + " " + name + " — " + balance);
}
```

***

### Formatting

```java
// It will be: "$1,500.00"
String fmt = PaperXAPI.format("dollar", 1500.0);

// It will be: "250"
String fmt = PaperXAPI.format("tokens", 250.0);
```

***

### Imports

```actionscript-3
import com.paperx.PaperXAPI;
import com.paperx.CurrencyManager;
import com.paperx.CurrencyManager.Currency;
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://warmania.gitbook.io/paperx-documentation/api-reference/paperx-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.