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

# EdPerks API

`es.edwardbelt.edperks.iapi.EdPerksAPI` is the public entry point. Obtain the singleton with `EdPerksAPI.getInstance()` (see [Introduction](/p/edperks/developers/introduction.md#getting-the-api)).

```java
package es.edwardbelt.edperks.iapi;

public interface EdPerksAPI {

    // --- Provider SPI ---
    void registerProvider(PerkProvider provider);
    List<PerkProvider> getProviders();
    PerkProvider getActiveProvider(Player player);

    // --- Perk on a tool item ---
    AppliedPerk getPerk(ItemStack tool);
    ItemStack setPerk(ItemStack tool, String perkId, int level);
    ItemStack clearPerk(ItemStack tool);
    AppliedPerk roll(Player player);

    // --- Tickets ---
    int getTickets(UUID playerId);
    void addTickets(UUID playerId, int amount);
    int getTotalRolls(UUID playerId);

    static void setInstance(EdPerksAPI instance);
    static EdPerksAPI getInstance();
}
```

***

## Provider methods

#### `void registerProvider(PerkProvider provider)`

Registers a host provider so its tools can carry perks. Safe to call from another plugin's `onEnable`. See the [PerkProvider SPI](/p/edperks/developers/edperks-api/perk-provider.md).

#### `List<PerkProvider> getProviders()`

All registered providers.

#### `PerkProvider getActiveProvider(Player player)`

The provider managing the player's **currently held** tool, or `null` if they hold no perkable tool.

***

## Perk methods

#### `AppliedPerk getPerk(ItemStack tool)`

The perk applied to `tool`, or `null` if it carries none. The returned [`AppliedPerk`](/p/edperks/developers/edperks-api/perk-provider.md#appliedperk) exposes the perk id, display name, level and resolved boost map.

```java
AppliedPerk perk = api.getPerk(player.getInventory().getItemInMainHand());
if (perk != null) {
    getLogger().info(perk.getDisplayName() + " level " + perk.getLevel());
    double money = perk.boost("money"); // 0 if not boosted
}
```

#### `ItemStack setPerk(ItemStack tool, String perkId, int level)`

Stamps `perkId` at `level` onto `tool` and returns the modified item. `perkId` must be a loaded perk (the file name in `perks/`).

#### `ItemStack clearPerk(ItemStack tool)`

Removes any perk from `tool` and returns the modified item.

#### `AppliedPerk roll(Player player)`

Rolls and applies a perk to the player's held tool, honouring pity. Returns the rolled perk, or `null` if the player has no perkable tool / the roll produced nothing. This is the same engine the menu's `[roll]` button uses (but does not itself consume a ticket — that's the menu's responsibility; use it for admin/event grants).

***

## Ticket methods

#### `int getTickets(UUID playerId)`

The player's current Perk Ticket balance.

#### `void addTickets(UUID playerId, int amount)`

Adds `amount` tickets (negative to subtract). Ideal for webstore / donation integrations.

#### `int getTotalRolls(UUID playerId)`

The player's lifetime roll count.

***

## Threading

All item and player operations must run on the **server main thread** (they mutate inventories). Ticket reads/writes are backed by the async-correct storage service and are safe to call from the main thread.

***

Next: the [PerkProvider SPI](/p/edperks/developers/edperks-api/perk-provider.md) — how to make your own plugin a host.


---

# 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://edseries-plugins.gitbook.io/p/edperks/developers/edperks-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.