GS2-Exchange Transaction Actions

Specification of verify/consume/acquire transaction actions

Consume Action

Gs2Exchange:DeleteAwaitByUserId

Delete Exchange Await by specifying a user ID

Deletes an exchange await record for the specified user. This cancels the pending exchange, and any rewards that have not yet been acquired are forfeited.

Supports quantity specification: NO

Whether the action is reversible: NO

	Type	Required	Default	Value Limits	Description
namespaceName	string	✓		~ 128 chars	Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
userId	string	✓		~ 128 chars	User ID Specify `#{userId}` to substitute the currently logged-in user’s ID.
awaitName	string	✓	UUID	~ 36 chars	Exchange Await name Maintains a unique name for each Exchange Await. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each Exchange Await.
timeOffsetToken	string			~ 1024 chars	Time offset token

{
    "action": "Gs2Exchange:DeleteAwaitByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "awaitName": "[string]Exchange Await name",
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Exchange:DeleteAwaitByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  awaitName: "[string]Exchange Await name"
  timeOffsetToken: "[string]Time offset token"

transaction.service("exchange").consume.delete_await_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    awaitName="[string]Exchange Await name",
    timeOffsetToken="[string]Time offset token",
})

Acquire Action

Gs2Exchange:ExchangeByUserId

Perform exchange by specifying a user ID

Executes a resource exchange based on the specified Exchange Rate Model for the specified user. Validates the rate model’s timing type: for ‘immediate’ timing, the namespace must have direct exchange enabled; for ‘await’ timing, the namespace must have await exchange enabled. A transaction (transaction) is issued to execute the consume/verify/acquire actions defined in the rate model, multiplied by the specified count.

Supports quantity specification: YES

Whether the action is reversible: NO

	Type	Required	Default	Value Limits	Description
namespaceName	string	✓		~ 128 chars	Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
rateName	string	✓		~ 128 chars	Exchange Rate Model name Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
userId	string	✓		~ 128 chars	User ID Specify `#{userId}` to substitute the currently logged-in user’s ID.
count	int	✓		1 ~ 1073741821	Number of exchanges
config	List<Config>		[]	0 ~ 32 items	Configuration values applied to transaction variables
timeOffsetToken	string			~ 1024 chars	Time offset token

{
    "action": "Gs2Exchange:ExchangeByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "rateName": "[string]Exchange Rate Model name",
        "userId": "[string]User ID",
        "count": "[int]Number of exchanges",
        "config": [
            {
                "key": "[string]Name",
                "value": "[string]Value"
            }
        ],
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Exchange:ExchangeByUserId
request:
  namespaceName: "[string]Namespace name"
  rateName: "[string]Exchange Rate Model name"
  userId: "[string]User ID"
  count: "[int]Number of exchanges"
  config: 
    - key: "[string]Name"
      value: "[string]Value"
  timeOffsetToken: "[string]Time offset token"

transaction.service("exchange").acquire.exchange_by_user_id({
    namespaceName="[string]Namespace name",
    rateName="[string]Exchange Rate Model name",
    userId="[string]User ID",
    count="[int]Number of exchanges",
    config={
        {
            key="[string]Name",
            value="[string]Value"
        }
    },
    timeOffsetToken="[string]Time offset token",
})

Gs2Exchange:IncrementalExchangeByUserId

Perform incremental cost exchange by specifying a user ID

Executes a resource exchange where the cost increases progressively with each execution, based on the specified Incremental Cost Exchange Rate Model for the specified user. The consume cost is calculated according to the model’s calculation type (linear formula or GS2-Script) and the current exchange count. A transaction (transaction) is issued to execute the consume and acquire actions.

Supports quantity specification: YES

Whether the action is reversible: NO

	Type	Required	Default	Value Limits	Description
namespaceName	string	✓		~ 128 chars	Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
rateName	string	✓		~ 128 chars	Incremental Cost Exchange Rate Model name Incremental Cost Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.).
userId	string	✓		~ 128 chars	User ID Specify `#{userId}` to substitute the currently logged-in user’s ID.
count	int	✓		1 ~ 1073741821	Number of exchanges
config	List<Config>		[]	0 ~ 32 items	Configuration values applied to transaction variables
timeOffsetToken	string			~ 1024 chars	Time offset token

{
    "action": "Gs2Exchange:IncrementalExchangeByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "rateName": "[string]Incremental Cost Exchange Rate Model name",
        "userId": "[string]User ID",
        "count": "[int]Number of exchanges",
        "config": [
            {
                "key": "[string]Name",
                "value": "[string]Value"
            }
        ],
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Exchange:IncrementalExchangeByUserId
request:
  namespaceName: "[string]Namespace name"
  rateName: "[string]Incremental Cost Exchange Rate Model name"
  userId: "[string]User ID"
  count: "[int]Number of exchanges"
  config: 
    - key: "[string]Name"
      value: "[string]Value"
  timeOffsetToken: "[string]Time offset token"

transaction.service("exchange").acquire.incremental_exchange_by_user_id({
    namespaceName="[string]Namespace name",
    rateName="[string]Incremental Cost Exchange Rate Model name",
    userId="[string]User ID",
    count="[int]Number of exchanges",
    config={
        {
            key="[string]Name",
            value="[string]Value"
        }
    },
    timeOffsetToken="[string]Time offset token",
})

Gs2Exchange:CreateAwaitByUserId

Create Exchange Await by specifying a user ID

Creates a new exchange await record for a time-delayed exchange. The specified rate model must have its timing type set to ‘await’; otherwise the request is rejected. The await starts with zero skip seconds, and the lock time defined in the rate model determines how long the user must wait before acquiring the rewards. Default configuration values can be set at creation time and will be merged with any config provided at acquisition time.

Supports quantity specification: YES

Whether the action is reversible: NO

	Type	Required	Default	Value Limits	Description
namespaceName	string	✓		~ 128 chars	Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
userId	string	✓		~ 128 chars	User ID Specify `#{userId}` to substitute the currently logged-in user’s ID.
rateName	string	✓		~ 128 chars	Exchange Rate Model name Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
count	int		1	1 ~ 10000	Number of exchanges The number of times this exchange should be performed. Multiple exchanges can be batched into a single await, multiplying both the cost consumed and the rewards received.
config	List<Config>		[]	0 ~ 32 items	Default configuration values applied when obtaining rewards
timeOffsetToken	string			~ 1024 chars	Time offset token

{
    "action": "Gs2Exchange:CreateAwaitByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "rateName": "[string]Exchange Rate Model name",
        "count": "[int]Number of exchanges",
        "config": [
            {
                "key": "[string]Name",
                "value": "[string]Value"
            }
        ],
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Exchange:CreateAwaitByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  rateName: "[string]Exchange Rate Model name"
  count: "[int]Number of exchanges"
  config: 
    - key: "[string]Name"
      value: "[string]Value"
  timeOffsetToken: "[string]Time offset token"

transaction.service("exchange").acquire.create_await_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    rateName="[string]Exchange Rate Model name",
    count="[int]Number of exchanges",
    config={
        {
            key="[string]Name",
            value="[string]Value"
        }
    },
    timeOffsetToken="[string]Time offset token",
})

