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 the defaults for that account type. The table below is for merchant keys; partner keys have a different scope set and partner developer keys are restricted to overview access — see Merchant-Partner API.

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. You do not have to choose between them: omit the blockchainIds parameter when creating a payment and the customer is offered every network your account can be paid on. Send it (an array of blockchain ID strings) only to restrict a payment to a subset. US merchant accounts ignore the parameter — 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 active at any given time. This endpoint lists platform-wide active blockchains, not the merchant's configured payable networks. Standard accounts also need external deposit addresses configured on the default Main branch. Omitting blockchainIds on create selects the intersection of those two sets.

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 you want to restrict a payment to specific networks.

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 current application limiter allows 60 requests per 60 seconds per tracked client, per replica, including failed authentication attempts. This is not a global per-key quota guarantee. Exceeding the limit returns HTTP 429 with error code E9001 — honor Retry-After and retry with backoff and fresh signing headers. Rate-limited responses carry X-MP-Should-Retry: true.