### Local Installation of B2BinPay API Client

Source: https://github.com/b2binpay/api-php/blob/master/README.md

Perform a local installation of the B2BinPay API client and copy the environment example file.

```bash
composer install --no-dev
cp .env.example .env
```

--------------------------------

### Install B2BinPay API Client with Composer

Source: https://github.com/b2binpay/api-php/blob/master/README.md

Install the B2BinPay API client using Composer by adding it to your project's dependencies.

```shell
composer require b2binpay/api-php
```

--------------------------------

### Run Local PHP Server

Source: https://github.com/b2binpay/api-php/blob/master/examples/README.md

Use this command to start a local development server on port 8000. Ensure you are in the directory containing your PHP files.

```bash
php -S localhost:8000
```

--------------------------------

### Example Bill Creation Response

Source: https://github.com/b2binpay/api-php/blob/master/examples/README.md

This is a sample response object received after successfully creating a bill. It contains details such as the bill ID, payment URL, address, and status.

```json
stdClass Object
(
    [id] => 18205
    [url] => https://gw-test.b2binpay.com/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJCMkJDcnlwdG9QYXkiLCJzdWIiOjE4MjA1LCJpYXQiOjE2MDIwNjM5MDJ9.XD36a2jVxlc6LNmC5nUwZvoezFVoO9T2PtKasIkO5Mo
    [address] => 5f7d8e1eb8e6cccbd8ca962b80445df1f7f38c57759f0
    [created] => 2020-10-01 15:45:02
    [expired] => 
    [status] => 1
    [tracking_id] => 1602063901
    [callback_url] =>
    [success_url] =>
    [error_url] =>
    [amount] => 1099353992000000000000
    [actual_amount] => 0
    [pow] => 18
    [transactions] => Array
        (
        )

    [currency] => stdClass Object
        (
            [iso] => 2005
            [alpha] => USDT
        )

    [message] => 
)
```

--------------------------------

### Access Bill Creation URL

Source: https://github.com/b2binpay/api-php/blob/master/examples/README.md

After starting the local server, navigate to this URL in your browser to initiate the bill creation process.

```http
http://localhost:8000/createBill.php
```

--------------------------------

### Create a Bill (Payment Invoice)

Source: https://context7.com/b2binpay/api-php/llms.txt

Use this snippet to create a payment bill. It includes steps for getting exchange rates, converting currency, optionally adding a markup, and then creating the bill with details like wallet ID, amount, currency, lifetime, and callback URLs. The response provides the bill ID, payment URL, blockchain address, and status.

```php
<?php
$provider = new B2Binpay\Provider(
    'your-api-key',
    'your-api-secret',
    true
);

// Step 1: Get rates and convert amount
$rates = $provider->getRates('USD');
$amount = $provider->convertCurrency('1000.00', 'USD', 'BTC', $rates);

// Step 2: Add markup (optional)
$finalAmount = $provider->addMarkup($amount, 'BTC', 10);

// Step 3: Create the bill
$bill = $provider->createBill(
    442,                                    // Wallet ID (from your B2BinPay account)
    $finalAmount,                           // Amount in cryptocurrency
    'BTC',                                  // Currency
    86400,                                  // Lifetime in seconds (24 hours)
    'ORDER-' . time(),                      // Tracking ID for your reference
    'https://yoursite.com/callback.php',    // Callback URL for status updates
    'https://yoursite.com/success',         // Success redirect URL (optional)
    'https://yoursite.com/error'            // Error redirect URL (optional)
);

// Bill response object: 
echo "Bill ID: " . $bill->id . "\n";
echo "Payment URL: " . $bill->url . "\n";
echo "Blockchain Address: " . $bill->address . "\n";
echo "Amount: " . $bill->amount . " (pow: " . $bill->pow . ")\n";
echo "Status: " . $bill->status . "\n";  // 1 = Created, 2 = Paid, -1 = Expired, -2 = Failed
echo "Currency: " . $bill->currency->alpha . "\n";

// Example response:
// Bill ID: 18205
// Payment URL: https://gw.b2binpay.com/eyJ0eXAi...
// Blockchain Address: 5f7d8e1eb8e6cccbd8ca962b...
// Status: 1

```

--------------------------------

### GET /virtual-wallets

Source: https://context7.com/b2binpay/api-php/llms.txt

Retrieve virtual wallets used for withdrawals and view their current balances.

```APIDOC
## GET /virtual-wallets

### Description
Retrieve virtual wallets used for withdrawals with their balances.

### Method
GET

### Query Parameters
- **filter** (array) - Optional - Filter criteria (currency, amount)
- **filter_type** (array) - Optional - Filter types (e.g., amount: gte)
- **sort** (string) - Optional - Sorting field
- **pagesize** (integer) - Optional - Number of records per page
- **page** (integer) - Optional - Page number

### Response
#### Success Response (200)
- **data** (array) - List of virtual wallet objects
- **id** (integer) - Wallet ID
- **name** (string) - Wallet name
- **amount** (integer) - Balance in smallest unit
- **pow** (integer) - Power of 10 for balance calculation
- **active** (boolean) - Wallet status
```

--------------------------------

### GET /bills

Source: https://context7.com/b2binpay/api-php/llms.txt

