@foile/crypto-pay-api: Integrating Cryptocurrency Payments with TON Blockchain

Crypto Pay is a payment system based on @CryptoBot, leveraging the TON Blockchain (The Open Network) to facilitate cryptocurrency transactions through an API. This library assists in interfacing with Crypto Pay via the Crypto Pay API.


To integrate the library, use the following command:

npm i @foile/crypto-pay-api


API Initialization

Firstly, create an application and obtain an API token by sending a /pay command to either @CryptoBot or @CryptoTestnetBot for testnet usage. Then, verify the API functionality by calling the getMe() method:

const { CryptoPay } = require('@foile/crypto-pay-api');
const cryptoPay = new CryptoPay(token);
const app = await cryptoPay.getMe();

Optional parameters such as hostname and protocol can be set as follows:

const cryptoPay = new CryptoPay(token, {
  hostname: 'testnet-pay.crypt.bot',
  protocol: 'https'
Net Bot Hostname
mainnet @CryptoBot pay.crypt.bot
testnet @CryptoTestnetBot testnet-pay.crypt.bot

Note: All queries to the Crypto Pay API must be sent over HTTPS.

Creating Invoices

Invoices can be created with various options, including supported assets and custom button names:

const { CryptoPay, Assets, PaidButtonNames } = require('@foile/crypto-pay-api');

const cryptoPay = new CryptoPay(token);
cryptoPay.createInvoice(Assets.BTC, 1, {
  description: 'kitten',
  paid_btn_name: PaidButtonNames.VIEW_ITEM,
  paid_btn_url: 'http://placekitten.com/150',

Refer to the examples directory for complete code samples.


Webhooks provide real-time updates for the application. It is recommended to use a secret path in the URL for security, e.g., https://www.example.com/<secret>.

const cryptoPay = new CryptoPay(token, {
  webhook: {
    serverHostname: 'localhost',
    serverPort: 4200,
    path: '/secret-path'

cryptoPay.on('invoice_paid', update => console.log(update.payload));

Simpler alias methods are also available for update handling:

cryptoPay.invoicePaid(update => console.log(update.payload));

API Methods

The library provides various methods for interacting with the Crypto Pay API, including but not limited to:

  • getMe(): Retrieves basic app information.
  • createInvoice(asset, amount, options): Creates a new invoice.
  • transfer(user_id, asset, amount, spend_id, options): Sends coins from the app to the user.
  • getInvoices(options): Retrieves invoices of the app.
  • getBalance(): Retrieves the app’s balance.
  • getExchangeRates(): Retrieves exchange rates of supported currencies.
  • getCurrencies(): Retrieves supported currencies.

Update Types

The library supports different update types, such as invoice_paid, to handle various events.


The library provides constants for assets and paid button names for convenience:

Constant Value
Assets.BTC BTC
Assets.TON TON
Assets.ETH ETH
PaidButtonNames.VIEW_ITEM viewItem
PaidButtonNames.OPEN_CHANNEL openChannel
PaidButtonNames.OPEN_BOT openBot
PaidButtonNames.CALLBACK callback

This article provides a comprehensive overview of integrating

cryptocurrency payments using the TON Blockchain with the @foile/crypto-pay-api library.