# API

**Assembly:** `Spark.Currency` **Interface:** `ICurrencyPlugin` **Implementation:** `CurrencyPlugin`

## Interface

```csharp
public interface ICurrencyPlugin
{
    // Wallet management
    WalletInstance CreateWallet(string walletId = null);
    WalletInstance CreateEntityWallet(string entityId, string walletId = null);
    WalletInstance GetWallet(string walletId);
    WalletInstance GetEntityWallet(string entityId);
    bool DestroyWallet(string walletId);

    // Currency operations
    bool AddCurrency(string walletId, string currencyId, long amount,
        bool suppressEvents = false, GameObject source = null);
    bool RemoveCurrency(string walletId, string currencyId, long amount,
        bool suppressEvents = false, GameObject source = null);
    bool SetCurrency(string walletId, string currencyId, long amount,
        bool suppressEvents = false, GameObject source = null);
    bool HasCurrency(string walletId, string currencyId, long amount);
    long GetCurrencyAmount(string walletId, string currencyId);

    // Transfer
    bool TransferCurrency(string sourceWalletId, string targetWalletId,
        string currencyId, long amount);

    // Conversion
    bool ProcessConversion(string walletId, string conversionEntryId,
        long count = -1);

    // Database queries
    List<CurrencyEntry> GetAllCurrencies();
    CurrencyEntry GetCurrency(string currencyId);
    List<CurrencyConversionEntry> GetAllConversions();
    CurrencyConversionEntry GetConversion(string conversionId);
}
```

## CurrencyEntry

Extends `SparkDatabaseEntry`. Defines a currency type.

| Field             | Type                    | Description                     |
| ----------------- | ----------------------- | ------------------------------- |
| `currencySymbol`  | string                  | Display symbol (e.g., "G", "$") |
| `maxAmount`       | long                    | Maximum amount (0 = unlimited)  |
| `startingAmount`  | long                    | Initial wallet amount           |
| `displayColor`    | Color                   | UI display color                |
| `displayFormat`   | CurrencyDisplayFormat   | Full or Abbreviate              |
| `conversionEntry` | CurrencyConversionEntry | Auto-conversion rule            |

**Methods:**

```csharp
string FormatAmount(long amount)
bool HasMaximumLimit()
long GetMaxAmount()
long GetStartingAmount()
```

## CurrencyConversionEntry

Extends `SparkDatabaseEntry`. Defines an exchange rate between currencies.

| Field            | Type          | Description                 |
| ---------------- | ------------- | --------------------------- |
| `sourceCurrency` | CurrencyEntry | Currency to convert from    |
| `targetCurrency` | CurrencyEntry | Currency to convert to      |
| `sourceAmount`   | long          | How much source is consumed |
| `targetAmount`   | long          | How much target is produced |

## WalletInstance

Runtime wallet managing currency balances.

**Methods:**

```csharp
bool Add(string currencyId, long amount)
bool Remove(string currencyId, long amount)
bool Has(string currencyId, long amount)
long GetAmount(string currencyId)
void SetAmount(string currencyId, long amount)
bool TryConvert(string conversionEntryId, long count)
Dictionary<string, long> GetAllCurrencies()
```

**Events:** `OnCurrencyChanged`, `OnCurrencyConverted`

Auto-conversion is supported with a maximum chain depth of 10 to prevent infinite loops.

## Events

| Event                      | Fields                                                | Description              |
| -------------------------- | ----------------------------------------------------- | ------------------------ |
| `CurrencyAddedEvent`       | WalletId, EntityId, CurrencyId, Amount, NewTotal      | Currency added           |
| `CurrencyRemovedEvent`     | WalletId, EntityId, CurrencyId, Amount, NewTotal      | Currency removed         |
| `CurrencySetEvent`         | WalletId, EntityId, CurrencyId, OldAmount, NewAmount  | Currency set directly    |
| `CurrencyConvertedEvent`   | WalletId, SourceCurrencyId, TargetCurrencyId, Amounts | Conversion executed      |
| `CurrencyTransferredEvent` | SourceWalletId, TargetWalletId, CurrencyId, Amount    | Transfer between wallets |
| `WalletCreatedEvent`       | WalletId, EntityId                                    | New wallet created       |
| `WalletDestroyedEvent`     | WalletId, EntityId                                    | Wallet destroyed         |

All currency events are struct-based `ISparkEvent` implementations.

## Commands

| Command                   | Description                       |
| ------------------------- | --------------------------------- |
| `AddCurrencyCommand`      | Add currency to a wallet          |
| `RemoveCurrencyCommand`   | Remove currency from a wallet     |
| `SetCurrencyCommand`      | Set currency to a specific amount |
| `ConvertCurrencyCommand`  | Execute a currency conversion     |
| `TransferCurrencyCommand` | Transfer between wallets          |
| `CreateWalletCommand`     | Create a new wallet               |
| `DestroyWalletCommand`    | Destroy a wallet                  |

## Components

| Component         | Description                               |
| ----------------- | ----------------------------------------- |
| `WalletEntity`    | Manages a wallet on a character entity    |
| `CurrencyDisplay` | UI component for showing currency amounts |

## Save Data

`CurrencyPluginSaveData` stores serialized wallet data per entity, including currency amounts.

## Usage

```csharp
var currency = Spark.GetPlugin<ICurrencyPlugin>();
if (currency != null)
{
    // Create a wallet for an entity
    var wallet = currency.CreateEntityWallet(entityId);

    // Add gold
    currency.AddCurrency(wallet.WalletId, "gold", 100);

    // Check if player can afford something
    if (currency.HasCurrency(wallet.WalletId, "gold", 50))
    {
        currency.RemoveCurrency(wallet.WalletId, "gold", 50);
    }

    // Transfer between wallets
    currency.TransferCurrency(playerWalletId, shopWalletId, "gold", 200);

    // Convert currency (e.g., 100 copper -> 1 silver)
    currency.ProcessConversion(wallet.WalletId, "copper_to_silver");
}
```


---

# 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://docs.sparkframework.dev/documentation/developer-guide/plugins/currency/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.