Retrieves a filtered and paginated list of bills.

```APIDOC
## GET /bills

### Description
Retrieve a filtered and paginated list of bills with various filtering options.

### Method
GET

### Parameters
#### Query Parameters
- **filter** (array) - Optional - Filter by wallet_id, status, created date range, currency, tracking_id, or address
- **filter_type** (array) - Optional - Define filter logic (e.g., bt, gt, gte, lt, lte)
- **sort** (string) - Optional - Sort order (e.g., -id for newest first)
- **pagesize** (int) - Optional - Results per page (max 250)
- **page** (int) - Optional - Page number

### Response
#### Success Response (200)
- **data** (array) - List of bill objects
- **meta** (object) - Pagination information (current_page, last_page, total)
```

--------------------------------

### Get currency rates

Source: https://github.com/b2binpay/api-php/blob/master/README.md

Retrieves current exchange rates for a specified base currency and rate type.

```php
$rates = $provider->getRates('BASE_CURRENCY', 'RATE_TYPE');
```

--------------------------------

### GET /transactions

Source: https://context7.com/b2binpay/api-php/llms.txt

Retrieve a list of blockchain transactions with support for filtering, sorting, and pagination.

```APIDOC
## GET /transactions

### Description
Retrieve blockchain transactions with filtering and pagination.

### Method
GET

### Query Parameters
- **filter** (array) - Optional - Filter criteria (currency, bill_id, status, tracking_id)
- **filter_type** (array) - Optional - Filter types
- **sort** (string) - Optional - Sorting field (e.g., -id)
- **pagesize** (integer) - Optional - Number of records per page
- **page** (integer) - Optional - Page number

### Response
#### Success Response (200)
- **data** (array) - List of transaction objects
- **id** (integer) - Transaction ID
- **bill_id** (integer) - Associated bill ID
- **amount** (string) - Transaction amount
- **status** (integer) - Transaction status (-2=Failed, 0=Pending, 1=Sent, 2=Approved)
- **transaction** (string) - Blockchain hash
```

--------------------------------

### Retrieve Transactions List in PHP

Source: https://context7.com/b2binpay/api-php/llms.txt

Fetches blockchain transactions with support for filtering, sorting, and pagination. Includes an example of retrieving a single transaction by its ID.

```php
<?php
$provider = new B2Binpay\Provider(
    'your-api-key',
    'your-api-secret',
    true
);

$currency = new B2Binpay\Currency();

$params = [
    'query' => [
        'filter' => [
            'currency' => $currency->getIso('BTC'),  // Filter BTC transactions only
            // 'bill_id' => 14033,                   // Filter by bill
            // 'status' => 2,                        // 2 = Approved
            // 'tracking_id' => 'ORDER-123',
        ],
        'filter_type' => [],
        'sort' => '-id',
        'pagesize' => 50,
        'page' => 1
    ]
];

$transactions = $provider->getTransactions($params);

foreach ($transactions->data as $tx) {
    echo "Transaction #{$tx->id}\n";
    echo "  Bill ID: {$tx->bill_id}\n";
    echo "  Amount: {$tx->amount} (pow: {$tx->pow})\n";
    echo "  Status: {$tx->status}\n";  // -2=Failed, 0=Pending, 1=Sent, 2=Approved
    echo "  Hash: {$tx->transaction}\n";
    echo "  Currency: {$tx->currency->alpha}\n";
    echo "  Created: {$tx->created}\n\n";
}

// Get single transaction by ID
$transaction = $provider->getTransaction(15499);
echo "Single transaction: #{$transaction->id} - {$transaction->amount}\n";
```

--------------------------------

### Get Bills List with Filters

Source: https://context7.com/b2binpay/api-php/llms.txt

Retrieve a paginated list of bills using various filtering options such as wallet ID, status, creation date range, currency, tracking ID, and address. You can also specify sorting order, results per page, and the current page number. The response includes bill data and pagination metadata.

```php
<?php
$provider = new B2Binpay\Provider(
    'your-api-key',
    'your-api-secret',
    true
);

$currency = new B2Binpay\Currency();

// Define filter parameters
$params = [
    'query' => [
        'filter' => [
            'wallet_id' => 442,                                    // Filter by wallet
            'status' => 2,                                         // 2 = Paid bills only
            'created' => '2020-01-01 00:00:00,2024-12-31 23:59:59' // Date range
            // 'currency' => $currency->getIso('BTC'),             // Filter by currency ISO
            // 'tracking_id' => 'ORDER-123',                       // Filter by tracking ID
            // 'address' => '5f7af8aed...',                        // Filter by address
        ],
        'filter_type' => [
            'created' => 'bt',  // bt = between, gt = greater, gte = greater or equal, lt = less, lte = less or equal
        ],
        'sort' => '-id',       // Reverse sort by ID (newest first)
        'pagesize' => 50,      // Results per page (max 250)
        'page' => 1
    ]
];

$bills = $provider->getBills($params);

// Process paginated results
foreach ($bills->data as $bill) {
    echo "Bill #{$bill->id}: {$bill->amount} - Status: {$bill->status}\n";

    // Check transactions on the bill
    foreach ($bill->transactions as $tx) {
        echo "  - Transaction #{$tx->id}: {$tx->amount} ({$tx->status})\n";
    }
}

// Pagination info
echo "Page: " . $bills->meta->current_page . " of " . $bills->meta->last_page . "\n";
echo "Total bills: " . $bills->meta->total . "\n";

```

