AI Core

Money and banking

money.transfer between two accounts, the banking script through ai-core, and bills through whatever billing script runs.

TypeScript
import { money, banking, billing } from "@aifivem/lib/server";

money is every balance on the server: a loaded player's accounts, a job's or gang's shared account, a transfer that moves money in one transaction, and the ledger. A character who is not connected is characters. banking and billing are the layers for the server's banking and billing scripts.

money

money.get

A loaded player's balance in one account.

Side: Server · Waits: no

Signature
money.get(source: number, account: string): number | null
Lua
local balance = aiLib.money.get(source, account)

Parameters

Prop

Type

Returns

number | null: the balance, or null when the player has no loaded character or the account type does not exist. A stored character's balances come from characters.get.

Example

import { money, notify } from "@aifivem/lib/server";

export function tellBalance(source: number): void {
  const bank = money.get(source, "bank");
  notify(source, bank === null ? "No character" : `Bank: $${bank}`, bank === null ? "error" : "inform");
}

money.add, money.remove and money.set

Changes one account of a loaded player, with a ledger row. These are the calls for a reward, a price, a salary your script pays.

Side: Server · Waits: no

Signature
money.add(source: number, account: string, amount: number, reason?: string): boolean
money.remove(source: number, account: string, amount: number, reason?: string): boolean
money.set(source: number, account: string, amount: number, reason?: string): boolean
Lua
local ok = aiLib.money.add(source, account, amount, reason)
local ok = aiLib.money.remove(source, account, amount, reason)
local ok = aiLib.money.set(source, account, amount, reason)

Parameters

Prop

Type

Returns

boolean: true when the change was made. false when the player has no loaded character, the account does not exist, the amount is not a whole number above 0, or - for remove - the balance cannot pay (unless the account type may go below zero).

Example

import { money, onClientCallback } from "@aifivem/lib/server";
import { fail } from "@aifivem/lib/shared";

onClientCallback("myshop:buyTools", { lock: true }, (source) => {
  if (!money.remove(source, "cash", 150, "shop:tools")) return fail("NOT_ENOUGH_CASH");
  // give the item here
  return { ok: true };
});

Paying one player from another is not a remove plus an add: a failure in the middle would make money appear or vanish. Use money.transfer, which is one database transaction.

money.sharedGet

The balance of a job's or gang's account - bank is what other frameworks call the society money.

Side: Server · Waits: no

Signature
money.sharedGet(type: "job" | "gang", id: string, account: string): number | null
Lua
local balance = aiLib.money.sharedGet(type, id, account)

Parameters

Prop

Type

Returns

number | null: the balance, or null when that job or gang has no such account (an unknown job, or an account type the server does not have).

money.sharedAdd and money.sharedRemove

Changes a job's or gang's account, with a ledger row - a company's income and its costs.

Side: Server · Waits: no

Signature
money.sharedAdd(type: "job" | "gang", id: string, account: string, amount: number, reason?: string): boolean
money.sharedRemove(type: "job" | "gang", id: string, account: string, amount: number, reason?: string): boolean
Lua
local ok = aiLib.money.sharedAdd(type, id, account, amount, reason)
local ok = aiLib.money.sharedRemove(type, id, account, amount, reason)

Returns

boolean: true when the change was made, false for an unknown job or gang, a missing account, a bad amount, or an account that cannot pay.

Example

import { money } from "@aifivem/lib/server";

/** A city contract the mechanic shop earns, and the fee it pays for parts. */
export function contractDone(job: string, pay: number, parts: number): boolean {
  if (!money.sharedAdd("job", job, "bank", pay, "city contract")) return false;
  return money.sharedRemove("job", job, "bank", parts, "parts");
}

money.transfer

Moves money from one account to another in one database transaction, with a ledger row on both sides. Use it for anything where money must not appear or vanish half way: paying another player, a job paying a bonus, a fee.

Side: Server · Waits: no

Signature
money.transfer(from: MoneyRef, to: MoneyRef, amount: number, reason?: string, fee?: number): boolean
Lua
local ok = aiLib.money.transfer(from, to, amount, reason, fee)

Parameters

Prop

Type

Returns

boolean: true when both rows were written. false when an amount is not a whole number, an account is missing, both are the same, or from cannot pay amount plus fee.

Example

import { onClientCallback, money, nearestPlayerTo, notify } from "@aifivem/lib/server";
import { fail, oneArg, readInt } from "@aifivem/lib/shared";

