> For the complete documentation index, see [llms.txt](/llms.txt)

# GS2-Exchange Transaction Actions

Specification of verify/consume/acquire transaction actions





## Consume Action



### Gs2Exchange:DeleteAwaitByUserId

Delete Exchange Await by 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.

**Quantity specification supported: NO**

**Reversible action: NO**

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128 chars | Namespace name<br>Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| userId | string |  | ✓|  |  ~ 128 chars | User ID<br>Specify `#{userId}` to substitute the currently logged-in user's ID. |
| awaitName | string |  | ✓| UUID |  ~ 36 chars | Exchange Await name<br>Maintains a unique name for each Exchange Await.<br>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 |




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

**YAML**
```yaml

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

**GS2-Script**
```lua

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 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.

**Quantity specification supported: YES**

**Reversible action: NO**

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




**JSON**
```json
{
    "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"
    }
}
```

**YAML**
```yaml

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"
```

**GS2-Script**
```lua

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 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.

**Quantity specification supported: YES**

**Reversible action: NO**

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




**JSON**
```json
{
    "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"
    }
}
```

**YAML**
```yaml

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"
```

**GS2-Script**
```lua

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 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.

**Quantity specification supported: YES**

**Reversible action: NO**

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128 chars | Namespace name<br>Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| userId | string |  | ✓|  |  ~ 128 chars | User ID<br>Specify `#{userId}` to substitute the currently logged-in user's ID. |
| rateName | string |  | ✓|  |  ~ 128 chars | Exchange Rate Model name<br>Unique Exchange Rate Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| count | int |  | | 1 | 1 ~ 10000 | Number of exchanges<br>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&lt;Config&gt; |  | | [] | 0 ~ 32 items | Default configuration values applied when obtaining rewards |
| timeOffsetToken | string |  | |  |  ~ 1024 chars | Time offset token |




**JSON**
```json
{
    "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"
    }
}
```

**YAML**
```yaml

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"
```

**GS2-Script**
```lua

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.

**Quantity specification supported: NO**

**Reversible action: NO**

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




**JSON**
```json
{
    "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"
    }
}
```

**YAML**
```yaml

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"
```

**GS2-Script**
```lua

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 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.

**Quantity specification supported: YES**

**Reversible action: NO**

|  | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128 chars | Namespace name<br>Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| userId | string |  | ✓|  |  ~ 128 chars | User ID<br>Specify `#{userId}` to substitute the currently logged-in user's ID. |
| awaitName | string |  | ✓| UUID |  ~ 36 chars | Exchange Await name<br>Maintains a unique name for each Exchange Await.<br>The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each Exchange Await. |
| skipType | string (enum)<br>enum {<br>&nbsp;&nbsp;"complete",<br>&nbsp;&nbsp;"minutes",<br>&nbsp;&nbsp;"totalRate",<br>&nbsp;&nbsp;"remainRate"<br>}<br> |  | | "complete" |  | Skip type"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<br>* 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 |




**JSON**
```json
{
    "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"
    }
}
```

**YAML**
```yaml

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"
```

**GS2-Script**
```lua

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",
})
```


---