@lnp2pBot

Here you'll find information about @lnp2pBot. This is a Telegram bot for buying and selling bitcoin on the Lightning Network, in a peer-to-peer manner, using your local currency without requiring KYC or providing personal data.

Quick Start Guide

1. Download a Lightning Network-compatible wallet (Recommended Wallets).

2. Get a Telegram username.

3. Start @lnp2pBot.

   

4. Find offers to buy or sell Sats at:

• https://market.lnp2pbot.com

• The general offer channel: @lnp2pbot Exchange

• A community that uses your fiat currency

  

5. When you take an offer, @lnp2pBot will guide you step by step through the buying/selling process.

6. If you don't find a suitable offer, create one and wait for someone to take it. Type /buy in @lnp2pBot to buy Sats or /sell to sell Sats, according to your preference, and it will guide you through the process. If you want your offer to be published in a specific community rather than the general offer channel, you need to set a default community.

7. Start buying and selling.

8. Find answers to your questions in the FAQ section.

Recommendations

• If you have any unanswered questions at https://lnp2pbot/learn, join the support group and ask there.

• Report bugs or suggest improvements in our GitHub repositories.

• Follow us on X so you don't miss important announcements.

FAQ

Here we try to answer frequent questions.

What is @lnp2pBot?

Lnp2pBot is a bitcoin exchange system for local currency, enabling easy and secure person-to-person transactions using Lightning Network. It is a Telegram bot that can be used pseudonymously, without user registration or identity verification. This tool only holds satoshis (the smallest unit of bitcoin) for the minimum necessary time, providing greater security to users compared to exchange services with internal wallets and complete custody of funds. Lnp2pBot is an open-source application, allowing for auditing, replication, modification, and redistribution with freedom. Go to @lnp2pBot

What is Lightning Network?

Lighting Network is a network of payment channels that works as a second layer protocol on the Bitcoin network, taking advantage of the property of writing smart contracts on its blockchain. It is a scalability solution that allows exponentially increasing the number of transactions and their speed by not needing on-chain confirmations, while drastically reducing network fees. Payments become instant and cost almost nothing.

What do I need to use @lnp2pBot?

You only need an account on Telegram with an active "username" or username to initialize the bot and interact with it. Additionally, you'll require a wallet that supports the Lightning Network. Here are some recommended wallets.

How do I initialize the bot?

Open a private chat with @lnp2pBot and click on "START" or execute the command /start.

• If you don't initialize the bot first, you won't be able to take any orders from the channels where they are published.

What are the channels for making exchanges on Telegram?

To create your Buy / Sell orders for Bitcoin, use the chat with @lnp2pbot.

The offers created with @lnp2pBot are published in Telegram channels from where they can be taken by clicking the Buy Satoshis or Sell Satoshis button that appears below each one.

There is a general channel @p2plightning where offers that do not belong to any community are listed, hence there are various fiat currencies available. Additionally, there are channels associated with communities where only offers with the fiat currencies permitted in those communities are published.

Where can I find offers in my local currency?

You can ask the bot by running the command /findcomms along with the code for your currency.

For instance, to see the communities in Venezuelan bolivars, you should type:

/findcomms ves

You can also search for offers filtered by currencies and communities on https://market.lnp2pbot.com and in the general channel @p2plightning.

Do I need to fill out any user registration or identity verification?

NO! Bitcoin was born as "a peer-to-peer electronic money system", and we are proud to support that principle. No personal information is required from you, the exchanges are entirely between peers, and @lnp2pBot does not collect or store any personal information of the parties involved.

What type of information do you collect from each user?

For the purposes of the user reputation system, lnp2pBot collects some statistics on your trades. Specifically, the number of completed transactions, the total volume traded, the counterparty rating and the record of disputes if any. Of this information, only the number of transactions and the counterparty rating are public by default. Meanwhile, showing the total volume traded and your username is optional (you choose to show it or not, by default it is not shown).

In case you want to show your username and/or volume traded to accompany your reputation in the offers you publish, you must do it manually through the following commands:

/showusername yes

/showvolume yes

Each command is sent as a direct message to the bot.

How does the user reputation system work?

For every transaction you conduct, you'll be asked to rate your counterpart, and they'll rate you in return. lnp2pBot uses a 5-star rating system that allows you to evaluate your experience, where 1 star is the lowest rating and 5 stars are the highest.

To determine reputation, the bot conducts an iterative calculation of the mean and standard deviation of the ratings and successful operations. Hence, in the initial transactions, even if you've been rated with the maximum, your reputation won't be high initially. It gradually increases as you conduct more operations with good ratings.

You can see this calculation at: https://github.com/lnp2pBot/bot/blob/main/bot/commands.js#L279

It's based on: https://math.stackexchange.com/questions/2148877/iterative-calculation-of-mean-and-standard-deviation

When you create an offer, it will include by default the number of successful operations you've conducted, the ratings received from your counterparts, and the number of operations performed. We recommend considering all these aspects when accepting an offer to avoid scams.

How do I create a sell order?

When chatting with @lnp2pBot you will find a "Menu" button. Click it to display the list of commands you can use. Select the sell command: /sell, to activate the wizard that will guide you through the selling process.

Once activated, the wizard will ask you to specify the fiat currency in which you want to trade:

Next, you must enter the amount, in fiat currency, that you want in exchange for your satoshis. Remember to enter only numbers in this step, so that the wizard can understand you.

You can also enter a range of amounts to buy, separating the numbers by a hyphen (-).

The bot will ask you the amount, in satoshis, you want to deliver. Here you have the possibility to use the "Market price" button. If you do so, the rate of Yadio. io will be applied.

The next thing the wizard prompts you for is the percentage premium or discount you want on your swap. If you want to increase the market rate (premium), select a positive number; if you want to decrease it (discount), select a negative number. If you want neither, use the "No premium or discount" button.

