Ban & Kick Exports

These exports let your own scripts ban, kick and unban players through CXA Anticheat. A ban created this way gets a normal CXA ban ID, shows the CXA ban screen and is checked on every join, exactly like a ban from the panel or the cxaban command.

Empty Duration Means the Default Duration

If you leave hours empty, BanPlayer uses the default duration from the ban system settings. Out of the box this is 0, which means permanent. Always pass the number of hours you want.

When to Use It

  • Your admin menu, Discord bot or support tool should ban players into the CXA ban list instead of keeping its own list.
  • A whitelist or application system should check whether a Discord or license identifier is already banned.
  • A staff tool should show the details of a ban ID that a player sends in an appeal.

Exports

BanPlayer

Bans an online player and drops them with the ban screen.

exports['cxa-anticheat']:BanPlayer(src, reason, hours, bannedBy)

Parameters:

  • src (number): The player's server ID
  • reason (string, optional): Shown on the ban screen and in the logs. Default: No reason given
  • hours (number, optional): Ban length in hours, 0 = permanent. Decimals work, 0.5 is 30 minutes. Default: the default duration of the ban system settings (0)
  • bannedBy (string, optional): Name saved as the issuer of the ban. Default: the name of the resource that called the export

Returns: The ban ID as a string, for example CXA-7KQ2MX, or false when the anticheat has not started or the player is not online.

What happens:

  • CXA creates a ban with the detection External. It matches the player's identifiers and hardware tokens, like every CXA ban.
  • The ban is saved in the cxa_bans table with oxmysql, or in data/bans.json without it, and stays after restarts.
  • The player is dropped with the ban screen. It shows your server name, the ban ID, the reason, the expiry date and your appeal link, if you set one.
  • A "Player Banned" message goes to your Bans webhook channel with the reason, the issuer, the ban ID and the expiry date.
  • The ban appears in the panel's Detections tab with the detection External and the name of the resource that called the export.
  • The ban is not shared with the CXA network. Only automatic bans from shared detections are shared.
  • Staff bypass is not checked. BanPlayer bans bypassed staff too, so check your own permissions before you call it.

KickPlayer

Drops an online player with the kick screen.

exports['cxa-anticheat']:KickPlayer(src, reason)

Parameters:

  • src (number): The player's server ID
  • reason (string, optional): Shown on the kick screen. Default: No reason given

Returns: true when the player was kicked, false when the player is not online.

What happens:

  • The player is dropped with the CXA kick screen, which shows your server name and the reason.
  • Nothing is logged. There is no webhook message and no panel entry. If you want a record, log the kick yourself, or use FlagPlayer with kick, which logs to the Kicks channel.

UnbanPlayer

Removes an active ban.

exports['cxa-anticheat']:UnbanPlayer(banId)

Parameters:

  • banId (string): The ban ID exactly as CXA shows it, for example CXA-7KQ2MX. It is case-sensitive.

Returns: true when an active ban was removed, false when there is no active ban with this ID.

What happens:

  • The ban is removed from memory at once, so the player can join again right away.
  • With oxmysql, the row stays in the cxa_bans table and is marked inactive. With JSON storage, it is removed from data/bans.json.
  • If the ban was shared with the CXA network as a global ban, it is withdrawn there too.
  • Nothing is logged. The cxaunban command writes to the Admin webhook channel, this export does not.

GetBan

Returns the record of an active ban.

exports['cxa-anticheat']:GetBan(banId)

Parameters:

  • banId (string): The ban ID, for example CXA-7KQ2MX. It is case-sensitive.

Returns: A table with the fields below, or nil when the ban does not exist, was removed or has expired. In JavaScript and TypeScript, "no ban" arrives as undefined.

FieldTypeWhat it contains
banIdstringThe ban ID, for example CXA-7KQ2MX
namestringThe player's name when they were banned. For offline bans, the banned identifier
reasonstringThe ban reason
detectionstringThe detection key for automatic bans (for example Noclip), Manual for bans from commands and the panel, External for bans from exports
identifiersstring[]The player's identifiers, plus new ones added when the player tried to join again
tokensstring[]The player's hardware tokens
bannedBystringThe issuer: CXA Anticheat for automatic bans, Console or Name (ID) for commands, Panel: name for the panel, your bannedBy for exports
createdAtnumberWhen the ban was created, as a Unix timestamp in seconds
expiresAtnumberWhen the ban ends, as a Unix timestamp in seconds. 0 means permanent

What happens:

  • The record is read from memory. No database query is made.
  • An expired ban is removed when you look it up, and nil is returned.

IsIdentifierBanned

Checks whether an identifier or a hardware token belongs to an active ban.

exports['cxa-anticheat']:IsIdentifierBanned(identifier)

Parameters:

  • identifier (string): A full identifier with its prefix, for example license:1234567890abcdef1234567890abcdef12345678 or discord:123456789012345678, or a hardware token

Returns: Two values. In Lua: true, banId when banned, false, nil when not. In JavaScript and TypeScript: the array [true, banId] when banned, false when not.

What happens:

  • The check runs in memory, so it is cheap to call, even when a player connects.
  • Only identifier types that bans match on count: by default license, license2, steam, discord, xbl, live and fivem. An ip: identifier only counts when IP matching is on. Hardware tokens count while token matching is on, which is the default.
  • Only this server's own bans are checked. Global bans from the CXA network are not.

Examples

Ban From Your Admin Menu

Your admin menu sends a ban request to the server. The server checks your own permission first, then bans through CXA and tells the admin the ban ID.

