Exports & Events

Complete API documentation for integrating with oxide-blackmarket.

---

Server Exports

Dealer Management

GetDealerNetId

Get the network ID of the current dealer entity.

local netId = exports['oxide-blackmarket']:GetDealerNetId()

Returns: number|nil - Network ID or nil if no dealer

---

GetDealerCoords

Get the current coordinates of the dealer (live position, accounts for wandering).

local coords = exports['oxide-blackmarket']:GetDealerCoords()

Returns: vector3|nil - Coordinates or nil if no dealer

---

GetDealerSpawnCoords

Get the original spawn coordinates of the dealer (the Config.Locations entry).

local coords = exports['oxide-blackmarket']:GetDealerSpawnCoords()

Returns: vector3|nil - Spawn coordinates or nil if no dealer

---

IsDealerActive

Check if the dealer entity currently exists.

local isActive = exports['oxide-blackmarket']:IsDealerActive()

Returns: boolean - True if dealer exists

---

IsDealerValid

Check if the dealer is valid (exists and entity is present). Functionally identical to IsDealerActive.

local isValid = exports['oxide-blackmarket']:IsDealerValid()

Returns: boolean - True if dealer is valid

---

Stock Management

GetDealerStock

Get the full stock table for all items.

local stock = exports['oxide-blackmarket']:GetDealerStock()

Returns: table - { [itemName] = quantity, ... }

---

GetItemStock

Get the stock quantity of a specific item.

local quantity = exports['oxide-blackmarket']:GetItemStock('weapon_pistol')

Parameters:

Name	Type	Description
itemName	string	Item name to check

Returns: number - Stock quantity (0 if not found)

---

UpdateDealerStock

Add or remove stock for an item.

local success = exports['oxide-blackmarket']:UpdateDealerStock('weapon_pistol', -1)

Parameters:

Name	Type	Description
itemName	string	Item name to update
amount	number	Amount to add (negative to subtract)

Returns: boolean - True if successful

---

Reputation Management

GetPlayerReputation

Get a player's black market reputation.

local rep = exports['oxide-blackmarket']:GetPlayerReputation(source)

Parameters:

Name	Type	Description
source	number	Player server ID

Returns: number - Reputation value (0 if not found)

---

SetPlayerReputation

Set a player's reputation to a specific value.

local success = exports['oxide-blackmarket']:SetPlayerReputation(source, 500)

Parameters:

Name	Type	Description
source	number	Player server ID
amount	number	Reputation to set

Returns: boolean - True if successful

---

AddPlayerReputation

Add reputation to a player.

local success = exports['oxide-blackmarket']:AddPlayerReputation(source, 50)

Parameters:

Name	Type	Description
source	number	Player server ID
amount	number	Reputation to add

Returns: boolean - True if successful

---

RemovePlayerReputation

Remove reputation from a player (minimum 0).

local success = exports['oxide-blackmarket']:RemovePlayerReputation(source, 100)

Parameters:

Name	Type	Description
source	number	Player server ID
amount	number	Reputation to remove

Returns: boolean - True if successful

---

AddReputationWithNotify

Add reputation and automatically trigger tier change notifications (TierUp/TierDown events).

local success = exports['oxide-blackmarket']:AddReputationWithNotify(source, 50)

Parameters:

Name	Type	Description
source	number	Player server ID
amount	number	Reputation to add

Returns: boolean - True if successful

---

RemoveReputationWithNotify

Remove reputation and automatically trigger tier change notifications.

local success = exports['oxide-blackmarket']:RemoveReputationWithNotify(source, 100)

Parameters:

Name	Type	Description
source	number	Player server ID
amount	number	Reputation to remove

Returns: boolean - True if successful

---

Client Exports

Dealer State

GetDealerEntity

Get the local dealer entity handle.

local entity = exports['oxide-blackmarket']:GetDealerEntity()

Returns: number|nil - Entity handle or nil

---

IsDealerActive

Check if dealer entity exists locally.

local isActive = exports['oxide-blackmarket']:IsDealerActive()

Returns: boolean - True if dealer exists

---

IsInMenu

Check if player is currently in the shop menu.

local inMenu = exports['oxide-blackmarket']:IsInMenu()

Returns: boolean - True if in menu

---

SetInMenu

Set the menu state (for external UI integrations).

exports['oxide-blackmarket']:SetInMenu(true)

Parameters:

Name	Type	Description
value	boolean	Menu state

---

UI Functions

