## Requirements

```
Ruby >= 3
```

## Installation

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

```
bundle add blockbee
```

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

```
gem install blockbee
```

[RubyGem Page](https://rubygems.org/gems/blockbee/)

## 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_url, 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_url`` is the URL that will be called upon payment.
* ``api_key`` is the API Key provided by BlockBee's [dashboard](https://dash.blockbee.io/).
* ``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_url, 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_url, 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](https://support.blockbee.io/article/how-the-priority-parameter-works) 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_url, 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](https://dash.blockbee.io/).
* ``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](https://dash.blockbee.io/).

#### 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](https://dash.blockbee.io/).
* ``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](https://dash.blockbee.io/).

#### 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](https://docs.blockbee.io/#tag/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](https://dash.blockbee.io/).
* ``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](https://dash.blockbee.io/).
* ``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](https://dash.blockbee.io/).
* ``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
```

2. 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
```

3. 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/