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, log or none, 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:
PunishmentWhat the player seesWebhook channel
banBanned and dropped with the ban screen, which shows your reasonBans
kickDropped with the kick screen, which shows your reasonKicks
warnAn on-screen warning and a chat line. The player staysWarns
logNothingDetections
noneNothing. Nothing is logged eitherNone
  • log and warn have a cooldown. Repeated flags for the same player within 10 seconds (Detection cooldown in the logging settings) are skipped. All your scripts share the External key, 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 FlagPlayer is issued by CXA Anticheat. It is shared with the CXA network only if you add External to the shared detections of global bans, which it is not by default.

Output: The console line looks like this:

Output
[CXA] John (ID: 12) -> External detection [log] reason: Delivery payout of 50000 (max 2500), resource: my-delivery

Online 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.

BandScore
red0 to 19
orange20 to 39
yellow40 to 59
lime60 to 79
green80 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 nil when join screening or the network check on connect is off, when the network could not be reached in time, when the player has no license identifier, or when the player is on the bypass identifier list, because those players skip the join checks.
  • You also get nil for 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)

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)

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
end

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;

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. FlagPlayer reports, it does not undo a payout.
  • Treat a nil trust 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.

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 FlagPlayer stay on your server unless you add External to 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 External or all for 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')

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 log and warn. It keeps spam out of your logs and is shared by every script that uses FlagPlayer.
  • 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