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:

Log in to the MiraclePay Dashboard as a Merchant Admin
Navigate to Settings then Developer tab
Copy your Client ID (UUID format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
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:

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:

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:

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:

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:

Example Request:

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

Example Response:

[
  {
    "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

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