# API Reference

Complete technical reference for VibesEZ-Laptop APIs.

## Server Exports

### Crypto Functions

#### AddCrypto(identifier, currency, amount, note)

Add cryptocurrency to player wallet.

```lua
exports['VibesEZ-Laptop']:AddCrypto(identifier, currency, amount, note)
```

**Parameters:**

| Name       | Type   | Required | Description                    |
| ---------- | ------ | -------- | ------------------------------ |
| identifier | string | Yes      | Player identifier              |
| currency   | string | Yes      | Currency code (BTC, ETH, etc.) |
| amount     | number | Yes      | Amount to add                  |
| note       | string | Yes      | Transaction note               |

**Returns:**

| Type    | Description                         |
| ------- | ----------------------------------- |
| boolean | true if successful, false if failed |
| string  | Error message if failed             |

**Example:**

```lua
local success, err = exports['VibesEZ-Laptop']:AddCrypto(
    'char1:12345',
    'BTC',
    100,
    'Completed job'
)

if not success then
    print('Error: ' .. err)
end
```

**Errors:**

* "Invalid identifier"
* "Currency not found"
* "Negative amount"
* "Max supply exceeded" (Controlled mode)
* "Database error"

***

#### RemoveCrypto(identifier, currency, amount, note)

Remove cryptocurrency from player wallet.

```lua
exports['VibesEZ-Laptop']:RemoveCrypto(identifier, currency, amount, note)
```

**Parameters:**

| Name       | Type   | Required | Description       |
| ---------- | ------ | -------- | ----------------- |
| identifier | string | Yes      | Player identifier |
| currency   | string | Yes      | Currency code     |
| amount     | number | Yes      | Amount to remove  |
| note       | string | Yes      | Transaction note  |

**Returns:**

| Type    | Description        |
| ------- | ------------------ |
| boolean | true if successful |
| string  | Error message      |

**Example:**

```lua
local success, err = exports['VibesEZ-Laptop']:RemoveCrypto(
    playerId,
    'BTC',
    50,
    'Item purchase'
)
```

**Errors:**

* "Invalid identifier"
* "Currency not found"
* "Insufficient balance"
* "Negative amount"
* "Wallet doesn't exist"

***

#### GetBalance(identifier, currency)

Get player balance for specific currency.

```lua
local balance = exports['VibesEZ-Laptop']:GetBalance(identifier, currency)
```

**Parameters:**

| Name       | Type   | Required | Description       |
| ---------- | ------ | -------- | ----------------- |
| identifier | string | Yes      | Player identifier |
| currency   | string | Yes      | Currency code     |

**Returns:**

