1 of 58

Bitcart Docs

Introduction

Bitcart is an open-source, self-hosted all-in-one solution for Bitcoin and other cryptocurrencies.

You can use it in a variety of ways: from payment processing via our ready tools to custom applications via our SDK.

If you have trouble using Bitcart, consider joining the communities listed on the official website to get help from Bitcart community members. Only file Github issue for technical issues you can't resolve through other channels or feature requests you've validated with other members of community.

Please check out our official website, our complete documentation and FAQ for more details.

Features

Direct, peer-to-peer cryptocurrency payments
No transaction fees (other than those for the crypto networks)
No processing fees
No middleman
No KYC
User has complete control over private keys (in fact, private keys aren't required at all)
Enhanced privacy
Enhanced security
Self-hosted
SegWit support
Lightning Network support
Opt-in Altcoin integrations
Easy to use API and SDK
Process payments for others
Powerful ready to use admin panel
Ready store to get your first customers
Many integrations available
Extendable the right way

How it works

In a nutshell

In layman's terms, Bitcart is a solution for anything you might need to do in cryptocurrencies ecosystem.

If you need to process payments as a merchant, Bitcart can serve either as a full invoicing system, or just as a payment processor for cryptocurrencies' payment methods. When checking out, the customer will be presented with an invoice. The invoice is a fresh address from your wallet that wasn't used before. This way, by avoiding address re-use, your privacy is enhanced. Bitcart is using Electrum wallet protocol and it's SPV (Simple Payment Verification) feature to verify sent payments. After successful payment, your Bitcart instance can automate most of the work needed to fulfill the order safely. You are provided with ready solutions for your store, your company or application. Anything is possible with Bitcart.

But if you just need a way to check the blockchain, or a way to create transactions (for tipping bot, for example), Bitcart provides ready developer tools for the most comfortable experience: ready and well-documented SDK, Merchants API (see it's swagger documentation here) and various plugins.

How is it different

Bitcart is a completely open source project. Every feature added, every change is documented and is publicly visible. There is no third-party between a merchant and a customer. Each merchant can set up their own individual instance, not dependent on other instances, or any third-party. Every action is under control of the merchant. As Bitcart is self-hosted, of course there are no processing or subscription fees.

As Bitcart is open source, everyone is welcome to read it's code, help in finding bugs and suggest new features! Security auditors can always inspect the quality of our code, and they have a secure way to report vulnerabilities to make them fixed before they were used for bad

There are a few projects existing in the cryptocurrencies sphere targeting payment processing, but Bitcart is way more than just that. Payment processing is just one of the possible use-cases, but the user can always choose which parts of Bitcart to use.

As Bitcart contains many features, it is modular (while most other projects aren't). That means, for example, that if you only need to use the SDK for custom apps-just enable our daemons only. If you also need to have a ready Merchants API to use in a store-like application, enable it too. If you need a powerful admin panel, you can enable it. And so on, Bitcart consists of individual independent parts, which are easy to customize and use.

Another key difference is that, we are open to community ideas, and the project is built by the community and is influenced by the community. Every important decision taken is decided via a public poll. We are building a positive community having fun and making use of Bitcart, with the same goal: to make it even better.

How it keeps funds secure

Payments via Bitcart are direct, peer to peer. The merchant receives the coins directly to their wallet, with no intermediary.

How it works? For each invoice, Bitcart generates a new address, belonging to the xpub entered, and this address is presented to the user. As this address is your wallet's address, you receive the funds directly. Bitcart just watches the payments, it can't modify anything along the way, as when configuring the wallet, you only need to enter a watch-only master public key.

That way, you have complete control of the funds received.

How it keeps data private

The data is shared only between two parties - the buyer and a seller. Only the data required for the app operation is saved, nothing else. The concept of decentralization is followed-if there are lots of indendent instances, there can't be a central server for anything. There are no data leaks in any operations, and all the information stored can only be viewed by the server owner (usually, the merchant)

How it resists censorship

Self-hosted
Can be run everywhere, from low-powered device like Raspberry Pi at home to enterprise-grade servers
No third-party
Can easily be re-deployed

Bitcart does not have a central point of failure since nobody is controlling it except for the user running it. If run on the cloud server, the hosting providers can potentially censor users by suspending hosting accounts or disabling access to virtual machines. This is always a risk for anyone using a hosting provider. Since no private keys are stored on the server, a censored individual can easily re-deploy the Bitcart with another host. Your coins are always inside your wallet. If an invoice is paid while your Bitcart instance on the server is down, the software will automatically determine and notify the merchant of offline invoice payments when your server is back up. If a hosting provider suspends the server, and there was no proper backup, server settings and invoice data may be lost, but on-chain payments are always in your wallet. For ultimate censorship-resistance, users should run Bitcart on their own hardware.

Beyond payment processing

Bitcart is not only a payment processor for merchants. It is called all-in-one crypto solution because it can be used for anything you want. It abstracts a lot of complex components into simple and easy to use interfaces, APIs and SDKs. Developers can build entire businesses and projects on top of the stack. Enterprises can use it as scalable and secure back-end of their infrastructure without ever having to put a trust in a third-party. Bitcart is a toolbox with lots of tools you can use, it's up to you how you want to use it.

Bitcart Basics

Use Case

Built with extensibility in mind, Bitcart is a feature-rich software with plenty of use-cases that can solve problems for different types of users.

In this guide, we will show you some of the use-cases of Bitcart, but it is by no means limited to the groups of users we mentioned.

So let's have a look at what you can do with Bitcart and what the benefits are of using it.

Merchants

By choosing Bitcart to process payments, you are:

Saving money (no fees, no subscriptions)
Cutting out the middle-man (Payments go directly to your wallet)
Enhancing privacy for you and your customers (no address re-use, no IP leaks to third parties)
Saving time (easy integration and installation)
Protecting yourself from interference in your business (self-sovereignty)
Reducing the costs for the server running your instance (lightweight but secure)
Decreasing the development time as we have ready solutions available for any kind of store

To enjoy most of these benefits, you don't even need to run a Bitcart instance yourself, you could just create an account on someone else's instance. It will be even easier to set up for free or a fee depending on the host's choice. Downside is that you will rely on the server admin to keep it functional and up-to-date.

With the growth of your business it will eventually become important to set-up your own server to be really independent.

Want to give it a try? Here is an up-to-date list of third-party hosts.

Online Store

If you're a merchant running an e-commerce business, you can easily deploy Bitcart and connect it to your store via integration plugins in just a few clicks. Or, if you don't have a store yet, you can use Bitcart's built-in store which is a ready solution which might be enough for your use case. You can start selling even without any programming!

Bitcart checkout is no different to any other payment gateway. Your customer gets an invoice. They pay it by scanning a QR code or by copy-pasting the amount and the address. When their payment is confirmed, you will be notified via your e-commerce CMS and additional configured actions will be executed, and you can ship the item. Take a look at our demo online store.

Physical Store

For physical stores, Bitcart has a web-based Point of Sale (POS) store which can be customized. Similarly to the online store, your customer is presented with an invoice that they can pay on the spot. You can create a watch-only wallet on your phone to be notified of the payments through the POS, without the need of any additional software. The POS store can be run on any web-connected device.

Freelancers & Bill Pay

Send anyone a request for payment by creating an invoice with custom amount in your admin panel (demo). With or without expiry, users can pay the invoice at any time.

Merchants or freelancers can use this for bill pay services. You can even use your admin panel to quickly request money from friends.

Lightning Network payments

No matter the kind of business you run, Bitcart offers a very easy way to get started on the Lightning Network. You can use and experiment with this innovative second-layer solution build on top of Bitcoin by following this guide. Both merchants and customers can use Bitcart to receive or make payments off-chain with instant confirmations and neglectable network fees.

Charities and Content Creators (Donations)

Charities, non-profits, content creators, and other organizations that want to accept cryptocurrency donations in a more private way than the traditional single bitcoin address method can utilize the Admin panel, and POS store for a better user experience.

Benefits of using Bitcart for accepting donations:

Saving money (no fees, no subscriptions)
Cutting out the middle-man (Payments go directly to your wallet)
Enhancing privacy for you and your customers (no address re-use, no IP leaks to third parties)

It is particularly important to mention that Bitcart prevents address reuse, as many people has been reusing address for donations in the past. Here is why you SHOULD NOT reuse Bitcoin(or any other cryptocurrency) address:

Privacy: reusing the same address for donations not only makes it incredibly easy to link it to your identity, it also compromises the privacy of your donators and every person that interacts with you
Security: by compromising your privacy, address reuse increases your attack surface, as people that want to steal from you or harm you would have A LOT of information about you and your donators
High fees: fees for a Bitcoin transaction are calculated according to the "size" of a transaction (which has nothing to do with the amount being sent). By reusing addresses, you are building huge transactions involving many inputs, that will cost you a lot in fees when you want to move them

You can read more about address reuse on the Bitcoin Wiki.

Local Payment Processor

When you deploy a self-hosted Bitcart instance, you can attach and create an unlimited number of stores and apps. This means when you launch Bitcart, you can become a payment processor for your family members, friends or your local community. You can do that to promote Bitcoin or other cryptocurrencies amongst people you know or to help out people that can't rely on other solutions.

While you're allowing them to rely on your Bitcart core instance, the payments go directly to their wallets, and you have zero control over their funds at any point in the transaction, and cannot charge a processing fee. You can, however, develop a registration paywall and charge monthly fees.

Take a look at the list of third-party hosts.

Cryptocurrency Exchanges

The number of merchants using Bitcart grows each day, and cryptocurrency exchanges could benefit from it by developing integration with Bitcart and allow instant conversion of cryptocurrency payments into local fiat currencies.

Being an open source project, Bitcart doesn't have the power to impose anything on exchanges, meaning that any of them could build on top of it, regardless of their size or the country they operate.

Hosting Providers

Hosting providers can (and some already did) create easy 1-click Bitcart deployment solutions for their customers. With the growing interest in Bitcart, hosting companies can tap into this source of new customers and make money by hosting easily-deployable Bitcart instances for merchants.

Developers

Bitcart community is amiable and open-minded. Developers can not only learn a lot and get their name out by working on an open-source project, but also participate in transforming the payment processing business.

Bitcart source code is a great source of learning, as it utilizes the modern and demanded tech stack. It has already helped many people in learning something: testing and TDD, docker, APIs building, and many more! Join us and discover many great things in tech world!

These are some of the many ways in which you can use Bitcart. Unleash your creativity and feel free to build your own solutions to solve problems.

Walkthrough

In this article, we will walk you through the Bitcart admin panel user interface and show you how to navigate through different options.

When creating an account, if you're the first user registered on the instance, you'll be granted superuser rights (full control over the server). On third-party hosts it is usually not so, but if you're hosting your own instance you'll of course become the full owner of it.

After you created the account on the Bitcart instance hosted by yourself or a third-party, you'll see a lot of information cards.

Note about the night mode of the panel. By default, admin panel uses day mode, but if in your local time it is from 8 pm to 6 am, night mode will be enabled automatically 😉 You can configure it by clicking the moon icon in the top right corner of the page.

Each information card contains summary about something in your account: wallets, stores, products, invoices, etc.

By clicking Details button in any of the cards you will be able to see full information about specific unit.

Note, wallets balance is displayed not in BTC, but in abstract currency. It is a sum of all your balances in different currencies.

If you're a superuser, you can click on profile icon in the top right corner of the page to visit server settings page.

From server settings page, you can control the users of your server, and many more. For more information, check Server Settings FAQ

Now, to the other common settings.

Each page basically contains one common thing - a datatable.

It is a feature-rich datatable, supporting searching, ordering, create/edit/delete actions, batch actions, and some additional actions depending on what page you're on. For example, on stores page, you can configure email settings for a store by clicking email icon in actions column.

Wallets

The core of Bitcart is creating a wallet. In Bitcart, one wallet represents one currency.

Default currency is btc, you can change that. When creating wallet, just select currency code from the ones available on your instance (btc,ltc etc.). Wallets may have a name and their xpub.

The nice feature of Bitcart is that it does not require your private keys, but it supports many different formats.

You can enter (x/y/z)pub - public key, (x/y/z)prv - private key, or even electrum seed - providing easiest migration possible from many wallets, especially electrum. If you don't have an xpub yet, we recommend you create a wallet somewhere. Electrum wallet provides the best integration with Bitcart, check Architecture page for more information.

When creating a wallet, it will get synced very fast (depends on the size of the wallet, but shouldn't take too long), and Bitcart will fetch it's balance and display it.

By clicking arrow near any of the rows, you can view some additional details, like wallet xpub.

Stores

You can create unlimited amount of stores in Bitcart.

Each store can contain any amount of products and associated invoices. Store is a base entrypoint for anything related to checkout.

Store may have multiple wallets connected. That way, connecting different wallets with different base currencies, you can achieve multicurrency checkout.

Selecting multiple wallets of the same currency is NOT recommended. On invoice creation, Bitcart will pick the first wallet of that currency, returned by database(they might be returned in any order).

If you want to send customers invoices on successful checkout, you should configure email server.

To do that, click on email icon in actions column, and enter SMTP server details.

Store email is the email used to send messages from, and the display email in Bitcart POS store.

Email host, port, login and password are credentials for your SMTP server. Email host shouldn't include any http:// or https:// parts. If your SMTP server requires TLS, turn on SSL/TLS switch.

When done(you should click save button first), click on Test ping button to see if your setup is working.

Note for gmail SMTP servers, you should enable access by turning on less secure apps (it is still secure, gmail apps aren't the requirement). You might also need to allow access on a new account.

From the email settings pop-up, you will also be able to load a ready preset for some popular email server providers.

Your store is the main configuration point for all the further actions with it, like invoice creation.

You can configure different policies from your store settings.

Store checkout settings

By clicking on settings icon, you will be presented with the store checkout settings pop-up, where you can change different settings affecting the checkout.

Invoice expiration time, in minutes. It affects the timer displayed in the checkout. It is the time in which the customer must send the payment, otherwise invoice is marked as expired
Use HTML templates - whether to render templates of email message sent to customer as html or as plain text. For more information, see this guide.

Discounts

It is optional page for your initial setup, you may skip it for now.

In many cases you might want to add some discounts to your store. New year discounts, other holidays? Limited time promocode discounts? Discount when paying in your preferred currency? Anything is possible with Bitcart.

Just provide a percent(integer) for your discount, and discount apply conditions:

promocode(optional, when not provided discount is always applied when other conditions succeed)
end date
currencies(comma separated list of currency to apply to, or empty to apply to all currencies)

You can link discounts to products in the products page.

When one invoice at creation time has matched multiple discounts, Bitcart will pick the best discount(by percent).

Products

Products are your base selling unit. Create your products, link them to your stores, add product details - and they will get displayed in your store POS!

Bitcart supports many different information for creating products:

Amount, displayed in store POS in USD
quantity(how many products of the same kind available)
product category(used for filtering in store POS to classify your products)
Discounts applied to the product(see previous section)
Product status(like in stock, not available, up to you)
Download url(for digital content, will be sent to customer in email)
Store, from which to take wallets and other information
Date of creation(auto-filled)
Product image(supports cropping, rotating and many more!)
Product description

Invoices

This page can be used to monitor your paid invoices, create new invoices and send them to friends, or to pay an invoice.

Supported information:

Price is the price in store's default currency, which will be converted to payment method's currency when generating payment URL
Currency, used to override store's default currency if needed
Store, from which to take wallets and other information
Connected products(for store POS, optional)
Promocode, if customer entered it during checkout process (auto-filled)
Notification URL where to send IPN notifications on invoice status change (more below)
Redirect URL, customer will be redirected to it after successful checkout.
Buyer email, if customer entered it during checkout process(auto-filled)
Order ID, used by external integrations like woocommerce, track your orders by searching for order id(auto-filled)
Discount - ID of the discount applied during invoice creation(auto-filled)
Invoice status, more below
Date of creation (auto-filled)
Payment methods - not editable fields, displaying checkout information

If your invoice contains connected products, you'll be able to know which products were bought by the customer. The name of the store will be used on checkout.

When converting to payment method's currency, destination currency's maximum decimal points is taken in mind, and the price is being formatted as per currency settings. The convert, the exchange rate is used. See this page for more information.

Notification URL

If you fill in notification URL, Bitcart instance will send IPN notifications to that URL via a POST request.

It will send the following json data:

{"id": invoice_id, "status": new_status}

When invoice status changes(Pending->complete, Pending->expired, etc.), notification will be sent.

It's up to you how to process that IPN notification. You should also verify that data sent is correct, as theoretically, anyone can send that POST request if they know your IPN handler URL. So, check that sent status is the same as the one got from get invoice request.

Invoices statuses can be one of the following:

Pending (in progress)
complete (invoice paid)
invalid (unexpected error)
expired
In progress (lightning network status)
Failed (lightning network status)

After invoice creation, you'll be able to view checkout information by clicking show button in payment methods column. It will display a so-called "invoice preview", it is not a fully functional checkout, but just an information dialog to display payment methods(it ignores invoice status).

By clicking open checkout you'll be redirected to full checkout, respecting invoice statuses and other things. Invoice URL can be safely shared with others and used for checkout right from your admin panel.

Notification providers

On this page you can configure your notification providers, to later connect them to your stores.

Supported information:

Notification provider name for display
Provider to use, you can choose of many available ones
Provider options, differing from provider to provider

Each notification provider has different settings. Refer to their documentation about how to get certain settings. After that, select needed provider, fill in the settings and save changes.

Then you can reuse notification providers by connecting them to needed stores!

When notification provider is connected, on each successful order it will be run to deliver a notification to you.

Templates

On templates page you can override global server templates, or create custom ones.

Available fields:

Name of template, you can select from built-in ones or type in a new one
Template text

All templates in Bitcart are rendered via Jinja2.

Read about it's syntax in their template designer documentation.

Read more about example usages of templates in Bitcart here

Template selection rules

When a template is being requested to render (for example, when sending notification via notification providers, or composing email message), it is selected in the following order:

If this product or store has template connected, it will be used
If it has no template connected, default global store or product template will be used (named store or product), if exists
If none of templates above are customized, default templates are used

Changing object's templates

On some pages, for example, stores or products pages, you will be able to edit templates per each item (per each product, per each store, etc.) If so, on such pages you will see the following icon:

By clicking on it, you will be able to override default templates for this item. Such templates are always used the first if they are set.

Note that in the example image above it is not necessary to connect default templates for each store, as the template we created is named notification, therefore overriding default ones for each store.

Payouts

Bitcart supports sending funds from your connected wallets to outside sources. This can be useful for refunds for example, or in case you don't want to open a separate wallet for each currency and use universal Bitcart interface.

Just enter:

Destination
Amount to send (in fiat currency, defaults to default currency of the store, for this screenshot it would be 1 USD)
Store to use (used for setting some defaults like currency)
Wallet to send from. Whether it's a smart contract or not will automatically be determined via wallet settings
(Optional) notification url where to send IPN notifications on payout status updates (a HTTP POST request with data in format {"id": "payout id", "status": "new status"}
(Optional) Maximum fee (in fiat currency selected). If predicted fee exceeds the max fee, the payout will halt.

When saving a payout, it won't be sent automatically. It will be set to pending status, waiting for your approval. There are a few statuses for you to use:

pending (just created), approved (manual approval by you, not sent yet), cancelled (manual cancel by you, not sent), sent (payout is sent, tx hash is available, transaction not confirmed yet), complete (payout is sent and confirmed, used fee is available in payout details), failed (something failed during payout sending)

Signing payouts

By default, all wallets in Bitcart are watch-only. We typically only require an address or xpub for payment processing needs. Private key is never required. In case you use the payouts feature, you will be able to connect relevant wallets used with their private keys. Signing will be done in a special "diskless" mode, where all operations will be performed in memory, with no data saved to disk.

But in case your wallet was created as a hot wallet, it will be used automatically without the need to supply it (note that in this case, as per regular wallet loading operations, the keys will be saved on disk)

Bitcart vs others

Most new merchants will likely only consider the price of the service. Since Bitcart is free, that may have led you here and if so, welcome.

First of all, as said above, Bitcart is fully free, fully opensource and has no limitations. You are your own bank.

The second main difference is that other services are usually providing only one thing - rate-limited API or a web interface. But Bitcart, as opposed to others, is a full-featured solution, all-in-one crypto solution. It can satisfy needs of any audience:

Merchants, providing ready solutions for your stores to accept cryptocurrency payments with the simplest setup
Server maintainers, providing simplest setup with a diversity of deployment options, with automatic updates (github release -> docker hub -> end machines)
Anyone else wanting to try out cryptocurrencies

Bitcart is a light self-hosted solution. It is as safe(even safer than most) as other solutions, but is light, easy to use and install.

The approximate system requirements differ, but almost any server is fine, less than 1 GB RAM and less than 10 GB disk.

Bitcart is made with extensibility in mind, so adding something new is easy. Written in Python, it's code is easy to review and read, adding new features is faster than in other projects.

Bitcart is also a great source of learning. We use many different technologies, creating the best User Experience. During the process of development, we met many different problems and solved them in elegant ways. You can learn those ways, and the technologies used, and become a professional developer.

The list of the reasons why you should use Bitcart can go on and on. Now some features of it as a payment processor:

Features

Every payment processor has features, here are some Bitcart features:

Free - No merchant processing fees.
Bitcoin - Accepting Bitcoin is the first step.
Altcoins - Accept cryptocurrency alternatives to Bitcoin.
Lightning - Rapid Bitcoin microtransactions using the Lightning Network.
Integrations - Wordpress & WooCommerce and custom integrations.
Point Of Sale - POS Interfaces for physical stores.
Unlimited Stores - Merchants can process payments for their own stores, or for others.
Payment Requests - Create & send a long-lived invoice requesting payment for goods or services.
Ready solutions for starting merchants - your own store and admin panel.
Solutions for checkout flow automation - you can create scripts to process the order for you.

Cost

It's important to note that payments made using the Bitcoin Network always require a transaction (miner) fee for it to be included in the blockchain. The Bitcoin Network determines if the transaction is authorized and when it is confirmed.

Bitcart creates direct payment invoices for merchants to provide to their customers. It also monitors the blockchain and stores the confirmation status of each payment or donation. To do this Bitcart requires hosting on a server which merchants can deploy on their own hardware, purchase a VPS (less than $3.5/mo), or use someone else's Bitcart instance to host your account (free or paid options).

If you deploy Bitcart using a VPS, the following types of fees are never charged:

Merchant fees
Subscription fees
Transfer fees
Software fees

Security

First rule of Bitcoin is always keep your private keys private. Using a secure wallet is recommended for new merchants as the only provider (creator) of private keys. If there is a chance that someone else (such as a website) knows, stores, or provides your private keys to you, it's generally accepted that they are not actually private.

Secondly, there is another area of security to consider on the applications layer where you have two main options:

- Many wallets do not allow payments to BIP 70 invoice urls.

Privacy

Bitcart will never ask a merchant for any personal identification.

Typically, when converting to or from fiat on behalf of a merchant, payment processors are required to collect personal information for Know Your Customer (KYC) and Anti-money laundering (AML) banking requirements. This may include personal information such as passport ID, phone number, address, bank account, etc.

Fortunately, the Bitcoin Network does not use or collect these types of personal information, and therefore neither does Bitcart. How Bitcart ensures privacy:

No middleman involved.
Information is shared between customer and seller only.
No address re-use.
Any non-decentralized solutions are avoided, instances are self-contained.

Decentralized

Many payment processors claim to have no middleman. They claim that funds go directly to your wallet or that they offer instant settlement. However, if the processor makes any of the following claims, they are most likely operating as a middleman:

Waiting time for a merchant to receive payment is longer than sufficient blockchain confirmation.
The payment processor combines customer payments before sending to the merchant's wallet.
If there are any kind of limits on transaction volume for the merchant.
If the payment processor can decline, reject or alter a payment after being sent from a customer's wallet.
If the payment processor has terms and conditions stating they can hold or freeze your account.
Fees for using the payment processor are automatically taken out from the customer's payment to the merchant.

Payment processors are able act as middlemen by using custodial wallets. A payment processor can use an internal custodial wallet for altering customer payments before routing them to merchants. This is how they can collect fees, hold payments for verification and processing, etc. This type of wallet is an intermediary between the merchant wallet and the customer wallet. It's the middleman wallet.

The payment processor may also provide a custodial wallet for the merchant to use. As mentioned above, this is advised against because your private keys may be compromised. If they claim to not save your private keys after giving them to you, it's likely you will not know the truth until it's too late. Centralized services may seem like an easier solution for the merchant. Unfortunately the trade-off is sacrifices in privacy, security and self-sovereignty which is normally obtained using the Bitcoin Network.

That's one of the reasons why Bitcart was created. To help merchants remove third party dependencies and simply use the Bitcoin Network freely and securely. Merchants have their own copy of the Bitcart software which runs on their own server or VPS of their choice and validates their own payments using their own node. It's a self-hosted Peer-to-Peer all-in-one crypto solution. There shouldn't be any trade-offs as setup is the simplest possible and we wanted to make this software user friendly.

As the Bitcart community continues to grow, more deployment methods, use cases and tutorials are continually being added to make it easier for non-technical users. Bitcart is completely open source. Anyone can join the community to suggest or create improvements, features, guides, etc. Feedback is always welcome.

Fiat

Currently, Bitcart is a processor without fiat conversion capabilities. As a merchant, this may be a difficult if business costs require fiat. Not providing fiat conversion allows Bitcart merchants to avoid KYC and AML identification verification. This also allows Bitcart to be free and available for anyone to use.

However, a fiat conversion feature is on the roadmap for Bitcart. Since merchants are always the owners of their private keys, they can always freely convert their coins manually, but for now there's no instant-fiat conversion.

Can't find this information for other payment processors?

It's probably a feature not a bug!
All of this information should be available to merchants.

Try it out

This section goes through the process of creating an account and store on our public Bitcart instance. (For evaluation purpose)

Create your first invoice

First let's create a new store:

Go to the demo website
In the login form click on Sign up here to create an account

Let's use Electrum to create a mainnet wallet for your store:

Download Electrum
Run Electrum
Click through the wizard and create a test wallet, using the default settings Electrum proposes
After the wallet is set up, go to "Wallet" > "Information" in the Electrum menu.
Copy the "Master Public Key" string (starting by *pub...)

Let's configure the store so it uses your Electrum wallet:

Go to Wallets page and create a new wallet with your copied xpub
Go to Stores page and create a new store with your new wallet connected
After that your test wallet should appear on the Wallets page of your Bitcart account

Then you can create an invoice, either through

the Invoices page on the website or
the process documented on the Custom integration
or the store POS, if you are the owner of the instance

Bitcart Demo

To see Bitcart in action, visit our demo apps and stores or check out some of the stores using Bitcart in production.

Deployment

Bitcart is extremely easy to deploy on your own server!

We have the minimal requirements ever possible:

1 GB RAM (2 GB if enabling ETH)
10 GB disk
Unix-based operating systems (something common like ubuntu is recommended)

Please refer to this diagram to choose your deployment method (you can see their descriptions in navigation sidebar at left):

In case you're not yet ready to choose where or how to host (it can cost as little as 3.5$ a month), you can try using Bitcart using our demo or third-party hosts.

Configurator

Bitcart Configurator allows you to easily deploy new Bitcart instances, or re-configuring existing ones, with ease and no technical skills.

Configurator demo is accessible at https://configurator.bitcart.ai

You can access it from your admin by clicking the configurator button.

It allows you to easily deploy a new instance by just answering a few questions.

Deployment destination

There are 3 deployment destinations available: remote, manual, and current instance.

Remote

By entering the server credentials, the Configurator will automagically connect to your server and deploy the instance, while you drink a cup of coffee!

For an example of successful deployment, watch the video above.

Manual

If you don't trust the configurator's server, or you just need a copiable script you can run yourself, you can use the manual mode. It generates a script for you to copy, based on selected settings.

Current instance

If you are the server admin, you will have access to the current instance mode. You can change settings of your current instance without logging in to your server. By clicking current instance button Bitcart loads all current settings which you can customize.

Domains

Coins

On this page you can configure and enable all the coins you want. For each coin you may enable lightning with just one click, or change network settings. Note that you must select at least one coin.

Additional

On the additional page, you may enable additional plugin packs, for example, Tor support.

Advanced

On this page you can configure advanced parameters. If you don't need to edit them, skip to the next page.

You can choose an installation pack (all, backend, frontend or none), and add more custom components, or edit the bitcart-docker repository URL.

Summary

On this page you can preview settings used. If something is wrong, you will see warnings.

When you are ready, click continue.

Deploy stage

After clicking continue, you will either see a ready script, or a progress bar, while configurator is deploying a new instance. Refer to each deployment destination for more details.

Docker Deployment

You may check out an easier method: Configurator

Bitcart uses docker for deployment. This allows us to simplify the installation and make Bitcart installable in almost any environment.

Currently Bitcart runs on 2 architectures: amd64 (most PC and servers), arm64 (raspberry pi). Arm32 is not supported officially anymore.

Almost every docker deployment starts like that:

sudo su -
git clone https://github.com/bitcart/bitcart-docker
cd bitcart-docker
# export needed settings, for example
export BITCART_HOST=yourdomain.tld
./setup.sh

Note the minus sign after su. It is required. If you are deploying on mac os, you don't need to enter the first command. This is to load all settings

There are different environment variables available in order to customize the deployment

In order for Bitcart to work, if you use BITCART_HOST, you should create a DNS A record from your domain registar, pointing to your current server

Environment variables are set like so:

export VARIABLE_NAME=value

Here are the main ones:

BITCART_HOST configures on which domain Bitcart should run. It is required unless you use any of the methods from local deployment. It works in one domain mode. Your Bitcart Store will be accessible at BITCART_HOST, admin panel at /admin and Merchants API at /api. For other ways of configuration (for example different servers), check the one domain guide
BITCART_CRYPTOS configures which coins to enable. It is a list of coin symbols separated by commas. By default only btc is enabled. For example, to enable btc and eth, you would run export BITCART_CRYPTOS=btc,eth
BITCART_REVERSEPROXY - configures the reverse proxy used. By default nginx-https is used (with automatic ssl certificates generation). It might be useful to disable it to access your services directly or you can set it to nginx to disable ssl
BITCART_ADDITIONAL_COMPONENTS - you can add additional components to your deployment. For example, using export BITCART_ADDITIONAL_COMPONENTS=tor enables tor.

There are also quite a few settings related to configuring coins in Bitcart. Each coin has the same set of settings you can configure:

COIN_NETWORK changes on which network the coin runs. For example: export BTC_NETWORK=testnet would enable testnet in BTC coin with no other changes required!
COIN_LIGHTNING enables lightning network for coins which support it (BTC-based). For BTC you would do: export BTC_LIGHTNING=true
COIN_DEBUG enables debug mode for daemons to log more information. For example export BCH_DEBUG=true
COIN_SERVER configures the daemon to use exact server you specify instead of connecting to many servers at once. For example export BNB_SERVER=https://bsc-dataseed.binance.org For btc-based coins, you can set up your own ElectrumX or Fulcrum server with your own full node. For eth-based coins, server is your full node's RPC url.

For the complete list of configuration settings you can use (to e.g. open some ports, change networks used or anything else), check out full configuration description at bitcart-docker github.

Local Deployment

If you want to try out Bitcart on your local machine, it is also possible. If you don't have a domain name, Bitcart provides a way to test in a local-only deployment.

This only works from the computer on which you install Bitcart directly. To access it from outside, you should either use Tor or your own domain name + static ip

Here and later we assume that you've cloned the bitcart-docker repository, entered that directory and entered root shell by using sudo su - (note that minus at the end, it's important!). If you're on mac os, use the scripts as your current user and don't enter root shell.

Local setup (.local domains, only current PC)

Tor setup (everywhere, requires tor browser)

It is even possible to combine both ways to be able to access both locally and from anywhere!

Manual Deployment

The process is basically the following:

Install OS required libraries
Install python3 (3.9+)
Install nodejs (20) and yarn
Install postgresql
Install redis (6.2.0+)
Clone and run all parts of Bitcart
(Optional) Open Firewall Ports and Access the Sites

Warning: Not recommended to use in production

Manual installation is NOT recommended in production. It should be only used for learning purpose.

Instead you should use the docker deployment.

The docker deployment will provide you easy update system and make sure that all moving parts are wired correctly without any technical knowledge. It will also setup HTTPS for you.

Typical manual installation

This steps have been done on ubuntu 22.04, adapt for your own install.

1) Install OS required libraries

sudo apt install libsecp256k1-dev

Or the equivalent for your os package manager

More info on libsecp256k1 in electrum docs or bitcoin core docs

2) Install Python 3

Usually it might have already been installed, but we also need pip3 and dev packages, so:

sudo apt install python3 python3-pip python3-dev

3) Install Node.JS and Yarn

sudo apt install nodejs
curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
sudo apt update && sudo apt install yarn

If nodejs from your distro is not at least the version we require, then you should install it via nodesource

Using a nodejs version higher than specified way work, but we officially support only 1 release series (usually current LTS)

4) Install PostgresSQL

Note, replace REPLACEME with your new postgres password.

sudo apt install postgresql postgresql-contrib
sudo -u postgres createdb bitcart
sudo -u postgres psql -U postgres -d postgres -c "alter user postgres with password 'REPLACEME';"

5) Install Redis