Next, you will need to specify the payment method. In this field, you can get creative and add emoticons or whatever you consider to make your request attractive.

The bot will proceed to publish your offer in the general or community channel you have set as default. It will remain visible for 23 hours if no one takes it before that time.

At any time you can cancel the offer, as long as no one has taken it, using the command /cancel followed by the order identifier. You can also copy the command plus the identifier in the chat with the bot.

The wizard will return a message confirming the cancellation and your offer will be removed from the offers channel.

In case your sale is taken, the bot will ask your counterparty to deliver a Lightning Network invoice.

At the same time, it will ask you to pay the invoice with the corresponding amount in satoshis, plus a 0.6% commission. Remember that the network may charge you an additional amount for payment routing. This amount will depend on the nodes through which your transaction will pass and the network status. The bot has nothing to do with this amount.

At this point, the bot will contact both parties to discuss the details of the exchange.

Once the bot receives notice that the fiat amount was paid, it sends you an alert to check your account. If everything is in order, you can release the satoshis with the command /release followed by the transaction identifier (or copy and paste the text into the bot chat) and the transaction will be executed.

The exchange is finished. Now you can rate your counterparty.

You can exit the wizard at any time by executing the /exit command.

To execute the same sell order, without using the wizard, you must type your order with the details: /sell <amount in sats> <amount in fiat> <fiat code> <payment method> [premium/discount] (without the special characters).

Example: /sell 100000 50 USD "bank xyz" I sell one hundred thousand sats at fifty dollars I charge by bank xyz.

In case there is any unsupported variable, the bot will indicate it to you during the order creation process. Once completed, the order will be published in the exchange channel and will be visible for a period of 23 hours.

How do I create a buy order?

The procedure is exactly the same as for a sell order. However, when you press the "Menu" button, select the /buy command instead of /sell. This will activate the wizard that guides you through the buying process.

Once activated, the wizard will prompt you to specify the fiat currency you want to transact with:

Next, enter the amount, in fiat currency, you wish to buy. Remember to input only numbers at this step so that the wizard can understand.

You can also enter a range of amounts to buy by separating the numbers with a hyphen (-).

The wizard will ask for the amount, in satoshis, you want to receive. Here, you have the option to use the "Market Price" button. If you do, it will apply the rate from Yadio.io.

Next, the wizard will request the percentage of premium or discount you desire in your exchange. If you want to increase the market rate (premium), select a positive number. If you want to decrease it (discount), choose a negative number. If you don’t want either, use the "No premium or discount" button.

You'll then need to specify the payment method. Here, you can get creative and add emojis or anything you feel will make your offer attractive.

The bot will proceed to publish your offer in the general channel or the one you've set as default for the community. It will remain visible for 23 hours if no one takes it before then.

At any time, you can cancel the offer, provided no one has taken it, using the command /cancel followed by the order identifier. You can also copy the command plus the identifier in the chat with the bot.

The wizard will return a message confirming the cancellation, and your offer will be removed from the offers channel.

If your offer is taken, the wizard will ask you to provide a Lightning Network invoice with the corresponding amount in satoshis. Simultaneously, it will ask your counterpart to pay the invoice.

At this point, the bot will connect both parties to discuss the exchange details.

Once you've made the fiat payment, notify the bot with the command /fiatsent. The bot will inform your counterpart to check and confirm the receipt of the money and proceed to release the satoshis. Remember, your wallet needs to be online to receive them.

The exchange is completed. Now you can rate your counterpart.

You can exit the wizard at any time by executing the command /exit.

To execute the same buy order without using the wizard, you must write your order details: /buy [premium/discount] (without special characters).

Example: /buy 100000 50 usd "xyz bank"

Buying one hundred thousand satoshis at fifty dollars paying via xyz bank.

Some examples of buy orders would be:

• Ex. /buy 0 50 ves "xyz bank": Buying fifty bolivars in satoshis - in this case, the bot will calculate at the market rate - paying via xyz bank
• Ex. /buy 0 10-100 pen "mobile payment": Buying from 10 to 100 new soles - in this case, the seller will choose the amount to sell you within that range - paying via mobile payment
• Ex. /buy 0 100 eur "mobile payment" -3: Buying 100 euros with a 3% discount - in this case, the bot will calculate at the market rate by discounting or increasing the percentage you choose - paying via mobile payment

If there's any incompatible variable, the bot will indicate it during the order creation process. Once completed, it will automatically publish on the exchange channel and remain visible for a period of 23 hours.

How do I search for and accept a buying or selling offer?

If you've never used @lnp2pbot before, you need to open it and type /start before taking any offers.

You'll find all active offers on the bot at https://market.lnp2pbot.com, including yours. There, you can filter by fiat and communities.

In the Telegram channel @p2plightning, you'll find offers that haven't been published in any community.

To find offers published in communities, type the command /findcomms <fiat code> within the bot. For more information, read here.

Review all the previous options until you find an order that suits your search, then click the Buy satoshis or Sell satoshis button, as appropriate. Next, go to the chat with @lnp2pbot to follow its instructions. If you find the offer from https://market.lnp2pbot.com, it will redirect you to the channel where it's published so you can take it.

• Another way to take an offer is to use the command /takeorder <order id>. For example, if you organize a Sat exchange with someone via @lnp2pbot, your counterpart can create the order and send you its ID. You can then directly take it from within the bot using the mentioned command, avoiding the need to go to the offers channel where it was published.

How do I cancel a posted order?

If the order hasn't been taken, type the command /cancel in your chat with the bot or select it from the "Menu." The bot will display your active orders. Choose the ID corresponding to the order you wish to cancel.

The ID or unique number of your order appears just below the acceptance and posting message of your order and is even indicated as an option to cancel it. You can also find it by typing the command /listorders.

If your order has already been taken or if you take an order and don’t wish to proceed, you'll need to initiate a cooperative cancellation.

