User Manual for lntxbot

lntxbot is a Telegram ("TG") bot which provides a custodial wallet to Telegram users.  The custodian is Telegram user fiatjaf, but anyone else can fork the code from his repository and clone the bot, and get help on their efforts in the development channel.

Commands are issued to telegram bots, both in a chat with the bot and in any group of which the bot is a member, using a forward slash. For example, in a group that contains @lntxbot, or in your direct messages with it, /help produces the text below, but without the hyperlinks.  If there are other bots in the same group, the command itself must be suffixed with "@lntxbot" (for example, /tip@lntxbot) so that TG directs it to the correct bot.

Usage:

  /start[<tutorial>]
  /tutorial[<tutorial>]
  /receive(lnurl <lnurl> | (<satoshis> | any) [<description>...] [--preimage=<preimage>])
  /invoice(lnurl <lnurl> | (<satoshis> | any) [<description>...] [--preimage=<preimage>])
  /fund(lnurl <lnurl> | (<satoshis> | any) [<description>...] [--preimage=<preimage>])
  /pay(lnurl [<satoshis>] | [now] [<invoice>])
  /decode(lnurl [<satoshis>] | [now] [<invoice>])
  /paynow(lnurl [<satoshis>] | [now] [<invoice>])
  /withdraw(lnurl [<satoshis>] | [now] [<invoice>])
  /send[anonymously] <satoshis> [<receiver>...] [--anonymous]
  /tip[anonymously] <satoshis> [<receiver>...] [--anonymous]
  /sendanonymously[anonymously] <satoshis> [<receiver>...] [--anonymous]
  /balance
  /apps
  /transactions[--in] [--out]
  /giveaway<satoshis>
  /coinflip<satoshis> [<num_participants>]
  /lottery<satoshis> [<num_participants>]
  /giveflip<satoshis> [<num_participants>]
  /fundraise<satoshis> <num_participants> <receiver>...
  /crowdfund<satoshis> <num_participants> <receiver>...
  /hide<satoshis> [<message>...] [--revealers=<num_revealers>] [--crowdfund=<num_participants>] [--public] [--private]
  /reveal<hidden_message_id>
  /microbet[list | bets | balance | withdraw | bet]
  /bitflash(orders | status | rate | <satoshis> <address>)
  /satellite(transmissions | <satoshis> [<message>...])
  /fundbtc<satoshis>
  /qiwi(list | <amount> (sat | rub) [to <target>] | default [<target>])
  /yandex(list | <amount> (sat | rub) [to <target>] | default [<target>])
  /gifts(list | [<satoshis>])
  /paywall[list | <url> <satoshis> <memo>... | balance | withdraw]
  /poker[deposit <satoshis> | balance | withdraw | status | url | play | (available|watch|wait) <minutes>]
  /sats4ads (on [<msat_per_character>] | off | rates | broadcast <spend_satoshis> [<message>...] [--max-rate=<maxrate>] [--skip=<offset>])
  /bluewallet[refresh]
  /lndhub[refresh]
  /toggle(ticket [<price>] | spammy | language [<lang>])
  /help[<command>]
  /stop
For more information on each command type /help<command>.

Conventions used in this manual:

Bold: Something for you to type into Telegram will be in bold.  For example, /start tutorial, below, is followed by an explanation of what it does if you type it into a place where the bot will process it.

Italics: I will use italics only for emphasis.

<Angle brackets>: The name of an argument in <angle brackets> indicates that it can be any value, as long as that value is the right kind of value.  For example, <satoshis> can be any integer, and <lnurl> can be any lnurl.  If it's part of something you can type into Telegram to make the bot do something, it will also be in bold, as explained above.

[Square brackets]: stuff in square brackets is optional.

Commands

Commands to the bot can contain underscores instead of spaces to separate arguments.  This allows users to create full commands that can simply be clicked to execute them (becase TG interprets the forward slash as the beginning of a link to a command).

/start will create your wallet.  There's no harm in sending the command multiple times.

/start tutorial will provide you with a lot of information that is not repeated here in this manual. The manual may refer to information from the tutorial, so it's recommended that you go through the tutorial now.

/tutorial is equivalent to /start, and still requires "tutorial" afterwards, as in /tutorial tutorial.