| Type   | Description                                |
| ------ | ------------------------------------------ |
| number | Wallet balance (0 if wallet doesn't exist) |
| nil    | If wallet/currency doesn't exist           |

**Example:**

```lua
local balance = exports['VibesEZ-Laptop']:GetBalance('char1:12345', 'BTC')
print('BTC Balance: ' .. (balance or 0))
```

**Notes:**

* Returns 0 or nil if wallet doesn't exist (config-dependent)
* Always validate return value

***

#### TransferCrypto(fromId, toId, currency, amount, note)

Transfer cryptocurrency between wallets.

```lua
local success, err = exports['VibesEZ-Laptop']:TransferCrypto(
    fromId, toId, currency, amount, note
)
```

**Parameters:**

| Name     | Type   | Required | Description         |
| -------- | ------ | -------- | ------------------- |
| fromId   | string | Yes      | Sender identifier   |
| toId     | string | Yes      | Receiver identifier |
| currency | string | Yes      | Currency code       |
| amount   | number | Yes      | Amount to transfer  |
| note     | string | Yes      | Transaction note    |

**Returns:**

| Type    | Description        |
| ------- | ------------------ |
| boolean | true if successful |
| string  | Error message      |

**Example:**

```lua
local success, err = exports['VibesEZ-Laptop']:TransferCrypto(
    player1, player2, 'BTC', 50, 'Game reward'
)
```

**Errors:**

* "Insufficient funds"
* "Invalid currency"
* "Invalid identifiers"
* "Transfer limit exceeded"
* "Receiver wallet doesn't exist"

***

#### GetWallets(identifier)

Get all wallets for a player.

```lua
local wallets = exports['VibesEZ-Laptop']:GetWallets(identifier)
```

**Parameters:**

| Name       | Type   | Required | Description       |
| ---------- | ------ | -------- | ----------------- |
| identifier | string | Yes      | Player identifier |

**Returns:**

```lua
{
    BTC = {
        address = "1A1z7agoat...",
        balance = 5.5,
        currency = "BTC"
    },
    ETH = {
        address = "0x742d35Cc...",
        balance = 25.0,
        currency = "ETH"
    }
}
```

**Example:**

```lua
local wallets = exports['VibesEZ-Laptop']:GetWallets('char1:12345')
for currency, wallet in pairs(wallets) do
    print(currency .. ': ' .. wallet.balance)
end
```

***

#### GetTransactionHistory(identifier, currency, limit)

Get transaction history for a wallet.

```lua
local transactions = exports['VibesEZ-Laptop']:GetTransactionHistory(
    identifier, currency, limit
)
```

**Parameters:**

| Name       | Type   | Required | Description                    |
| ---------- | ------ | -------- | ------------------------------ |
| identifier | string | Yes      | Player identifier              |
| currency   | string | No       | Filter by currency             |
| limit      | number | No       | Max transactions (default 100) |

**Returns:**

```lua
{
    {
        id = "tx_12345",
        type = "sent",
        amount = 50,
        recipient = "char1:67890",
        timestamp = 1234567890,
        note = "Payment",
        status = "confirmed"
    },
    -- ... more transactions
}
```

***

## Client Events

### Opening/Closing Laptop

```lua
-- Open laptop
TriggerEvent('laptop:client:open')

-- Close laptop
TriggerEvent('laptop:client:close')
```

***

## NUI Events

### From Server to NUI

```lua
SendNUIMessage({
    action = 'updateBalance',
    data = {
        currency = 'BTC',
        balance = 100.5
    }
})
```

### From NUI to Server

```javascript
fetch(`https://${GetParentResourceName()}/ServerCallback`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        action: 'getBalance',
        currency: 'BTC'
    })
})
```

***

## Configuration Files

### config/crypto.lua

```lua
Config.Crypto = {
    Enabled = true,
    EconomyMode = 'static',  -- static, controlled, simulated, liquidity
    DefaultCurrency = 'BTC',
    
    Currencies = {
        BTC = {
            name = 'Bitcoin',
            symbol = 'BTC',
            basePrice = 50000,
            -- Additional fields depend on economy mode
        }
    }
}
```

### config/apps.lua

```lua
Config.PreinstalledApps = {
    {
        id = 'notes',
        label = 'Notes',
        defaultInstalled = true
    }
}
```

***

## Error Codes

| Code | Message                 | Cause                | Solution                 |
| ---- | ----------------------- | -------------------- | ------------------------ |
| 1001 | Invalid identifier      | Bad player ID        | Verify identifier format |
| 1002 | Currency not found      | Unknown currency     | Check currency name      |
| 1003 | Insufficient balance    | Not enough funds     | Check balance first      |
| 1004 | Wallet doesn't exist    | Wallet not created   | Create wallet first      |
| 1005 | Database error          | DB connection failed | Check server logs        |
| 1006 | Transfer limit exceeded | Over daily limit     | Wait or adjust limits    |
| 1007 | Max supply exceeded     | Controlled mode cap  | Check maxSupply setting  |

***

## Data Types

### Wallet Object

```typescript
interface Wallet {
    address: string;        // Unique wallet address
    balance: number;        // Current balance
    currency: string;       // Currency code
    created: number;        // Creation timestamp
    lastTransaction: number; // Last tx timestamp
}
```

### Transaction Object

```typescript
interface Transaction {
    id: string;             // Unique transaction ID
    type: 'sent' | 'received' | 'exchange';
    amount: number;         // Transaction amount
    recipient?: string;     // Recipient identifier
    sender?: string;        // Sender identifier
    timestamp: number;      // Transaction time
    note: string;          // Transaction note
    status: 'pending' | 'confirmed' | 'failed';
    fee?: number;          // Transaction fee
}
```

***

## Rate Limits

| Operation   | Limit     | Duration   |
| ----------- | --------- | ---------- |
| Add Crypto  | 1000      | Per minute |
| Get Balance | Unlimited | Per second |
| Transfer    | 100       | Per minute |
| Get History | 50        | Per minute |

***

## Version Compatibility

| Version | Release Date | Status     |
| ------- | ------------ | ---------- |
| 1.0.0   | April 2026   | Active     |
| 0.9.0   | March 2026   | Deprecated |

***

## Changelog

### v1.0.0

* Initial release
* All core APIs stable
* Multi-currency support
* All economy modes

### Future

* Performance improvements
* Additional APIs based on feedback

***

***

## Integration Examples

### Job Reward System

```lua
-- resources/[jobs]/job_delivery/server.lua

