# API Access

We have three data objects: `AccountData`, `CoinsData`, and `VirtualData`. Both `CoinsData` and `VirtualData` are stored within the `AccountData` object, with `VirtualData` being stored as a `List<VirtualData>`.

## Use LightCoins as a maven dependency

```xml
<repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
</repository>

<dependency>
    <groupId>com.github.lightPlugins</groupId>
    <artifactId>lightCcins</artifactId>
    <!-- Make sure you are using the latest version! -->
    <version>CurrentVersion</version>
    <scope>provided</scope>
</dependency>
```

## Use LightCoins as a gradle dependency

```gradle
repositories {
	mavenCentral()
	maven { url 'https://jitpack.io' }
}

dependencies {
        implementation 'com.github.lightPlugins:lightCoins:Tag'
}
```

## Some examples of how to use the API

First, let's understand how LightCoins works and how it is structured.

```java
public class SomeEconomyClass {
    
    /**
     * Get the LightCoinsAPI instance
     * Do not create a new instance of LightCoinsAPI, use this method instead
     * @return The LightCoinsAPI instance
     */
    public LightCoinsAPI getLightCoinsAPI() {
        return LightCoins.instance.getLightCoinsAPI();
    }
    
    /**
     * Get the account data of a player
     * @param playerName The name of the player. Can be a UUID, String or OfflinePlayer object.
     * @return The account data object of the target player. Can be null!
     */
    public AccountData getAccountData(String playerName) {
        return getLightCoinsAPI().getAccountData(playerName);
    }
    
    /**
     * Get the coins data of a player (Default Currency)
     * @param playerName The name of the player. Can be a UUID, String or OfflinePlayer object.
     * @return The coins data object of the target player. Can be null!
     */
    public CoinsData getCoinsData(String playerName) {
        return getAccountData(playerName).getCoinsData();
    }
    
    /**
     * Get the virtual data of a player (Virtual Currency)
     * @param playerName The name of the player. Can be a UUID, String or OfflinePlayer object.
     * @return The virtual data object of the target player. Can be null!
     */
    public List<VirtualData> getVirtualData(String playerName) {
        return getAccountData(playerName).getVirtualCurrencies();
    }
    
    /**
     * Get the specified virtual data of a player (Virtual Currency)
     * @param playerName The name of the player. Can be a UUID, String or OfflinePlayer object.
     * @param currencyName The name of the virtual currency
     * @return The virtual data object of the target player. Can be null!
     */
    public VirtualData getSomeCustomCurrency(UUID uuid, String currencyName) {
        return getAccountData(uuid).getVirtualCurrencyByName(currencyName);
    }
}
```

Lets do some transaction with the default Currency (Vault). In this case we add some amount of coins to a specified player.

```java
/**
 * Add coins to a player
 * @param uuid The uuid of the player. Can be a UUID, String(playername) 
 *             or OfflinePlayer object.
 * @param amount The amount of coins to add
 * @return The economy response object
 */
public EconomyResponse addCoinsToPlayer(UUID uuid, BigDecimal amount) {
    return getCoinsData(uuid).addCoins(amount);
}


public void someMethode(Player player) {
    
    UUID uuid = player.getUniqueId();
    BigDecimal amount = BigDecimal.valueOf(100);
    
    EconomyResponse response = addCoinsToPlayer(uuid, amount);
    
    if(response.transactionSuccess()) {
        // transaction was successful
    } else {
        // transaction failed
        player.sendMessage("Transaction failed: " + response.errorMessage);
    }
}
```

Let's interact with a custom currency. In this case, we are looking for "gems" and want to remove some of them. Here is an example of how it works

```java
/**
 * Remove coins from a player
 * @param uuid The uuid of the player.
 * @param amount The amount of coins to remove
 * @return The economy response object
 */
public VirtualResponse removeCoinsFromPlayer(UUID uuid, String gemsCurrency, BigDecimal amount) {
    // Get the virtual data of the player
    VirtualData virtualData = getAccountData(uuid).getVirtualCurrencyByName(gemsCurrency);
    // Check if the currency exists
    if(virtualData != null) {
        // Remove the balance from the player
        return virtualData.removeBalance(amount);
    }
    // return a new virtual response with a custom failure message
    return new VirtualResponse(new BigDecimal(0), new BigDecimal(0), 
            VirtualResponse.VirtualResponseType.FAILURE, "Currency not found");
    
}

public void anotherMethode(Player player) {

    UUID uuid = player.getUniqueId();
    BigDecimal amount = BigDecimal.valueOf(100);

    VirtualResponse response = removeCoinsFromPlayer(uuid, "gems", amount);

    if(response.transactionSuccess()) {
        // transaction was successful
    } else {
        // transaction failed, for e.g the player does not have enough gems
        player.sendMessage("Transaction failed: " + response.errorMessage);
    }
}
```

LightCoins comes also with Events. There are 2 Events currently. These events are only for the default currency (vault).

## Custom Events

* LightCoinsDepositEvent
* LightCoinsWithdrawEvent


---

# Agent Instructions: 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://lightplugins.gitbook.io/docs/lightcoins/api-access.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.