.. _prerequisites:

Prerequisites
=============

Before integrating with MiraclePay, you need to obtain your API credentials and understand the available blockchain networks.

API Credentials
---------------

The API uses HTTP Basic Authentication to authenticate your requests. You need your **Client ID** and **API Key** to make API calls.

**How to get your credentials:**

1. Log in to the `MiraclePay Dashboard <https://dashboard.miraclepay.com>`_ as a **Merchant Admin**
2. Navigate to **Settings** then **Developer** tab
3. Copy your **Client ID** (UUID format: ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx``)
4. Copy your **API Key** (starts with ``mpay_``)

**Authentication Header:**

Combine your Client ID and API Key with a colon, Base64-encode them, and include in the ``Authorization`` header:

.. code-block:: text

   Authorization: Basic base64(clientId:apiKey)

**Example:**

If your Client ID is ``a1b2c3d4-e5f6-7890-abcd-ef1234567890`` and API Key is ``mpay_abc123xyz``, the header would be:

.. code-block:: text

   Authorization: Basic YTFiMmMzZDQtZTVmNi03ODkwLWFiY2QtZWYxMjM0NTY3ODkwOm1wYXlfYWJjMTIzeHl6

.. warning::

   **Security Best Practices:**

   - Never expose your credentials in client-side code
   - Store Client ID and API Key in environment variables or a secrets manager
   - Rotate your API Key immediately if compromised
   - Never commit credentials to version control

Supported Blockchains
---------------------

MiraclePay supports multiple blockchain networks. Use the ``blockchainIds`` parameter (an array of blockchain ID strings) when creating payments.

**Production Networks:**

.. list-table::
   :widths: 20 30 20 30
   :header-rows: 1

   * - Blockchain ID
     - Network
     - Asset
     - Description
   * - ``btc``
     - Bitcoin Mainnet
     - BTC
     - Native Bitcoin payments
   * - ``eth``
     - Ethereum Mainnet
     - ETH
     - Native Ethereum payments
   * - ``eth-usdc``
     - Ethereum Mainnet
     - USDC
     - USDC stablecoin on Ethereum
   * - ``sol``
     - Solana Mainnet
     - SOL
     - Native Solana payments
   * - ``tron``
     - Tron Mainnet
     - TRX
     - Native Tron payments
   * - ``tron-usdt``
     - Tron Mainnet
     - USDT
     - USDT stablecoin on Tron
   * - ``tron-usdc``
     - Tron Mainnet
     - USDC
     - USDC stablecoin on Tron

**Test Networks:**

.. list-table::
   :widths: 20 30 20 30
   :header-rows: 1

   * - Blockchain ID
     - Network
     - Asset
     - Description
   * - ``btc-test``
     - Bitcoin Testnet
     - tBTC
     - Bitcoin testnet for development
   * - ``eth-test``
     - Ethereum Sepolia
     - ETH
     - Ethereum testnet
   * - ``eth-usdc-test``
     - Ethereum Sepolia
     - USDC
     - USDC on Ethereum testnet
   * - ``sol-test``
     - Solana Devnet
     - SOL
     - Solana testnet
   * - ``tron-test``
     - Tron Shasta
     - TRX
     - Tron testnet
   * - ``tron-usdc-test``
     - Tron Shasta
     - USDC
     - USDC on Tron testnet
   * - ``tron-usdt-test``
     - Tron Shasta
     - USDT
     - USDT on Tron testnet

.. tip::

   Always test your integration using testnet blockchain IDs (e.g., ``eth-test``) before switching to production networks.

Get Active Blockchains
----------------------

Retrieve the list of currently active blockchains for your merchant account:

**Endpoint:** ``GET /external/blockchains/active``

**Headers:**

.. list-table::
   :widths: 20 80
   :header-rows: 1

   * - Header
     - Value
    * - ``Authorization``
      - Basic authentication (Base64 encoded ``clientId:apiKey``)

**Example Request:**

.. code-block:: bash

   curl -X GET https://api.miraclecash.info/external/blockchains/active \
     -H "Authorization: Basic $(echo -n 'your_client_id:your_api_key' | base64)"

**Example Response:**

.. code-block:: json

   [
     {
       "id": "eth",
       "name": "Ethereum Mainnet",
       "isActive": true,
       "assetSymbol": "ETH",
       "assetName": "Ethereum"
     },
     {
       "id": "tron-usdt",
       "name": "Tron USDT",
       "isActive": true,
       "assetSymbol": "USDT",
       "assetName": "Tether"
     }
   ]

Use the ``id`` field values in the ``blockchainIds`` array when creating payment prompts.

Base URLs
---------

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Environment
     - Base URL
   * - Production
     - ``https://be.miraclepay.com``
   * - Development
     - ``https://api.miraclecash.info``