Handcash Telegram Bot

Getting Started 

In order to start using your Handcash Wallet directly from Telegram you need follow this steps:

1) Click to open a Telegram private chat with @HandcashBot
2) Type /connect to generate your private authorization link
3) Click in the authorization link and connect to your Handcash wallet
4) Authorize the Handcash Telegram Bot app and make sure it returns to a succesful authorization page.
5) Learn the commands below and enjoy HandcashBot services on your Telegram account.


@Handcashbot on Telegram

Bot features 

Direct Transactions 

The /pay and /tip commands sends direct transactions only to the valid users you have mentioned in the command receivers list.

Valid receivers on the list can be:

  1. Any HandCash handle: $username
    The HandCash users $handles only needs to be a valid. They are not required to be on your HandCash friends list to be able to receive.

  2. A Telegram handle: @username
    Will work only if the Telegram user being mentioned has already connected to his HandCash wallet, or if had already assigned a valid $handle, paymail or BSV address to his Telegram account with /set prefixed commands.

  3. A valid paymail: username@domain.tld
    The paymail needs to be valid and is validated on the HandCash api layer, failing the transaction if invalid.

  4. A valid BSV address
    Any valid BSV mainnet address is accepted.

Randomized Transactions 

The /pew and /rain commands sends transactions to a number of random users picked from a shuffled list of valid users.

Valid users lists are:

  1. Users on your HandCash friends list
    When running randomized commands from the bot private chat, the bot picks the users randomly from your shuffled list of HandCash friends. You can also use the &friends and &handcash placeholder to refer to your group of HandCash friends list.

  2. Active users on groups/chat rooms
    When running randomized commands from group chats, the bot picks the users randomly from a shuffled list of the group members that has the bot activated.

Transaction Messages 

You can send custom text messages to all receivers with your bot transactions.

Use the pipe operator, or “|” character, immediately after your receivers list, or after the receivers count, and just type your custom message, like the example below:

/command [amount] [currency alias] to [receiver list|receivers count] | My optional custom message!

If you don’t type any message, the bot will pick a random one from a poll of short quotes.

Special Placeholders 

Special lists placeholders are reserved words that you can type on your commands receivers list to reference a group of users you are targeting on your receivers list.

The special lists placeholders handles are:

  1. all or &all
    Represents all group members that have the bot activated, when used from inside group chats.
    Represents all users in your HandCash friends list, when used from inside bot private chat.

  2. friends or &friends or handcash or &handcash
    Represents all users in your HandCash friends list.

Currency conversion 

The bot automatically converts fiat values to satoshis in any transaction that uses the supported fiat aliases. This is done by using the builtin conversion function that comes with the HandCash wallet api. The prices for the conversions are the same used by HandCash when you send transactions by typing fiat values directly from your HandCash wallet.

Currency aliases 

There are multiple names and characters options for you to refer to the units or currencies when running the bot commands. So, you can confortably use your preferred name to make your transactions.

The table below shows all supported UNIT ALIASES:

Unit AliasUnit NameDescriptionOther Aliases
SATSatoshis1 SatoshiS, SATS, SATOSHI, SATOSHIS
BSVBitcoinSV100.000.000 Satothis₿, BITCOINSV, BITCOIN, BSVS
DURODuro500 SatoshisĐ, D, DU, DUR, DUROS
KILOKilosats1.000 SatoshisK, KS, KILOS, KILOSAT, KILOSATS
MEGAMegasats1.000.000 SatoshisM, MS, MEGAS, MEGASAT, MEGASATS

The table below shows all supported CURRENCIES ALIASES:

Currency AliasCurrency NameOther Aliases
USDUS DollarUSD, $, DOLLAR, DOLLARS, DOLAR, DOLARS
EUREurozone EuroEUR, €, EURO, EUROS
GBPBritish PoundGBP, £, POUND, POUNDS
JPYJapanese YenJPY, YEN
ARSArgentinian Peso–
AUDAustralian Dollar–
BRLBrazilian RealBRL, R$, REAL, REAIS
CADCanadian Dollar
CHFSwiss FrancFRANC
CNYChinese YuanYUAN
COPColombian Peso–
CZKCzech KorunaKORUNA
DKKDanish Krone–
HKDHong Kong Dollar–
KRWKorean WonWON
MXNMexican Peso–
NOKNorwegian Krone–
NZDNew Zealand Dollar–
PHPPhilippine Peso–
RUBRussian RubleRUBLE
SEKSwedish KronaKRONA
SGDSingapore Dollar–
THBThai BahtTHAI, BAHT
ZARSouth African RandRAND

Bot commands 

/connect command 

The /connect command connects your Handcash wallet to your Telegram user, by generating a personal authorization link only from inside the @HandcashBot private chat.

/balance command 

Type /balance to see your wallet spendable balance from your private chat with the bot. If you type /balance from a public chat, the bot will always answer from the private chat.

The "Spendable balance" may appear lower than your actual total HandCash balance. 
Please check the "Spending Limit" setting within your HandCash app to update your limit for connected apps.

/pay command

/pay [amount] [currency alias] to [receivers list]
| [optional custom message]

Use the /pay command to SEND the SAME AMOUNT
to each OF THE valid RECEIVERS ON THE LIST
USAGE EXAMPLES:

1) /pay 25000 SAT to @friend1
Sends 25.000 satoshis to a telegram user named @friend1 with a random message from the bot

2) /pay 25 K to $friend1 | Your custom message
Sends 25.000 satoshis to the HandCash handle $friend1 while sending a custom text message.