--------------------------------

### GET /bills/{id}

Source: https://context7.com/b2binpay/api-php/llms.txt

Retrieves details of a specific bill by its ID.

```APIDOC
## GET /bills/{id}

### Description
Retrieve details of a specific bill by its ID.

### Method
GET

### Parameters
#### Path Parameters
- **id** (int) - Required - The unique identifier of the bill

### Response
#### Success Response (200)
- **id** (int) - Bill ID
- **url** (string) - Payment URL
- **address** (string) - Blockchain address
- **created** (string) - Creation timestamp
- **status** (int) - Bill status
- **amount** (float) - Requested amount
- **actual_amount** (float) - Actual amount paid
- **transactions** (array) - List of transactions associated with the bill
```

--------------------------------

### Get Exchange Rates

Source: https://context7.com/b2binpay/api-php/llms.txt

Retrieve current exchange rates for cryptocurrency conversion. Rates can be fetched with a specified base currency (e.g., 'USD', 'EUR') for deposit or withdrawal operations. The response includes rate details like 'from', 'to', 'rate', and 'pow'.

```php
<?php
$provider = new B2Binpay\Provider(
    'your-api-key',
    'your-api-secret',
    true
);

// Get deposit rates with USD as base currency (default)
$rates = $provider->getRates('USD');

// Get rates with EUR as base currency
$ratesEur = $provider->getRates('EUR');

// Get withdrawal rates
$withdrawRates = $provider->getRates('USD', 'withdraw');

// Rates response contains array of rate objects:
// [
//   {
//     "from": {"iso": 840, "alpha": "USD"},
//     "to": {"iso": 1000, "alpha": "BTC"},
//     "rate": "0.00009523",
//     "pow": 8
//   },
//   ...
// ]

foreach ($rates as $rate) {
    echo "1 USD = " . $rate->rate . " " . $rate->to->alpha . "\n";
}
```

--------------------------------

### Get Single Bill Details

Source: https://context7.com/b2binpay/api-php/llms.txt

Retrieve detailed information for a specific bill using its unique ID. This includes the bill's URL, blockchain address, creation and expiration timestamps, status, tracking ID, requested amount, actual amount paid, currency details, and a list of all associated transactions.

```php
<?php
$provider = new B2Binpay\Provider(
    'your-api-key',
    'your-api-secret',
    true
);

$billId = 18205;
$bill = $provider->getBill($billId);

echo "Bill ID: " . $bill->id . "\n";
echo "URL: " . $bill->url . "\n";
echo "Address: " . $bill->address . "\n";
echo "Created: " . $bill->created . "\n";
echo "Expired: " . ($bill->expired ?? 'Never') . "\n";
echo "Status: " . $bill->status . "\n";
echo "Tracking ID: " . $bill->tracking_id . "\n";
echo "Requested Amount: " . $bill->amount . "\n";
echo "Actual Amount Paid: " . $bill->actual_amount . "\n";
echo "Currency: " . $bill->currency->alpha . " (ISO: " . $bill->currency->iso . ")\n";

// List all transactions for this bill
echo "\nTransactions:\n";
foreach ($bill->transactions as $tx) {
    echo "  ID: {$tx->id}, Amount: {$tx->amount}, Status: {$tx->status}, Hash: {$tx->transaction}\n";
}

```

--------------------------------

### Create a bill

Source: https://github.com/b2binpay/api-php/blob/master/README.md

Initializes a new bill using the provider instance. Ensure the wallet currency matches the bill currency.

```php
$bill = $provider->createBill(  
        'WALLET_ID',
        'AMOUNT',
        'CURRENCY',
        'LIFETIME',
        'TRACKING_ID',
        'CALLBACK_URL',
        'SUCCESS_URL',
        'ERROR_URL'
  );
```

--------------------------------

### Create B2Binpay Provider Instance in Test Mode

Source: https://github.com/b2binpay/api-php/blob/master/README.md

To use the testing sandbox, pass `true` as the third parameter when creating a new B2Binpay\Provider instance.

```php
$provider = new B2Binpay\Provider(
    'API_KEY',
    'API_SECRET',
    true
);
```

--------------------------------

### Initialize B2BinPay Provider

Source: https://context7.com/b2binpay/api-php/llms.txt

Initialize the Provider class, the main entry point for API operations. Provide your API key and secret. Set the third parameter to true for sandbox/testing mode. You can also retrieve an authorization token for manual API calls.

```php
<?php
require_once 'vendor/autoload.php';

// Production mode
$provider = new B2Binpay\Provider(
    'your-api-key',
    'your-api-secret'
);

// Sandbox/Testing mode (pass true as third parameter)
$provider = new B2Binpay\Provider(
    'your-test-api-key',
    'your-test-api-secret',
    true  // Enable sandbox mode
);

// Get authorization token for manual API calls
$authToken = $provider->getAuthToken();
echo "Access Token: " . $authToken;
```

--------------------------------

### Create B2Binpay Provider Instance

Source: https://github.com/b2binpay/api-php/blob/master/README.md