sudo apt install redis-server

Ensure that your redis version is > 6.2.0. Check with redis-server -v.

If redis from your distro is too old, install from official redis repository

6) Clone and prepare Bitcart components

Bitcart core(daemons) & Merchants API:

git clone https://github.com/bitcart/bitcart
cd bitcart
# Optional: Create virtual environment instead of using the global python environment
python3 -m venv env
source env/bin/activate
# continue installation
sudo pip3 install -r requirements.txt
sudo pip3 install -r requirements/production.txt
sudo pip3 install -r requirements/daemons/btc.txt

For any other daemon(coin) you want to use, run:

sudo pip3 install -r requirements/daemons/coin_name.txt

Where coin_name is coin code(btc, ltc, etc.).

Create a file conf/.env It contains all the settings. For now, we just need to set database password and enabled cryptos.

# Replace REPLACEME with your database password
# specify used cryptocurrencies with BITCART_CRYPTOS

cat > conf/.env << EOF
DB_PASSWORD=REPLACEME
BITCART_CRYPTOS=btc,ltc
EOF

Apply database migrations:

alembic upgrade head

Bitcart admin panel

git clone https://github.com/bitcart/bitcart-admin
cd bitcart-admin
yarn
yarn build

Bitcart store

git clone https://github.com/bitcart/bitcart-store
cd bitcart-store
yarn
yarn build

