Fiat MoonPay API Reference
API Reference for the @tetherto/wdk-protocol-fiat-moonpay module
API Reference
Complete API documentation for the @tetherto/wdk-protocol-fiat-moonpay module.
Constructor
new MoonPayProtocol(account, config)
Creates a new MoonPayProtocol instance.
Parameters:
| Name | Type | Description |
|---|---|---|
account | IWalletAccount | IWalletAccountReadOnly | undefined | Wallet account for transactions |
config | MoonPayProtocolConfig | Configuration object |
Config Options:
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
apiKey | string | Yes | - | Your MoonPay publishable API key |
signUrl | function | No | - | Callback used to sign buy and sell widget URLs through a trusted backend |
cacheTime | number | No | 600000 | Cache duration for currencies (ms) |
environment | 'production' | 'sandbox' | No | production | MoonPay widget URL endpoint set |
Example:
import MoonPayProtocol from '@tetherto/wdk-protocol-fiat-moonpay';
const moonpay = new MoonPayProtocol(walletAccount, {
apiKey: 'pk_live_xxxxx',
environment: 'production',
});Omitting signUrl returns unsigned widget URLs. For signed URLs, use the backend callback pattern in Configuration; returning the input unchanged does not sign it.
Methods
buy(options)
Generates a MoonPay widget URL for purchasing cryptocurrency. If signUrl is configured, the URL is signed through that callback before being returned.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
options.cryptoAsset | string | Yes | Cryptocurrency code (e.g., 'eth', 'btc') |
options.fiatCurrency | string | Yes | Fiat currency code (e.g., 'usd', 'eur') |
options.cryptoAmount | number | bigint | No* | Amount in smallest crypto units |
options.fiatAmount | number | bigint | No* | Amount in smallest fiat units (cents) |
options.recipient | string | No | Wallet address (uses account address if not provided) |
options.config | MoonPayBuyParams | No | Widget configuration options |
*Either cryptoAmount or fiatAmount must be provided, but not both.
Returns: Promise\<{ buyUrl: string }\>
sell(options)
Generates a MoonPay widget URL for selling cryptocurrency. If signUrl is configured, the URL is signed through that callback before being returned.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
options.cryptoAsset | string | Yes | Cryptocurrency code |
options.fiatCurrency | string | Yes | Fiat currency code |
options.cryptoAmount | number | bigint | No* | Amount in smallest crypto units |
options.fiatAmount | number | bigint | No* | Amount in smallest fiat units |
options.refundAddress | string | No | Refund wallet address |
options.config | MoonPaySellParams | No | Widget configuration options |
Returns: Promise\<{ sellUrl: string }\>
quoteBuy(options)
Gets a price quote for a cryptocurrency purchase.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
options.cryptoAsset | string | Yes | Cryptocurrency code |
options.fiatCurrency | string | Yes | Fiat currency code |
options.cryptoAmount | number | bigint | No* | Amount in smallest crypto units |
options.fiatAmount | number | bigint | No* | Amount in smallest fiat units |
options.config | MoonPayQuoteBuyParams | No | Quote parameters |
Returns: Promise\<MoonPayBuyQuote\>
{
cryptoAmount: bigint, // Crypto amount you'll receive
fiatAmount: bigint, // Fiat amount to pay
fee: bigint, // Total fee amount
rate: string, // Exchange rate
metadata: MoonPayBuyQuoteMetadata
}quoteSell(options)
Gets a price quote for selling cryptocurrency.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
options.cryptoAsset | string | Yes | Cryptocurrency code |
options.fiatCurrency | string | Yes | Fiat currency code |
options.cryptoAmount | number | bigint | Yes | Amount in smallest crypto units |
options.config | MoonPayQuoteSellParams | No | Quote parameters |
Returns: Promise\<MoonPaySellQuote\>
{
cryptoAmount: bigint, // Crypto amount to sell
fiatAmount: bigint, // Fiat amount you'll receive
fee: bigint, // Total fee amount
rate: string, // Exchange rate
metadata: MoonPaySellQuoteMetadata
}getSupportedCryptoAssets()
Fetches the list of supported cryptocurrencies. Results are cached.
Returns: Promise\<MoonPaySupportedCryptoAsset[]\>
{
code: string, // Currency code (e.g., 'eth')
decimals: number, // Decimal places
networkCode: string, // Network identifier
name: string, // Display name
metadata: MoonPayCryptoCurrencyDetails
}getSupportedFiatCurrencies()
Fetches the list of supported fiat currencies. Results are cached.
Returns: Promise\<MoonPaySupportedFiatCurrency[]\>
{
code: string, // Currency code (e.g., 'usd')
decimals: number, // Decimal places
name: string, // Display name
metadata: MoonPayFiatCurrencyDetails
}getSupportedCountries()
Fetches the list of supported countries.
Returns: Promise\<MoonPaySupportedCountry[]\>
{
code: string, // ISO country code
name: string, // Country name
isBuyAllowed: boolean, // Buy operations allowed
isSellAllowed: boolean,// Sell operations allowed
metadata: MoonPayCountryDetail
}getTransactionDetail(txId, direction?)
Retrieves details of a specific transaction.
Parameters:
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
txId | string | Yes | - | MoonPay transaction ID |
direction | 'buy' | 'sell' | No | 'buy' | Transaction type |
Returns: Promise\<MoonPayTransactionDetail\>
{
status: 'completed' | 'failed' | 'in_progress',
cryptoAsset: string,
fiatCurrency: string,
metadata: MoonPayBuyTransaction | MoonPaySellTransaction
}Treat metadata as potentially sensitive provider data. Avoid logging or retaining the complete object when the application needs only the normalized status and asset fields.
Types
MoonPayProtocolConfig
interface MoonPayProtocolConfig {
apiKey: string;
signUrl?: (urlForSignature: string) => Promise<string>;
cacheTime?: number;
environment?: 'production' | 'sandbox';
}MoonPayBuyParams
Widget configuration options for buy() operations:
interface MoonPayBuyParams {
// UI options (shared with MoonPaySellParams)
colorCode?: string;
theme?: 'dark' | 'light';
themeId?: string;
language?: string;
showAllCurrencies?: boolean;
showOnlyCurrencies?: string;
showWalletAddressForm?: boolean;
redirectURL?: string;
unsupportedRegionRedirectUrl?: string;
skipUnsupportedRegionScreen?: boolean;
// Buy-specific options
defaultCurrencyCode?: string;
walletAddress?: string;
walletAddressTag?: string;
walletAddresses?: string;
walletAddressTags?: string;
contractAddress?: string;
networkCode?: string;
lockAmount?: boolean;
email?: string;
externalTransactionId?: string;
externalCustomerId?: string;
paymentMethod?: string;
}MoonPaySellParams
Widget configuration options for sell() operations:
interface MoonPaySellParams {
// UI options (shared with MoonPayBuyParams)
colorCode?: string;
theme?: 'dark' | 'light';
themeId?: string;
language?: string;
showAllCurrencies?: boolean;
showOnlyCurrencies?: string;
showWalletAddressForm?: boolean;
redirectURL?: string;
unsupportedRegionRedirectUrl?: string;
skipUnsupportedRegionScreen?: boolean;
// Sell-specific options
defaultBaseCurrencyCode?: string;
refundWalletAddresses?: string;
lockAmount?: boolean;
email?: string;
externalTransactionId?: string;
externalCustomerId?: string;
paymentMethod?: string;
}MoonPayQuoteBuyParams
interface MoonPayQuoteBuyParams {
extraFeePercentage?: number; // 0-10%
paymentMethod?: string;
areFeesIncluded?: boolean;
walletAddress?: string;
}MoonPayQuoteSellParams
interface MoonPayQuoteSellParams {
extraFeePercentage?: number; // 0-10%
payoutMethod?: string;
}HTTP request errors
Non-success HTTP responses from quoteBuy(), quoteSell(), getTransactionDetail(), getSupportedCryptoAssets(), getSupportedFiatCurrencies(), and getSupportedCountries() throw an ordinary Error. The message includes the HTTP status code, the reason phrase when supplied, and the response body when it is readable and non-empty. Body detail is trimmed and limited to 500 Unicode code points, followed by ... when truncated.
Treat error messages as potentially sensitive provider data. Redact them before displaying them to end users or sending them to logs or analytics. Network and response-parsing failures can have different messages; do not branch on the complete error text.
Next Steps
- Configuration - Setup and configuration options
- Usage Guide - Common usage patterns