Instantiate the B2Binpay\Provider class using your API key and secret to access your B2BinPay account.

```php
$provider = new B2Binpay\Provider(
    'API_KEY',
    'API_SECRET'
);
```

--------------------------------

### Create bill with callback parameters

Source: https://github.com/b2binpay/api-php/blob/master/README.md

Creates a bill with specific tracking and callback URL configurations.

```php
$bill = $provider->createBill(
        'WALLET_ID',
        $amount,
        'CURRENCY',
        'LIFETIME',
        '202009051801',
        'https://my.callback.url/callback.php'
    );
```

--------------------------------

### Retrieve Virtual Wallets in PHP

Source: https://context7.com/b2binpay/api-php/llms.txt

Fetches virtual wallets and their balances. Includes logic for calculating the actual balance using the wallet's power factor.

```php
<?php
$provider = new B2Binpay\Provider(
    'your-api-key',
    'your-api-secret',
    true
);

$params = [
    'query' => [
        'filter' => [
            // 'currency' => 1000,  // Filter by currency ISO (1000 = BTC)
            // 'amount' => 100,     // Filter by minimum balance
        ],
        'filter_type' => [
            // 'amount' => 'gte',   // Balance greater than or equal
        ],
        'sort' => '-id',
        'pagesize' => 50,
        'page' => 1
    ]
];

$wallets = $provider->getVirtualWallets($params);

foreach ($wallets->data as $wallet) {
    // Calculate actual balance (amount / 10^pow)
    $balance = $wallet->amount / pow(10, $wallet->pow);

    echo "Wallet #{$wallet->id}: {$wallet->name}\n";
    echo "  Currency: {$wallet->currency->alpha}\n";
    echo "  Balance: {$balance} {$wallet->currency->alpha}\n";
    echo "  Active: " . ($wallet->active ? 'Yes' : 'No') . "\n";
    echo "  Next Unique ID: {$wallet->next_unique_id}\n\n";
}

// Get single virtual wallet
$wallet = $provider->getVirtualWallet(45);
echo "Wallet {$wallet->name}: " . ($wallet->amount / pow(10, $wallet->pow)) . " {$wallet->currency->alpha}\n";
```

--------------------------------

### Use Currency Helper Class in PHP

Source: https://context7.com/b2binpay/api-php/llms.txt

Utilize the Currency class to map between symbols and ISO codes, retrieve precision settings, and fetch currency names.

```php
<?php
$currency = new B2Binpay\\\Currency();

// Get ISO code from currency symbol
$btcIso = $currency->getIso('BTC');      // Returns: 1000
$ethIso = $currency->getIso('ETH');      // Returns: 1002
$usdtIso = $currency->getIso('USDT');    // Returns: 2005
$usdtEthIso = $currency->getIso('USDT-ETH');  // Returns: 2005

// Get currency symbol from ISO code
$symbol = $currency->getAlpha(1000);     // Returns: 'BTC'
$symbol2 = $currency->getAlpha(1002);    // Returns: 'ETH'

// Get precision (decimal places) for a currency
$btcPrecision = $currency->getPrecision(1000);   // Returns: 8
$ethPrecision = $currency->getPrecision(1002);   // Returns: 18
$xrpPrecision = $currency->getPrecision(1010);   // Returns: 6

// Get currency name
$name = $currency->getName(1000);        // Returns: 'Bitcoin'
$name2 = $currency->getName(1002);       // Returns: 'Ethereum'

// Get maximum precision supported
$maxPrecision = $currency->getMaxPrecision();  // Returns: 18

// Supported cryptocurrencies with ISO codes:
// BTC (1000), ETH (1002), LTC (1003), DASH (1005), BCH (1006)
// XMR (1007), XRP (1010), XEM (1012), ADA (1018), DOGE (1019)
// ZEC (1020), XLM (1021), EOS (1022), TRX (1026), NEO (2014)
// BNB (2025), USDT (2005), USDC (2024), DAI (2068), BUSD (2077)
// PAX (2021), TUSD (2022), GUSD (2023)
```

--------------------------------

### Callback Handling and Verification

Source: https://github.com/b2binpay/api-php/blob/master/README.md

Details on how to handle callbacks from B2BinPay for bill status changes and how to verify the authenticity of these callbacks.

```APIDOC
## Callback Handling

### Description
When a bill's status changes, B2BinPay can send a callback notification to your specified `CALLBACK_URL`. You can also include a `TRACKING_ID` in the `createBill` request to help identify the order associated with the callback.

**Important:** Your `CALLBACK_URL` must respond with an HTTP `200 OK` status and the message 'OK' to confirm receipt. Failure to do so may result in the payment not being considered complete.

### Callback Response Example
```php
<?php
header('HTTP/1.1 200 OK');
exit('OK');
?>
```

## Callback Verification

### Description
To ensure the security and authenticity of callbacks, you can verify the signature provided in the callback request headers using the `$provider->verifySign()` method.

### Method
POST (for receiving callback data)

### Endpoint
Your configured `CALLBACK_URL`

### Parameters (from POST data)
- **sign.time** (string) - The timestamp associated with the signature.
- **sign.hash** (string) - The signature hash to verify.

### Verification Logic
```php
<?php
// Assuming $provider is an instance of your B2BinPay client

