GameMaker Studio · GML · Currency & store

gmda_grantCurrency

Applies a panel-defined currency grant by reason key (quest payout, level-up bonus).

Asynchronous (result via event)

Signature

gmda_grantCurrency(reason_key, [idempotency_key]) -> real

What it does

POSTs /currency/grant with the session headers. This is the generic reason-keyed grant path, distinct from the rewards claim path (daily/periodic). The queued grant_completed event carries success and response (the RPC payload, including the new balances and the amount applied). When success is false, response (or the event's error field) explains why, for example grant_not_found, cooldown_daily or cap_exceeded. Returns 1 once dispatched, or 0 when there is no active session.

Parameters

Name	Type	Default	Description
reason_key	string	required	The grant's reason key configured in the panel (e.g. "quest_reward").
idempotency_key	string	optional	Optional key to make retries safe so the grant is never applied twice. Omit it and the client generates a 24-character key for you.

How to call it

Call gmda_grantCurrency(reason_key), then read the grant_completed event with gmda_pollEvent(). This is for in-game rewards, not real-money purchases (use gmda_buyPack for those).

Result event: grant_completed { success, response }

Example

gmda_grantCurrency("quest_reward");

// in the Step event, drain the queue:
var e = gmda_pollEvent();
while (!is_undefined(e)) {
    if (e.event == "grant_completed") {
        if (e.success) show_debug_message("granted");
        else show_debug_message("grant failed");
    }
    e = gmda_pollEvent();
}

Use cases

Pay out currency when the player completes a quest.
Award a level-up or first-login bonus defined in the panel (subject to cooldowns or caps).

What it does

Name

Type

Default

Description

reason_key

string

required

The grant's reason key configured in the panel (e.g. "quest_reward").

idempotency_key

string

optional

Optional key to make retries safe so the grant is never applied twice. Omit it and the client generates a 24-character key for you.

Example

gmda_grantCurrency("quest_reward"); // in the Step event, drain the queue: var e = gmda_pollEvent(); while (!is_undefined(e)) { if (e.event == "grant_completed") { if (e.success) show_debug_message("granted"); else show_debug_message("grant failed"); } e = gmda_pollEvent(); }