> ## Documentation Index
> Fetch the complete documentation index at: https://mythicframework.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Finance - Crypto

> Cryptocurrency coin management, wallets, and exchange operations

The Crypto component manages cryptocurrency coins, player wallets, and exchange operations (buying, selling, transferring).

## Overview

Access via `Crypto` (server-side only).

<CardGroup cols={2}>
  <Card title="Coin Management" icon="coins">
    Create and manage coin types
  </Card>

  <Card title="Wallets" icon="wallet">
    Player crypto holdings
  </Card>

  <Card title="Exchange" icon="arrow-right-arrow-left">
    Buy, sell, and transfer crypto
  </Card>
</CardGroup>

<Note>
  Crypto balances are stored in the character's data as `Crypto[ACRONYM] = amount`. Players access crypto through a CryptoWallet ID linked to their character.
</Note>

***

## Coin Management

### Crypto.Coin:Create

Register or update a cryptocurrency type.

```lua theme={null}
Crypto.Coin:Create(name, acronym, price, buyable, sellable)
```

<ParamField path="name" type="string" required>
  Full coin name (e.g., "Bitcoin")
</ParamField>

<ParamField path="acronym" type="string" required>
  Short identifier (e.g., "BTC")
</ParamField>

<ParamField path="price" type="number" required>
  Price per unit in dollars
</ParamField>

<ParamField path="buyable" type="boolean" required>
  Whether players can buy this coin
</ParamField>

<ParamField path="sellable" type="boolean" required>
  Whether players can sell this coin
</ParamField>

**Example:**

```lua theme={null}
-- Register coins
Crypto.Coin:Create('Bitcoin', 'BTC', 50000, true, true)
Crypto.Coin:Create('Cayo Coin', 'CAYO', 150, true, false)  -- Can buy, can't sell
```

***

### Crypto.Coin:Get

Get data for a specific coin.

```lua theme={null}
Crypto.Coin:Get(acronym)
```

<ResponseField name="coin" type="table|nil">
  Coin data or `nil` if not registered
</ResponseField>

***

### Crypto.Coin:GetAll

Get all registered coins.

```lua theme={null}
Crypto.Coin:GetAll()
```

<ResponseField name="coins" type="table">
  Array of all registered coin data
</ResponseField>

***

## Wallet Operations

### Crypto:Has

Check if a player owns a minimum amount of a coin.

```lua theme={null}
Crypto:Has(source, coin, amount)
```

<ParamField path="source" type="number" required>
  Player server ID
</ParamField>

<ParamField path="coin" type="string" required>
  Coin acronym (e.g., "BTC")
</ParamField>

<ParamField path="amount" type="number" required>
  Minimum amount to check
</ParamField>

<ResponseField name="has" type="boolean">
  `true` if player owns >= amount
</ResponseField>

**Example:**

```lua theme={null}
if Crypto:Has(source, 'BTC', 2) then
    -- Player has at least 2 BTC
end
```

***

## Exchange Operations

### Crypto.Exchange:IsListed

Check if a coin is tradeable on the exchange.

```lua theme={null}
Crypto.Exchange:IsListed(coin)
```

***

### Crypto.Exchange:Buy

Purchase cryptocurrency using the player's bank account.

```lua theme={null}
Crypto.Exchange:Buy(coin, target, amount)
```

<ParamField path="coin" type="string" required>
  Coin acronym
</ParamField>

<ParamField path="target" type="number" required>
  Character State ID (SID) of the buyer
</ParamField>

<ParamField path="amount" type="number" required>
  Amount of coin to buy
</ParamField>

<ResponseField name="success" type="boolean">
  `true` if purchase was successful
</ResponseField>

**Example:**

```lua theme={null}
local char = Fetch:Source(source):GetData('Character')
local stateId = char:GetData('SID')

-- Buy 2 BTC for the player
Crypto.Exchange:Buy('BTC', stateId, 2)
```

***

### Crypto.Exchange:Sell

Sell cryptocurrency back for bank balance.

```lua theme={null}
Crypto.Exchange:Sell(coin, target, amount)
```

<ParamField path="coin" type="string" required>
  Coin acronym (must be sellable)
</ParamField>

<ParamField path="target" type="number" required>
  Character State ID (SID) of the seller
</ParamField>

<ParamField path="amount" type="number" required>
  Amount of coin to sell
</ParamField>

<ResponseField name="result" type="number|boolean">
  New balance or `false` if failed
</ResponseField>

***

### Crypto.Exchange:Add

Add cryptocurrency directly to a wallet (no bank charge).

```lua theme={null}
Crypto.Exchange:Add(coin, target, amount, skipAlert)
```

<ParamField path="coin" type="string" required>
  Coin acronym
</ParamField>

<ParamField path="target" type="string" required>
  CryptoWallet ID (from `char:GetData('CryptoWallet')`)
</ParamField>

<ParamField path="amount" type="number" required>
  Amount to add
</ParamField>

<ParamField path="skipAlert" type="boolean" optional>
  Skip phone notification
</ParamField>

**Example:**

```lua theme={null}
-- Reward crypto for completing a job
local char = Fetch:Source(source):GetData('Character')
local walletId = char:GetData('CryptoWallet')

Crypto.Exchange:Add('BTC', walletId, 0.5)
```

***

### Crypto.Exchange:Remove

Remove cryptocurrency from a wallet.

```lua theme={null}
Crypto.Exchange:Remove(coin, target, amount, skipAlert)
```

<ResponseField name="success" type="boolean">
  `true` if successfully removed
</ResponseField>

***

### Crypto.Exchange:Transfer

Transfer cryptocurrency between two wallets.

```lua theme={null}
Crypto.Exchange:Transfer(coin, sender, target, amount)
```

<ParamField path="coin" type="string" required>
  Coin acronym
</ParamField>

<ParamField path="sender" type="number" required>
  Sender's State ID (SID)
</ParamField>

<ParamField path="target" type="string" required>
  Recipient's CryptoWallet ID
</ParamField>

<ParamField path="amount" type="number" required>
  Amount to transfer
</ParamField>

<ResponseField name="success" type="boolean">
  `true` if transfer was successful
</ResponseField>

**Example:**

```lua theme={null}
-- Transfer crypto between players
local char = Fetch:Source(source):GetData('Character')
local senderSID = char:GetData('SID')
local targetWalletId = '...' -- Recipient's CryptoWallet ID

local success = Crypto.Exchange:Transfer('BTC', senderSID, targetWalletId, 1.5)
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Finance - Banking" icon="building-columns" href="/api/finance/banking">
    Bank account operations
  </Card>

  <Card title="Finance - Payments" icon="money-bill-transfer" href="/api/finance/payments">
    Bills and fines
  </Card>

  <Card title="Characters API" icon="user" href="/api/characters/exports">
    Character data access
  </Card>
</CardGroup>