API Endpoints

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

API URL

URL for POST requests: /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."
}