if (!isset($_POST['sign']['time']) || !isset($_POST['sign']['hash'])) {
    header('HTTP/1.1 400 Bad Request');
    exit('Missing signature data');
}

$isVerified = $provider->verifySign($_POST['sign']['time'], $_POST['sign']['hash']);

if (!$isVerified) {
    header('HTTP/1.1 401 Unauthorized');
    exit('Signature verification failed');
}

// Process the callback data if verification is successful
// ...

// Respond with OK to acknowledge receipt
header('HTTP/1.1 200 OK');
exit('OK');
?>
```

**Warning:** Each callback generates a new signature hash. If you receive a hash that has been used previously, treat it as an unauthorized request and return an error.
```

--------------------------------

### Retrieve Withdrawals List in PHP

Source: https://context7.com/b2binpay/api-php/llms.txt

Fetches a list of withdrawals with optional filtering and pagination. Requires a configured B2Binpay provider instance.

```php
<?php
$provider = new B2Binpay\Provider(
    'your-api-key',
    'your-api-secret',
    true
);

$currency = new B2Binpay\Currency();

$params = [
    'query' => [
        'filter' => [
            'virtual_wallet_id' => 45,
            'currency' => $currency->getIso('BTC'),
            // 'status' => 2,                        // 2 = Sent
            // 'tracking_id' => 'WITHDRAW-123',
            // 'created' => '2024-01-01 00:00:00,2024-12-31 23:59:59',
        ],
        'filter_type' => [
            // 'created' => 'bt',
        ],
        'sort' => '-id',
        'pagesize' => 50,
        'page' => 1
    ]
];

$withdrawals = $provider->getWithdrawals($params);

foreach ($withdrawals->data as $w) {
    $amount = $w->amount / pow(10, $w->pow);
    $fee = isset($w->fee) ? $w->fee / pow(10, $w->pow) : 'N/A';

    echo "Withdrawal #{$w->id}\n";
    echo "  Amount: {$amount} {$w->currency->alpha}\n";
    echo "  Fee: {$fee}\n";
    echo "  Address: {$w->address}\n";
    echo "  Status: {$w->status}\n";
    echo "  Transaction Hash: " . ($w->transaction ?? 'Pending') . "\n\n";
}

// Get single withdrawal
$withdrawal = $provider->getWithdrawal(1072);
echo "Withdrawal #{$withdrawal->id}: Status {$withdrawal->status}\n";
```

--------------------------------

### Configure B2BinPay API Client in composer.json

Source: https://github.com/b2binpay/api-php/blob/master/README.md

Alternatively, you can add the B2BinPay API client to your composer.json file under the 'require' section.

```json
{
  "require": {
    "b2binpay/api-php": "^1.2"
  }
}
```

--------------------------------

### Create Withdrawal PHP Method

Source: https://github.com/b2binpay/api-php/blob/master/README.md

Initiates a withdrawal from a virtual wallet to a specified blockchain address.

```php
$bill = $provider->createWithdrawal(  
        'VIRTUAL_WALLET_ID',
        'AMOUNT',
        'CURRENCY',
        'ADDRESS',
        'UNIQUE_ID',
        'TRACKING_ID',
        'CALLBACK_URL',
        'MESSAGE',
        'WITH_FEE'
    );
```

--------------------------------

### Create Cryptocurrency Withdrawal in PHP

Source: https://context7.com/b2binpay/api-php/llms.txt

Initiates a withdrawal to an external address. Demonstrates currency conversion and handling specific requirements like destination tags for Ripple.

```php
<?php
$provider = new B2Binpay\Provider(
    'your-api-key',
    'your-api-secret',
    true
);

// Get rates and convert amount (if withdrawing from different currency wallet)
$rates = $provider->getRates('USD', 'withdraw');
$amount = $provider->convertCurrency('500.00', 'USD', 'BTC', $rates);

// Create withdrawal
$withdrawal = $provider->createWithdrawal(
    45,                                         // Virtual wallet ID
    $amount,                                    // Amount to withdraw
    'BTC',                                      // Currency
    'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh',  // Destination blockchain address
    time(),                                     // Unique ID (must be unique per withdrawal)
    'WITHDRAW-' . time(),                       // Tracking ID (optional)
    'https://yoursite.com/callback.php',        // Callback URL (optional)
    null,                                       // Message (for Ripple, NEM, Stellar, EOS, Binance Chain)
    false                                       // Include fee in amount (optional)
);

echo "Withdrawal ID: " . $withdrawal->id . "\n";
echo "Virtual Wallet ID: " . $withdrawal->virtual_wallet_id . "\n";
echo "Address: " . $withdrawal->address . "\n";
echo "Amount: " . $withdrawal->amount . " (pow: " . $withdrawal->pow . ")\n";
echo "Fee: " . ($withdrawal->fee ?? 'Pending') . "\n";
echo "Status: " . $withdrawal->status . "\n";  // 0=Waiting, 1=Pending, 2=Sent, -2=Failed
echo "Unique ID: " . $withdrawal->unique_id . "\n";
echo "Currency: " . $withdrawal->currency->alpha . "\n";

// For Ripple with destination tag
$xrpWithdrawal = $provider->createWithdrawal(
    46,                    // XRP virtual wallet ID
    '100',                 // Amount
    'XRP',                 // Currency
    'rPT1Sjq2YGr...',      // XRP address
    time(),                // Unique ID
    'XRP-WITHDRAW-001',    // Tracking ID
    null,                  // Callback URL
    '12345678'             // Destination tag (message parameter)
);
```

