FiveM money types: cash, bank and black money on ESX, QBCore and QBox

Players have more than one kind of money: the cash in their pocket, the bank account, and on many servers a dirty money balance. Each framework names and handles them differently, and ox_inventory adds a third way. This article shows the account names, the functions to add and remove money, how ox_inventory treats cash, and why the reason string matters.

#ESX accounts

ESX has three standard accounts:

On the server, with the player object:

ESX = exports['es_extended']:getSharedObject()
local xPlayer = ESX.GetPlayerFromId(source)

-- read
local cash = xPlayer.getAccount('money').money
local bank = xPlayer.getAccount('bank').money
local black = xPlayer.getAccount('black_money').money

-- add / remove
xPlayer.addAccountMoney('bank', 500, 'job-payout')
xPlayer.removeAccountMoney('black_money', 200, 'drug-purchase')

xPlayer.addAccountMoney(account, amount, reason) and removeAccountMoney take the account name first. For cash only, there are shortcuts:

xPlayer.addMoney(100, 'sold-item')
xPlayer.removeMoney(100, 'bought-item')
local cash = xPlayer.getMoney()

removeAccountMoney does not check the balance for you. Check first, or the account can go negative on some versions:

if xPlayer.getAccount('money').money >= price then
    xPlayer.removeAccountMoney('money', price, 'shop')
end

If the player object is nil, see ESX xPlayer is nil.

#QBCore money

QBCore keeps its money in PlayerData.money, with cash, bank and crypto:

local QBCore = exports['qb-core']:GetCoreObject()
local Player = QBCore.Functions.GetPlayer(source)

-- read
local cash = Player.PlayerData.money.cash
local bank = Player.PlayerData.money.bank

-- add / remove
Player.Functions.AddMoney('bank', 500, 'job-payout')
Player.Functions.RemoveMoney('cash', 50, 'shop-purchase')

Player.Functions.AddMoney(type, amount, reason) and Player.Functions.RemoveMoney(type, amount, reason) take the type first. RemoveMoney returns false when the player has not enough, so use the result:

if Player.Functions.RemoveMoney('cash', price, 'shop-purchase') then
    Player.Functions.AddItem('burger', 1)
else
    TriggerClientEvent('QBCore:Notify', source, 'Not enough cash', 'error')
end

There is no built-in black money account in QBCore. Servers that need one usually use an item (marked bills) or a custom type added to Config.Money, and the next section covers the item option. If QBCore is nil in your script, see the GetCoreObject fix.

#QBox

QBox is based on QBCore, so the same Player.Functions.AddMoney and RemoveMoney calls work on the player object, and the money types are the same. QBox also has exports on qbx_core, so check the exports of your qbx_core version for the money functions before you use them in new code. The shape is the same: a type, an amount and a reason.

#ox_inventory: cash as an item

With ox_inventory, cash can be an item instead of a number. The standard item is called money, and dirty money is black_money. Both are in ox_inventory/data/items.lua.

-- give cash as an item
exports.ox_inventory:AddItem(source, 'money', 500)

-- count it
local cash = exports.ox_inventory:Search(source, 'count', 'money')

-- take it
exports.ox_inventory:RemoveItem(source, 'money', 100)

-- dirty money
exports.ox_inventory:AddItem(source, 'black_money', 1000)

On an ESX server with ox_inventory, the money and black_money accounts are shown as items in the inventory, and xPlayer.addAccountMoney('money', ...) ends up in those items. Use one way only. If a script adds cash with the ESX function and another with AddItem, test that the two agree on your setup before you ship it. The bank is not an item and stays a number.

Warning: cash as an item has weight and can be dropped, stolen or stored in a stash. This is intended, but it changes how robbery and shop scripts behave. See stashes in ox_inventory.

#The reason string

reason is the last argument of the money functions. It does not change the amount. It is passed along with the change so that the framework, or a logging script, can record why the money moved.

Player.Functions.AddMoney('cash', 250, 'taxi-job-payout')
xPlayer.addAccountMoney('bank', 250, 'taxi-job-payout')

Use a short, consistent text that names the script and the action. When a player's balance looks wrong, a search for taxi-job-payout in the logs finds the line in seconds. If you also send logs to Discord, see Discord webhook logs. For the balance side of the economy, see balancing a FiveM economy.

#Rules for safe money code

• Change money on the server only. Never accept an amount sent by the client.
• Check the balance before you remove, and use the return value on QBCore.
• Pass a reason every time.
• Pick one money source per account, so cash is not stored twice, once as a number and once as an item.

#Checklist