Gs2Exchange:AcquireForceByUserId

Receive rewards for Exchange Await without waiting for the lock time

Force-acquires the rewards for an exchange await regardless of whether the lock time has elapsed. This bypasses the normal wait time check, allowing immediate reward acquisition. The provided config values are merged with the default config set at await creation time. A transaction (transaction) is issued to execute the acquire actions defined in the rate model.

Supports quantity specification: NO

Whether the action is reversible: NO

	Type	Required	Default	Value Limits	Description
namespaceName	string	✓		~ 128 chars	Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
userId	string	✓		~ 128 chars	User ID Specify `#{userId}` to substitute the currently logged-in user’s ID.
awaitName	string	✓	UUID	~ 36 chars	Exchange Await name Maintains a unique name for each Exchange Await. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each Exchange Await.
config	List<Config>		[]	0 ~ 32 items	Configuration values applied to transaction variables
timeOffsetToken	string			~ 1024 chars	Time offset token

{
    "action": "Gs2Exchange:AcquireForceByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "awaitName": "[string]Exchange Await name",
        "config": [
            {
                "key": "[string]Name",
                "value": "[string]Value"
            }
        ],
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Exchange:AcquireForceByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  awaitName: "[string]Exchange Await name"
  config: 
    - key: "[string]Name"
      value: "[string]Value"
  timeOffsetToken: "[string]Time offset token"

transaction.service("exchange").acquire.acquire_force_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    awaitName="[string]Exchange Await name",
    config={
        {
            key="[string]Name",
            value="[string]Value"
        }
    },
    timeOffsetToken="[string]Time offset token",
})

Gs2Exchange:SkipByUserId

Skip Exchange Await by specifying a user ID

Accelerates or skips the waiting time of an exchange await. Supports four skip types: ‘complete’ skips the entire remaining wait, ‘minutes’ adds the specified minutes to skip seconds, ’totalRate’ skips a percentage of the total lock time, and ‘remainRate’ skips a percentage of the remaining wait time. The skip seconds are capped at the total lock time and cannot exceed it.

Supports quantity specification: YES

Whether the action is reversible: NO

Type Condition Required Default Value Limits Description

namespaceName

string

✓

~ 128 chars

Namespace name

Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).

userId

string

✓

~ 128 chars

User ID
Specify #{userId} to substitute the currently logged-in user’s ID.

awaitName

string

✓

UUID

~ 36 chars

Exchange Await name

Maintains a unique name for each Exchange Await.
The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each Exchange Await.

skipType

string (enum)
enum {
  “complete”,
  “minutes”,
  “totalRate”,
  “remainRate”
}

“complete”

Skip type

Definition	Description
“complete”	Complete skip
“minutes”	Skip by specifying time(minutes)
“totalRate”	Skip by specifying the percentage of total waiting time
“remainRate”	Skip by specifying the percentage of remaining waiting time

minutes

int

{skipType} == “minutes”

0 ~ 2147483646

Minutes to skip

* Enabled only if skipType is “minutes”

rate float {skipType} == “totalRate” or {skipType} == “remainRate” 0 ~ 1 Percentage of time to skip

timeOffsetToken string ~ 1024 chars Time offset token

{
    "action": "Gs2Exchange:SkipByUserId",
    "request": {
        "namespaceName": "[string]Namespace name",
        "userId": "[string]User ID",
        "awaitName": "[string]Exchange Await name",
        "skipType": "[string]Skip type",
        "minutes": "[int]Minutes to skip",
        "rate": "[float]Percentage of time to skip",
        "timeOffsetToken": "[string]Time offset token"
    }
}

action: Gs2Exchange:SkipByUserId
request:
  namespaceName: "[string]Namespace name"
  userId: "[string]User ID"
  awaitName: "[string]Exchange Await name"
  skipType: "[string]Skip type"
  minutes: "[int]Minutes to skip"
  rate: "[float]Percentage of time to skip"
  timeOffsetToken: "[string]Time offset token"

transaction.service("exchange").acquire.skip_by_user_id({
    namespaceName="[string]Namespace name",
    userId="[string]User ID",
    awaitName="[string]Exchange Await name",
    skipType="[string]Skip type",
    minutes="[int]Minutes to skip",
    rate="[float]Percentage of time to skip",
    timeOffsetToken="[string]Time offset token",
})