.. _prerequisites: Prerequisites ============= Before integrating with MiraclePay, you need to create an API key and understand the available blockchain networks. API Keys -------- All requests to the External Payments API are signed with an API key. A key consists of three credentials: .. list-table:: :widths: 20 25 55 :header-rows: 1 * - Credential - Format - Notes * - **Key ID** - ``mpay_pk_`` + 24 hex chars - Public identifier, sent with every request. * - **Secret** - ``mpay_sk_`` + 64 hex chars - Used to compute request signatures. **Shown only once**, at key creation — store it immediately. * - **Passphrase** - base64url string - Sent with every request alongside the key ID. **How to create a key:** 1. Log in to the merchant panel at `https://admin.miraclecash.info `_ as a **Merchant Admin** 2. Navigate to **Settings** → **Developer** → **API Keys** 3. Click **Create API Key**, give it a name, and choose its scopes 4. Copy the **secret** now — it is displayed only this once **Scopes:** Each key carries a set of scopes controlling which endpoints it may call. Omitting scopes at creation grants all of them. .. list-table:: :widths: 30 70 :header-rows: 1 * - Scope - Grants access to * - ``payment_prompts:write`` - ``POST /external/v1/payments/prompt`` * - ``payment_prompts:read`` - ``GET /external/v1/payments`` and ``GET /external/v1/payments/:id`` * - ``blockchains:read`` - ``GET /external/v1/blockchains/active`` **Key lifecycle:** - **Rotate** — issues a new secret and passphrase under the same key ID. The old pair keeps working for a 24-hour grace period (or is invalidated immediately if you choose so), letting you deploy new credentials without downtime. - **Revoke** — permanently disables the key. Requests fail with :ref:`E2005 `. - **Expiry** — keys can optionally be given an expiry date; expired keys fail with :ref:`E2006 `. - You can have at most **10 active keys** per merchant account. .. warning:: **Security Best Practices:** - Never expose your secret or passphrase in client-side code — sign requests only from your backend - Store credentials in environment variables or a secrets manager - Rotate the key immediately if compromised - Never commit credentials to version control - Give each key only the scopes it needs Supported Blockchains --------------------- MiraclePay supports multiple blockchain networks. On standard accounts, use the ``blockchainIds`` parameter (an array of blockchain ID strings) when creating payments. US merchant accounts omit ``blockchainIds`` entirely — the customer picks the network on the hosted checkout page (see :ref:`external_payments_api`). **Production Networks:** .. list-table:: :widths: 20 30 20 30 :header-rows: 1 * - Blockchain ID - Network - Asset - Description * - ``avax`` - Avalanche C-Chain - AVAX - Native Avalanche payments * - ``avax-usdt`` - Avalanche C-Chain - USDT - USDT stablecoin on Avalanche * - ``bnb`` - BNB Smart Chain - BNB - Native BNB payments * - ``bnb-usdt`` - BNB Smart Chain - USDT - USDT stablecoin on BNB Smart Chain * - ``btc`` - Bitcoin Mainnet - BTC - Native Bitcoin payments * - ``eth`` - Ethereum Mainnet - ETH - Native Ethereum payments * - ``eth-usdc`` - Ethereum Mainnet - USDC - USDC stablecoin on Ethereum * - ``eth-usdt`` - Ethereum Mainnet - USDT - USDT stablecoin on Ethereum * - ``sol`` - Solana Mainnet - SOL - Native Solana payments * - ``sol-usdc`` - Solana Mainnet - USDC - USDC stablecoin on Solana * - ``tron`` - Tron Mainnet - TRX - Native Tron payments * - ``tron-usdc`` - Tron Mainnet - USDC - USDC stablecoin on Tron * - ``tron-usdt`` - Tron Mainnet - USDT - USDT stablecoin on Tron **Test Networks:** .. list-table:: :widths: 20 30 20 30 :header-rows: 1 * - Blockchain ID - Network - Asset - Description * - ``avax-test`` - Avalanche Fuji - AVAX - Avalanche testnet * - ``bnb-test`` - BNB Smart Chain Testnet - BNB - BNB testnet * - ``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 * - ``eth-usdt-test`` - Ethereum Sepolia - USDT - USDT on Ethereum testnet * - ``sol-dev`` - Solana Devnet - SOL - Solana devnet * - ``sol-usdc-dev`` - Solana Devnet - USDC - USDC on Solana devnet * - ``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 ---------------------- Not every supported network is necessarily available to your account at any given time. Retrieve the list of currently active blockchains: **Endpoint:** ``GET /external/v1/blockchains/active`` **Required scope:** ``blockchains:read`` The request must be signed — see :ref:`authentication` for the signing scheme and a runnable curl example. **Example Response:** .. code-block:: json [ { "object": "blockchain", "id": "eth", "name": "Ethereum Mainnet", "isActive": true, "assetSymbol": "ETH", "assetName": "Ethereum" }, { "object": "blockchain", "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 URL -------- .. list-table:: :widths: 30 70 :header-rows: 1 * - Environment - Base URL * - Development - ``https://api.miraclecash.info`` All endpoint paths in this guide are relative to the base URL, and the full path (including the ``/external/v1`` prefix) is part of the request signature. Rate Limits ----------- The External Payments API is rate limited to **60 requests per 60 seconds**. Exceeding the limit returns HTTP 429 with error code :ref:`E9001 ` — honor the ``Retry-After`` header and retry with backoff. Rate-limited responses carry ``X-MP-Should-Retry: true``: the same request succeeds once the window clears.