# TonApi Events

## Events and actions

Events describe changes to the account balances in TON. Each event consists of one or more actions. Common transfers of coins and tokens are single-action events, while a trade on DEX produces a multi-action event.

Each event provides information from the perspective of all involved accounts. For example, an [NftItemTransfer](#NftItemTransfer) event will be returned for the sender’s account, recipient’s account and for the token address.

Events are offered in two flavors:

* Type [Event](#Event) contains complete set of all the actions and fees for all parties involved.
* Type [AccountEvent](#AccountEvent) contains a subset of actions relevant to a given account. Instead of a list of fees, it contains a single Fee object describing fees paid by the account.

## Events vs transactions

TON blockchain consists of _contracts_ that send _messages_ to each other and update their own states via _transactions_. These are low-level building blocks for the wallets, tokens and decentralized apps.

_Events_ and _actions_ are higher level abstractions that combine together multiple messages and transactions in a single entity that is easier to understand. For example, a single action `NftSend` consists of three transactions: (1) authentication on the sender’s wallet, (2) ownership update on the NFT contract, (3) notification sent to the new owner.

Transactions and messages form a tree, while events are flat lists of actions.

## Understanding fees

TON network has a complex system of fees. Sometimes both the sender and the recipient are paying fees for storage (_rent_) and processing costs (_gas_). When an additional contract is deployed, wallets typically send extra coins to cover the costs and initial balance of a new contract as _deposit_, while receiving unused back as _refund_.

One account may produce multiple actions while paying common fees for its storage and gas. To avoid any confusion, on API response for an event there can be return Array of [Fee](#Fee) objects, each for every account involved.

The fees are broken down in the following slots:

* **total**: total amount of fees paid by the account during the event. Calculated as `gas`+`rent`+`deposit`-`refund`.
* **gas**: total amount of coins spent for the processing of the messages by the account over all transactions within the event.
* **rent**: total amount of coins paid for the storage rent by the account.
* **deposit**: total amount of coins transferred by the wallet to cover the costs of the entire transaction chain. Some of these are left as balances of the newly created contracts.
* **refund**: excess coins from the `deposit` that were returned to the sender after the operation is completed.

Note: sometimes `refund` may exceed `deposit` and the `total` fees could become negative. This may happen e.g. when a subscription contract is destroyed and its balance is returned to the merchant.

## Presenting events

To display the events correctly it is necessary to filter out actions that are not related to the account. This is done automatically by the API when you request [AccountEvents](#AccountEvent) instead of plain [Events](#Event).

The user’s wallet should check whether the transfer is incoming or outgoing using the sender/recipient addresses.

## Failed actions

Actions may fail and the appropriate messages may or may not bounce. Failure is indicated by the `status` field in each action. Bouncing is not indicated explicitly, but is reflected in `refund` field in the fees:

* If the message has failed and bounced, then the action is considered as not happened; the TONs sent are marked within the `deposit` in the `Fee` object and returned TONs are specified in the `refund` field.
* If the message has failed, but not bounced, then action is considered as not happened; the TONs sent are marked within the `deposit` in the `Fee` object.
* If the message is sent as non-bounceable to the uninitialized contract, then the action is successful.

## Versioning

Each version of API guarantees a fixed set of events.

E.g. if v1 does not recognize usage of a DEX, it will return a simple `JettonTransfer` with a recipient address being the DEX contract. When v2 adds `JettonPlaceOnSale` action, old clients will still render plain transfers.

From the API perspective all the newer actions are reformatted in terms of older actions on the fly for compatibility.

## Definitions

### Event

Complete description of the event for all accounts involved.

This event can be returned for any TON contract address: wallet account, NFT item, subscription contract, sale contract etc.

{
    "event_id":    "<event-id>",
    "timestamp":   15612039230,   // timestamp of the initial transaction
    "fees": [Fee],                // 
    "actions": [
        Action<TonTransfer>,
        Action<TonDeploy>,
        Action<NftCollectionCreate>,
        Action<NftCollectionTransfer>,
        Action<NftItemCreate>,
        Action<NftItemTransfer>,
        Action<NftSalePlace>,
        Action<NftSaleFulfill>,
        Action<JettonMint>,
        Action<JettonTransfer>,
        Action<JettonBurn>,
        Action<SubscriptionCreate>,
        Action<SubscriptionCancel>,
        Action<SubscriptionPayment>,
    ]
}

### AccountEvent

Filtered-down description of the event for a given account. Contains a subset of actions that are relevant to the given account.

This event can only be returned for wallet contracts. If you want to receive events for a given token or a sale contract, request [Events](#event) instead.

{
    "event_id":    "<event-id>",
    "timestamp":   15612039230,   // timestamp of the initial transaction
    "account":     Account,
    "fee": Fee,
    "actions": [
        Action<TonTransfer>,
        Action<TonDeploy>,
        Action<NftCollectionCreate>,
        Action<NftCollectionTransfer>,
        Action<NftItemCreate>,
        Action<NftItemTransfer>,
        Action<NftSalePlace>,
        Action<NftSaleFulfill>,
        Action<JettonMint>,
        Action<JettonTransfer>,
        Action<JettonBurn>,
        Action<SubscriptionCreate>,
        Action<SubscriptionCancel>,
        Action<SubscriptionPayment>,
    ]
}

### Fee

{
    "account":   Address,   // account that paid the fees
    "total":     "100",     // = gas+rent+deposit-refund
    "gas":       "80",      // nanocoins cost of gas
    "rent":      "10",      // nanocoins cost of rent
    "deposit":   "110",     // nanocoins sent with the message from the account
    "refund":    "100",     // nanocoins returned to the account as a response msg or a bounced msg
}

### Action

{
    "type":     "<action-type>",
    "status":   ActionStatus,
    "<action-type>": TonTransfer | TonDeploy | NftCollectionCreate...
}

### ActionStatus

Action could be pending, completed or failed.

ActionStatus = "pending" | "ok" | "failed"

Pending status is for actions that map to queued outgoing messages that are not yet processed by the destination contract and shardchain. Pending status may also belong to all the actions when the event is in the mempool.

Failed action maps on a failed transaction. Such transaction may or may not bounce the message: the resulting difference in coins is reflected within the [Fee](#Fee) structure.

### TonTransfer

{
    "amount":       "100000000",        // nanocoins
    "recipient":    Account,   // address of the recipient
    "sender":       Account,     // address of the sender
    "payload":      "<hex-encoded payload>",
    "comment":      "Hello, world", // optional
}

### TonDeploy

{
    "amount":       "100000000",        // nanocoins
    "recipient":    Account,   // address of the recipient
    "sender":       Account,     // address of the sender
    "state_init":   "<hex-encoded stateinit>", // recipient’s StateInit
    "payload":      "<hex-encoded payload>",
    "comment":      "Hello, world", // optional
}

### NftCollectionCreate

TBD.

### NftCollectionTransfer

TBD.

### NftItemCreate

TBD.

### NftItemTransfer

  {
    "nft":          NFTItem, 
    "sender":       Account,    // address of the sender
    "recipient":    Account,    // address of the recipient
    "payload":      "<hex-encoded payload>",
    "comment":      "Hello, world" // utf8 string from payload
  }

### NftSalePlace

  {
    "owner":          Account, // owner of the token who places it on sale
    "nft_item":       NFTItem,
    "nft_collection": NFTCollection
    "sale_id":        Address,  // contract of the sale
    "price": {
        "currency": "TON",
        "amount":   "12345", // nanocoins
    },
  },

### NftSaleFulfill

When the sale is fulfilled, the payment is reflected in the `TonTransfer` action towards the seller’s account.

  {
    "nft_item":       NFTItem,
    "nft_collection": NFTCollection
    "sale_id":        Address,        // contract of the sale
    "recipient":      Account,        // who received the token
    "owner":          Account,
  },

### JettonMint

TBD.

### JettonTransfer

  {
    "jetton":       Jetton, 
    "amount":       "1000000",  // base units for this jetton
    "sender":       Account,    // address of the sender
    "recipient":    Account,    // address of the recipient
    "payload":      "<hex-encoded payload>",
    "comment":      "Hello, world" // utf8 string from payload
  }

### JettonBurn

TBD.

### SubscriptionCreate

When the subscription is created, full amount is deposited to the subscription contract. The base amount is left on the contract and the remaining coins are transferred out to the recipient. Hence, the difference is paid by the recipient and recorded as `FeePayment.deposit`.

  {
    "recipient":    Account,
    "sender":       Account,
    "contract_id":  Address,
    "subscription": Subscription,
    "amount":       "1000000000", // nanocoins
    "interval":     "2629800", // seconds
  },

### SubscriptionCancel

Reminder of coins on the subscription contract are recorded as `FeePayment.refund` for the recipient.

Coins attached to the message by the user who cancels subscription are recorded as `FeePayment.deposit` on their end.

  {
    "recipient":    Account,
    "sender":       Account,
    "contract_id":  Address, 
    "subscription": Subscription,
  },

### SubscriptionPayment

  {
    "recipient":    Account,
    "sender":       Account,
    "contract_id":  Address, 
    "amount":       "1000000000",
    "subscription": Subscription,
  },

## Entities

### Address

Address represents TON contract location: workchain + hash.

Address = "<wc>:<hex-encoded hash>"  // e.g. 0:afe8f8ade781324...

### Account

{
    "address": Address,
    "name":    "Ton foundation" // optional
    "icon":    "https://ton.org/logo.png", // optional
    "isScam":  false, // optional
}

### NFTItem

{
    "id":             Address, 
    "collection_id":  Address, // optional
    "name":           "Token name",
    ...
}

### NFTCollection

{
    "id":      Address, 
    "name":    "Collection name",
    ...
}

### Jetton

{
    "id":           Address, 
    "name":         "Token name",
    "symbol":       "TKN",
    "icon":         "https://example.com/tkn.png",
    "divisibility": 9,
    ...
}

### Subscription

{
    "id":        Address, 
    "amount":    "10000000",      // nanocoins
    "interval":  23564800,        // seconds
    "name":      "Product name",  // optional
}