local function completeDelivery(src, reward)
    local xPlayer = QBCore.Functions.GetPlayer(src)
    
    -- Add crypto reward
    exports['VibesEZ-Laptop']:AddCrypto(
        xPlayer.identifier,
        'BTC',
        reward,
        'Job: Package delivery completed'
    )
    
    TriggerClientEvent('chat:addMessage', src, {
        args = {'Dispatch', 'Delivery complete! ₿' .. reward .. ' received'}
    })
end

-- Event listener
RegisterNetEvent('job:delivery:complete', function(reward)
    completeDelivery(source, reward)
end)
```

### Store Payment System

```lua
-- resources/[stores]/store_system/server.lua

local function processPayment(buyer, seller, amount, item)
    -- Check buyer has funds
    local balance = exports['VibesEZ-Laptop']:GetBalance(buyer, 'BTC')
    
    if not balance or balance < amount then
        return false, 'Insufficient funds'
    end
    
    -- Process transfer
    local success = exports['VibesEZ-Laptop']:TransferCrypto(
        buyer,
        seller,
        'BTC',
        amount,
        'Purchase: ' .. item
    )
    
    return success
end

RegisterNetEvent('store:purchase', function(item, price)
    local src = source
    local xPlayer = QBCore.Functions.GetPlayer(src)
    
    local success, message = processPayment(
        xPlayer.identifier,
        storeOwner.identifier,
        price,
        item
    )
    
    if success then
        TriggerClientEvent('chat:addMessage', src, {
            args = {'Store', 'Purchase successful!'}
        })
    else
        TriggerClientEvent('chat:addMessage', src, {
            args = {'Store', message}
        })
    end
end)
```

### Criminal Activity Payout

```lua
-- resources/[criminal]/heist/server.lua

local function distributeHeistRewards(players, rewards)
    for _, playerId in ipairs(players) do
        local player = QBCore.Functions.GetPlayer(playerId)
        
        if player then
            exports['VibesEZ-Laptop']:AddCrypto(
                player.identifier,
                'BTC',
                rewards[playerId],
                'Heist: Score earned'
            )
        end
    end
end
```

### Casino System

```lua
-- resources/[casino]/casino_games/server.lua

local function processPayout(playerId, amount, winType)
    local xPlayer = QBCore.Functions.GetPlayer(playerId)
    
    exports['VibesEZ-Laptop']:AddCrypto(
        xPlayer.identifier,
        'SERVER',  -- Use server-specific currency for casino
        amount,
        'Casino: ' .. winType .. ' win'
    )
end

local function collectBet(playerId, amount)
    local xPlayer = QBCore.Functions.GetPlayer(playerId)
    local balance = exports['VibesEZ-Laptop']:GetBalance(
        xPlayer.identifier,
        'SERVER'
    )
    
    if balance >= amount then
        exports['VibesEZ-Laptop']:RemoveCrypto(
            xPlayer.identifier,
            'SERVER',
            amount,
            'Casino: Bet placed'
        )
        return true
    end
    return false
end
```

### Error Handling

Check if exports exist before using:

```lua
local function hasCrypto()
    return GetResourceState('VibesEZ-Laptop') == 'started' and
           type(exports['VibesEZ-Laptop']) ~= 'undefined'
end

if hasCrypto() then
    -- Use exports safely
else
    print('VibesEZ-Laptop not available')
end
```

### Event-Driven Architecture

Listen for wallet changes:

```lua
RegisterNetEvent('VibesEZ-Laptop:walletUpdated', function(currency, newBalance)
    print('Wallet updated: ' .. currency .. ' = ' .. newBalance)
end)

RegisterNetEvent('VibesEZ-Laptop:transferCompleted', function(currency, amount, recipient, note)
    print('Transfer complete: Sent ' .. amount .. ' ' .. currency .. ' to ' .. recipient)
end)
```

### Batch Operations

Process multiple transactions efficiently:

```lua
local function batchRewards(playerList, rewardPerPlayer, currency)
    for _, playerId in ipairs(playerList) do
        exports['VibesEZ-Laptop']:AddCrypto(
            playerId,
            currency,
            rewardPerPlayer,
            'Weekly event reward'
        )
    end
end

-- Usage: Distribute 100 BTC to all online players
local onlinePlayers = GetPlayers()
batchRewards(onlinePlayers, 100, 'BTC')
```


---

# 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://vibesez.gitbook.io/vibesez/docs/laptop/for-developers/api-reference.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.