Custom Flags & Trust
Your own scripts often know better than any anticheat what is impossible on your server, for example a payout that is far too high for a job. FlagPlayer lets them report it to CXA Anticheat, which then logs and punishes it like one of its own detections. GetTrustScore tells you how much the CXA network trusts a player's account, and IsActive tells you whether the anticheat is running.
A Flag Is Only as Good as Your Check
FlagPlayer punishes whatever your script reports. Base every flag on facts the server knows, never on a value the client sends without checks, and run a new check with log for a few days before you switch it to kick or ban.
When to Use It
- A money, item or reward event receives a request that your server knows is impossible.
- One of your scripts finds a value that cannot happen in normal play, such as a crafting result that skips the materials.
- A feature, such as a player market or a VIP area, should only be open to accounts with enough trust.
- Your script should use CXA when it is running and fall back to its own logging when it is not.
Exports
FlagPlayer
Reports your own detection and applies a punishment.
exports['cxa-anticheat']:FlagPlayer(src, reason, punishment, hours)
Parameters:
- src (number): The player's server ID
- reason (string, optional): What your script found. Shown in the logs and on the ban or kick screen. Default: the label
External detection - punishment (string, optional):
ban,kick,warn,logornone, in lower case. Default:log - hours (number, optional): Ban length for
ban,0= permanent. Default: the default duration of the ban system settings (0)
Returns: true when CXA handled the flag. This includes none, and a repeated log or warn that the cooldown skipped. false when the anticheat is not active, the player is offline or already being removed, or the player is bypassed or has External or all paused.
What happens:
- The flag is handled as the detection
External, shown as "External detection". - Except with
none, CXA prints a console line, sends a chat alert to online staff and adds an entry with your reason and your resource name to the panel's Detections tab. - The punishment decides what the player sees and which webhook channel gets the message:
| Punishment | What the player sees | Webhook channel |
|---|---|---|
ban | Banned and dropped with the ban screen, which shows your reason | Bans |
kick | Dropped with the kick screen, which shows your reason | Kicks |
warn | An on-screen warning and a chat line. The player stays | Warns |
log | Nothing | Detections |
none | Nothing. Nothing is logged either | None |
logandwarnhave a cooldown. Repeated flags for the same player within 10 seconds (Detection cooldown in the logging settings) are skipped. All your scripts share theExternalkey, so they also share this cooldown.- No screenshot is attached.
- The warning text shows the detection label, not your reason:
Anticheat warning: External detection. Keep doing it and you will be removed from the server. - A ban from
FlagPlayeris issued byCXA Anticheat. It is shared with the CXA network only if you addExternalto the shared detections of global bans, which it is not by default.
Output: The console line looks like this:
[CXA] John (ID: 12) -> External detection [log] reason: Delivery payout of 50000 (max 2500), resource: my-deliveryOnline staff get a chat alert with the prefix [CXA] and the text John (ID: 12) flagged for External detection [log].
GetTrustScore
Returns the player's trust score and band.
exports['cxa-anticheat']:GetTrustScore(src)
Parameters:
- src (number): The player's server ID
Returns: A table { score, band }, or nil when no score is known. In JavaScript and TypeScript, "no score" arrives as undefined.
| Band | Score |
|---|---|
red | 0 to 19 |
orange | 20 to 39 |
yellow | 40 to 59 |
lime | 60 to 79 |
green | 80 to 100 |
What happens:
- The CXA network calculates the score when the player joins, from account ages, linked accounts, network history and global bans. CXA keeps it for the rest of the session. See Account Trust.
- The score exists even when the trust score join check is off. Some factors, such as the Steam account age, are only checked while that join check is on.
- You get
nilwhen join screening or the network check on connect is off, when the network could not be reached in time, when the player has nolicenseidentifier, or when the player is on the bypass identifier list, because those players skip the join checks. - You also get
nilfor players who joined before CXA last restarted, until they reconnect.
IsActive
Tells you whether the anticheat is running and licensed.
exports['cxa-anticheat']:IsActive()
Parameters: None.
Returns: true when the folder is named cxa-anticheat, the anticheat has started and the license is verified. Otherwise false.
What happens:
- Nothing changes. It only reads the current state.
- While CXA restarts, the export does not exist for a moment. Check
GetResourceState('cxa-anticheat')before you call it, as shown on Server Exports.
Examples
Flag Impossible Payouts
Your delivery job never pays more than 2,500. The server checks the requested amount, refuses anything higher and reports it. After three flags, the player is kicked.
local MAX_PAYOUT = 2500 -- The most one delivery can ever pay
local strikes = {}
RegisterNetEvent('my-delivery:server:finish', function(amount)
local src = source
amount = tonumber(amount) or 0
if amount > MAX_PAYOUT then
-- Refuse the payout first, then report it
strikes[src] = (strikes[src] or 0) + 1
local punishment = strikes[src] >= 3 and 'kick' or 'log'
local reason = ('Delivery payout of %d (max %d)'):format(amount, MAX_PAYOUT)
exports['cxa-anticheat']:FlagPlayer(src, reason, punishment)
return
end
-- Pay the player with your framework here
end)
AddEventHandler('playerDropped', function()
strikes[source] = nil -- Forget the strikes when the player leaves
end)const MAX_PAYOUT = 2500; // The most one delivery can ever pay
const strikes = new Map<number, number>();
onNet('my-delivery:server:finish', (amount: number) => {
const src = source;
const value = Number(amount) || 0;
if (value > MAX_PAYOUT) {
// Refuse the payout first, then report it
const count = (strikes.get(src) ?? 0) + 1;
strikes.set(src, count);
const punishment = count >= 3 ? 'kick' : 'log';
const reason = `Delivery payout of ${value} (max ${MAX_PAYOUT})`;
exports['cxa-anticheat'].FlagPlayer(src, reason, punishment);
return;
}
// Pay the player with your framework here
});
on('playerDropped', () => {
strikes.delete(source); // Forget the strikes when the player leaves
});Gate a VIP Feature by Trust Band
Only accounts from the yellow band upwards may list items on your VIP market.
local BAND_RANK = { red = 1, orange = 2, yellow = 3, lime = 4, green = 5 }
local function hasTrust(src, minimumBand)
local trust = exports['cxa-anticheat']:GetTrustScore(src)
if not trust then
return false -- Unknown score: decide yourself whether to allow or deny
end
return BAND_RANK[trust.band] >= BAND_RANK[minimumBand]
end
RegisterNetEvent('my-market:server:createListing', function(item, price)
local src = source
if not hasTrust(src, 'yellow') then
TriggerClientEvent('chat:addMessage', src, { args = { 'Market', 'Your account cannot sell on the VIP market yet.' } })
return
end
-- Create the listing here
end)const BAND_RANK: Record<string, number> = { red: 1, orange: 2, yellow: 3, lime: 4, green: 5 };
function hasTrust(src: number, minimumBand: string): boolean {
const trust = exports['cxa-anticheat'].GetTrustScore(src);
if (!trust) return false; // Unknown score: decide yourself whether to allow or deny
return BAND_RANK[trust.band] >= BAND_RANK[minimumBand];
}
onNet('my-market:server:createListing', (item: string, price: number) => {
const src = source;
if (!hasTrust(src, 'yellow')) {
emitNet('chat:addMessage', src, { args: ['Market', 'Your account cannot sell on the VIP market yet.'] });
return;
}
// Create the listing here
});Fall Back When CXA Is Not Running
local function report(src, reason)
local running = GetResourceState('cxa-anticheat') == 'started' and exports['cxa-anticheat']:IsActive()
if running then
exports['cxa-anticheat']:FlagPlayer(src, reason, 'log')
else
-- Your own log while the anticheat is not available
print(('[my-script] %s (%d): %s'):format(GetPlayerName(src), src, reason))
end
endfunction report(src: number, reason: string): void {
const running = GetResourceState('cxa-anticheat') === 'started' && exports['cxa-anticheat'].IsActive();
if (running) {
exports['cxa-anticheat'].FlagPlayer(src, reason, 'log');
} else {
// Your own log while the anticheat is not available
console.log(`[my-script] ${GetPlayerName(src.toString())} (${src}): ${reason}`);
}
}Typed Signatures
type CxaPunishment = 'ban' | 'kick' | 'warn' | 'log' | 'none';
type CxaTrustBand = 'red' | 'orange' | 'yellow' | 'lime' | 'green';
interface CxaTrust {
score: number; // 0 to 100
band: CxaTrustBand;
}
interface CxaFlagExports {
FlagPlayer(src: number, reason?: string, punishment?: CxaPunishment, hours?: number): boolean;
GetTrustScore(src: number): CxaTrust | undefined;
IsActive(): boolean;
}
const cxa = exports['cxa-anticheat'] as CxaFlagExports;---@alias CxaPunishment 'ban'|'kick'|'warn'|'log'|'none'
---@alias CxaTrustBand 'red'|'orange'|'yellow'|'lime'|'green'
---@class CxaTrust
---@field score integer 0 to 100
---@field band CxaTrustBand
---@class CxaFlagExports
---@field FlagPlayer fun(self: CxaFlagExports, src: integer, reason?: string, punishment?: CxaPunishment, hours?: number): boolean
---@field GetTrustScore fun(self: CxaFlagExports, src: integer): CxaTrust|nil
---@field IsActive fun(self: CxaFlagExports): boolean
---@type CxaFlagExports
local cxa = exports['cxa-anticheat']Recommendations
Good to Know
- Start every new flag with
log. Watch the panel's Detections tab for a few days, then raise it. - Put the facts into the reason: the value, the limit, the item. Your staff judge the flag from that text.
- Refuse the action before you flag.
FlagPlayerreports, it does not undo a payout. - Treat a
niltrust score as "unknown", not as "bad". Players who joined before a CXA restart have no score until they reconnect. - Test with a player who is not bypassed. Staff with bypass are never flagged.
Related Features
Detections & Punishments
ban,kick,warn,logandnonework exactly as for CXA's own detections. See Detections & Punishments.
Account Trust
- How the score and the bands are calculated, and how to block low-trust accounts at join, is explained in Account Trust.
Logging & Discord
- Flags go to the Bans, Kicks, Warns or Detections channel, depending on the punishment. See Logging & Discord.
Bans & the CXA Network
- Bans from
FlagPlayerstay on your server unless you addExternalto the shared detections. See Bans & the CXA Network.
Common Problems
FlagPlayer Returns false
What you see: The call returns false and nothing is logged.
How to fix it:
- You may be testing on yourself as staff. Bypassed players are never flagged. Test with a normal account.
- Check that no script paused
Externalorallfor that player. - Check
IsActive()and that the player is still online.
The Player Stays and Is No Longer Checked
What you see: After a flag, the player stays on the server, but CXA ignores them and blocks their entities and explosions until they reconnect.
How to fix it:
- The punishment value was not one of the five supported values. Use lower case exactly as written. Any other value is logged like
log, but CXA then treats the player as already being removed.
-- ❌ Capital letter: not a supported punishment
exports['cxa-anticheat']:FlagPlayer(src, 'Duplicated items', 'Kick')
-- ✅ Lower case
exports['cxa-anticheat']:FlagPlayer(src, 'Duplicated items', 'kick')// ❌ Capital letter: not a supported punishment
exports['cxa-anticheat'].FlagPlayer(src, 'Duplicated items', 'Kick');
// ✅ Lower case
exports['cxa-anticheat'].FlagPlayer(src, 'Duplicated items', 'kick');Only the First Flag Shows Up
What you see: Your script flags a player several times in a row, but only one entry appears.
How to fix it:
- This is the 10 second cooldown for
logandwarn. It keeps spam out of your logs and is shared by every script that usesFlagPlayer. - Count the attempts in your own script and send one flag with the total, or raise the punishment after several attempts, as in the payout example above.
GetTrustScore Returns nil
What you see: GetTrustScore returns nil for a player who is online.
How to fix it:
- Check that join screening and the network check on connect are on in the panel.
- If CXA restarted after the player joined, the score comes back when the player reconnects.
- Players on the bypass identifier list skip the join checks and never get a score.
© 2026 CodeXart Studios · CXA Anticheat