Run everything

Bitcart core(daemons) & Merchants API:

Start daemons from the bitcart repo directory:

python3 daemons/btc.py

For any other coin, do the similar procedure:

python3 daemons/coin_name.py

Start api:

gunicorn -c gunicorn.conf.py main:app

Start background worker:

python3 worker.py

If you want to run a specific coin on a test network or change other environment settings you can update the .env file in the bitcart conf/ directory

Bitcart admin panel

cd bitcart-admin
yarn start

Bitcart store

cd bitcart-store
NUXT_PORT=4000 yarn start

Default ports

The Bitcart API runs on port 8000.
Daemons on ports 5000-500X
The Bitcart Admin panel runs on port 3000
The Bitcart Store runs on port 4000.

(Optional) Open Firewall Ports and Access the Sites

If you are running Bitcart on your local machine - you will not need to do these steps. You can go ahead and access the system with:

Bitcart Admin Panel: http://127.0.0.1:3000/
Bitcart Store: http://127.0.0.1:4000/
Bitcart Merchants API: http://127.0.0.1:8000/

If you are running Bitcart on a remote machine, you will need to do additional things to access them.

Option 1: Nginx proxy (Recommended)

This option is recommended to proxy secure incoming requests to the correct bitcart process.

Install Nginx

sudo apt install nginx