3) /pay 50 DURO to @friend1 $friend2 | Your custom message
Sends 50 DUROS to a telegram user named @friend1 and to a HandCash handle $friend2 while sending the custom message text to both users.

4) /pay 0.01 USD to @friend1 $friend2 paymail@domain.tld | Your custom message
Sends the equivalent to 0.01 USD (converted to satoshis) to a telegram user named @friend1, a HandCash handle $friend2 and paymail paymail@domain.tld, while sending the custom message text to all users.

5) /pay 0.001 BSV to 1PPDUNhuiJCrzF7BAm2m1Lus1bdVqQpqWR
Sends the equivalent to 0.001 BSV (100.000 satoshis) directly to a BSV valid address.

/pew command

/pew [amount] [currency alias] to [receivers count]
| [optional custom message]

Use the /pew command to SEND the SAME AMOUNT
to EACH OF A number of RECEIVERS RANDOMLY PICKED FROM
YOUR HandCash FRIENDS LIST or Telegram group MEMBERS.
USAGE EXAMPLES:

1) /pew 25000 SAT to 2
From bot private chat: 
Sends 25.000 satoshis to each of 2 users, randomly picked from your HandCash friends lists, with the same random message to each receiver.

From a group chat: 
Sends 25.000 satoshis to each of 2 users, randomly picked from the active group members, with the same random message to each receiver.

2) /pew 100 DURO to 4 | Your custom message
From bot private chat: 
Sends 100 DUROS (50.000 satoshis) to each of 4 users, randomly picked from your HandCash friends lists, with the same typed custom message to each receiver.

From a group chat: 
Sends 100 DUROS (50.000 satoshis) to each of 4 users, randomly picked from the active group members, with the same typed custom message to each receiver.

3) /pew 0.01 USD to all | Your custom message
From bot private chat: 
Sends 0.01 USD (converted to satoshis) to ALL users on your HandCash friends lists, with the same typed custom message to each receiver.

From a group chat: 
Sends 0.01 USD (converted to satoshis) to ALL users that are active group members, with the same typed custom message to each receiver.

/rain command

/rain [amount] [currency alias] to [receivers count]
| [optional custom message]

Use the /rain command to SEND THE TOTAL AMOUNT
equally DIVIDED BETWEEN A NUMBER OF RECEIVERS RANDOMLY PICKED
FROM your HANDCASH friends LIST or Telegram group MEMBERS.
USAGE EXAMPLES:

1) /rain 0.1 BSV SAT to 10
From bot private chat: 
Sends 0.01 BSV (1.000.000 satoshis) to each of 10 users, randomly picked from your HandCash friends lists, with the same random message to each receiver.

From a group chat: 
Sends 0.01 BSV (1.000.000 satoshis) to each of 10 users, randomly picked from the active group members, with the same random message to each receiver.

2) /rain 10 $ to 5 | Your custom message
From bot private chat: 
Sends 2 USD (converted to satoshis) to each of 5 users, randomly picked from your HandCash friends lists, with the same typed custom message to each receiver.

From a group chat: 
Sends 2 USD (converted to satoshis) to each of 5 users, randomly picked from the active group members, with the same typed custom message to each receiver.

3) /rain 10000 DURO to all | Duro party! 
From bot private chat: 
Shares 10.000 (5.000.000 satoshis) between ALL users on your HandCash friends lists, with the same 'Duro party!' message to each receiver.

From a group chat: 
Shares 10.000 DURO (5.000.000 satoshis) between ALL users that are active group members, with the same 'Duro party!' message to each receiver.

/fund command

/fund [amount] [currency alias]
| [optional custom message]

Use the /FUND command to DONATE AND SUPPORT
THE BSV BOTS PROJECT DEVELOPMENT
USAGE EXAMPLES:

1) /fund 21000000 BSV | Love BSV Bots!
Just kidding! Any micropayment is appreciated in the path of building.
My special thanks to every supporter on the path. 🙏

/currencies command

The currency command can be used in two ways:

  1. To know about all units and currencies aliases currently supported by the bot
  2. To know the price being used by HandCash at a given momento in any of the supported fiat aliases. 
USAGE EXAMPLES:

1) /currencies
Displays a list of supported units and fiat currencies aliases.

2) /currencies USD EUR GBP
Displays the current prices used by HandCash for automatic fiat conversion on payments.

/active command 

Type /active inside a group to show the number of users seen by the bot in the group.

Type /active inside bot private chat to show the number of your friends in HandCash wallet.

/sync command 

Type /sync command to synchronize your current HandCash friends list or to synchronize active users from inside your groups.

The /sync commands can only be executed from your bot private chat, or by group admins inside their own groups.

/sethandle command 

Type /sethandle to associate a HandCash $handle to your Telegram account so you can start receiving BSV from other people when they use the bot.

USAGE EXAMPLE:
/sethandle $yourHandcashHandle

/setpaymail command 

Type /setpaymail to associate a Paymail to your Telegram account so you can start receiving BSV from other people when they use the bot.

USAGE EXAMPLE:
/setpaymail yourpaymail@domain.tld

/setaddress command 

Type /setaddress to associate a BSV address to your Telegram account so you can start receiving BSV from other people when they use the bot.

USAGE EXAMPLE:
/setaddress [valid BSV address]

/disconnect command 

Type /disconnect to remove all your Telegram and HandCash info from the bot memory.

/fees command 

Type /fees to see the current small fees currently being charged for bot usage.

/help command 

Type /help to see a lista of commands available in the bot directly from Telegram.