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:

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:

Log in to the merchant panel at https://admin.miraclecash.info as a Merchant Admin
Navigate to Settings → Developer → API Keys
Click Create API Key, give it a name, and choose its scopes
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.

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 E2005.
Expiry — keys can optionally be given an expiry date; expired keys fail with 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 External Payments API).

Production Networks:

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:

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 Authentication for the signing scheme and a runnable curl example.

Example Response:

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

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