Add configuration for each component: bitcart-store, bitcart and bitcart-admin

vim /etc/nginx/sites-available/bitcart-admin.conf

server {
    server_name bitcart-admin.<mysite>.com;
    access_log /var/log/nginx/bitcart-admin.access.log;
    error_log /var/log/nginx/bitcart-admin.error.log;

    location / {
        proxy_pass http://localhost:3000;
    }
}

Enable the config

sudo ln -s /etc/nginx/sites-available/bitcart-admin.conf /etc/nginx/sites-enabled

Add DNS records for your server names to point to your VM's ip

Check the config and reload nginx

sudo nginx -t
sudo systemctl reload nginx

Add TLS certificates with the letsencrypt CA for the sites

sudo apt install certbot
sudo certbot --nginx

Now you should be able to access the components over TLS. You can then also enable http2 in your nginx configuration if you want.

You might want to look at the FAQ for more detailed info on the Nginx configuration options

Option 2: No proxy

If you have a firewall, you will want to open ports 3000, 4000 and 8000. Using ufw as an example:

sudo ufw allow 3000
sudo ufw allow 4000
sudo ufw allow 8000

yarn is listening on localhost 127.0.0.1 by default and you won't be able to access it over the internet unless you reverse proxy it with nginx. If you want to expose it without reverse proxy, use the environment variable: NUXT_HOST=0.0.0.0 to listen on all interfaces.

