esx_addonaccount

esx_addonaccount is a server-only library resource that stores money outside of the normal player accounts. Use it whenever money belongs to a job, a business or a property instead of a player's wallet, for example society funds used by esx_society and esx_billing.

OverviewCopy Anchor Link

There are two kinds of accounts, controlled by the shared column of the addon_account table:

• Shared (shared = 1): a single account without an owner. Typical for society_<job> accounts.
• Personal (shared = 0): one account per player identifier. The resource creates the row automatically when a player loads (esx:playerLoaded) and stores the loaded accounts on the player as xPlayer.get('addonAccounts').

InstallationCopy Anchor Link

ensure oxmysql
ensure esx_lib
ensure es_extended
ensure esx_addonaccount
ensure esx_society
ensure esx_billing

INSERT INTO `addon_account` (`name`, `label`, `shared`) VALUES
  ('society_mechanic', 'Mechanic', 1),
  ('property_black_money', 'Black money (property)', 0);

On startup the resource runs a schema migration. It adds a generated owner_key column and a unique key on (account_name, owner_key) if they are missing. The migration aborts (and disables all accounts) instead of changing data when it finds problems:

• addon_account_data is not InnoDB
• rows with account_name IS NULL or owner = ''
• duplicate rows for the same account and owner

ConfigurationCopy Anchor Link

esx_addonaccount has no config.lua. Everything is driven by the addon_account table.

Server exportsCopy Anchor Link

GetSharedAccountCopy Anchor Link

exports.esx_addonaccount:GetSharedAccount(name)

Returns the account object or nil if the account does not exist or the resource is not ready yet.

local account = exports.esx_addonaccount:GetSharedAccount('society_mechanic')

if account and account.addMoney(2500) then
    print(('Mechanic society now has $%s'):format(account.money))
end

GetAccountCopy Anchor Link

exports.esx_addonaccount:GetAccount(name, owner)

Returns the personal account object or nil. Accounts are only kept in memory for loaded players (offline accounts are evicted about once a minute after they are saved), so call this for online players.

local xPlayer = ESX.GetPlayerFromId(source)
local stash = exports.esx_addonaccount:GetAccount('property_black_money', xPlayer.identifier)

if stash then
    stash.removeMoney(1000)
end

AddSharedAccountCopy Anchor Link

exports.esx_addonaccount:AddSharedAccount(society, amount)

Creates a shared account at runtime (inserts into both tables) and returns it. If the account already exists, the existing object is returned and nothing is inserted. Returns nil on invalid input or a failed insert.

exports.esx_addonaccount:AddSharedAccount({ name = 'society_bahama', label = 'Bahama Mamas' }, 10000)

Account objectCopy Anchor Link

amount must be a whole number between 0 and 2147483647. Floats, negative numbers and NaN are rejected and the method returns false. Every successful change is saved to the database right away (with automatic retry every 5 seconds on failure).

EventsCopy Anchor Link

All events are local server events. Clients cannot trigger them.

Listening for changes is useful for logging:

AddEventHandler('esx_addonaccount:removeMoney', function(name, amount, owner)
    if name:find('^society_') then
        print(('[audit] %s lost $%s'):format(name, amount))
    end
end)

The getter events still work, but the exports are simpler and avoid callback nesting:

TriggerEvent('esx_addonaccount:getSharedAccount', 'society_police', function(account)
    if account then account.addMoney(500) end
end)

Integration tipsCopy Anchor Link

• Society accounts follow the society_<job name> pattern. esx_society and esx_billing rely on that naming.
• Store item stashes in esx_addoninventory and generic key/value data in esx_datastore.
• New rows in addon_account are picked up without a restart when ESX fires esx:sqlCatalogReady for that table, or when you trigger esx_addonaccount:refreshAccounts on the server.

Common issuesCopy Anchor Link

• addMoney returns false: you passed a float (for example a percentage cut like price * 0.15). Round first with math.floor.
• Console says "Duplicate addon accounts" or "Invalid account_name/empty owner": the migration stopped on purpose. Clean up the listed rows in addon_account_data by hand, then restart the resource.
• Account is nil right after a server start: another resource asked before esx_addonaccount finished loading. Check for nil and retry, or make sure the dependent resource starts later.

RelatedCopy Anchor Link

• esx_society
• esx_addoninventory
• esx_datastore
• Money and accounts guide
• Database schema

Frequently asked questions