--------------------------------

### Retrieve Transfers List in PHP

Source: https://context7.com/b2binpay/api-php/llms.txt

Fetches internal wallet transfers with filtering options. Uses the provider instance to query transfer data.

```php
<?php
$provider = new B2Binpay\Provider(
    'your-api-key',
    'your-api-secret',
    true
);

$currency = new B2Binpay\Currency();

$params = [
    'query' => [
        'filter' => [
            'type' => 0,  // 0=Blockchain deposit, 1=Bank, 2=Auto withdraw, etc.
            'source_currency' => $currency->getIso('BTC'),
            // 'target_currency' => $currency->getIso('USDT'),
            // 'virtual_wallet_id' => 45,
            // 'status' => 1,  // 0=Pending, 1=Sent, -1=Failed
        ],
        'filter_type' => [],
        'sort' => '-id',
        'pagesize' => 50,
        'page' => 1
    ]
];

$transfers = $provider->getTransfers($params);

foreach ($transfers->data as $t) {
    $sourceAmount = $t->source_amount / pow(10, $t->source_pow);
    $targetAmount = $t->target_amount / pow(10, $t->target_pow);

    echo "Transfer #{$t->id}\n";
    echo "  Source: {$sourceAmount} {$t->source_currency->alpha}\n";
    echo "  Target: {$targetAmount} {$t->target_currency->alpha}\n";
    echo "  Rate: {$t->rate}\n";
    echo "  Status: {$t->status}\n";
    echo "  Type: {$t->type}\n\n";
}

// Get single transfer
$transfer = $provider->getTransfer(4551);
echo "Transfer #{$transfer->id}: {$transfer->source_amount} -> {$transfer->target_amount}\n";
```

--------------------------------

### Currency Helper Class

Source: https://context7.com/b2binpay/api-php/llms.txt

Utilize the Currency class for converting between currency codes and ISO numbers, and retrieving precision information for supported cryptocurrencies.

```APIDOC
## Currency Helper Class

Use the Currency class to convert between currency codes and ISO numbers, and get precision information.

### Methods

- **getIso(string $currencyCode): int**
  Converts a currency code (e.g., 'BTC', 'USDT-ETH') to its corresponding ISO number.

- **getAlpha(int $isoCode): string**
  Converts an ISO number to its corresponding currency code (e.g., 1000 to 'BTC').

- **getPrecision(int $isoCode): int**
  Retrieves the precision (number of decimal places) for a given currency ISO code.

- **getName(int $isoCode): string**
  Retrieves the full name of the currency for a given ISO code (e.g., 'Bitcoin' for 1000).

- **getMaxPrecision(): int**
  Returns the maximum precision supported across all currencies.

### Supported Cryptocurrencies

- BTC (1000)
- ETH (1002)
- LTC (1003)
- DASH (1005)
- BCH (1006)
- XMR (1007)
- XRP (1010)
- XEM (1012)
- ADA (1018)
- DOGE (1019)
- ZEC (1020)
- XLM (1021)
- EOS (1022)
- TRX (1026)
- NEO (2014)
- BNB (2025)
- USDT (2005)
- USDC (2024)
- DAI (2068)
- BUSD (2077)
- PAX (2021)
- TUSD (2022)
- GUSD (2023)

### Example Usage

```php
<?php
$currency = new B2Binpay\Currency();

// Get ISO code from currency symbol
$btcIso = $currency->getIso('BTC');      // Returns: 1000

// Get currency symbol from ISO code
$symbol = $currency->getAlpha(1000);     // Returns: 'BTC'

// Get precision (decimal places) for a currency
$btcPrecision = $currency->getPrecision(1000);   // Returns: 8

// Get currency name
$name = $currency->getName(1000);        // Returns: 'Bitcoin'

// Get maximum precision supported
$maxPrecision = $currency->getMaxPrecision();  // Returns: 18
```
```

--------------------------------

### Currency Conversion API

Source: https://github.com/b2binpay/api-php/blob/master/README.md

Provides functionality to retrieve real-time currency exchange rates and convert amounts between supported currencies.