The store and admin site need public access to the bitcart api (URL should be resolvable both client and server side).

Using the manual method you need to set that with environment variables. The complete setup of the Bitcart Admin Panel and Store may look like this:

# bitcart-admin
NUXT_HOST="0.0.0.0" BITCART_ADMIN_API_URL="http://bitcart-api-ip:8000" yarn start
# bitcart-store
NUXT_PORT=4000 NUXT_HOST="0.0.0.0" BITCART_STORE_API_URL="http://bitcart-api-ip:8000" yarn start

Note: The above is the minimum to make it work and not a production grade solution. We still recommend to use docker deployment unless you really know what you're doing.

Access the site remotely

Bitcart Admin Panel: http://my-bitcart-admin-ip:3000/
Bitcart Store: http://my-bitcart-store-ip:4000/
Bitcart Merchants API: http://my-bitcart-store-ip:8000/

Continue with: Your first invoice

(Optional) Managing Processes

If you want the procaesses: bitcart api, daemons, worker and frontend (bitcart admin and bitcart store) to be managed with automatic startup, error reporting etc then consider using supervisord or systemd to manage the processes.

Upgrading manual deployment

Note: it is recommended to use docker deployment for easy upgrades.

To upgrade manually, follow the following steps:

1) Stop everything already running

Merchants API, workers, daemons, Admin panel and Store should be stopped

2) Pull latest changes

Run :

git pull

For every Bitcart component directory (Merchants API, Admin Panel, Store).

3) Upgrade dependencies

Bitcart core(daemons) & Merchants API:

sudo pip3 install -r requirements.txt
sudo pip3 install -r requirements/production.txt
sudo pip3 install -r requirements/daemons/btc.txt

Bitcart admin

yarn

Bitcart store

yarn

4) Apply new database migrations

In Bitcart core(daemons) & Merchants API directory, run:

alembic upgrade head

5) Rebuild store and admin

For Bitcart Admin Panel and Store, run:

yarn build

6) Start everything again

Follow instructions here

Hardware Deployment

Sometimes you might want to run Bitcart on your own hardware. This is a bit more complicated than using a VPS. But in the end you will get way better security and control over your data.

Note that no matter where you host Bitcart, as your private keys are never required, your data is always safe, you can export and move the data to any server. So if you started on a VPS, you can use our backups feature to create a backup of all your data and restore on your own hardware.

Requirements

Here are the requirements for running Bitcart on your own hardware:

High-speed internet connection. The faster the better. This is to ensure the speed of invoice detection
Any hardware ever. Yes, that's right! You can use your old PC or basically anything for that. Our minimal requirements are 1 GB RAM and around 10 GB disk. AMD64 hardware is the most tested one, but if needed, refer to our raspberry pi guide
Any linux-based OS would suffice, but using something like Ubuntu 20.04 is the most common choice.
(Optional) Static ip - that's required only if your setting up with your own domain name. If you only plan to use bitcart locally/via tor, this is not needed
(Optional) Domain name - see the note above

Setup

This guide assumes that you have static ip set up and your own domain name. If not, refer to the local setup guide.

Configure static IP in ubuntu via something like this guide
If you have a domain name, create a DNS A record pointing to your static ip address (tip: you can get it if you type whatsmyip in google)
Set up port forwarding on your router for ports 80 and 443 to your machine ip address. Every router is different, usually there are guides existing on any model
Recommended: install ssh server, configure firewall and fail2ban (to prevent excessive failed logins from random ips on the internet):

sudo apt update
sudo apt install -y openssh-server fail2ban git ufw
sudo ufw allow from 192.168.1.0/24 to any port 22
sudo ufw allow 80, 443
sudo ufw status
sudo ufw enable

You should replace 192.168.1.0/24 with your own subnet. This is to allow ssh connections only from your local network. You may not need it.

