Embedded Wallets
How to
Setup Authentication
Telegram
Authorize

Telegram Authorize

Telegram Authorize API

Overview

This API endpoint allows you to login to your Xellar Embedded wallet account using telegram account.

  • HTTP Method: POST
  • Endpoint v2: /api/<VERSION>/auth/telegram

Request Body Parameters

  • data (required if dataString empty): The data object containing the id, first_name, last_name, username, photo_url, auth_date, hash. Remember to include all data from the Telegram response. If one of the data is missing, the request will fail.
  • dataString (required if data empty): If you are using Telegram Mini App, you can use this parameter instead. The dataString is Telegram initData that you get from the Telegram Mini App. Please do not modify the initData you received, because the request will fail.
  • botUsername (required): The bot username which was generated when you create a bot on Telegram.

Example Request Body

{
    "data": {
        "id": "123456789",
        "first_name": "John",
        "last_name": "Doe", // Optional, depends on the user's telegram profile
        "username": "johndoe", // Optional, depends on the user's telegram profile
        "photo_url": "https://t.me/i/userpic/320/johndoe.jpg", // Optional, depends on the user's telegram profile
        "auth_date": "1630510000",
        "hash": "f1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0t1u2v3w4x5y6z7"
    },
    // OR using dataString if you are using Telegram Mini App
    "dataString": "auth_date=1696600040&query_id=XXxxXXXXXXXxxxx&id=123456789&first_name=John&last_name=Doe&username=johndoe&is_premium=true&hash=f1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0t1u2v3w4x5y6z7",
    "botUsername": "your_bot_username"
}

Request

Request Headers

  • x-client-secret (required): Client secret which was generated when register in Xellar Embedded API Service Dashboard.

Example Request Syntax

cURL

curl -X POST -H "Content-Type: application/json" -H "x-client-secret: $YOUR_CLIENT_SECRET" -d '{ 
    "data": {
        "id": "123456789",
        "first_name": "John",
        "last_name": "Doe",
        "username": "johndoe",
        "photo_url": "https://t.me/i/userpic/320/johndoe.jpg",
        "auth_date": "1630510000",
        "hash": "f1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0t1u2v3w4x5y6z7"
    },
    "dataString": "auth_date=1696600040&query_id=XXxxXXXXXXXxxxx&id=123456789&first_name=John&last_name=Doe&username=johndoe&is_premium=true&hash=f1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0t1u2v3w4x5y6z7",
    "botUsername": "your_bot_username"
}' <BASE_URL>/api/<VERSION>/auth/telegram

Response

The response will include a JSON object with the following properties:

  • status (number): The HTTP status code of the response (e.g., 200 for success).
  • message (string): A message providing additional information about the operation.
  • data (object): An object containing the accessToken and isWalletCreated. If the account already has an embedded wallet, the response will include walletToken and isWalletCreated.
    • rampableAccessToken : JWT token used to access the Rampable Operation endpoint. This token will only be available if the account already create a rampable account and the organization has enabled the rampable feature.
    • address (string): (Version 1 only) the wallet address of the user.
    • addresses (array): (Version 2 only) the wallet addresses of the user. The array contains the network and address of the wallet.

Example Response (if account do not have an Embedded wallet)

{
    "status": 200,
    "message": "ok",
    "data": {
        "rampableAccessToken": "your_rampable_access_token_here",
        "accessToken": "eyy9afadeasf31....",
        "isWalletCreated": false
    }
}

Example Response (if account already have an Embedded wallet)

{
    "status": 200,
    "message": "ok",
    "data": {
        "rampableAccessToken": "your_rampable_access_token_here",
        "walletToken": "eyy9afadeasf31....",
        "isWalletCreated": true,
        "address": "0x123546..."
    }
}

Example Response (if account already have an Embedded wallet in v2)

📝

This response only works on v2

{
    "status": 200,
    "message": "ok",
    "data": {
        "rampableAccessToken": "your_rampable_access_token_here",
        "walletToken": "eyy9afadeasf31....",
        "refreshToken": "eysfsfsffssf1....",
        "isWalletCreated": true,
        "addresses": [
            {
                "network": "evm",
                "address": "0x123546..."
            },
            {
                "network": "solana",
                "address": "Af3sdf8JsjF..."
            },
            {
                "network": "bitcoin",
                "address": "bc1q3sdf8JsjF..."
            }
        ]
    }
}
Configuring TelegramWhatsapp