# Notification Events

The SDK is notification based, so from within your game, you will need to have a clean way of responding to each with complementary events. This is to prevent games needing to continuously poll our backend for updates. The SDK is focused around providing data streams for two assets - NFTs and tokens.

## Game Actions

### BalanceRequested

When a request is made for the user's balance, a BalanceRequested event is triggered. 

The handler for this event should respond with balance for the user by using the function `SendBalance(receivedEvent, balance)`. The RequestId stored in event will be used for request identification on API-side.

```
Event: {
    string UserEmail,
    string RequestId
}
```

This is an example of the notification that will be sent to the game:

```json
{
  event: 'BalanceRequested',
  requestId: '26ebb6e3-48f8-46d5-b930-a302368f0701',
  email: 'user@test.com'
}
```

### InGameCurrencyDeposit

When the user has exchanged on-chain tokens into in-app currency, the game receives a notification with amount deposited for the current user. 

It is up to the game to update the user's in-game currency with the amount provided. The game will need to increment the user's in-game currency by this amount.

```
Event: {
    string UserEmail, 
    double BalanceIncrease,
    string TxHash
}
```

This is an example of the notification that will be sent to the game:

```json
{
  event: 'InGameCurrencyDeposit',
  requestId: '00077f08-26b4-4f95-a1ac-9ba914982273',
  email: 'test@catheongaming.com',
  balanceIncrease: 555,
  txHash: '0xc13d7905be5c989378a945487cd2a1193627ae606009e28e296d48ddaec66162'
}
```

### NftLinkStatusChanged

When the user links or unlinks an NFT to the game, an NftLinkStatusChanged event is triggered.

```
Event: { 
    string user_email,
    string wallet_address,
    string token_address,
    int status,
    string metadata
}
```

This is an example of the notification that will be sent to the game:

```json
{
  user_email: 'w54661c@gmail.com',
  wallet_address: '0xB05D9f248cCf546fE9d52A9ADA340cc361c8c163',
  token_address: '0x086cce368ee810f77257479b90bed1bb164420b5_176',
  status: 0,
  metadata: '{"metadata":{"name":"Runt the Wolf #4664","image":"https://storage.googleapis.com/fractal-launchpad-public-assets/angrymals/assets/4372.png","attributes":[{"value":"Runt","trait_type":"Angrymal"},{"value":"Wolves","trait_type":"Race"},{"value":"Common","trait_type":"Rarity"},{"value":"Brain dome","trait_type":"Hat"},{"value":"None","trait_type":"Eyes"},{"value":"None","trait_type":"Mouth"},{"value":"None","trait_type":"Makeup"},{"value":"None","trait_type":"Ears"},{"value":"Chinese dress","trait_type":"Dress"}],"description":"Show off your support with wacky in-game player banners that enables the core play-to-earn functionality, unlocks exclusive features, events and additional bonuses"},"collection":{"name":"Genesis Player Banner","symbol":"Angrymals"}}'
}
```

### InGameCurrencyWithdrawal

This event will be sent to the game when the user starts to exchange in-game currency for on-chain tokens. 

The handler for this event should adjust the user balance and respond with a `Result` by using the function `SendWithdrawResult(receivedEvent, result)`.

For details on how the token withdrawal works, please have a look at this [call diagram](https://hackmd.io/g5c7eXtnRAW5aaprgvtnfg?view). 

```
Event: {
    string RequestId,
    string UserEmail, 
    double BalanceDecrease
}
```

This is an example of the notification that will be sent to the game:

```json
{
  event: 'InGameCurrencyWithdrawal',
  requestId: '9ad3e825-ba65-4b0a-b03b-8f4e39cf1fd3',
  email: 'test@catheongaming.com',
  balanceDecrease: 555
}
```

### RollbackWithdrawal

This event will be sent to the game when an on-chain transaction fails. 

The handler for this event should adjust user balance and respond with `Result` by using the function `SendRollbackWithdrawResult(receivedEvent, result)`. 

```
Event: {
    string RequestId,
    string UserEmail, 
    double BalanceIncrease,
    string TxHash
}
```

This is an example of the notification that will be sent to the game:

```json
{
  event: 'RollbackWithdrawal',
  requestId: 'e95a9342-3c06-4223-83b3-0428bb89f524',
  email: 'test@catheongaming.com',
  balanceIncrease: 555,
  txHash: '0xc13d7905be5c989378a945487cd2a1193627ae606009e28e296d48ddaec66162'
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.catheongaming.com/notification-events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.