Clone and install Bitcart (replace bitcart.yourdomain.com with the actual domain name):

sudo su -
git clone https://github.com/bitcart/bitcart-docker
export BITCART_HOST=bitcart.yourdomain.com
./setup.sh

You may customize additional settings by export'ing more things. For example, use BITCART_CRYPTOS to customize the list of coins enabled. For the full list, see docker deployment page

All done! Enjoy your Bitcart instance! If needed, check out backups support on how to restore the data from your previous instance.

Raspberry Pi Deployment

Raspberry Pi is a good low-power solution to host Bitcart at home. It is quite cheap and you can use it to build a lot of custom stuff.

We recommend using the latest RPI4, but RPI3 would be good too.

What's good is: Bitcart can work with any RPI flavour, even 1 GB RAM is enough to run Bitcart. Though we recommend picking up a bit more (2 GB) just to avoid slowdowns.

As for the disk, SD card, USB memory or SSD - it doesn't matter, just know that SSD is usually faster. Basically any disk on the market should have enough space (10 GB)

Important note about 32-bit operating systems

It is recommended that you install 64-bit version of raspberry pi OS, as it is tested natively via our CI systems. 32 bit version is obsolete and is no longer officially supported. But if you want to stay 32 bits, note that on debian modern docker images may fail to start, although we try to fix that bug in our setup scripts.

Setup

We won't provide the details of how to install OS on your RPI, but raspbian should work fine. Check those guides for getting started and downloading an OS image

Open a terminal on your RPI if you have connected a display to it, or ssh to your RPI.

Start a root shell: sudo su -

Upgrade your system, install firewall and secure your pi from unnecessary ssh spam:

apt update && apt upgrade -y && apt autoremove
apt install -y ufw fail2ban git
sudo ufw allow from 192.168.1.0/24 to any port 22
ufw allow 80, 443
ufw status
ufw enable

You should replace 192.168.1.0/24 with your own subnet. This is to allow ssh connections only from your local network. You may not need it.

Clone and install Bitcart

git clone https://github.com/bitcart/bitcart-docker
cd bitcart-docker
export BITCART_HOST="raspberrypi.local"
export BITCART_REVERSEPROXY="nginx"
./setup.sh

Ensure that your local computer you'll be accessing your Bitcart from /etc/hosts entry for raspberry pi matches BITCART_HOST. Or instead set BITCART_HOST to your raspberry pi ip address directly.

That's it! You can now access Bitcart store at http://raspberrypi.local, admin at http://raspberrypi.local/admin, api at https://raspberrypi.local/api. For other ways of deployment (your own domain/tor) check docker deployment and tor support

Third-Party Hosting

A third-party host is someone who runs Bitcart instance and enables registration for other users. They might be free (but could accept donations) or with paid access.

Sometimes it's hard for users to deploy a new instance, but they want to try right away. That's what third-party hosts are for.

In general, it's not recommended to use them especially if you plan to scale your business, but it's great for testing.

Our demo at https://admin.bitcart.ai showcases all coins Bitcart supports, but we don't recommend using it for commercial purposes.

There are some hosts ran by others

List of third-party hosts

admin.bsty.business (BTC, BSTY, free)

How do I get added to that list?

You can contact us in one of our communities. Your server should have enabled server registration in server management settings.

What are the limitations of this?

The only limitation is that you won't be able to access server management pages. Other than that, it's pretty much the same unless server owner has forked Bitcart. Check this guide for details on server management settings.

Is it safe?

Well, in most cases yes, but you should be aware of scams! People might fork Bitcart and customize it to be malicious. We never intercept the payment process and never require a private key (except for lightning network). Also, watch your wallet to check if the host replaced your public key with their own! Some public hosts also handle a lot of customers of different services, so if you self-host one yours won't be that loaded.

Your first invoice

Registering on an instance

The first step in setting up your Bitcart instance is creating a user account. The first created account on a newly-deployed Bitcart instance is automatically - admin.

To register, visit your Bitcart URL and fill in the account registration form. Input your password, password confirmation, e-mail and click "Register". You will automatically be logged in.

Creating a wallet

Inside Bitcart, you can setup and manage an unlimited number of wallets. Each wallet has its own xpub (BTC-based blockchains) or a single wallet address (ETH-based blockchains), and currency. One wallet holds one currency.

Bitcart is a non-custodial software, which means that all the funds received to your store, will end up directly into your connected wallet.

You need to have your blockchain wallets created beforehand to specify their details in Bitcart! (more on this below)

Creating a wallet for Bitcoin-based blockchains (BTC)

To manage the funds received to your Bitcart wallet, you can use an external wallet.

We recommend that you use the wallet which:

Allows connection to a full node
Allows custom gap limit

Creating a wallet for ETH-based blockchains (ETH, BSC)

You can use any ETH-compatible wallets (e.g. MetaMask, or Mycellium) to create your ETH or BSC wallets. Copy-paste your wallet address from wallet software to Bitcart into "Wallet / Xpub" input.

Creating a wallet in Bitcart UI

To setup wallets, make sure you're logged in into your account, and go to > Wallets by clicking Details button on the card. Click on the create wallet button and fill in the wallet name, currency(optional, default btc) and xpub (or wallet address for ETH-based blockchains).

Create a store

Inside Bitcart, you can create and manage an unlimited number of stores. Each store has its own wallet or wallets (it allows multicurrency checkout), can create products, invoices or be connected with external e-commerce software through one of the integrations.

To create a store, make sure you're logged in into your account, and go to > Stores page by clicking on Details in it's card. Click on the New Store button. Enter the store name, and select this store's wallets.

Customizing your Bitcart Store Settings

You can always edit your store by clicking the edit icon.

To configure email servers, click on email icon in actions column.

Creating your invoice

You can create your invoice in a variety of different ways

Via admin panel UI

This method is one of the most obvious. You can create invoices from the panel, manage your orders and send links to checkout pages to your customers. Click on the show button in the payment methods column to view the checkout page.

Via store POS

Via our e-commerce integrations

Depending on the CMS you're using, you can easily connect Bitcart to your online store. Currently, Bitcart offers following integrations :

Join our community!

That's it, your first invoice was created with ease!

Electrum wallet

This document explains how to connect a desktop Electrum Wallet to Bitcart.

Electrum wallet is recommended, as Bitcart is tightly integrated with it, providing the best user experience and speed.

Register an account in your Bitcart instance
Download and install Electrum Wallet

Electrum Wallet Setup

After the installation, open Electrum Wallet by clicking on the icon on your desktop.

Quick Setup

Create a new Electrum Wallet
In Electrum, Wallet > Information - copy the Master Public Key.
In Bitcart, Wallets > Create wallet > Paste the Extended Public Key in xpub field

Step by Step

The following setup guides you through setting up an entirely new Bech32 (SegWit) Wallet in Electrum. If you already have a wallet skip to the Extended Public Key copying.

Firstly, give your wallet a name, for example, Bitcart Wallet and click Next.

Choose Standard wallet and proceed by clicking the Nextbutton.

Since we're creating a brand-new wallet,choose Create a new seed and Next

From the multiple choice menu, select SegWit and Next

IMPORTANT NOTE: If you're a merchant, instead of SegWit (Bech32), it's recommended to use SegWit wrapped (P2SH) format. This guide explains how to create P2SH wallet in Electrum that's more suited for merchants, due to compatibility with legacy wallets customers use.

IMPORTANT NOTE 2: Write down your recovery words in the order you see them on the screen. Write them down a piece of paper and store it somewhere secure. Take your time and triple check each word. Do not store your seed in a digital format (photograph, text document). Whoever has the access to your seed can access your funds. Confirm that the seed has been properly backed up by re-entering it in the same order. Once the seed is validated, proceed to the next step.

It's highly recommended that you encrypt your wallet. Select a password that you can easily remember and mark make sure Encrypt Wallet File is marked. Proceed by clicking Next.

When the wallet loads (it may take few moments), in the top menu, click on the Wallet and thenInformation .

Select and copy the Master Public Key. This is the public key from which Bitcart will derive addresses.

Return to your Bitcart. Click on the Details button in the Wallets card and click on the New Wallet button. Enter your wallet name and Paste the Master Public Key from electrum to xpub field. Click Save.

Configuring the Gap Limit in Electrum

In the top menu, click on the View and thenShow Console .

Enter following commands in Electrum console and press enter on your keyboard.

 wallet.change_gap_limit(100)