By initiating a cooperative cancellation, your counterpart will be informed of your intent to cancel. If they agree, they'll also write /cancel <order id>, after which the Sats will be returned to the seller.

If your counterpart doesn’t agree to cancel, you can initiate a dispute by typing the command /dispute.

Is there a limit (minimum or maximum) on the amounts I can trade?

From the bot’s side, there are no limits to the volume of your transaction. However, it will depend on the network's capacity and the channel's liquidity that you can find a maximum limit at a given moment.

How long does it take to complete a transaction?

It depends on several factors. Being a P2P exchange, the primary variable is the acceptance of your offer by a counterpart. Your listing will be available for up to 23 hours and will automatically be removed if nobody takes it.

Once an offer is accepted, there's a 15-minute window to pay the lightning invoice and for the bot to connect both parties. From this point, there's a maximum of 23 hours to finalize the transaction. After this time, the order expires, and the satoshis will be returned to the originating wallet. That's why users should use only instant fiat money payment methods for their transactions.

When both participants are online and agree on immediate payment methods, transactions are nearly instantaneous.

Should I pay fees and commissions?

The bot charges a fixed fee of 0.6%. This fee includes the network fee, so there are no additional charges. This commission is paid only by the seller, not the buyer.

Some communities establish a small discount on the commissions for operations carried out within them. To find out the discount for each community, check https://market.lnp2pbot.com in the COMMUNITIES section.

What exchange rate does the bot use?

When creating an order, you can choose to specify only the fiat amount to pay/receive, without indicating the quantity of sats you want to buy/sell. In this case, you should select the Market Price button, and the bot will calculate the market rate offered by yadio.io at the moment your order is taken.

When you select the Market Price button, you can also set a premium or discount for your offer. This means an increase or decrease will be applied to the bitcoin price indicated by yadio.io at the time the offer is taken.

Practical examples with their meanings:

• Buying Sats +1%: I want to buy Sats 1% more expensive (above) than the BTC price indicated by yadio.io at the time someone takes my offer.

• Buying Sats -5%: I want to buy Sats 5% cheaper (below) than the BTC price indicated by yadio.io at the time someone takes my offer.

• Selling Sats +3%: I want to sell Sats 3% more expensive (above) than the BTC price indicated by yadio.io at the time someone takes my offer.

• Selling Sats -4%: I want to sell Sats 4% cheaper (below) than the BTC price indicated by yadio.io at the time someone takes my offer.

In which countries and languages is it available?

As a P2P exchange on Telegram, technically, it's available for anyone using this app. However, currently, the bot interacts with a list of 94 fiat currencies with which you can create buy/sell orders using the Market Price button on the assistant.

Here's the list. To view it within @lnp2pBot, type /listcurrencies.

For now, @lnp2pBot is fully available in English, Spanish, Portuguese, French, Italian, German, Russian, and Ukrainian.

To change the assistant's language, use the /setlang command.

If you'd like to help translate lnp2pBot into your language, you can propose your collaboration. This is a good starting point.

How Can I Find Communities that Use My Currency?

By executing the command: /findcomms followed by the desired currency code (you can use the ISO 4217 standard currency code), lnp2pBot will display the communities created that operate with your currency.

Additionally, on https://market.lnp2pbot.com, you can view all existing communities and some of their statistics, such as their creator, their solvers, the percentage of discount, the creation date, among others.

There might also be communities that operate with sats against another cryptocurrency. There are no limitations for the user.

In the following image, we can see the result of /findcomms usd

How do I post offers in a community?

When you start using @lnp2pBot, the orders you create are by default posted in https://t.me/p2plightning, which is the general channel where you can find offers in various fiat currencies.

If you want to post offers in a channel specifically for your currency, you need to do so through a community that incorporates it.

• You can search for all communities operating with the desired currency at https://market.lnp2pbot.com.

• You can also type within the bot:

/findcomms <fiat code>

For example, /findcomms usd is used to search for all communities trading with USD. If you don't know your currency code, type /listcurrencies in the bot and find it.

Upon selecting a community, the bot will display the number of successful orders, the trading volume operated in the last 24 hours, and the number of users posting their offers there. To set which community you want to publish your offers in, you should select the "Use as default" button.

• Another way to do it is by typing: /setcomm <@communityGroupName | telegram-group-id> (/setcomm along with the group name or its Telegram ID).

To create an order within a community, use the /buy or /sell command depending on what you want. From there, the bot will give you step-by-step instructions, and your offer will be published in the selected community.

More Information:

• You can only have one community configured by default at a time, and therefore, all your offers will be posted there.

• To leave a community and post offers again in the general channel, you should type: /setcomm off

• If you want to post an offer in multiple communities simultaneously, you need to create it in each one separately: first, post it in one, then configure another as default and post there as well, and so on for all the communities you want it in.

Another way is to type your order as a command within the chat of a community where the bot is an administrator, as it will recognize it and post the offer in that community without you needing to set it as default.

• You can take offers from as many communities as you want without having to configure any of them as default.

Recommended Wallets

The following wallets have shown better performance when used with @lnp2pBot:

• Breez Wallet
• Blixt Wallet
• Phoenix Wallet

Notes on other wallets

-Before selling Sats using any Lightning Network wallet (or exchange), make sure to check if it supports the payment of hold invoices (the type of invoices that the bot uses as escrow)

• With Wallet of Satoshi, you can receive Sats from a purchase without any issue. However, if you're selling Sats and the order is cancelled, your wallet balance may take some time to update, and the Sats may not appear available until several hours later, even though they remain in the WoS node. This delay is due to WoS updating the balance of its users periodically. A similar situation may occur with any other custodial service, including other wallets and exchanges that support withdrawals on the Lightning Network.

