Money and Accounts

ESX Legacy stores a player's money in accounts: money (cash), bank and black_money by default. On the server you read and change them through the xPlayer object, for example xPlayer.addAccountMoney('bank', 500, 'Job reward'), and you configure which accounts exist and how much new players start with in es_extended/shared/config/main.lua.

OverviewCopy Anchor Link

Accounts are saved as JSON in the users.accounts column, for example {"bank":50000,"money":0,"black_money":0}. ESX saves players every 10 minutes and when they disconnect. Only the server can change money; clients receive updates through the esx:setAccountMoney event.

Configure accountsCopy Anchor Link

Config.Accounts = {
    bank = {
        label = TranslateCap("account_bank"),
        round = true,
        transferable = false,
    },
    black_money = {
        label = TranslateCap("account_black_money"),
        round = true,
    },
    money = {
        label = TranslateCap("account_money"),
        round = true,
    },
}

Config.StartingAccountMoney = { bank = 50000 }

Change the starting moneyCopy Anchor Link

Config.StartingAccountMoney is used when a character is created, and as the fallback value for any account a loading player does not have yet. New players get no cash by default. To give them some:

Config.StartingAccountMoney = { money = 500, bank = 5000 }

Existing players are not affected unless the account is new to them.

Read and change money (server)Copy Anchor Link

All account methods take the account name as a string. Amounts must be numbers.

xPlayer.getAccount(accountName)                      -- { name, money, label, round, index } or nil
xPlayer.getAccounts(minimal)                         -- list, or { name = money } when minimal is true
xPlayer.addAccountMoney(accountName, money, reason)  -- true on success
xPlayer.removeAccountMoney(accountName, money, reason)
xPlayer.setAccountMoney(accountName, money, reason)
xPlayer.getMoney() / addMoney(money, reason) / removeMoney(money, reason) / setMoney(money)

Return values and errorsCopy Anchor Link

• removeAccountMoney returns false when the balance would go negative or when rounding turns the amount into 0. It never allows negative balances.
• addAccountMoney returns false if the new balance would overflow.
• An unknown account name, a non-number amount, or an amount of 0 or less raises a Lua error with the default inventory. Validate input first, especially values that came from a client.

Example: a safe purchaseCopy Anchor Link

ESX = exports['es_extended']:getSharedObject()

local PRICE <const> = 250

RegisterNetEvent('coffee:buy', function()
    local xPlayer = ESX.GetPlayerFromId(source)
    if not xPlayer then return end

    -- Price is decided on the server, never sent by the client
    if not xPlayer.removeAccountMoney('money', PRICE, 'Coffee shop') then
        return xPlayer.showNotification('Not enough cash')
    end

    xPlayer.addInventoryItem('coffee', 1)
end)

Removing the money first and checking the boolean is enough to prevent the classic "buy with no money" exploit. Do not trust a price, account or amount sent by the client; see Callbacks for validating client input.

Example: pay from bank, fall back to cashCopy Anchor Link

local function charge(xPlayer, amount, reason)
    if xPlayer.removeAccountMoney('bank', amount, reason) then
        return 'bank'
    end
    if xPlayer.removeAccountMoney('money', amount, reason) then
        return 'money'
    end
    return nil
end

Read money on the clientCopy Anchor Link

The client gets a copy of the accounts in ESX.PlayerData.accounts. Use it for display only.

local bank = ESX.GetAccount('bank')
if bank then
    print(('Bank balance: $%s'):format(ESX.Math.GroupDigits(bank.money)))
end

RegisterNetEvent('esx:setAccountMoney', function(account)
    print(('%s is now %s'):format(account.name, account.money))
end)

Money eventsCopy Anchor Link

A simple server-side money log:

AddEventHandler('esx:removeAccountMoney', function(playerId, accountName, amount, reason)
    if amount >= 100000 then
        print(('[money] %s removed %s from %s (%s)'):format(playerId, amount, accountName, reason))
    end
end)

Add a custom accountCopy Anchor Link

Config.Accounts = {
    bank = { label = TranslateCap("account_bank"), round = true, transferable = false },
    black_money = { label = TranslateCap("account_black_money"), round = true },
    money = { label = TranslateCap("account_money"), round = true },
    crypto = { label = "Crypto", round = false, transferable = false },
}

Config.StartingAccountMoney = { bank = 50000, crypto = 0 }

PaychecksCopy Anchor Link

Salaries come from the player's job grade (job_grades.salary) and are paid into bank.

With society payouts enabled, a player whose company cannot cover the salary gets a "company has no money" notification and is not paid. Jobs without a registered society are paid normally. xPlayer.togglePaycheck(false) pauses paychecks for one player.

Society (company) moneyCopy Anchor Link

Company money lives in esx_addonaccount shared accounts named society_<job>, not on the player. Use the GetSharedAccount export on the server:

local account = exports.esx_addonaccount:GetSharedAccount('society_police')
if account then
    account.addMoney(5000)
    print(('Police funds: %s'):format(account.money))
end

The account object has addMoney, removeMoney and setMoney. Setup is described in Create a job and on the esx_addonaccount page.

Common issuesCopy Anchor Link

RelatedCopy Anchor Link

• xPlayer reference
• Main config
• Create a job
• esx_banking
• Callbacks

Frequently asked questions