If you are running a version older than Electrum 4, also enter the following command and press enter

wallet.storage.write()

Restart your Electrum and verify that the newly set gap limit is correct by entering in the console:

wallet.gap_limit

There's no good answer to how much you should set the gap limit to. Most merchants set 100-200. If you're a big merchants with high transaction volume, you can try with even higher gap limit.

For more details about the Gap Limit, check the FAQ.

Electrum and Bitcart are now connected. Any payments received to your Bitcart will be visible in Electrum, where you can further spend them.

Guides

ETH payments plugin

ETH payments plugin allows to improve payments UX of ETH-based coins (currently ETH, TRX, BNB, POL) and all their tokens (USDT, USDC and more on those chains) by disabling address prompt and accepting payments from exchanges. This allows you to boost your sales massively as this plugin allows you to accept all currencies Bitcart supports + ETH-based coins with the best UX possible while still remaining non-custodial, with minimum security risks and by saving on network fees (using just 1 transfer instead of the usual 2 to withdraw tokens from your pool addresses)

Users guide

Purchase

First of all, to buy the plugin, ensure you are running Bitcart v0.9.0.0 or later

Open your plugins page and click on purchase button:

After that you will be able to choose monthly or yearly billing.

Ensure the email address you enter is not a disposable one, it will be used to send you license key, billing invoices and plugin updates

If you have any issues with payment, please contact us at hello@bitcart.ai or in official community groups.

Activation

After successful payment you will receive an email with your license key and plugin download URL. There is no need to download the plugin unless you have some custom setup, everything can be done in admin panel UI.

Next, head to plugins page and enter your license key there

After you have added the key, purchase button will turn into install button. Just press it to install the plugin.

Don't forget to click the reload plugins button to apply changes. It will take a few minutes for plugin to build as it applies updates to the admin panel which take more time to build.

Wallets setup

After that, address prompt should be removed automatically. If after 10+ minutes it doesn't disappear, please contact us

Native coins

For native coins (like ETH, TRX and others), when payment is received to the wallet pool address, it is sent to your primary address automatically, because when we have a native coin on address, we can just send all of it minus network fees to the primary address.

Tokens

For tokens (like USDT, USDC and others), it can't send payment to your primary address without paying network fees. As for tokens it is needed to pay network fee in native coin, and wallet pool addresses don't have it, that's why it is needed.

That's where the plugin shines in, it allows us to cut network fees by using only 1 transfer instead of 2.

First, you need to create a fresh wallet, which will be used only for paying network fees. Ensure to not deposit too much to it, as this is the only private key that is inserted into the system and has higher risks of being compromised if e.g. the server gets hacked. But your primary wallet is always safe as you just enter it's address.

Let's create a fresh wallet in let's say, trust wallet:

You can use the seed directly, or if you really want to have a private key specifically, you can do it for example with Bitcart cli by running this on server:

Note the space before the command. This is used to not save the seed into bash history.

Coin is eth, trx etc.

Managing wallet pool

The plugin adds a new page for wallets: address pool management. It is accessible by clicking an icon near any of your eth-based wallets.

This page is another key feature of the plugin: you can view all your addresses used in invoices from one page

Status has the following values:

Free - ready to be re-used in upcoming invoices
In invoice - attached to a currently active invoice. It is freed when invoice gets either expired or paid
Pending payout - invoice with this address was paid, so it will be attempted to do a withdrawal. Actual withdrawal will happen only if it meets min withdrawal and network fee criteria, and for tokens, if fee private key was set and has enough balance
In payout - payout is being performed right now

Init Status indicates whether the fee wallet is authorized to send payments to your primary wallet from this pool's address in just 1 transfer:

Uninitialized - address is new and hasn't been set up yet. Ensure you have your fee private key set and that fee wallet has balance
Initializing - address is in the process of being initialized
Initialized - address is fully set up and ready to use. For non-token payments, this is always the case as no fee wallet is required.

If needed, you can trigger withdrawal manually if you click on withdraw button. Also batch withdraw and delete actions are available.

Troubleshooting

If you want to view debug logs of the plugin, click on profile icon->server management->policies

And enable the debug checkbox near eth_payments plugin:

You will then be able to view debug logs in server logs of your instance.

FAQ

What makes the plugin worth it? How is it any different from all already existing solutions on the market?

The main difference is that, existing solutions are custodial and they store all information about your payments, customers and anything else they can get. Also custodial means money gets sent from your customers to their intermediate addresses, and only then sent to you. Which means if they want they can lock you out of your funds.

Bitcart on the other hand, operates by accepting payments directly to your wallet. Private key is never required either. For plugin to work it does require generating unique deposit addresses, but private keys for all addresses in your wallet pool are stored in your local database and not stored anywhere else. Which means, even in worst case you always have private keys to withdraw the funds, and the plugin automatically sends payments from pool addresses to your primary address without any manual intervention.

Also as everything is hosted on your own server, you have full control over your data: order information is never shared with anyone, everything is stored on your server only.

And another key feature is: when sending tokens from pool addresses where no native coin is present, the usual flow is 2 transfers: first, estimate the approximate amount of network fee needed for a token transfer, and send that to the pool address, wait for some time when it gets confirmed, and then send the tokens.

The plugin on the other hand requires only 1 transfer: if pool address is initialized, the fee wallet is able to send tokens from pool address to your primary address utilizing it's native coins, avoiding the second transfer. This makes it way more reliable and allows to save on network fees.

Which information does the plugin collect?

The plugin collects minimal information possible for accurate billing and abuse control:

Monthly volume done by using the plugin only (this is sent as a dictionary where key is invoice currency, value is total). No order information leaves your server, plugin uses database query to collect aggregate numbers only and send to license server for accurate billing
Plugin version
Machine ip + machine id. Used for abuse control, by default only 1 server can use the plugin at the same time. If you switch servers, wait 6 hours for the old plugin to stop sending license checks, then a new server can be switched to automatically. If you need it faster contact us and we'll reset machine binding

What is monthly volume and how is it determined?

The plugin collects aggregate sum of paid invoices where payment method used is created by the plugin (so ETH-based coins only, coins untouched by the plugin are not billed) over the last month

The information is sent to license server where it uses it's exchange rates to combine it into one final USD amount.

If I pick yearly billing, am I still billed for volume?

Yes, but only if you exceed the monthly 2000$ unbilled volume. The plugin price itself will be billed once a year, and each month where you do exceed the thresold, you will be billed only on the excess amount.

How do you charge fees? Is it still non-custodial?

Yes, we don't intervene in your invoice generation or payouts at all. Everything is processed by your server. At the end of the month (your billing period), you will receive an email with bitcart invoice to pay. It is calculated based on your billing cycle and monthly volume stat. You have 7 days to pay the invoice until the plugin gets deactivated. If it does, you have to contact us and we can re-issue the invoice

Bitcart Plugins Development

Creating a New Plugin

Bitcart plugins are modular components that can extend the functionality of your Bitcart instance. A plugin can consist of one or more of the following components:

Backend: Server-side logic, database models, and API endpoints
Admin: Extensions to the admin panel UI
Store: Customizations for the store frontend
Docker: Docker compose deploy customizations

This will guide you through creating a new plugin by asking for:

Plugin name
Author
Description
Component types to include

To install plugin to develop alongside bitcart, you can use bitcart-cli plugin install .

It is recommended to pass --dev flag to install plugin in development mode. It uses symlinks to link the plugin to the bitcart source code, so when you make changes to the plugin, they are reflected immediately.

It asks for paths where you cloned bitcart, bitcart-admin and other repositories. You can pass --save flag to save paths to config, so that it is never asked again.

After you are done developing and want to remove it from codebase:

Backend Plugin Development

Plugin Structure

A backend plugin must have a plugin.py file which as a Plugin class that implements the BasePlugin class from api.plugins. The basic structure is:

Database Models

To add custom database tables:

Create a models.py file in your plugin directory
Define SQLAlchemy models
Manage migrations using alembic:

Basically same commands as alembic, but you provide your plugin name.

This will create a new migration in the versions/ directory. Migrations are automatically applied when the plugin is loaded.

Hooks and Filters

Bitcart provides two extension mechanisms:

Hooks: Execute actions at specific points
Filters: Modify data as it flows through the system

To find hooks and filters, you can search the codebase for apply_filters and run_hook.