• It's common for payments from @lnp2pBot to Muun wallet to fail because the bot can only pay a maximum routing fee of up to 0.2%. Hence, it might not cover the invoice when Muun charges fees higher than that. In such cases, you'll need to generate a new invoice from another wallet (More info here). It's also possible that if you're selling Sats from Muun wallet and the order is canceled, a fee will still be charged because Muun wallet isn't a native LN wallet; it's an on-chain wallet that operates through submarine swaps. For any transaction, you'll have to pay the mining fee, even if the bot's hold invoice was canceled.

• In Aqua Wallet, you can receive Sats from a purchase without any issue, but despite being a self-custody wallet, if you're selling Sats and the order gets cancelled, your wallet balance may take several hours to update (sometimes up to 48 hours) because they have enabled a waiting period for refunding any failed payments.

Common Problems and Solutions

I'm trying to take an order, but nothing happens

When you press the Buy Satoshis or Sell Satoshis button on an offer, @lnp2pbot will respond privately with what you need to do to complete the process. For the bot to respond to your request, it's necessary to initialize it because no bot can open a chat with you initially if you haven't used it before. Open @lnp2pbot and type the command /start or tap the Start button, then try taking the order again, return to the bot, and follow its instructions.

• If you were already using the bot and the last time you did so was before March 2023, you need to reinitialize it with the command /start because it was reset, and its previous database wasn't preserved.

I tried to pay an invoice with an insufficiently funded wallet, and now @lnp2pbot tells me the invoice was used

Wait for 15 minutes for the transaction time to expire, and then initiate it again to generate a new invoice.

My counterpart had an issue sending me the fiat payment and then disappeared; my sats got stuck

The transaction will automatically cancel after 23 hours, and your satoshis will appear in your wallet as a failed payment. If you want to expedite the process, you can open a dispute with the command /dispute <order id>.

A user mistakenly took my purchase, and I've already made the payment in satoshis

A cooperative cancellation can be initiated. Both parties need to execute the command /cancel <order id>.

I canceled an order, but the sats haven't returned to my wallet. How long should I wait?

When an order is canceled, the seller's satoshis immediately return to the node/wallet that made the payment. If you use a self-custody wallet or your own node, you won't have any issues. However, if you use a wallet that custodies your funds, you'll need to wait for them to reflect your balance in their internal system. This can take from a few minutes to a couple of hours depending on the wallet, but all wallets return 100% of your funds. Patience is key.

I'm buying, and the bot doesn't ask me for an invoice; instead, it directly connects me with the seller

This happens when you have a lightning address activated. In that case, the purchased satoshis will be sent directly there without asking for a new invoice for each purchase. To check your lightning address, type the command /settings within the bot. If you want to deactivate it, type the command /setaddress off within the bot.

How do I know if the seller actually released the sats?

If @lnp2pBot tells you that the vendor released, it really is, but if you want to verify it you can do it as follows:

Write to the bot /listorders and if the bot is still in the process of paying your invoice the status you will see will be PAID_HOLD_INVOICE, if the bot has already paid the invoice the order will not appear on the list.

When an order has status PAID_HOLD_INVOICE, the seller no longer has any responsibility because he/she has released the sats, if you have problems receiving go to the section The seller released but I don't get the sats in my wallet.

The seller released, but I haven't received the Sats in my wallet

Possible Causes

Sometimes, the bot cannot find successful routes to make the payment for various reasons. It could be due to a poor connection between the origin and destination, or it can be more complicated, such as nodes connected to the destination charging very high fees.

The @lnp2pBot node is willing to pay up to 0.2% of the total transaction amount in routing fees. If this fee is higher, the bot simply won't make the payment. Some non-native Lightning wallets might charge more than 0.2% when the mempool is congested, and the bot won't be able to pay them (more information on wallets here).

Another scenario could be that you lack 'inbound capacity.' For instance, if you're using the Blixt wallet and have just opened a channel, all the funds in that wallet would be outbound, and you wouldn't have the capacity to receive. In this case, all payments to that wallet will fail. Modern wallets like Phoenix wallet address this by indicating the lack of inbound capacity and proposing channel modifications (splice in) to ensure the new received payment is on the user's side (more inbound capacity). This wallet charges a fee for this service.

Solution

When a payment fails, the bot will attempt to make the payment two more times with 5-minute intervals. If it continues to fail, the bot will ask you to provide a new invoice to continue trying. It's advisable to generate this invoice from another wallet.

If you don't input the invoice within 20 minutes after the bot requests it, that assistant will be canceled, and it won't request it again later. In that case, you should input it using the command: /setinvoice <order id> <lightning invoice> (Do not include the symbols <>, separate each part with a space, and do not reuse invoices).

If you've tried several times and still haven't received the Sats, stay calm. It's no longer possible to cancel the transaction or return the Sats to the seller. Instead, they are in the bot's node, and you can continue trying with new invoices as many times as necessary until you receive them.

Support

@lnp2pbot isn't a company, so it doesn't have a technical support department. However, there's a community you can turn to if you need assistance.

The main Telegram groups where you can ask for help are:

• Spanish Group: https://t.me/lnp2pbotHelp
• English Group: https://t.me/LNp2pBotHelpEn

Additionally, you can ask questions and request help in the community of the bot you're using and stay in direct contact with the administrator and the solver(s) of that community.

Contacting Developers

If you need to get in touch with the developers of @lnp2pBot, use our GitHub. If you have a proposal or wish to report an issue, navigate to the issues section and create a new one.

I'm a developer and want to contribute

Great! Thank you for your interest. In the issues section, you'll find a list of tasks to be resolved. Choose one labeled help wanted. If you have any doubts, feel free to ask by commenting. Then, if you're sure you want to tackle it, comment on the issue. Those tagged good first issue are often simple and serve as a good starting point to familiarize yourself with the code.

Since the inception of this project, we aimed to operate @LNP2Pbot without making much noise. It was crucial to test the bot within a small community before showcasing the final product to the world. That's why we started working with the Spanish-speaking Lightning community, which welcomed the project very positively. The feedback received has allowed the bot to grow and improve every day.