RegisterNetEvent('my-admin:server:ban', function(targetId, hours, reason)
    local src = source
    -- Only staff with your own ACE permission may ban
    if not IsPlayerAceAllowed(src, 'myadmin.ban') then
        return
    end
    if GetResourceState('cxa-anticheat') ~= 'started' then
        return
    end
    -- Issuer shown in the logs and in GetBan
    local issuer = ('Admin Menu: %s'):format(GetPlayerName(src))
    -- Always pass the hours, an empty value means the default (permanent)
    local banId = exports['cxa-anticheat']:BanPlayer(tonumber(targetId), reason, tonumber(hours) or 24, issuer)
    if banId then
        TriggerClientEvent('chat:addMessage', src, { args = { 'Admin', ('Player banned, ban ID: %s'):format(banId) } })
    else
        TriggerClientEvent('chat:addMessage', src, { args = { 'Admin', 'Player is offline or the anticheat is not running.' } })
    end
end)

Look Up and Remove a Ban

A console command for your support team. It prints the ban, then removes it and writes its own log line, because UnbanPlayer logs nothing.

-- Usage in the server console: appealunban CXA-7KQ2MX
RegisterCommand('appealunban', function(src, args)
    if src ~= 0 then
        return -- Console only
    end
    local banId = (args[1] or ''):upper() -- Ban IDs are upper case
    local ban = exports['cxa-anticheat']:GetBan(banId)
    if not ban then
        print(('No active ban %s'):format(banId))
        return
    end
    print(('%s was banned by %s for: %s'):format(ban.name, ban.bannedBy, ban.reason))
    if exports['cxa-anticheat']:UnbanPlayer(banId) then
        print(('Ban %s removed after an appeal'):format(banId)) -- Your own log line
    end
end, true)

Check an Applicant Before Accepting

Your whitelist application system checks the applicant's Discord identifier before staff accept them.

local function isApplicantBanned(discordId)
    -- Pass the full identifier, with the "discord:" prefix
    local banned, banId = exports['cxa-anticheat']:IsIdentifierBanned('discord:' .. discordId)
    if banned then
        print(('Applicant is banned, ban ID: %s'):format(banId))
    end
    return banned
end

Typed Signatures

interface CxaBanRecord {
  banId: string;
  name: string;
  reason: string;
  detection: string;
  identifiers: string[];
  tokens: string[];
  bannedBy: string;
  createdAt: number; // Unix time in seconds
  expiresAt: number; // Unix time in seconds, 0 = permanent
}

interface CxaBanExports {
  BanPlayer(src: number, reason?: string, hours?: number, bannedBy?: string): string | false;
  KickPlayer(src: number, reason?: string): boolean;
  UnbanPlayer(banId: string): boolean;
  GetBan(banId: string): CxaBanRecord | undefined;
  IsIdentifierBanned(identifier: string): [true, string] | false; // Banned: [true, banId]
}

const cxa = exports['cxa-anticheat'] as CxaBanExports;

Recommendations

Good to Know

  • Always pass hours. An empty value falls back to the default duration, which is permanent unless you changed it.
  • Pass a bannedBy such as Admin Menu: John. It shows up in the Bans channel and in GetBan, so you know who banned whom.
  • Keep the reason short and clear. The player reads it on the ban screen.
  • Store the ban ID, not the player name. Ban IDs are unique, names are not.
  • KickPlayer and UnbanPlayer write no log. Log those actions in your own script if your staff need a record.

Console & Chat Commands

  • cxaban, cxaunban and cxabaninfo work on the same ban list. See Console & Chat Commands.
  • The commands log to the Admin webhook channel, the exports KickPlayer and UnbanPlayer do not.

Bans & the CXA Network

  • Bans from BanPlayer are never shared as global bans.
  • Read how global bans are shared and enforced in Bans & the CXA Network.

Logging & Discord

  • BanPlayer writes to the Bans channel. Set its webhook in the panel under Webhooks & keys. See Logging & Discord.

Common Problems

BanPlayer Returns false

What you see: BanPlayer returns false and the player stays on the server.

How to fix it:

  • Check that the player is still online. BanPlayer only bans online players. For players who left, use the cxabanoffline command.
  • Check IsActive(). Before the anticheat has started, BanPlayer does nothing.
  • In Lua, call it with a colon (:), not a dot.

The Ban Is Permanent Instead of Temporary

What you see: You wanted a short ban, but the ban screen says Never (permanent).

How to fix it:

  • Pass the hours as the third argument. An empty or unreadable value falls back to the default duration.
  • The unit is hours, not minutes or days.
-- ❌ No hours: the default duration (permanent) is used
exports['cxa-anticheat']:BanPlayer(target, 'Combat logging')

-- ❌ Minutes instead of hours: this is a 30 hour ban
exports['cxa-anticheat']:BanPlayer(target, 'Combat logging', 30)

-- ✅ 30 minutes = 0.5 hours
exports['cxa-anticheat']:BanPlayer(target, 'Combat logging', 0.5)

UnbanPlayer or GetBan Finds Nothing

What you see: You pass a ban ID that exists, but UnbanPlayer returns false or GetBan returns nothing.

How to fix it:

  • Ban IDs are case-sensitive. Convert the input to upper case first.
  • The ban may have expired or been removed already. Check it with cxabaninfo <banId> in the server console.

IsIdentifierBanned Always Returns false

What you see: A player is banned, but the check for their identifier says they are not.

How to fix it:

  • Pass the full identifier with its prefix.
  • ip: identifiers only count when IP matching is switched on in the ban system settings.
  • The identifier type must be in the list of matched identifiers.
-- ❌ Missing prefix
exports['cxa-anticheat']:IsIdentifierBanned('123456789012345678')

-- ✅ Full identifier
exports['cxa-anticheat']:IsIdentifierBanned('discord:123456789012345678')

© 2026 CodeXart Studios · CXA Anticheat