Commands for Sending and Receiving

/receive, /invoice, and /fund are all equivalent.  This command, followed by one of the three argument patterns shown below, is how you can collect payments.

/receive lnurl <lnurl> will generate a BOLT11 invoice using the data available through the lnurl you provide. Amounts will be added to your @lntxbot balance. 

/receive <satoshis> [<description>] [--preimage=<preimage>] will create an invoice for the number of satoshis you indicated.  You can tell lntxbot what to use as the preimage.

/receive any [<description>] [--preimage=<preimage>] will create an invoice without any amount, allowing whoever pays it to choose what to pay.

/pay, /decode, and /withdraw are equivalent.  This command, when sent as a reply to another message containing an invoice (for example, in a group), asks privately if you want to pay the invoice, through your chat with @lntxbot.  It also lists the value of the invoice, the Node ID of the receiving node, and the hash of the secret, or "preimage," used to route the payment.   If it isn't a reply, then it must be followed by one of the two following argument patterns, and in the second case, the private request to confirm that you want to pay can be skipped by adding now before the <invoice>:

/pay lnurl <satoshis>

/pay <invoice>

/paynow is a way to skip the private request without using "now". At the time of writing, /paynow lnurl <lnurl> returned a larger lnurl instead of simply paying the lnurl'ed amount.

/send and /tip are equivalent.  This command, when sent as a reply to another message, will send a payment to the author of that other message only if no other user is specified as the receiver.  The receiver will be notified of the payment if they have never talked to the bot, or they have but subsequently blocked it.  That notification will identify the sender unless one of the three following methods is used to send (or tip) anonymously:

1. anonymously appears after the command, and before the amount.
2. --anonymous appears at the end of the command arguments.
3. The command used is sendanonymously.

/lottery and /coinflip are equivalent.  This command starts a fair lottery with the given number of participants.

/coinflip <satoshis> [<num_participants>] will create a message that allows num_paticipants (or two, if that argument is not specified) to participate, but you will be one of them, so /coinflip <satoshis> 3 is what you need to have two more people participate. Once the specified number of people have joined (and paid <satoshis>), the bot will choose one of them at random to collect all those payments.

Commands for Examining Your Wallet

/balance will cause the bot to send you a direct message which displays four amounts of satoshis:

1. Your current balance.
2. The total amount you have received.
3. The total amount you have sent.
4. The total amount of fees you have paid to route lightning payments.

/transactions will cause the bot to send you a direct message that lists the last 25 transactions with the oldest first.  This list has pagination controls so that you can see your full history, but only 25 transactions at a time.  You can filter this list to contain only receipts or only sends by adding --in or --out after the command.

Commands for Group Activity

In the following commands, chat participants are invited to act together.  It is not possible to accept an invitation twice.  For example, if there should be three participants in a "giveflip," you can be only one of them. Clicking the button to join something in which you're already participating will generate an error message.

/giveaway <satoshis> will create a message in your chat with two buttons.  One of them allows you to cancel the giveaway.  The other can be used by anyone to claim the amount you specified.

/giveflip <satoshis> [<num_participants>] is just like coinflip with two important differences:

1. There is no entry fee.
2. You can't participate, but you pay the winner the amount you specified.

/fundraise and /crowdfund are equivalent.  This command invites others to contribute to a fund that, if enough people participate, will collect funds for a specific user.