Communities

Communities were design so that users may interact in small groups, adapted to their tastes and needs.

Communities can be created around a project, a currency, or a country, for example.

Anyone can create a community and interact with the bot from it. Witch leaves creators/administrators with great power in their hands, “a great power comes with a great responsibility” This means that once users start working in their own communities, they will also have to manage any disputes that may occur.

Trust

The model we have chosen to resolve disputes is that of trust. This seems paradoxical for those who work with Bitcoin and advocate of "trustless" systems. The truth is that the goal is to develop systems in which we do not have to trust anyone. But after thinking a lot about dispute resolution systems, we had to accept that you always have to trust someone to some extent.

Benevolent Dictator

Having accepted that trusting someone is necessary to resolve a dispute, how can we create fewer incentives for disputes to arise? Regarding this matter, the community has proposed several ideas. The one we've developed is to utilize the concept of a "benevolent dictator." This individual acts as a "dictator" whom people accept and trust to make decisions for the community's welfare. Let's say it's a trusted mediator within the community.

The benevolent dictator is the creator of the community, responsible for appointing dispute solvers or 'solvers'. These individuals are publicly recognized within the community (by their Telegram username). The community is responsible for reporting if these users are performing their duties correctly or not. In a community where the "benevolent dictator" selects solvers correctly, everything will function well. In a community where the dictator makes mistakes, community members might move to another community or create a new one. This way, we delegate this responsibility to the communities.

How do I create a community?

To create a community, simply type the /community command. After this, the bot will ask you to indicate the following:

• Community Name: A name to identify your community.
• Currencies: Fiat currencies that can operate in the community. These must be entered separately from a blank space. For example, for an Uruguayan community, "UYU USD" can be added.
• Community Group: This is the main group where members of the community meet. Both @lnp2pbot and the person creating the community must be administrators in this group. Users will be able to create orders by sending bot commands in this group.
• Order book channel or channels: Orders will be published where we indicate to the bot. If we enter a single channel, the purchases and sales will be published in that channel, but if you indicate two channels, the purchases will be published in the first and the sales in the second. Channels are entered separately with a blank space and both the bot and the community creator must be channel admins.
• Solvers: We must indicate the “usernames” of the users who will be in charge of resolving the disputes, separated by a blank space.
• Channel for disputes: In this channel, the bot will publish when a user initiates a dispute. Both the bot and the community creator must be channel administrators.

Let's Get Started. Communities, First Steps

To create a community, you must type or select the command /community from the menu. From there, the bot will guide you through the process.

In this post, there are the details, for a better understanding. It's important to note that both you and the bot must be administrators in both the community group and the channels linked to it.

Modifying a community

To modify any field, we simply execute the /mycomms command and the bot will show you a menu that will help you select the community you want to modify and the specific field.

Creating orders

The operation of the bot remains exactly the same, by default it creates the orders in a global channel. But since we have created a new community we want our order to be published in the channel that we have associated with the community. There are two ways to create an order in the new community.

We enter the community group (in the case of our example it would be @p2pZimbabwe) and within the group, we execute the usual command: /sell or /buy. If we want something more private, we tell the bot our default community by running the /setcomm @p2pZimbabwe command. From then on, all orders you create privately will go to the corresponding channel linked to @p2pZimbabwe. You can change your default community at any time with /setcomm @Coolercommunity (example). You can also go back to the previous state, where you didn't have a community by default, by running /setcomm off.

Incentives

Since its inception, @lnp2pbot has charged a fee to the seller for a successfully completed order, which is currently set at 0.6%. When the order is created within a community, the bot splits this fee: a portion goes to the bot, and the rest becomes the community's profit.

The proportions are: 67% of the commission goes to the bot, and the remaining 33% goes to the community.

For example, in a transaction of 100,000 satoshis, the seller pays a commission of 600 satoshis. From that amount, 402 satoshis go to the bot, and the remaining 198 satoshis go to the community.

However, to incentivize competition, the community has the authority to decrease its 'profit'. Instead of charging the entire 33%, it can reduce a percentage in its commissions.

In the previous example, instead of charging the full 198 satoshis (100%), it could choose to charge 99 satoshis (50%). The remaining satoshis act as a discount for the seller, who would then pay 501 satoshis instead of the initial 600 satoshis.

Managing a Community

Once the community has been created, it is necessary to start the administration work.

The first thing is to designate at least one person to resolve disputes that arise. That person is the solvers.

Then, establish the channels in which purchases and sales will be made. At first, a single channel will suffice for both, but as the community grows it may be necessary to establish a channel for each.

Another of the tasks of the administrator is to decide the rate that the community will charge. Here you have the explanation of how the rates work.

The administrator can modify any field of the community whenever he wants.

IMPORTANT: To execute the community administration commands, the community with which you want to work must be selected by default. To do this, use the 'Use by default' button that is displayed after executing /findcomms, you can also do it with the command /setcomm @tobemanagedgroup. A telegram group gets its @group by going public.

What is a solver

Solvers are users appointed by the community administrator and are responsible for resolving disputes and maintaining order.

A community must have at least one solver. There is no requirement to be a solver. The administrator can add or remove them at any time.

The administrator can be a solver in his community.

Resolving disputes

When a user initiates a dispute, a message is sent by the bot to the dispute channel. Only solvers can take it by tapping the Take dispute button. Before taking a dispute, the solver must be sure that he/she have the community setted up, to set up the community, the solver must run the command /setcomm @community-group.

Once the solver takes the dispute, the bot will send them all the necessary information to resolve it. The solver will also have to communicate with each party, understand what happened, and complete the order or cancel it.

Completing an Order

Many disputes arise because one of the parties took time to respond to a message, there was a misunderstanding, or there was a delay in a payment. These are straightforward cases that only require patience and assistance in communication.