OpenShopUI

Open the shop UI with specific data.

exports['oxide-blackmarket']:OpenShopUI(shopData)

Parameters:

Name	Type	Description
shopData	table	Shop data from server

---

CloseShopUI

Close the shop UI.

exports['oxide-blackmarket']:CloseShopUI()

---

UpdateShopUI

Update the shop UI display.

exports['oxide-blackmarket']:UpdateShopUI('stock', { item = 'weapon_pistol', stock = 5 })

Parameters:

Name	Type	Description
type	string	Update type
data	table	Update data

---

IsShopOpen

Check if shop UI is open.

local isOpen = exports['oxide-blackmarket']:IsShopOpen()

Returns: boolean - True if shop is open

---

IsNUIOpen

Wrapper for IsShopOpen. Returns true if shop UI is open.

local isOpen = exports['oxide-blackmarket']:IsNUIOpen()

Returns: boolean - True if NUI is open

---

Utility Functions

IsLoggedIn

Check if the player is currently logged in.

local loggedIn = exports['oxide-blackmarket']:IsLoggedIn()

Returns: boolean - True if logged in

---

IsPlayerPolice

Check if the current player has a police job (cached from job data).

local isPolice = exports['oxide-blackmarket']:IsPlayerPolice()

Returns: boolean - True if player's job is in Config.PoliceJobs

---

Server Callbacks

Callbacks use Community Bridge's callback system. Trigger from client with Callback.Trigger, register on server with Callback.Register.

GetReputation

Get player reputation data.

Callback.Trigger('oxide-blackmarket:server:GetReputation', function(data)
    print('Rep:', data.rep)
    print('Tier:', data.tier)
    print('Tier Name:', data.tierName)
end)

Returns:

Field	Type	Description
rep	number	Reputation value
tier	number	Tier level (0-4)
tierName	string	Tier name

---

GetPed

Get dealer entity data.

Callback.Trigger('oxide-blackmarket:server:GetPed', function(netId, coords)
    if netId then
        print('Dealer NetId:', netId)
        print('Coords:', coords)
    end
end)

Returns:

Parameter	Type	Description
netId	number|nil	Network ID
coords	vector3|nil	Coordinates

---

IsPlayerPolice

Check if a player has a police job (server-side verification).

Callback.Trigger('oxide-blackmarket:server:IsPlayerPolice', function(isPolice)
    print('Is police:', isPolice)
end)

Returns: boolean - True if player's job is in Config.PoliceJobs

---

Client Events

Events sent from server to client.

Dealer Events

SpawnDealer

Notifies client to initialize dealer entity.

RegisterNetEvent('oxide-blackmarket:client:SpawnDealer', function(netId, coords)
    -- netId: number - Network ID of dealer
    -- coords: vector3 - Spawn coordinates
end)

---

DespawnDealer

Notifies client to clear dealer state.

RegisterNetEvent('oxide-blackmarket:client:DespawnDealer', function()
    -- No parameters (or optional netId for cleanup)
end)

---

SpawnHitSquad

Dispatches hit squad to the player who killed the dealer.

RegisterNetEvent('oxide-blackmarket:client:SpawnHitSquad', function(coords)
    -- coords: table - { x, y, z } death coordinates
end)

---

Reputation Events

TierUp

Notifies client of tier increase.

RegisterNetEvent('oxide-blackmarket:client:TierUp', function(tierName)
    -- tierName: string - New tier name
end)

---

TierDown

Notifies client of tier decrease.

RegisterNetEvent('oxide-blackmarket:client:TierDown', function(tierName)
    -- tierName: string - New tier name
end)

---

TierChanged

Notifies client of any tier change (fires before TierUp/TierDown).

RegisterNetEvent('oxide-blackmarket:client:TierChanged', function(newTier, newTierName)
    -- newTier: number - New tier level (0-4)
    -- newTierName: string - New tier name
end)

---

ReputationLost

Notifies client that reputation was lost (plays sound).

RegisterNetEvent('oxide-blackmarket:client:ReputationLost', function()
    -- No parameters
end)

---

Shop Events

OpenShop

Opens shop UI with data.

RegisterNetEvent('oxide-blackmarket:client:OpenShop', function(shopData)
    -- shopData: table - Contains inventory, prices, etc.
end)

---

TransactionResult

Result of buy/sell transaction.

RegisterNetEvent('oxide-blackmarket:client:TransactionResult', function(success, message, updateData)
    -- success: boolean - Transaction succeeded
    -- message: string - Result message
    -- updateData: table|nil - Updated data (cash, stock, etc.)
end)

