API Endpoints

Work in progress

This page is a placeholder.

Here, you can view information about existing endpoints and how to make requests for them.

API URL

URL for POST requests: https://tganalytics.xyz/events

POST events

This request is needed to record an event in the database.

Body

The request body may contain an array rather than a single event. The main thing is that all events in the array satisfy the scheme below.

Required

Field	Type	Description
`user_id`	number	Unique identifier for the user.
`event_name`	string	The name of the event from the supported events.
`session_id`	string	Session identifier for tracking user sessions. Must be UUID.
`app_name`	string	The name of the application that you specified when creating the token

Optional

Field	Type	Description
`is_premium`	boolean	If the user has a premium account, by default - false
`is_success`	boolean	Indicates whether a wallet is connected or the transaction was successful, by default - false
`error_message`	string	Error message if the wallet connection or transaction is unsuccessful
`error_code`	number	Description: error code if the wallet connection or transaction is unsuccessful
`wallet_address`	string	Wallet address involved in the event
`wallet_type`	string	Type of the wallet
`wallet_version`	string	Version of the wallet software
`auth_type`	enum	Type of authorization used. `0` - `ton_addr`, `1` - `ton_proof`.
`valid_until`	string	Timestamp until when a transaction offer is valid
`from`	string	Wallet address initiating the transaction
`messages`	`{ address: string; amount: string }`	List of transactions `{to, amount}` involved in the event
`custom_data`	object	Object to store custom event details as needed
`client_timestamp`	string	The time when the event occurred on the client
`platform`	string	The platform from which the MiniApp was opened
`locale`	string	User language code
`start_param`	string	`tgWebAppStartParam`
`url_referer`	string	The URL of the web application from which the request was sent
`scope`	string	Event scope

Request body example:

[
  {
    "event_name": "app-init",
    "session_id": "10c574d9-6d2c-4e6d-a141-ce6da141ce6d",
    "user_id": 111111111,
    "app_name": "docs",
    "is_premium": true,
    "platform": "tdesktop",
    "locale": "en",
    "client_timestamp": "1743503599534"
  }
]

[
  {
    "event_name": "connection-started",
    "custom_data": {
      "ton_connect_sdk_lib": "3.0.3",
      "ton_connect_ui_lib": "2.0.5"
    },
    "session_id": "10c574d9-6d2c-4e6d-a141-ce6da141ce6d",
    "user_id": 111111111,
    "app_name": "docs",
    "is_premium": true,
    "platform": "tdesktop",
    "locale": "en",
    "client_timestamp": "1743503647541"
  }
]

[
  {
    "event_name": "connection-error",
    "is_success": false,
    "error_message": "Connection was cancelled",
    "error_code": null,
    "custom_data": {
      "ton_connect_sdk_lib": "3.0.3",
      "ton_connect_ui_lib": "2.0.5"
    },
    "session_id": "10c574d9-6d2c-4e6d-a141-ce6da141ce6d",
    "user_id": 111111111,
    "app_name": "docs",
    "is_premium": true,
    "platform": "tdesktop",
    "locale": "en",
    "client_timestamp": "1743503683701"
  }
]

Headers

Instead of YOUR_TOKEN, you need to specify the token received using the managing integration. (TO DO link)

{
    "TGA-Auth-Token": "YOUR_TOKEN",
    "Content-Type": "application/json"
}

Responses

HTTP201

Description: The event has been successfully recorded
Content:

{
    "message": "Success record."
}

HTTP400

Description: The event was not recorded due to server issues
Content:

{
    "message": "Failed to record"
}

HTTP400

Description: The token was entered incorrectly or in the wrong format
Content:

{
    "message": "The token is not specified in the headers or is specified incorrectly."
}

HTTP400

Description: The entered token is invalid (was not created through a Data Chief bot)
Content:

{
    "message": "Token is invalid."
}

HTTP400

Description: The request body contains the application name that does not match the token
Content:

{
    "message": "Invalid app_name is specified."
}

HTTP400

Description: the body specified in the request was not validated (for example, the type of one of the fields does not match)
Content:

{
    "status": 400,
    "message": "VALIDATION_MISMATCH_REPORT"
}

HTTP403

Description: an attempt to use the API on a domain name that does not match the token
Content:

{
    "message": "The domain name does not match."
}

HTTP429

Description: too many requests from the client in a certain amount of time
Content:

{
    "message": "Too many requests. Try again later."
}

API Endpoints

On this page