Other cases involve malicious intent, such as when a seller wants to keep the fiat money and get the sats returned. In these cases, the solver can execute the /settleorder command, which recognizes the received payment and automatically sends the sats to the buyer.

Completing an Order When Fiat Takes Too Long to Arrive

With @lnp2pbot, payment methods ensuring instant fiat transfer should be used. However, there might be instances where the fiat takes longer than usual to reach the sat seller, for example, due to issues in payment processing by the bank. In such situations, the buyer risks the possibility that the seller does not receive the fiat before the hold invoice expires, hence not releasing the sats. However, once it expires, the seller will have the sats again, followed by the fiat. The buyer would then be at the mercy of the seller's goodwill, who might or might not send the satoshis, without any bot intervention. To prevent this, users can turn to the solvers in their community to act as mediators.

A solver can make the bot charge the hold invoice from the seller using the /freezeorder <order_id> command. This way, they can wait long enough for the fiat to arrive, and when it does, the solver will release the sats using the /paytobuyer <order_id> command. The buyer's invoice may have expired during the process, so they'll need to update it by typing /setinvoice <order id> <lightning invoice>.

This solution implies custody of the sats by the bot and should only be used when no other options exist.

Canceling an order

The other alternative that the solver has is to cancel the order if the case warrants it. To do this, use the /cancelorder command. This returns the sats to the seller.

Removing disputes

Every time a user initiates a dispute, both he and his counterpart are involved in it. Until it is resolved, both remain related, when resolved, the solver has the power to eliminate this dispute from one of the users or both, if he needs it, with the command /deldispute username order-id.

Banning a User from the Community

If a solver deems it necessary, they can ban a user from the community using the command /ban followed by their username.

Secure Exchanges on @lnp2pbot

@lnp2pbot is a secure tool for peer-to-peer bitcoin exchange without KYC. When two individuals connect to engage in a purchase, the seller's Satoshis (Sats) remain locked in their own wallet via a hold invoice and cannot be utilized while in this state. Once the buyer sends fiat money and the seller confirms to the bot that they've received it, the Sats are then transferred to the bot's node, which promptly pays the buyer.

The bot incorporates a user reputation system that considers the number of successful transactions and received ratings. Moreover, it displays the duration for which a person has been using the platform. These details can assist you in making decisions regarding accepting or declining offers according to your own interests.

Additionally, every community on the bot has at least one Solver responsible for mediating disputes that may arise. They request necessary evidence from the involved parties and determine the rightful recipient of the Sats. If a scammer is detected, they are permanently banned from using the bot.

Scam Attempts

Scam attempts using the bot are not frequent, but like any decentralized, KYC-free peer-to-peer exchange, it's not immune to them. To avoid falling victim to scams, caution must be exercised, being attentive to suspicious behavior, and in case of doubt, cancel the operation or open a dispute.

Possible Scams:

• A scammer trying to buy Sats might use the /fiatsent command to claim they've sent fiat money when, in reality, they haven't, hoping the seller will trust their word and release the Sats without verifying the receipt of fiat. It's crucial for the seller to ensure they've received fiat before using the /release command, even if the buyer sends an image as proof of payment, as it could be manipulated.

• Some fiat payment methods are reversible, like PayPal, which scammers can exploit to purchase Sats and then reverse the fiat transfer. We recommend using only irreversible payment methods to avoid this type of scam.

• To increase the decentralized use of the bot, there's an option for any user to create a community. Despite excellent outcomes, there's a possibility that a scammer creates a community where they act as a Solver and make fraudulent dispute decisions, either with other scammers or as part of operations. However, this kind of scam would have a short duration, as the scammer would be quickly exposed, impacting the community's reputation, leading to user loss, and banning of scammers. Before joining a community, it's advisable to research the creator and the Solvers, check if they have common groups, their overall reputation, as well as consider the group's trading volume, age, number of users, and verify their authenticity.

• A fraudulent seller might take advantage of the hold invoices in @lnp2pbot, which have an expiry time of around 23 hours. They might not use the /release command to release the Sats despite receiving fiat from the buyer, allowing the invoice time to expire with excuses or even disconnecting intentionally. This aims to reclaim the Sats and keep the fiat without any interference from the bot or a Solver. To prevent this, when purchasing Sats, use an instant payment method. If the seller doesn't release the Sats and remains unresponsive after a couple of hours, open a dispute. Never wait until close to the time limit to initiate a dispute, as the solver might not resolve it before it expires, resulting in the Sats being returned to the seller.

• Some scammers establish multiple operations within the bot to build relationships with users and then contact them privately to persuade them to conduct transactions outside the bot. This is risky as there's no guarantee they'll fulfill their part. We recommend not engaging in transactions outside the bot, even if the offers seem enticing. You can suggest conducting them using @lnp2pbot for mutual security.

Tips to Avoid Scams

• If you're using @lnp2pbot for the first time, educate yourself about how it works, review available documentation, and start with small amounts until you fully understand the process.

• Before accepting an offer, check the user's reputation, the number of trades, the bot usage time, as well as the trade volume if visible. Be wary of offers that seem too good, especially if they come from users with a short history using the bot but with numerous operations.

• Avoid engaging in trades outside the bot.

• Do not agree to change the fiat payment method if it wasn't part of the initial offer.

• If you feel uncomfortable with a trade, you can request a cooperative cancellation as long as the fiat hasn't been sent.

• Exercise caution with new and low-volume communities.

• Do not agree to trade in another community if it wasn't your choice.

• If you're planning to open a dispute, do it on time, well before 23 hours have passed since the offer was accepted.

• If you notice suspicious behavior, report it to the corresponding community administrators. They can take appropriate measures to protect users and inform administrators of other communities.

• Share only essential personal information necessary for the exchange. Avoid providing more information than necessary, such as your personal phone number, address, etc.