```APIDOC
## GET /api/rates

### Description
Retrieves current exchange rates for a specified base currency and rate type.

### Method
GET

### Endpoint
/api/rates

### Parameters
#### Path Parameters
None

#### Query Parameters
- **BASE_CURRENCY** (string) - Optional - The currency against which rates are calculated. Defaults to 'USD'.
- **RATE_TYPE** (string) - Optional - The type of rates to retrieve ('deposit' or 'withdrawal'). Defaults to 'deposit'.

### Request Example
`GET /api/rates?BASE_CURRENCY=EUR&RATE_TYPE=withdrawal`

### Response
#### Success Response (200 OK)
- **rates** (object) - An object containing currency pairs and their exchange rates.

#### Response Example
```json
{
  "rates": {
    "USD": {
      "EUR": 0.92,
      "GBP": 0.79
    },
    "EUR": {
      "USD": 1.08,
      "GBP": 0.86
    }
  }
}
```

## POST /api/convert

### Description
Converts a given amount from one currency to another using the latest exchange rates.

### Method
POST

### Endpoint
/api/convert

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **AMOUNT** (string) - Required - The amount to convert.
- **BASE_CURRENCY** (string) - Required - The currency of the provided amount.
- **CURRENCY** (string) - Required - The target currency for conversion.
- **rates** (object) - Optional - Pre-fetched exchange rates. If not provided, rates will be fetched internally.

### Request Example
```json
{
  "AMOUNT": "100",
  "BASE_CURRENCY": "USD",
  "CURRENCY": "EUR",
  "rates": {
    "USD": {
      "EUR": 0.92
    }
  }
}
```

### Response
#### Success Response (200 OK)
- **converted_amount** (string) - The converted amount in the target currency.

#### Response Example
```json
{
  "converted_amount": "92.00"
}
```
```

--------------------------------

### Acknowledge callback

Source: https://github.com/b2binpay/api-php/blob/master/README.md

Returns a 200 OK response to the B2BinPay server to confirm receipt of the callback.

```php
header('HTTP/1.1 200 OK');
exit('OK');
```

--------------------------------

### Create Bill API

Source: https://github.com/b2binpay/api-php/blob/master/README.md

Allows for the creation of new bills with specified amounts, currencies, and optional tracking and URL parameters. The payment currency must match the wallet's currency.

```APIDOC
## POST /api/bills

### Description
Creates a new bill for payment.

### Method
POST

### Endpoint
/api/bills

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **WALLET_ID** (int) - Required - The ID of the wallet to create the bill from. The wallet's currency determines the bill's currency.
- **AMOUNT** (string) - Required - The amount of the bill in the specified currency.
- **CURRENCY** (string) - Required - The currency of the bill. Must be supported and match the wallet's currency.
- **LIFETIME** (int) - Required - The duration in seconds until the bill expires.
- **TRACKING_ID** (string) - Optional - A unique identifier for tracking the bill. Returned in the callback.
- **CALLBACK_URL** (string) - Optional - The URL to send payment status callbacks to.
- **SUCCESS_URL** (string) - Optional - The URL to redirect the user to after successful payment.
- **ERROR_URL** (string) - Optional - The URL to redirect the user to after an unsuccessful payment.

### Request Example
```json
{
  "WALLET_ID": "12345",
  "AMOUNT": "100.50",
  "CURRENCY": "USD",
  "LIFETIME": 3600,
  "TRACKING_ID": "order_abc123",
  "CALLBACK_URL": "https://example.com/callback",
  "SUCCESS_URL": "https://example.com/success",
  "ERROR_URL": "https://example.com/error"
}
```

### Response
#### Success Response (201 Created)
- **bill_id** (string) - The unique identifier for the created bill.
- **payment_url** (string) - The URL where the user can pay the bill.

#### Response Example
```json
{
  "bill_id": "bill_xyz789",
  "payment_url": "https://pay.b2binpay.com/pay?bill_id=bill_xyz789"
}
```
```

--------------------------------

### Add markup

Source: https://github.com/b2binpay/api-php/blob/master/README.md

Applies a percentage-based markup to a given amount for a specific currency.

```php
$amount = $provider->addMarkup($amount, 'CURRENCY', 10);
```

--------------------------------

### Callback Structures

Source: https://github.com/b2binpay/api-php/blob/master/README.md

Reference for the data structures returned in bill and withdrawal callbacks.

```APIDOC
## Callback Structures

### Bill Callback
Contains bill details including ID, status, amount, actual_amount, transactions list, and signature verification data.

### Withdraw Callback
Contains withdrawal details including ID, virtual_wallet_id, status, amount, fee, transaction hash, and signature verification data.
```

--------------------------------

### System Status Codes

Source: https://github.com/b2binpay/api-php/blob/master/README.md

Reference tables for various system statuses used in the B2BinPay API.

```APIDOC
## System Status Codes

### Bill Statuses
- -2: Failed
- -1: Expired
- 1: Created
- 2: Paid

### Transaction Statuses
- -4: Waiting for return
- -3: Returned
- -2: Failed
- -1: Expired
- 0: Pending
- 1: Sent
- 2: Approved

### Withdraw Statuses
- -2: Failed
- 0: Waiting
- 1: Pending
- 2: Sent

### Transfer Statuses
- -1: Failed
- 0: Pending
- 1: Sent
```

--------------------------------

### Add Markup API

Source: https://github.com/b2binpay/api-php/blob/master/README.md

Allows for the addition of a percentage-based markup to an existing amount in a specified currency.

```APIDOC
## POST /api/markup

### Description
Adds a specified percentage markup to a given amount.

### Method
POST

### Endpoint
/api/markup

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **amount** (string) - Required - The base amount to which the markup will be added.
- **currency** (string) - Required - The currency in which the amount and markup are calculated.
- **markup_percentage** (integer) - Required - The percentage to add as markup.

### Request Example
```json
{
  "amount": "100.00",
  "currency": "USD",
  "markup_percentage": 10
}
```

### Response
#### Success Response (200 OK)
- **amount_with_markup** (string) - The final amount after the markup has been applied.

#### Response Example
```json
{
  "amount_with_markup": "110.00"
}
```
```

