@tetherto/wdk-protocol-fiat-moonpay

Note: This package is in beta. Please test in a dev setup first.

A simple way to integrate MoonPay widget for on-ramp and off-ramp services. You can generate signed or unsigned URLs for the MoonPay widget, get quotes for buying and selling crypto, and read protocol-related data. This package can be used in both frontend and backend environments.

🔍 About WDK

This is part of WDK (Wallet Development Kit). WDK helps you build safe, non‑custody wallets. Read more at https://docs.wallet.tether.io.

🌟 Features

• Generate signed or unsigned widget URL to buy Crypto (On-ramp)
• Generate signed or unsigned widget URL to sell Crypto (Off-ramp)
• Get quotes (buy and sell)
• Get supported currencies, countries
• Get buy/sell transaction details

⬇️ Installation

npm install @tetherto/wdk-protocol-fiat-moonpay

🚀 Quick Start

Basic Usage

import MoonPayProtocol from '@tetherto/wdk-protocol-fiat-moonpay'

const signUrl = async (urlForSignature) => {
  const response = await fetch('https://your-backend.example.com/moonpay/sign-url', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ urlForSignature })
  })

  if (!response.ok) {
    throw new Error(`Failed to sign MoonPay URL: ${response.status} ${response.statusText}`)
  }

  const { signedUrl } = await response.json()

  return signedUrl
}

// Initialize protocol
const moonpay = new MoonPayProtocol(undefined, {
  apiKey: 'YOUR_PUBLISHABLE_API_KEY',
  signUrl,
  environment: 'sandbox'
})

// Get a buy quote
const buyQuote = await moonpay.quoteBuy({
  fiatCurrency: 'usd',
  cryptoAsset: 'eth',
  fiatAmount: 100
})

// Generate a buy widget URL
const { buyUrl } = await moonpay.buy({
  fiatCurrency: 'usd',
  cryptoAsset: 'eth',
  fiatAmount: 100,
  recipient: '0xabc'
})

console.log('Buy URL:', buyUrl)

// Get a sell quote
const sellQuote = await moonpay.quoteSell({
  fiatCurrency: 'usd',
  cryptoAsset: 'eth',
  cryptoAmount: 100
})

// Generate a sell widget URL
const { sellUrl } = await moonpay.sell({
  fiatCurrency: 'usd',
  cryptoAsset: 'eth',
  cryptoAmount: 100,
  refundAddress: '0xabc'
})

📚 API Reference

MoonPayProtocol

Main class for MoonPay integration.

Constructor

new MoonPayProtocol(account, config)

Parameters:

• account (IWalletAccount | IWalletAccountReadOnly | undefined): The wallet account to use to interact with the protocol
• config (object): The protocol config
  • apiKey (string): Your publishable Moonpay API key.
  • signUrl (function, optional): Callback used to sign buy/sell URLs via a trusted provider (e.g., a backend service). If not provided, the protocol returns unsigned URLs.
  • cacheTime (number, optional): The duration in milliseconds to cache supported currencies.
  • environment ("production" | "sandbox", optional): The environment to use for MoonPay endpoints and widget URLs. Defaults to "production". Use "production" for live transactions and "sandbox" for testing with non-real funds.

Methods

| Method | Description | Returns | |--------|-------------|---------| | buy(options) | Generates a widget URL to purchase crypto | Promise<BuyResult> | | sell(options) | Generates a widget URL to sell crypto | Promise<SellResult> | | quoteBuy(options) | Gets a quote for a crypto asset purchase | Promise<MoonPayBuyQuote> | | quoteSell(options) | Gets a quote for a crypto asset sale | Promise<MoonPaySellQuote> | | getTransactionDetail(txId, direction) | Retrieves the details of a transaction | Promise<MoonPayTransactionDetail> | | getSupportedCryptoAssets() | Retrieves a list of supported crypto assets | Promise<MoonPaySupportedCryptoAsset[]> | | getSupportedFiatCurrencies() | Retrieves a list of supported fiat currencies | Promise<MoonPaySupportedFiatCurrency[]> | | getSupportedCountries() | Retrieves a list of supported countries | Promise<MoonPaySupportedCountry[]> |

buy(options)

Generates a widget URL to purchase crypto.

Options:

• fiatCurrency (string): The fiat currency code (e.g., 'usd').
• cryptoAsset (string): The crypto asset code (e.g., 'eth').
• fiatAmount (number, optional): The amount in fiat currency.
• cryptoAmount (number, optional): The amount in crypto asset.
• recipient (string, optional): The wallet address to receive funds. If not provided, uses the account address.
• config (object, optional): Additional MoonPay widget parameters.

sell(options)

Generates a widget URL to sell crypto.

Options:

• fiatCurrency (string): The fiat currency code (e.g., 'usd').
• cryptoAsset (string): The crypto asset code (e.g., 'eth').
• fiatAmount (number, optional): The amount in fiat currency.
• cryptoAmount (number, optional): The amount in crypto asset.
• refundAddress (string, optional): The wallet address for refunds. If not provided, uses the account address.
• config (object, optional): Additional MoonPay widget parameters.

quoteBuy(options)

Gets a quote for a crypto asset purchase.

Options:

• fiatCurrency (string): The fiat currency code.
• cryptoAsset (string): The crypto asset code.
• fiatAmount (number, optional): The amount in fiat currency.
• cryptoAmount (number, optional): The amount in crypto asset.
• config (object, optional): Additional MoonPay quote parameters.

quoteSell(options)

Gets a quote for a crypto asset sale.

Options:

• fiatCurrency (string): The fiat currency code.
• cryptoAsset (string): The crypto asset code.
• cryptoAmount (number): The amount in crypto asset (Required).
• config (object, optional): Additional MoonPay quote parameters.

getTransactionDetail(txId, direction)

Retrieves the details of a transaction.

Parameters:

• txId (string): The transaction ID.
• direction ('buy' | 'sell'): The direction of the transaction. Defaults to 'buy'.

getSupportedCryptoAssets()

Retrieves a list of supported crypto assets.

getSupportedFiatCurrencies()

Retrieves a list of supported fiat currencies.

getSupportedCountries()

Retrieves a list of supported countries.

📝 Notes

• Works with networks and currencies supported by MoonPay.
• Check MoonPay documentation for the full list of widget parameters, supported cryptocurrencies and regions.
• The package provides the baseline for MoonPay integration. To fully utilize the power of MoonPay widget, take a look at MoonPay documentation for the full list of parameters.
• The apiKey can be retrieved through MoonPay dashboard.
• It is highly recommended to test the entire buy/sell flow in the sandbox environment. Read more here.

🔒 Security Considerations

• Keep your secretKey safe on your backend. Expose a backend signing API to clients, and have signUrl call that API to retrieve the signed MoonPay URL.

🛠️ Development

Building

# Install dependencies
npm install

# Build TypeScript definitions
npm run build:types

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

Testing

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

📜 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🆘 Support

For support, please open an issue on the GitHub repository.