/crowdfund <satoshis> <num_participants> <receiver> [<message>] places a message in the chat with a "contribute" button.  By issuing this command, you become the first contributor.  It is not possible to cancel this message. <receiver> must start with the @symbol, although TG  may remove it if it refers to a user using their name instead of their username (for example, for users that don't have usernames).

/hide creates an opportunity for you to get paid for providing some content. You may hide the whole message, or prefix the part to hide with a prompt that will be displayed to everyone and then a tilde (~) to indicate where  the hidden part starts. You can reveal the hidden part to everyone or just to those who paid.  You can require that any number of people pay before everyone sees the content, or restrict the content to the first people who pay.

/hide <satoshis> ["<prompt>" ~] "<secret>" will provide you with a message ID for your hidden message.  Below it will be a button you can use to share your hidden content in any other chat where each user can pay to see it or a subset of users can pay so everyone can see it.  Be sure not to use double-quotes inside the secret or the prompt, and to surround each of them with the double quotes.  You can limit the number of users who have to pay, or limit the number who get to see it.  Here are the optional arguments and how they work:

--revealers=<num_revealers> will only allow this number of people to see the secret.

--crowdfund=<num_participants> will show the secret to the whole group once this many people pay.

--private will allow any number of people to pay to see the secret privately in their chat with the bot.

--public will allow everyone to see the secret once one person pays the price.

--public and --private will both be ignored if one of the other two arguments are used.

Your hidden message will remain in the bot's database for 72 hours.

/reveal <hidden_message_id> will provide you with a (perhaps customized) prompt to pay to see hiden content.  If you are the user who hid the message, you won't actually pay.  When you click the button from /hide to share your hidden content in a group, it executes the /reveal command in the group, giving everyone there the opportunity to pay for your content.

/sats4ads creates a marketplace for advertisements.  To get paid to receive ads in your chat with the bot, use the "on" command.

/sats4ads on <millisats> tells the bot to send you ads and pay you the indicated rate per character.  Pictures and videos in ads count as 300 characters.  If you demand a high price, you will see fewer ads and may earn less.

/sats4ads broadcast <satoshis> will send ads to lntxbot users who have turned on the feature, starting with those who demand the smallest fees, and spending the indicated number of satoshis until it runs out of subscribers or funds. To send an ad to others who have subscribed to ads, use this command as a reply to the message you want to use as the ad.  The bit will respond with the number of sats you spent and the number of advertisees your message reached. The broadcast command has two optional arguments:

--max-rate=<satoshis> will prevent the bot from sending your ad to people who have demanded enough millisats per character to make your transmission to them cost more than this amount.  Note that every ad sent costs the broadcaster one additional satoshi beyone wht they pay to the advertisee.

--skip=<offset> will skip the indicated number of advertisees.  If you used too small a budget and reached fewer people than you wanted, you can broadcast again and skip that many people. Note that if any advertisees who have not seen your ad set their rate low enough to be one of the first offset advertisees, they will be skipped, and possibly someone who has a higher fee and already saw your ad will see it again.  Fret not! Repetition is crucial in advertising.

/sats4ads off will prevent you from receiving any more ads in your chat with the bot.

/sats4ads rates will respond with a list of each rate (millisatoshis per character) that users have chosen to use and the number of users demanding that rate.

Commands Integrating other Apps

The following list of application names are integrated with lntxbot to some degree.  It's currently beyond the scope of this manual to describe their use, but an understanding of the apps themselves (URLs provided below) ought to make their use clear.  The author requests that you let him know if there are potential misunderstandings about how these integrations should work that he can address by updating this post.

/apps is a command that will provide a list of the apps that are integrated into lntxbot.

/microbet is a simple service that allows people to bet against each other on sports games results. The bet price is fixed and the odds are calculated considering the amount of back versus lay bets. There's a 1% fee on all withdraws.
/microbet_bet displays all open bet markets so you can yours.
/microbet_bets shows your bet history.
/microbet_balance displays your balance.
/microbet_withdraw withdraws all your balance.

Bitflash is a service that does cheap onchain transactions from Lightning payments. It does it cheaply because it aggregates many Lightning transactions and then dispatches them to the chain after a certain threshold is reached.
/bitflash_100000_3NRnMC5gVug7Mb4R3QHtKUcp27MAKAPbbJ buys an onchain transaction to the given address using bitflash.club's shared fee feature. Will ask for confirmation.
/bitflash_orders lists your previous transactions.

/satellite connects lntxbot to the Blockstream Satellite which is a service that broadcasts Bitcoin blocks and other transmissions to the entire planet. You can transmit any message you want and pay with some satoshis:
/satellite 13 'hello from the satellite! vote trump!' queues that transmission to the satellite with a bid of 13 satoshis.  The following commands can be used as the first argument to /satellite:
/satellite transmissions lists your transmissions.

GoLightning.club is the cheapest way to get your on-chain funds to Lightning, at just 99 satoshi per order. First you specify how much you want to receive, then you send money plus fees to the provided BTC address. Done.
/fundbtc_1000000 creates an order to transfer 0.01000000 BTC from an on-chain address to your bot balance.

/qiwi (list | <amount> (sat | rub) [to <target>] | default [<target>])
Transfer your satoshis to your Qiwi account instantly. Powered by @lntorubbot.
/qiwi 50 rub to 777777777 sends the equivalent of 50 rubles to 77777777.
/qiwi default 999999999 sets 999999999 as your default account.
/qiwi 10000 sat sends 10000 sat as rubles to your default account.
/qiwi_default shows your default account.
/qiwi_list shows your past transactions. 

/yandex (list | <amount> (sat | rub) [to <target>] | default [<target>])
Transfer your satoshis to your Yandex.Money account instantly. Powered by @lntorubbot.
/yandex 50 rub to 777777777 sends the equivalent of 50 rubles to 77777777.
/yandex default 999999999 sets 999999999 as your default account.
/yandex 10000 sat sends 10000 sat as rubles to your default account.
/yandex_default shows your default account.
/yandex_list shows your past transactions.

Lightning Gifts is the best way to send satoshis as gifts to people. A simple service, a simple URL, no vendor lock-in and no fees.
By generating your gifts on @lntxbot you can keep track of the ones that were redeemed and the ones that weren't.
/gifts lists the gifts you've created.
/gifts_1000 creates a gift voucher of 1000 satoshis.

paywall.link is a Paywall Generator. It allows you to sell digital goods (files, articles, music, videos, any form of content that can be published on the open web) by simply wrapping their URLs in a paywall.
By generating your paywalls on @lntxbot you can keep track of them all without leaving Telegram and get information on how much of each you've sold.
/paywall will list all your paywalls.
/paywall https://mysite.com/secret-content 230 'access my secret content' will create a paywall for a secret content with a price of 230 satoshis.
/paywall_balance will show your paywall.link balance and ask you if you want to withdraw it.
/paywall_withdraw will just withdraw all your paywall.link balance to your @lntxbot balance.

Lightning Poker is the first and simplest multiplayer live No-Limit Texas Hold'em Poker game played directly with satoshis. Just join a table and start staking sats.
By playing from an account tied to your @lntxbot balance you can just sit on a table and your poker balance will be automatically refilled from your @lntxbot account, with minimal friction.
/poker_deposit_10000 puts 10000 satoshis in your poker bag.
/poker_balance shows how much you have there.
/poker_withdraw brings all the money back to the bot balance.
/poker_status tells you how active are the poker tables right now.
/poker_url displays your secret game URL which you can open from any browser and gives access to your bot balance.
/poker_play displays the game widget.
/poker_watch_120 will put you in a subscribed state on the game for 120 minutes (2 hours) and notify other subscribed people you are waiting to play. You'll be notified whenever there were people playing. If you join a game you'll be unsubscribed.
Inline query: This command can also be called as an inline query from group or personal chats where the bot isn't added. The syntax is similar, but simplified: @lntxbot poker then wait for a "search result" to appear.

/lndhub and /bluewallet are equivalent. This command duplicates your bot wallet into the Bluewallet app

/bluewallet prints a string like "lndhub://<login>:<password>@<url>" which must be copied and pasted on BlueWallet's import screen for importing your bot wallet on BlueWallet. After that, you can use the same account from both places interchangeably.
/bluewallet_refresh erases your previous password and prints a new string. You'll have to reimport the credentials on BlueWallet after this step. Only do it if your previous credentials were compromised.

/toggle Toggles bot features in groups on/off. In supergroups it can only be run by admins.
/toggle_ticket_10 starts charging a fee for all new entrants. Useful as an antispam measure. The money goes to the group owner.
/toggle_ticket stops charging new entrants a fee.
/toggle_spammy toggles 'spammy' mode. 'spammy' mode is off by default. When turned on, tip notifications will be sent in the group instead of only privately.

/help [<command>] will provide a help message if there is a command with the specified name.

/stop will stop the bot from sending you messages.To allow it to send you messages again, use /start.

Thanks for reading!  If you'd like to tip me for this manual, /tip@lntxbot [You Choose] @dscotese in Telegram.