• If someone you've traded with before sends you fiat money without prior notice (even claiming it was a mistake) and demands you send them the corresponding Sats, it could be a bridge scam. In such cases, it's advisable to return the fiat to the same account it was sent from and avoid continuing with the forced exchange they're attempting to push you into.

Account Triangulation Scams or Bridge Scams

This type of scam is challenging to prevent and detect because, from the seller's perspective, everything seems to proceed normally. It's important to note that they can occur in any type of peer-to-peer exchange, not just on @lnp2pbot. These scams involve a scammer acting as an intermediary between the victim and the seller, where the seller receives the fiat sent by the victim but hands over the Sats to the scammer.

The scammer offers the sale of products or services (whether it's a second-hand item or even iPhone unlocking) on any social network or specialized platform for buying and selling. When the victim contacts the scammer, they request an upfront payment. Simultaneously, the scammer posts an offer to buy Sats on @lnp2pbot (or another peer-to-peer exchange) for an amount equivalent to the fiat they aim to scam (they might put up an offer with a high premium to make it more attractive). When the scammer finds a Sats seller and requests their details to receive the fiat, they provide these details to the victim for the aforementioned upfront payment. Once the victim's fiat reaches the Sats seller and the seller presses the /release command, the bitcoins are released to the scammer, who disappears and never fulfills the service or sale promised to the victim.

It's crucial to emphasize that the Sats seller is also a victim in this triangulation, as they interact only with the scammer, unaware of a third party in the exchange. They assume that the fiat they receive was directly sent by the buyer of their Sats. However, they might face accusations of fraud when their bank details are provided to authorities in a report regarding payment for a service or product that wasn't received. It's advisable not to delete the bot's history or chats with your Sats buyers or to create a backup, as these records might be necessary as evidence to prove that no one was scammed.

Some scammers might even ask for additional personal information from sellers to later share it with the direct victims of the triangulation, creating a sense of trust. Therefore, it's recommended not to provide personal information like phone numbers, full names, or addresses unless it's essential for the payment method used.

Bridge Scam Prevention

There isn't a foolproof method to completely prevent a seller from engaging in a bridge scam. However, besides following the previously mentioned tips to prevent scams, there are other measures you, as a seller, could take to reduce the risk, such as:

• If you want to make a large sale of Sats, it's preferable to split it into several smaller sales, unless the buyer has a good history of transactions with you and consistently uses the same bank account.

• Be cautious if a buying offer seems too good to be true; it might be a scam.

• In fiat payment methods that allow adding comments to the transfer, you could ask the buyer to write a specific phrase you mention at that moment, like "I'm buying an orange." This way, if they were a scammer, they'd have to ask the victim to write that comment to send the fiat, which could raise suspicion as it's highly unlikely that they are buying an orange.

You can modify that phrase to a numerical code or another message you find appropriate to prevent a scam. Another method, though not highly recommended due to privacy concerns, is to request the phrase to be: "This payment is for a purchase of X Sats on @lnp2pbot for order ID: Y."

• Some fiat payment methods don't allow adding comments but reveal both parties' phone numbers. In such cases, you could ask the buyer, before releasing the Sats, for an SMS from the number that sent the fiat, containing any of the aforementioned messages or similar messages. Another approach could be a call initiated by them or you, directly confirming no third-party involvement in the fiat transfer.

• Another option, not highly recommended if you wish to respect the buyer's privacy, is to request a video call on Telegram where they show they possess the card from which they sent the money. However, they don't need to show their face for this purpose.

Remember, if you're uncomfortable with a transaction, you can engage in a cooperative cancellation with /cancel and return the fiat to the same account from which it was sent. If the other party is unwilling to cooperate, you should open a dispute with /dispute and wait for a solver to resolve the case.

The preventive measures mentioned here may not apply to all fiat money payment methods. If you're aware of other methods, please share them and contribute to preventing scams.

How to contribute?

lnp2pBot is a fully open-source project, maintained by the community. Many users ask how they can contribute, or if code knowledge is necessary to do so. In this section, we present some ways in which you can collaborate. Although these are not the only ways, any type of help is valuable for the project. Thank you very much for considering it!

• Translation of the Bot: If you are multilingual, you can help translate the bot into other languages to enhance its accessibility.

• Help with Documentation and its translation: If you have skills in writing and/or translation, you can collaborate to improve the project documentation and/or translate it, making it more accessible and understandable for everyone.

• Development: If you are a developer, your skills are essential. You can contribute by writing code, implementing new features, and fixing bugs.

• Report bugs: If you encounter any errors or unexpected behavior in the bot, reporting them is very useful. It helps us improve the stability and quality of the project.

• Propose improvements: If you have ideas to enhance lnp2pBot, we invite you to share them with us. Several important features of the bot have originated from community proposals.

• Create video tutorials and guides: If you have skills in creating multimedia content, you can produce video tutorials or written guides to help users make the most out of the bot.

• Dissemination on social media: Sharing information about lnp2pBot on social media helps increase its visibility and attract more people interested in contributing or using it.

• Donations: If you would like to financially support the development and maintenance of lnp2pBot, please consider making a donation. Each contribution helps cover hosting, development, and other project-related expenses. You can donate to lnp2pbot@getalby.com, thank you!

How to translate the bot?

To translate lnp2pBot, you must do a pull request (Pull Request or PR) on the GitHub repository https://github.com/lnp2pBot/bot by adding a new .yaml file in https://github.com/lnp2pBot/bot/tree/main/locales with the translation of the bot strings.

The new yaml file should be named using language codes ISO 639-1, for example, in Spanish it is es, then the name should be es.yaml.

You can use as a guide https://github.com/lnp2pBot/bot/blob/main/locales/en.yaml, copy it and modify only the texts that are not a key (the keys are the ones before the colon : ).

You can also use as a reference some previously added language PR: https://github.com/lnp2pBot/bot/pull/460.

If you are not a technical person, don't worry, just download en.yaml or the translation where you feel most comfortable, translate it and send it to some administrator of the telegram group.

How to translate and collaborate with documentation?

The lnp2pBot documentation has been created with mdBook, a versatile tool that enables us to organize it clearly and coherently, this includes the creation of chapters, sections, cross-links, etc, ensuring fluid navigation and easy comprehension of the content.

Below, we provide a step-by-step guide on how to translate the documentation. This guide can also be useful if you wish to add more content or improve existing material:

1. Install Rust: https://www.rust-lang.org/tools/install

2. Install mdBook:

$ cargo install mdbook

3. Clone the repository and create a new language directory: Clone the repository https://github.com/lnp2pBot/doc-site and then create a new directory for the language you want to translate the documentation into, based on the existing English or Spanish directory (these are the most frequently updated).

$ git clone https://github.com/lnp2pBot/doc-site.git

$ cd doc-site

$ cp -r english <your-language>

4. Modify the book.toml file: You must set the language and title parameters in the book.toml file. For language, you must use the language codes ISO 639-1; and fot title, replace "Learn" with its equivalent in your language.

language = "en" title = "Learn @lnp2pBot"

5. View the Book Locally: Once inside the directory that we have copied, you can see what the book looks like locally using the following command:

$ cd <your-language>

$ mdbook serve

Then, open http://localhost:3000 in your web browser to view the created workbook.

6. Start Translation: To begin translating the documentation, access each .md file within the src directory. Any changes you make will automatically appear updated in the book at http://localhost:3000 while mdBook is running.

• In the SUMMARY.md file, you will find the structure of the book's chapters. You only need to translate the chapter titles, enclosed in brackets [ ], without modifying the links, enclosed in parentheses ( ).

• To replace an image or gif with one in your language place it in /assets/images/ and delete the original file, but give the new one the same name.

• Do not translate .md file names or links.

7. Send a Pull Request (PR): Once you have finished the translation submit a pull request (Pull Request or PR) in the GitHub repository https://github.com/lnp2pBot/doc-site.

Tips

• Check out this guide on How to format texts with markdown.
• You could do the translations without using mdBook by simply translating each file and submit the PR, although that way you could make mistakes
• If you encounter difficulties following this tutorial, please contact an administrator of the telegram group for assistance.

Development

This guide is based on the Bisq contributing guide.

Anyone is welcome to contribute to lnp2pBot. If you're looking for somewhere to start contributing, check out the good first issue list.

Communication Channels

Most communication about lnp2pBot happens on the main Telegram group. Discussion about code changes happens in GitHub issues and pull requests.

Contributor Workflow

All lnp2pBot contributors submit changes via pull requests. The workflow is as follows:

• Fork the repository
• Create a topic branch from the master branch
• Commit patches
• Squash redundant or unnecessary commits
• Submit a pull request from your topic branch back to the main branch of the main repository
• Make changes to the pull request if reviewers request them and request a re-review

Pull requests should be focused on a single change. Do not mix, for example, refactorings with a bug fix or implementation of a new feature. This practice makes it easier for fellow contributors to review each pull request.

Reviewing Pull Requests

@lnp2pbot follows the review workflow established by the Bitcoin Core project. The following is adapted from the Bitcoin Core contributor documentation:

Anyone may participate in peer review which is expressed by comments in the pull request. Typically reviewers will review the code for obvious errors, as well as test out the patch set and opine on the technical merits of the patch. Project maintainers take into account the peer review when determining if there is consensus to merge a pull request (remember that discussions may have been spread out over GitHub and Telegram). The following language is used within pull-request comments:

• ACK means "I have tested the code and I agree it should be merged";
• NACK means "I disagree this should be merged", and must be accompanied by sound technical justification. NACKs without accompanying reasoning may be disregarded;
• utACK means "I have not tested the code, but I have reviewed it and it looks OK, I agree it can be merged";
• Concept ACK means "I agree in the general principle of this pull request";
• Nit refers to trivial, often non-blocking issues.

Please note that Pull Requests marked NACK and/or GitHub's Change requested are closed after 30 days if not addressed.

Style and Coding Conventions

Coding standards

We try to use Airbnb javascript style guide in order to have a cleaner code.

Configure Git user name and email metadata

See https://help.github.com/articles/setting-your-username-in-git/ for instructions.

Write well-formed commit messages

From https://chris.beams.io/posts/git-commit/#seven-rules:

1. Separate subject from body with a blank line
2. Limit the subject line to 50 characters (*)
3. Capitalize the subject line
4. Do not end the subject line with a period
5. Use the imperative mood in the subject line
6. Wrap the body at 72 characters (*)
7. Use the body to explain what and why vs. how

Sign your commits with GPG

See https://github.com/blog/2144-gpg-signature-verification for background and https://help.github.com/articles/signing-commits-with-gpg/ for instructions.

Keep the git history clean

It's very important to keep the git history clear, light and easily browsable. This means contributors must make sure their pull requests include only meaningful commits (if they are redundant or were added after a review, they should be removed) and no merge commits.

Report bugs

If you encounter any errors or unexpected behavior, please report them to us as soon as possible.

To do so, simply visit https://github.com/lnp2pBot/bot/issues and click on New issue. From there, select Bug report, provide a clear title summarizing the issue, and complete the bug report template. Feel free to include any additional information, even if it's not explicitly requested in the template. Once you're done, submit the report by clicking Submit new issue.

Thank you for helping us improve!

Propose improvements

lnp2pBot is maintained by its community, and many great improvements have stemmed from user proposals. If you have ideas that could enhance the bot's functionality, streamline user experience, or any other suggestions, feel free to share them. Your input could make a significant difference!

To submit your proposal, visit https://github.com/lnp2pBot/bot/issues and select New issue. Choose Feature request, provide a clear title summarizing your proposal, and fill out the information in the template. You're welcome to include additional details, even if not requested in the template. Finally, submit your request by clicking Submit new issue.

Thank you for contributing!