---

Loot Events

SpawnLoot

Spawn loot bag at location.

RegisterNetEvent('oxide-blackmarket:client:SpawnLoot', function(coords, lootId)
    -- coords: table - { x, y, z }
    -- lootId: string - Unique loot identifier
end)

---

RemoveLootBag

Remove loot bag from world.

RegisterNetEvent('oxide-blackmarket:client:RemoveLootBag', function(lootId)
    -- lootId: string - Loot to remove
end)

---

LootCollected

Plays loot collection sound.

RegisterNetEvent('oxide-blackmarket:client:LootCollected', function()
    -- No parameters
end)

---

Pager Events

PagerSending

Pager is sending message.

RegisterNetEvent('oxide-blackmarket:client:PagerSending', function()
    -- No parameters
end)

---

PagerResult

Pager response received.

RegisterNetEvent('oxide-blackmarket:client:PagerResult', function(success, message, coords, spawnCoords)
    -- success: boolean - Request succeeded
    -- message: string|nil - Result message (nil for Tier 2-3 success)
    -- coords: vector3|nil - Dealer coords (Tier 4 only)
    -- spawnCoords: vector3|nil - Spawn coords for area name resolution (Tier 2-3)
end)

---

PagerUsed

Pager cooldown started.

RegisterNetEvent('oxide-blackmarket:client:PagerUsed', function()
    -- No parameters
end)

---

SetDealerWaypoint

Set waypoint from email button.

RegisterNetEvent('oxide-blackmarket:client:SetDealerWaypoint', function(data)
    -- data: table - { x, y }
end)

---

Server Events

Events sent from client to server.

Dealer Events

DealerKilled

Report dealer death.

TriggerServerEvent('oxide-blackmarket:server:DealerKilled', deathCoords, wasSurrendered)
-- deathCoords: table - { x, y, z } (sent by client but ignored by server; server uses entity coords)
-- wasSurrendered: boolean - Was dealer surrendered when killed

---

ArrestDealer

Arrest the dealer (police only).

TriggerServerEvent('oxide-blackmarket:server:ArrestDealer', netId)
-- netId: number - Dealer network ID

---

Shop Events

RequestShop

Request shop data to open UI.

TriggerServerEvent('oxide-blackmarket:server:RequestShop')
-- No parameters

---

Purchase

Purchase an item.

TriggerServerEvent('oxide-blackmarket:server:Purchase', itemName, quantity)
-- itemName: string - Item to purchase
-- quantity: number - Amount to buy

---

Sell

Sell an item.

TriggerServerEvent('oxide-blackmarket:server:Sell', itemName, quantity)
-- itemName: string - Item to sell
-- quantity: number - Amount to sell

---

Loot Events

CollectLoot

Collect loot from bag.

TriggerServerEvent('oxide-blackmarket:server:CollectLoot', lootId)
-- lootId: string - Loot bag identifier

---

Integration Examples

Check Player Reputation from Another Resource

-- Server-side
local function getPlayerBlackmarketTier(source)
    local rep = exports['oxide-blackmarket']:GetPlayerReputation(source)

    if rep >= 1000 then return 4, 'Inner Circle'
    elseif rep >= 600 then return 3, 'Trusted'
    elseif rep >= 300 then return 2, 'Connected'
    elseif rep >= 100 then return 1, 'Street'
    else return 0, 'Unknown'
    end
end

-- Usage
local tier, tierName = getPlayerBlackmarketTier(source)
print('Player is ' .. tierName .. ' tier')

Reward Reputation for Completing Tasks

-- Server-side: Give rep when player completes a heist
RegisterNetEvent('heist:server:completed', function()
    local src = source
    -- Use WithNotify variant to automatically trigger tier change notifications
    exports['oxide-blackmarket']:AddReputationWithNotify(src, 100)
end)

Check Dealer Location from Another Resource

-- Server-side: Get dealer location for GPS
local function getDealerLocation()
    if exports['oxide-blackmarket']:IsDealerValid() then
        return exports['oxide-blackmarket']:GetDealerCoords()
    end
    return nil
end

Custom Shop Item with Stock Check

-- Server-side: Check if item is in stock before custom purchase
local function canBuyFromDealer(itemName, quantity)
    local stock = exports['oxide-blackmarket']:GetItemStock(itemName)
    return stock >= quantity
end