onClientCallback("my-cash:give", { args: oneArg((v) => readInt(v, 1, 100_000)), lock: true }, (source, amount) => {
  const target = nearestPlayerTo(source, 2);
  if (target === null) return fail("NOBODY_NEAR");
  if (!money.transfer({ source, account: "cash" }, { source: target, account: "cash" }, amount, "give:cash"))
    return fail("NOT_ENOUGH_CASH");
  notify(target, `You received $${amount}`, "success");
  return { ok: true };
});

money.history

The ledger rows of an account, newest first: what moved, the balance after it, the reason, who did it and when. Works for a player's account, a job's or gang's account, and a stored character's account.

Side: Server · Waits: yes

Signature
money.history(account: LedgerRef, query?: LedgerQuery): Promise<LedgerPage>
Lua
local page = aiLib.money.history(account, query)

Parameters

Prop

Type

Returns

A LedgerPage: rows and the next to pass as before (null on the last page). ai-core writes a row a moment after the change, so the newest row may be a few milliseconds behind the balance.

Example

import { money } from "@aifivem/lib/server";

/** The last 20 bank rows of a stored character. */
export async function statement(charId: number) {
  const page = await money.history({ owner: "character", id: String(charId), account: "bank" }, { limit: 20 });
  return page.rows.map((r) => `${r.at}: ${r.amount} (${r.reason})`);
}

banking

banking talks to the banking script through ai-core's banking layer. Job money itself always moves through money or ai-core's exports.

banking.open

Opens the banking script's screen for a player.

Side: Server · Waits: no

Signature
banking.open(source: number): boolean
Lua
local ok = aiLib.banking.open(source)

Returns true when opened. false when the script cannot be opened from outside or none runs.

onClientCallback("my-atm:open", (source) => (banking.open(source) ? { ok: true } : fail("BANK_UNAVAILABLE")));

banking.societyBalance

A job's society balance, for display. In ai-core's core account mode it is ai-core's job account; in own mode the banking script's own.

Side: Server · Waits: no

Signature
banking.societyBalance(job: string): number | null
Lua
local balance = aiLib.banking.societyBalance(job) -- number or nil

Returns the balance, or null (Lua nil) when none runs or the script keeps none.

const balance = banking.societyBalance("mechanic") ?? 0;

banking.provider

Side: Server · Waits: no

Signature
banking.provider(): string | null
Lua
local name = aiLib.banking.provider()

Returns the banking script the layer uses, or null.

console.log(`banking through ${banking.provider() ?? "nothing"}`);

billing

billing sends bills through whatever billing script runs; without one, ai-core's own bills (the player pays from a list on screen, the money moves when they pay). Texts are already translated.

billing.send

Sends a bill from a job (fines, service fees) or from a player.

Side: Server · Waits: no

Signature
billing.send(bill: BillRequest): boolean
Lua
local ok = aiLib.billing.send(bill)

BillRequest

Prop

Type

Returns

boolean: true when sent, false when invalid or refused.

Example

import { billing, nearestPlayerTo, online } from "@aifivem/lib/server";
import { fail } from "@aifivem/lib/shared";

function fine(officer: number, amount: number) {
  if (!online.onDutyIn(officer, ["police"])) return fail("NOT_ON_DUTY");
  const target = nearestPlayerTo(officer, 3);
  if (target === null) return fail("NOBODY_NEAR");
  return billing.send({ to: target, amount, label: "Speeding", from: officer, job: "police" })
    ? { ok: true }
    : fail("BILL_FAILED");
}

billing.unpaid

The player's open bills.

Side: Server · Waits: yes (Promise in TypeScript, yields the thread in Lua)

Signature
billing.unpaid(source: number): Promise<UnpaidBill[] | null>
Lua
local bills = aiLib.billing.unpaid(source) -- table[] or nil, call inside a thread

Returns UnpaidBill[] (id, label, amount still owed, sender), or null when the billing script cannot list them.

const bills = await billing.unpaid(source);
const owed = bills?.reduce((sum, bill) => sum + bill.amount, 0) ?? 0;

billing.pay

The player pays one of their open bills.

Side: Server · Waits: no

Signature
billing.pay(source: number, id: string): boolean
Lua
local ok = aiLib.billing.pay(source, id)

Prop

Type

Returns true when paid. false when refused (not enough money, unknown bill) or the billing script takes payments only in its own screen.

if (!billing.pay(source, billId)) return fail("PAY_FAILED");

billing.provider

Side: Server · Waits: no

Signature
billing.provider(): string | null
Lua
local name = aiLib.billing.provider()

Returns the billing script bills go to, "ai-core" for ai-core's own bills.

if (billing.provider() === "ai-core") console.log("using ai-core's own bills");

On this page