Endpoints

Here you can view information about existing endpoints and how to make requests for them. URL for requests: https://tganalytics.xyz

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

• user_id

  • Type: number

  • Description: unique identifier for the user.

• event_name

  • Type: string

  • Description: the name of the event from the supported

• session_id

  • Type: string (must be UUID)

  • Description: session identifier for tracking user sessions

• app_name

  • Type: string

  • Description: the name of the application that you specified when creating the token

Optional

• is_premium

  • Type: boolean

  • Description: if the user has a premium account, by default - false

• is_success

  • Type: boolean

  • Description: indicates whether a wallet is connected or the transaction was successful, by default - false

• error_message

  • Type: string

  • Description: error message if the wallet connection or transaction is unsuccessful

• error_code

  • Type: number

  • Description: error code if the wallet connection or transaction is unsuccessful

• wallet_address

  • Type: string

  • Description: wallet address involved in the event

• wallet_type

  • Type: string

  • Description: type of the wallet

• wallet_version

  • Type: string

  • Description: version of the wallet software

• auth_type

  • Type: enum(0 - 'ton_addr', 1 - 'ton_proof')

  • Description: type of authorization used

• valid_until

  • Type: string

  • Description: timestamp until when a transaction offer is valid

• from

  • Type: string

  • Description: wallet address initiating the transaction

• messages

  • Type: { address: string; amount: string }[]

  • Description: list of transactions {to, amount} involved in the event

• custom_data

  • Type: object

  • Description: object to store custom event details as needed

• client_timestamp

  • Type: string

  • Description: the time when the event occurred on the clent

• platform

  • Type: string

  • Description: the platform from which the MiniApp was opened

• locale

  • Type: string

  • Description: user language code

• start_param

  • Type: string

  • Description: tgWebAppStartParam

• url_referer

  • Type: string

  • Description: the URL of the web application from which the request was sent

• scope

  • Type: string

  • Description: event scope

Request Body Example`s:

[
  {
    "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 bot

{
    "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."
}