For example, db_modify_wallet would be called right after wallet is saved in db.

So you can use it like this:

And in filters first argument you receive is the value which you can return unmodified or modify. Other arguments are optional data

Example:

Plugin Settings

To add custom settings for your plugin:

Settings are automatically available in the admin panel and can be accessed via:

Dependencies

If you need to add backend dependencies, create a requirements.txt file in your plugin directory, it will be installed automatically.

Frontend Plugin Development

Admin Panel Extensions

Extending the UI

Add custom routes in routes.js:

Add dependencies to package.json

Store Extensions

Store plugins follow a similar structure to admin plugins but are specifically for the store frontend. They can:

Add custom pages
Extend existing components
Add new payment methods
Customize the checkout process

Plugin Packaging

To package your plugin:

This creates a .bitcart file that can be installed on any Bitcart instance.

Best Practices

Use descriptive names for hooks and filters
Document your plugin's requirements and dependencies
Handle errors gracefully
Clean up resources in the shutdown method
Follow the existing code style
Test your plugin thoroughly before distribution

Plugin Lifecycle

Plugin discovery and loading
Database migrations
Plugin initialization (startup)
Hook/filter registration
Settings registration
UI component registration (if applicable)
Background worker setup (if needed)
Shutdown cleanup on server stop

Default nodes/your own node

You may have a question: which servers does Bitcart use by default? It depends on the coin!

Default nodes

BTC-based coins

If using BTC-based coins where we use Electrum or it's forks, it is connected to a network of electrumx/fulcrum servers, which are indexers of the blockchain. It connects to multiple servers, verifying with SPV (Simple Payment Verification) that the results acquired are valid. It is reliable enough and can handle any load. This is the same list you would see if you downloaded Electrum wallet yourself and connected to the network

Other coins (ETH-based, TRX, XMR)

For other coins we don't have something like electrum existing, and we also don't have a network of blockchain indexers.

That's why for those coins Bitcart daemons require at least 1 full node RPC to be configured. In coins like ETH free RPCs are widespread and have good rate limits. So the defaults will always use some free RPCs which should be good enough for Bitcart to run

New since Bitcart v0.9.0.0: it is now possible to use multiple nodes, so if one RPC fails, it will use the next one in the list and so on, allowing to specify as many servers as possible, archieving unbreakable stability

Defaults are usually set in docker compose components.

NOTE: Since Bitcart v0.9.0.0, seed server feature was launched. Servers are no longer hardcoded in yml files, so in case some RPC breaks, users won't need to update each of their instances, we can edit it in the seed server and the daemon will update links at maximum in 1 hour. This is the default behaviour inside docker deployments now. To disable it, set COIN_SERVER to some specific server, just as it was done before.

If you want to view the current list of servers used for each specific coin, you can call seed server directly, for example:

Your own node

BTC-based coins

Then you can point Bitcart to it via COIN_SERVER. You can force to connect to only your server and not others via COIN_ONESERVER.

Other coins (ETH-based, TRX, XMR)

Just run the full node of the coin you selected, and then set COIN_SERVER to the RPC url of your node.

One domain mode

One domain mode is an opt-out feature, enabled by default, which simplifies the configuration of domains.One domain mode allows running all Bitcart services under one domain.

If you are deploying a new instance from the Bitcart Configurator, it is the default mode enabled.

But this was not always the case, one domain mode was added in Bitcart version 0.3.0.0.

You only need to set one environment variable to run Bitcart: BITCART_HOST.

All the services will run either under the root domain, or the suburls on that domain.

One domain mode is enabled, when the following settings are unset:

BITCART_ADMIN_HOST
BITCART_ADMIN_URL
BITCART_STORE_HOST
BITCART_STORE_URL

Depending on the configuration, the service that will run on the root domain is selected in the following order (if available): store, admin, api.

So, if all 3 components are enabled, and BITCART_HOST is bitcart.mydomain.com, then:

The store will run at https://bitcart.mydomain.com
The admin will run at https://bitcart.mydomain.com/admin
The Merchants API will run at https://bitcart.mydomain.com/api

Or, if only the Merchants API is enabled, then it will run right at https://bitcart.mydomain.com.

Why is "one domain mode" there, and it is not the only possible configuration variable?

Because despite having the easy-to-use one-domain mode, we also support advanced use cases.

For example, you may need to run Merchants API on one server, and admin and store on another one.

It is completely possible.

On one server (with api), you would run:

And on another one (with admin and store), you would run:

Backups

Bitcart supports backing up it's data on one server and restoring it on another.

It is available via both UI and terminal.

Backups management from admin panel

To enter backups management page, go to profile->server management->backups

From there you can start a backup right away, it uses settings from this page to do it.

Backup settings

You can select which backup provider to use. All of them, except for local, require setting environment variables as you can see on the screen above.

Local

Local provider just saves the backup on your current machine.

It is saved to /var/lib/docker/volumes/backup_datadir/_data/

Backups are named YYYYMMDD-HHMMSS-backup.tar.gz

SCP

SCP provider copies the file from your server to SCP_TARGET and deletes backup locally

Required settings:

SCP_TARGET: for example username@ip/where/to/put/backups

S3

S3 provider sends your file to amazon S3 and then deletes it locally

Required settings:

S3_BUCKET: in which bucket to save the backup
S3_PATH: where exactly in the bucket to save the backup

Scheduling backups

It is possible schedule backups to run automatically.

For backups to work, your settings must be valid (otherwise it will just fail every time), and you need to tick the scheduled backups checkbox. The timer will be saved even after server restarts.

Settings are saved automatically, and if you had existing schedule configured and change frequency/turn off and then on again backups, the timer will be reset

We assume that daily is exactly every day, weekly is every 7 days, monthly is every 30 days

Restoring backups

Restoring backups is as easy as just uploading backup file to your instance!

Backups management from terminal

Creating backups

Backup settings are configured via environment variables

If you need to run backup for scp provider, you would run:

Restoring backups

Assuming that your file is named backup.tar.gz, just run:

Lightning Network

Lightning network support is experimental, as the lightning network itself.

Process with caution, and don't put large amounts in your lightning channels.

Before enabling lightning, please read all the warnings.

Lightning network in Bitcart is supported via Electrum's lightning network implementation

It has some limitations, please read the most up-to-date version at your admin panel.

To enable lightning network, for each coin, run:

Where COIN is coin symbol (i.e. BTC, LTC)

Note that it will utilize a bit more server resources, but not by much.

When enabled, you will be able to enable lightning on the wallets page.

Currently lightning is only supported in the native segwit wallets.

When opening a non-supported wallet (or if lightning is disabled in the daemon), you will see the following page:

If lightning is supported, by clicking on the lightning icon and accepting all warnings, it will be enabled for the wallet.

If lightning is enabled for a wallet, then, along with the regular coin payment method, a lightning one will be created.

As your Bitcart daemons are standalone lightning nodes, you will need to open lightning channels from scratch. You can use the lightning management page for this

Lightning management

From the lightning management page, you will see your lightning balance, your node id, list of open channels, and you will be able to close, force-close or open new channels.

You can also pay lightning invoices from that page via your node.

Lightning checkout

From the checkout page, customers will be able to scan either the lightning invoice, or your node id.

That way they can open a channel with you

Transaction speed

What does transaction speed mean?

First of all, transaction speed applies only to on-chain invoices. All lightning invoices are instantly marked as complete.

To understand why transaction speed setting is needed, you need to understand the invoice statuses in Bitcart:

When invoice has just been created, it has pending status.

If no payment has been sent within the invoice time frame (expiration time), invoice is marked expired. Expired invoices no longer listen for incoming payments, but you may manually mark it complete.

If a payment has been sent within the invoice time frame (expiration time), invoice status is set to paid.

With paid status, customer is redirected to the redirect URL, and checkout page shows paid. But all the notifications, emails and custom scripts aren't executed yet.

When payment has been confirmed (has >= 1 confirmations), invoice status is set to confirmed.

When payment's number of confirmations is >= transaction speed, invoice status is set to complete, and all the postorder actions are executed (like notifications).

So, transaction speed controls how fast you want your invoice to be complete. Default value of 0 provides the fastest checkout, but it is not always good for your use case, it might be not safe.

Value of 1 means waiting for one confirmation, which is enough in most cases.

You can set transaction speed to any value between 0 and 6 (there is no point in waiting past 6 confirmations).