BlockBee's Ruby Library

View as Markdown

Requirements

text
Ruby >= 3

Installation

Install the gem and add to the application's Gemfile by executing:

text
bundle add blockbee

If bundler is not being used to manage dependencies, install the gem by executing:

text
gem install blockbee

RubyGem Page

API and utils

Importing in your project file

Ruby
require 'blockbee'

Get information (service of regarding a cryptocurrency)

Ruby
require 'blockbee'

info = BlockBee::API.get_info(coin, prices)

# or if you wish to get full BlockBee service information

info = BlockBee::API.get_info(nil, prices)

Where

  • coin is the coin you wish to use, from BlockBee's supported currencies (e.g 'btc', 'eth', 'erc20_usdt', ...).
  • prices by default 0. If 1 will return the prices of the cryptocurrencies converted to all supported FIAT currencies.

Generating a new Address

Ruby
require 'blockbee'

blockbee_helper = BlockBee::API.new(coin, callback, api_key, own_address: own_address, parameters: parameters, bb_params: bb_params)

address = blockbee_helper.get_address

# or address['address_in'] if you just wish the address string

Where:

  • coin is the coin you wish to use, from BlockBee's supported currencies (e.g 'btc', 'eth', 'erc20_usdt', ...).
  • callback is the URL that will be called upon payment.
  • api_key is the API Key provided by BlockBee's dashboard.
  • own_address (optional) is your own crypto address, where your funds will be sent to.
  • parameters (optional) is any parameter you wish to send to identify the payment, such as {orderId: 1234}.
  • bb_params (optional) parameters that will be passed to BlockBee _(check which extra parameters are available here: https://docs.blockbee.io/#operation/create).

Response sample:

JSON
{
  "status": "success",
  "address_in": "0xe10818d4037B7C427109dFbCFC2c8757c0352FE8",
  "address_out": "0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d",
  "callback_url": "https://webhook.site/ef8e2859-12a9-4028-8a94-51582e83dd05?order_id=13435",
  "minimum_transaction_coin": "1.00000000",
  "priority": "default",
  "multi_token": true
}

Getting notified when the user pays

Once your customer makes a payment, BlockBee will send a callback to your callbackUrl. This callback information is by default in GET but you can se it to POST by setting post => 1 in bb_params. The parameters sent by BlockBee in this callback can be consulted here: https://docs.blockbee.io/#operation/confirmedcallbackget

Checking the logs of a request

Ruby
require 'blockbee'

blockbee_helper = BlockBee::API.new(coin, callback, api_key, own_address: own_address, parameters: parameters, bb_params: bb_params)

logs = blockbee_helper.get_logs

Same parameters as before, the data returned can b e checked here: https://docs.blockbee.io/#operation/logs

Response sample:

JSON
{
  "status": "success",
  "callback_url": "https://example.com/?order_id=1235",
  "address_in": "0x58e90D31530A5566dA97e34205730323873eb88B",
  "address_out": "0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d",
  "notify_pending": false,
  "notify_confirmations": 1,
  "priority": "default",
  "callbacks": []
}

Generating a QR code

Ruby
require 'blockbee'

blockbee_helper = BlockBee::API.new(coin, callback, api_key, own_address: own_address, parameters: parameters, bb_params: bb_params)

qrcode = blockbee_helper.get_qrcode(value: value, size: size)

Where:

  • value is the value requested to the user in the coin to which the request was done. Optional, can be empty if you don't wish to add the value to the QR Code.
  • size Size of the QR Code image in pixels. Optional, leave empty to use the default size of 300.

Response is an object with qr_code (base64 encoded image data) and payment_uri (the value encoded in the QR), see https://docs.blockbee.io/#operation/qrcode for more information.

Response sample:

JSON
{
  "status": "success",
  "qr_code": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAIAAAD2HxkiAAAYeklEQVR4nO3daZQdZZkH8Od5q+quvXenO3tCQtg3WQLDOiwi4FEGRA96RhkRlEUd9cw5Ojif/DTOHEcF4YAwntFRhBEHBPWoKAECGNnXSICQBEL23m/fvkvV+8yHut3pEPoSaop6qjv/3wcOSbrurVv3/vutW8/7vMUiQgCgx2jvAMD+DiEEUIYQAihDCAGUIYQAyhBCAGUIIYAyhBBAmdvk35g5sf2IS4S5BxFe5nTPEu8Ri3ceRYwvM9qjRXiWBJ49MU1eJkZCAGUIIYAyhBBAGUIIoAwhBFCGEAIoQwgBlDWrE05HvQ9YvRw33Q4kU1iL9mjxvmsxVkqbbBJhn2fihxMjIYAyhBBAGUIIoAwhBFCGEAIoQwgBlCGEAMoQQgBlUYr1Tej2ekajXvieTmrbcJs8UYQdSPMbPZ149xkjIYAyhBBAGUIIoAwhBFCGEAIoQwgBlCGEAMpYruhPuZ9Ltdu4y6NF66lNZsVk9Q7dZGwkBlCGEAMoQQgBlCCGAMoQQQBlCCKAMIQRQhhACKEMIAZQ1K9bHWERWr0cnc6vgNL/MmUh9efhkjidGQgBlCCGAMoQQQBlCCKAMIQRQhhACKEMIAZRFaepNs2QaNONtEdZtOFbvqY33oWbiYtYYCQGUIYQAyhBCAGUIIYAyhBBAGUIIoAwhBFCGEAIoa1asn85MbF1NtxYegXpFOALsWDI3fsZICKAMIQRQhhACKEMIAZQhhADKEEIAZQghgDKEEEBZlGJ9EzEWvhMryMa4Ane8dX/1lQ1wBCKIUN/HSAigDCEEUIYQAihDCAGUIYQAyhBCAGUIIYCymOuEqZXMms2JLbOdTAEt3lJtjHXYeMV7MCPsM0ZCAGUIIYAyhBBAGUIIoAwhBFCGEAIoQwgBlCGEAMr2l2J9vOItIiezzHMyNxKPMMFA/QbX6guNYyQEUIYQAihDCAGUIYQAyhBCAGUIIYAyhBBAGSdT2IlXMh26EUQ7MjGW49K8Wm4yTb3qtU0s/gsw8yCEAMoQQgBlCCGAMoQQQBlCCKAMIQRQhhACKItSrE8z3fKuet05AvVVw5PpkI79iWKEkRBAGUIIoAwhBFCGEAIoQwgBlCGEAMoQQgBlzeqEAJAAjIQAyhBCAGUIIYAyhBBAGUIIoAwhBFCGEAIoQwgBlP0fDDJ0PYOZxyEAAAAASUVORK5CYII=",
  "payment_uri": "0x0E945b1554c8029A6B9bE1F7A24ae75d2F44d8DB"
}

Usage

html.erb
<img src={"data:image/png;base64,#{qr_code}"}/>

Estimating transaction fees

Ruby
require 'blockbee'

estimation = BlockBee::API.get_estimate(coin, addresses, priority)

Where:

  • coin is the coin you wish to check, from BlockBee's supported currencies (e.g 'btc', 'eth', 'erc20_usdt', ...)
  • addresses The number of addresses to forward the funds to. Optional, defaults to 1.
  • priority Confirmation priority, (check this article to learn more about it). Optional, defaults to default.

Response is an object with estimated_cost and estimated_cost_usd, see https://docs.blockbee.io/#operation/estimate for more information.

Response sample:

JSON
{
  "status": "success",
  "estimated_cost": "0.00637010",
  "estimated_cost_currency": {
    "AED": "0.03",
    "AUD": "0.01",
    "BGN": "0.01",
    "BRL": "0.04"
  }
}

Converting between coins and fiat

Ruby
require 'blockbee'

blockbee_helper = BlockBee::API.new(coin, callback, api_key, own_address: own_address, parameters: parameters, bb_params: bb_params)

conversion = blockbee_helper.get_conversion(from_coin, value)

Where:

  • value value to convert in from.
  • from_coin currency to convert from, FIAT or crypto.

Response is an object with value_coin and exchange_rate, see https://docs.blockbee.io/#operation/convert for more information.

Response sample:

JSON
{
  "status": "success",
  "value_coin": "241.126",
  "exchange_rate": "0.803753"
}

Getting supported coins

Ruby
require 'blockbee'

supported_coins = BlockBee::API.get_supported_coins

Response is an array with all supported coins.

Response sample:

JSON
{
  "btc": {
    "coin": "Bitcoin",
    "logo": "https://api.cryptapi.io/media/token_logos/btc.png",
    "ticker": "btc",
    "minimum_transaction": 8000,
    "minimum_transaction_coin": "0.00008000",
    "minimum_fee": 546,
    "minimum_fee_coin": "0.00000546",
    "fee_percent": "1.000",
    "network_fee_estimation": "0.00002518"
  },
  "bch": {
    "coin": "Bitcoin Cash",
    "logo": "https://api.cryptapi.io/media/token_logos/bch.png",
    "ticker": "bch",
    "minimum_transaction": 50000,
    "minimum_transaction_coin": "0.00050000",
    "minimum_fee": 546,
    "minimum_fee_coin": "0.00000546",
    "fee_percent": "1.000",
    "network_fee_estimation": "0.00000305"
  }
}

Checkout

Requesting Payment

Ruby
require 'blockbee'

blockbee_helper = BlockBee::Checkout.new(notify_url: NOTIFY_URL, api_key: API_KEY, parameters: {
  'order_id': 2022
}, bb_params: {
  'post' => 1
})

payment_page = blockbee_helper.payment_request(redirect_url, value)

Where:

  • api_key is the API Key provided by our Dashboard.
  • parameters is any parameter you wish to send to identify the payment, such as {'order_id': 1234}.
  • bb_params parameters that will be passed to BlockBee _(check which extra parameters are available here: https://docs.blockbee.io/#operation/create).
  • redirect_url URL in your platform, where the user will be redirected to following the payment. Should be able to process the payment using the success_token.
  • notify_url URL in your platform, where the IPN will be sent notifying that a payment was completed. Parameters are available here: https://docs.blockbee.io/#operation/paymentipn.
  • value amount in currency set in Payment Settings you want to receive from the user.

Getting notified when the user completes the Payment

When receiving payments, you have the option to receive them in either the notify_url or the redirect_url, but adding the redirect_url is required (refer to our documentation at https://docs.blockbee.io/#operation/paymentipn).

Payment samples:

JSON
{
  "status": "success",
  "success_token": "G4asA2xwEr0UeY2IZqlZjX3IYrNofmnIAkzHPAoxmpmlYP9ZLTvQUolKN0X27Z0B",
  "payment_url": "https://pay.blockbee.io/payment/OcRrZGsKQFGsoi0asqZkr97WbitMxFMb/",
  "payment_id": "OcRrZGsKQFGsoi0asqZkr97WbitMxFMb"
}

Payment Logs

Fetch Payment information and IPN logs.

Ruby
require 'blockbee'

logs = BlockBee::Checkout.payment_logs(token, api_key)

Where:

  • token is the payment_id returned by the payment creation endpoint.
  • api_key is the API Key provided by BlockBee's dashboard.

Response sample:

JSON
{
  "status": "success",
  "is_paid": false,
  "is_pending": false,
  "is_expired": false,
  "is_partial": false,
  "payment_data": [
    {
      "value": "0.000137",
      "value_paid": "0",
      "value_outstanding": "0.000137",
      "exchange_rate": "0.0000137489",
      "coin": "btc",
      "txid": []
    }
  ],
  "notifications": []
}

Requesting Deposit

Ruby
require 'blockbee'

blockbee_helper = BlockBee::Checkout.new(notify_url: NOTIFY_URL, api_key: API_KEY, parameters: {
  'order_id': 2022
}, bb_params: {
  'post' => 1
})

deposit_page = blockbee_helper.deposit_request

Where:

  • api_key is the API Key provided by our Dashboard.
  • parameters is any parameter you wish to send to identify the payment, such as {'order_id': 1234}.
  • bb_params parameters that will be passed to BlockBee (check which extra parameters are available here: https://docs.blockbee.io/#operation/deposit).
  • notify_url URL in your platform, where the IPN will be sent notifying that a deposit was done. Parameters are available here: https://docs.blockbee.io/#operation/depositipn.

Response sample:

JSON
{
  "status": "success",
  "payment_url": "https://pay.blockbee.io/deposit/jv12du8IWqS96WVDjZK2J285WOBOBycc/",
  "payment_id": "jv12du8IWqS96WVDjZK2J285WOBOBycc"
}

Deposit Logs

Fetch Deposit information and IPN logs.

Ruby
require 'blockbee'

logs = BlockBee::Checkout.deposit_logs(token, api_key)

Where:

  • token is the payment_id returned by the deposit creation endpoint.
  • api_key is the API Key provided by BlockBee's dashboard.

Response sample:

JSON
{
  "status": "success",
  "deposits": [],
  "total_deposited": "0",
  "currency": "USDT",
  "notifications": []
}

Payouts

Create Payout / Payout Request

This function can be used by you to create Payouts.

Ruby
require 'blockbee'

coin = 'polygon_matic'

requests = {
    '0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d' => 0.5,
    '0x18B211A1Ba5880C7d62C250B6441C2400d588589' => 0.1
}

create_payout = BlockBee::API.create_payout(coin, payout_requests, api_key, process)

Where:

  • coin The cryptocurrency you want to request the Payout in (e.g btc, eth, erc20_usdt, ...).
  • requests Address(es) together with the amount that must be sent.
  • api_key is the API Key provided by BlockBee's dashboard.
  • process If the Payout Requests will be sent right away. Defaults to False. Note: if True will instantly queue the payouts to be sent to the destination addresses.

Response sample:

If process is false.

JSON
{
  "status": "success",
  "request_ids": [
    "3825d29b-7a8f-47da-8623-e99850674247",
    "d9925105-ea5f-4661-8d01-505096212ac5"
  ]
}

If process is true.

JSON
{
  "status": "success",
  "payout_info": {
    "id": "d9219d07-a8e5-4d89-a869-3c5717a25b27",
    "status": "Created",
    "from": "",
    "requests": {
      "0xA8EbeD50f2e05fB4a25b2DdCdc651A7CA769B5CF": "0.300000000000000000",
      "0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d": "0.200000000000000000"
    },
    "total_requested": "0.5",
    "total_with_fee": "0.505",
    "total_fiat": "",
    "fee": "0.005",
    "coin": "bep20_usdt",
    "txid": "",
    "timestamp": "05/03/2024 15:00:00"
  },
  "queued": true
}

List Payouts / Payout Requests

List all Payouts or Payout Requests in your account.

Note: If requests is True it will fetch a Payout Requests list.

Ruby
require 'blockbee'

list_payouts = BlockBee::API.list_payouts(coin, status, page, api_key, payout_request)

Where:

  • coin The cryptocurrency you want to request the lists in (e.g btc, eth, erc20_usdt, ...).
  • status The status of the Payout / Payout Request. Possible statuses are:
    • Payout Request: [all, pending, rejected, processing, done]
    • Payout: [created, processing, done, error]
  • page This endpoint is paginated and will show only 50 items per page. Defaults to 1.
  • api_key is the API Key provided by BlockBee's dashboard.
  • payout_request If True will fetch Payout Requests, otherwise will fetch Payouts. Defaults to False.

Response sample:

JSON
{
  "status": "success",
  "payouts": [
    {
      "id": "3825d29b-7a8f-47da-8623-e99850674247",
      "status": "Done",
      "total_requested": "0.6",
      "total_with_fee": "0.606",
      "total_fiat": "",
      "fee": "0.006",
      "coin": "polygon_matic",
      "timestamp": "13/03/2024 17:48:39"
    }
  ],
  "num_pages": 1
}

Get Payout Wallet

Gets your Payout Wallet for the specified coin. Can algo get the balance.

Ruby
require 'blockbee'

wallet = BlockBee::API.get_payout_wallet(coin, api_key, balance)

Where:

  • coin The cryptocurrency you want to request the lists in (e.g btc, eth, erc20_usdt, ...).
  • api_key is the API Key provided by BlockBee's dashboard.
  • balance If True will also fetch the balance of the address.

Response sample:

JSON
{
  "address": "0x18B211A1Ba5880C7d62C250B6441C2400d588589",
  "balance": "2.7"
}

Create Payout with Payout Request ID(s)

With this function you can create a Payout in the created status by simply providing an array with the Payout Requests ID.

Ruby
require 'blockbee'

payout_ids = [52211, 52212]

payout = BlockBee::API.create_payout_by_ids(api_key, payout_ids)

Where:

  • payout_ids its an array with the Payout Requests ID.

Response sample:

JSON
{
  "status": "success",
  "payout_info": {
    "id": "d9219d07-a8e5-4d89-a869-3c5717a25b27",
    "status": "Created",
    "from": "",
    "requests": {
      "0xA8EbeD50f2e05fB4a25b2DdCdc651A7CA769B5CF": "0.300000000000000000",
      "0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d": "0.200000000000000000"
    },
    "total_requested": "0.5",
    "total_with_fee": "0.505",
    "total_fiat": "",
    "fee": "0.005",
    "coin": "bep20_usdt",
    "txid": "",
    "timestamp": "05/03/2024 15:00:00"
  }
}

Process Payout by ID

By default, a Payout when created will be in created state. With this function you may finish it using its ID.

Ruby
require 'blockbee'

payout = BlockBee::API.process_payout(api_key, payout_ids)

Where:

  • payout_ids Its the ID (or multiple ID) of the Payout you wish to fulfill.

Response sample:

JSON
{
  "status": "success",
  "payout_info": {
    "id": "d9219d07-a8e5-4d89-a869-3c5717a25b27",
    "status": "Created",
    "from": "",
    "requests": {
      "0xA8EbeD50f2e05fB4a25b2DdCdc651A7CA769B5CF": "0.300000000000000000",
      "0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d": "0.200000000000000000"
    },
    "total_requested": "0.5",
    "total_with_fee": "0.505",
    "total_fiat": "",
    "fee": "0.005",
    "coin": "bep20_usdt",
    "txid": "",
    "timestamp": "05/03/2024 15:00:00"
  },
  "queued": true
}

Check the Payout status

Will return all important information regarding a Payout, specially its status.

Ruby
require 'blockbee'

payout_id = 51621

status = BlockBee::API.check_payout_status(api_key, payout_id)

Where:

  • payout_id Its the ID of the Payout you wish to check.

Response sample:

JSON
{
  "status": "success",
  "payout_info": {
    "id": "d9219d07-a8e5-4d89-a869-3c5717a25b27",
    "status": "Done",
    "from": "0x18B211A1Ba5880C7d62C250B6441C2400d588589",
    "requests": {
      "0xA6B78B56ee062185E405a1DDDD18cE8fcBC4395d": "0.500000000000000000",
      "0x18B211A1Ba5880C7d62C250B6441C2400d588589": "0.100000000000000000"
    },
    "total_requested": "0.6",
    "total_with_fee": "0.606",
    "total_fiat": "",
    "fee": "0.006",
    "coin": "polygon_matic",
    "txid": "0xf9aa1618a7e460f8c68b6a02369b5058282c53a4ee23f967abef0d35203f328c",
    "timestamp": "13/03/2024 18:10:35"
  }
}

Testing

Option 1: Using .env file (Recommended)

  1. Copy the example environment file:
Bash
cp .env.example .env
  1. Edit .env with your actual API credentials:
Bash
# Required: Your BlockBee API Key from https://dash.blockbee.io/
BLOCKBEE_API_KEY=your-actual-api-key-here

# Required: Callback URL for payment notifications
BLOCKBEE_CALLBACK_URL=https://your-domain.com/webhook
  1. Install dependencies and run tests:
Bash
bundle install
bundle exec rake test

Option 2: Using environment variables

Alternatively, you can set environment variables directly:

Bash
export BLOCKBEE_API_KEY="your-api-key-here"
export BLOCKBEE_CALLBACK_URL="https://your-domain.com/webhook"
bundle exec rake test

Note: If no API key is provided, only basic tests (like version check) will run. The .env file is automatically ignored by git to keep your credentials secure.

Help

Need help? Contact us @ https://blockbee.io/contacts/