--------------------------------

### POST /createWithdrawal

Source: https://github.com/b2binpay/api-php/blob/master/README.md

Creates a new withdrawal from a virtual wallet to a specified blockchain address.

```APIDOC
## POST /createWithdrawal

### Description
Creates a new withdrawal from a virtual wallet to any blockchain. If the virtual wallet currency differs from the withdrawal currency, the system performs an automatic conversion.

### Parameters
#### Request Body
- **VIRTUAL_WALLET_ID** (int) - Required - ID of the virtual wallet.
- **AMOUNT** (string) - Required - Amount to be withdrawn.
- **CURRENCY** (string) - Required - Currency code for the withdrawal.
- **ADDRESS** (string) - Required - Blockchain address for the withdrawal.
- **UNIQUE_ID** (int) - Required - Unique positive number for the transaction.
- **TRACKING_ID** (string) - Optional - Custom tracking identifier.
- **CALLBACK_URL** (string) - Optional - URL for callback notifications.
- **MESSAGE** (string) - Optional - Required for specific blockchains like Ripple, NEM, Stellar, EOS, and Binance Chain.
- **WITH_FEE** (boolean) - Optional - Whether to include the commission in the withdrawal amount.
```

--------------------------------

### Handle Webhook Callbacks and Verify Signatures

Source: https://context7.com/b2binpay/api-php/llms.txt

Validates incoming webhook signatures using the provider and processes withdrawal or bill callback data. Always respond with a 200 OK status after processing.

```php
<?php
require_once 'vendor/autoload.php';

$provider = new B2Binpay\Provider(
    'your-api-key',
    'your-api-secret',
    true
);

// Verify the callback signature
$signTime = $_POST['sign']['time'];
$signHash = $_POST['sign']['hash'];

$isValid = $provider->verifySign($signTime, $signHash);

if (!$isValid) {
    // Invalid signature - reject the callback
    header('HTTP/1.1 401 Unauthorized');
    exit();
}

// Determine callback type and process
if (!empty($_POST['virtual_wallet_id'])) {
    // This is a WITHDRAWAL callback
    $withdrawalId = $_POST['id'];
    $status = $_POST['status'];  // 0=Waiting, 1=Pending, 2=Sent, -2=Failed
    $txHash = $_POST['transaction'];
    $amount = $_POST['amount'];
    $fee = $_POST['fee'];

    // Update your database with withdrawal status
    // updateWithdrawalStatus($withdrawalId, $status, $txHash);

    echo "Withdrawal #{$withdrawalId} status: {$status}\n";

} else {
    // This is a BILL (deposit) callback
    $billId = $_POST['id'];
    $status = $_POST['status'];  // 1=Created, 2=Paid, -1=Expired, -2=Failed
    $trackingId = $_POST['tracking_id'];
    $actualAmount = $_POST['actual_amount'];

    // Process each transaction
    foreach ($_POST['transactions'] as $tx) {
        $txId = $tx['id'];
        $txAmount = $tx['amount'];
        $txHash = $tx['transaction'];
        $txStatus = $tx['status'];  // 0=Pending, 1=Sent, 2=Approved

        // Verify transaction hasn't been processed before (prevent duplicates)
        // if (!isTransactionProcessed($txHash)) {
        //     processDeposit($billId, $txAmount, $txHash);
        // }
    }

    echo "Bill #{$billId} status: {$status}\n";
}

// IMPORTANT: Always respond with 200 OK and body "OK"
header('HTTP/1.1 200 OK');
echo 'OK';
```

--------------------------------

### Convert currency

Source: https://github.com/b2binpay/api-php/blob/master/README.md

Converts an amount between currencies using provided or fetched rates.

```php
$amount = $provider->convertCurrency('AMOUNT', 'BASE_CURRENCY', 'CURRENCY', $rates);
```

--------------------------------

### Convert Currency

Source: https://context7.com/b2binpay/api-php/llms.txt

Convert amounts between fiat and cryptocurrencies using current exchange rates. The converter automatically handles precision based on currency requirements. You can optionally pass the rates array to avoid automatic fetching.

```php
<?php
$provider = new B2Binpay\Provider(
    'your-api-key',
    'your-api-secret',
    true
);

// Get current rates
$rates = $provider->getRates('USD');

// Convert 100 USD to Bitcoin
$btcAmount = $provider->convertCurrency(
    '100.00',      // Amount to convert
    'USD',         // Source currency
    'BTC',         // Target currency
    $rates         // Rates array (optional, fetched automatically if not provided)
);

echo "100 USD = " . $btcAmount . " BTC\n";
// Output: 100 USD = 0.00952300 BTC

// Convert 500 EUR to Ethereum
$ratesEur = $provider->getRates('EUR');
$ethAmount = $provider->convertCurrency('500.00', 'EUR', 'ETH', $ratesEur);
echo "500 EUR = " . $ethAmount . " ETH\n";

// Convert without passing rates (will be fetched automatically)
$ltcAmount = $provider->convertCurrency('250.00', 'USD', 'LTC');
echo "250 USD = " . $ltcAmount . " LTC\n";
```