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.5is 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_banstable with oxmysql, or indata/bans.jsonwithout 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
Externaland 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.
BanPlayerbans 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_banstable and is marked inactive. With JSON storage, it is removed fromdata/bans.json. - If the ban was shared with the CXA network as a global ban, it is withdrawn there too.
- Nothing is logged. The
cxaunbancommand 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.
| Field | Type | What it contains |
|---|---|---|
banId | string | The ban ID, for example CXA-7KQ2MX |
name | string | The player's name when they were banned. For offline bans, the banned identifier |
reason | string | The ban reason |
detection | string | The detection key for automatic bans (for example Noclip), Manual for bans from commands and the panel, External for bans from exports |
identifiers | string[] | The player's identifiers, plus new ones added when the player tried to join again |
tokens | string[] | The player's hardware tokens |
bannedBy | string | The issuer: CXA Anticheat for automatic bans, Console or Name (ID) for commands, Panel: name for the panel, your bannedBy for exports |
createdAt | number | When the ban was created, as a Unix timestamp in seconds |
expiresAt | number | When 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
nilis 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:1234567890abcdef1234567890abcdef12345678ordiscord: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,liveandfivem. Anip: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)onNet('my-admin:server:ban', (targetId: number, hours: number, reason: string) => {
const src = source;
// Only staff with your own ACE permission may ban
if (!IsPlayerAceAllowed(src.toString(), 'myadmin.ban')) return;
if (GetResourceState('cxa-anticheat') !== 'started') return;
// Issuer shown in the logs and in GetBan
const issuer = `Admin Menu: ${GetPlayerName(src.toString())}`;
// Always pass the hours, an empty value means the default (permanent)
const banId: string | false = exports['cxa-anticheat'].BanPlayer(Number(targetId), reason, Number(hours) || 24, issuer);
if (banId) {
emitNet('chat:addMessage', src, { args: ['Admin', `Player banned, ban ID: ${banId}`] });
} else {
emitNet('chat:addMessage', src, { args: ['Admin', 'Player is offline or the anticheat is not running.'] });
}
});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)// Usage in the server console: appealunban CXA-7KQ2MX
RegisterCommand('appealunban', (src: number, args: string[]) => {
if (src !== 0) return; // Console only
const banId = (args[0] ?? '').toUpperCase(); // Ban IDs are upper case
const ban = exports['cxa-anticheat'].GetBan(banId);
if (!ban) {
console.log(`No active ban ${banId}`);
return;
}
console.log(`${ban.name} was banned by ${ban.bannedBy} for: ${ban.reason}`);
if (exports['cxa-anticheat'].UnbanPlayer(banId)) {
console.log(`Ban ${banId} removed after an appeal`); // Your own log line
}
}, 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
endfunction isApplicantBanned(discordId: string): boolean {
// Pass the full identifier, with the "discord:" prefix
const result: [true, string] | false = exports['cxa-anticheat'].IsIdentifierBanned(`discord:${discordId}`);
if (result) {
const [, banId] = result; // Banned: [true, banId]
console.log(`Applicant is banned, ban ID: ${banId}`);
return true;
}
return false; // Not banned: false
}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;---@class CxaBanRecord
---@field banId string
---@field name string
---@field reason string
---@field detection string
---@field identifiers string[]
---@field tokens string[]
---@field bannedBy string
---@field createdAt integer Unix time in seconds
---@field expiresAt integer Unix time in seconds, 0 = permanent
---@class CxaBanExports
---@field BanPlayer fun(self: CxaBanExports, src: integer, reason?: string, hours?: number, bannedBy?: string): string|false
---@field KickPlayer fun(self: CxaBanExports, src: integer, reason?: string): boolean
---@field UnbanPlayer fun(self: CxaBanExports, banId: string): boolean
---@field GetBan fun(self: CxaBanExports, banId: string): CxaBanRecord|nil
---@field IsIdentifierBanned fun(self: CxaBanExports, identifier: string): boolean, string|nil
---@type CxaBanExports
local cxa = exports['cxa-anticheat']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
bannedBysuch asAdmin Menu: John. It shows up in the Bans channel and inGetBan, 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.
KickPlayerandUnbanPlayerwrite no log. Log those actions in your own script if your staff need a record.
Related Features
Console & Chat Commands
cxaban,cxaunbanandcxabaninfowork on the same ban list. See Console & Chat Commands.- The commands log to the Admin webhook channel, the exports
KickPlayerandUnbanPlayerdo not.
Bans & the CXA Network
- Bans from
BanPlayerare never shared as global bans. - Read how global bans are shared and enforced in Bans & the CXA Network.
Logging & Discord
BanPlayerwrites 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.
BanPlayeronly bans online players. For players who left, use thecxabanofflinecommand. - Check
IsActive(). Before the anticheat has started,BanPlayerdoes 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)// ❌ 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')// ❌ Missing prefix
exports['cxa-anticheat'].IsIdentifierBanned('123456789012345678');
// ✅ Full identifier
exports['cxa-anticheat'].IsIdentifierBanned('discord:123456789012345678');© 2026 CodeXart Studios · CXA Anticheat