https://github.com/tetherto/wdk-protocol-fiat-moonpay
https://github.com/tetherto/wdk-protocol-fiat-moonpay
Last synced: about 1 month ago
JSON representation
- Host: GitHub
- URL: https://github.com/tetherto/wdk-protocol-fiat-moonpay
- Owner: tetherto
- License: apache-2.0
- Created: 2025-11-24T15:05:53.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-06-16T12:32:29.000Z (about 1 month ago)
- Last Synced: 2026-06-16T14:22:48.275Z (about 1 month ago)
- Language: JavaScript
- Size: 391 KB
- Stars: 1
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# @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
```bash
npm install @tetherto/wdk-protocol-fiat-moonpay
```
## 🚀 Quick Start
### Basic Usage
```javascript
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
```javascript
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` |
| `sell(options)` | Generates a widget URL to sell crypto | `Promise` |
| `quoteBuy(options)` | Gets a quote for a crypto asset purchase | `Promise` |
| `quoteSell(options)` | Gets a quote for a crypto asset sale | `Promise` |
| `getTransactionDetail(txId, direction)` | Retrieves the details of a transaction | `Promise` |
| `getSupportedCryptoAssets()` | Retrieves a list of supported crypto assets | `Promise` |
| `getSupportedFiatCurrencies()` | Retrieves a list of supported fiat currencies | `Promise` |
| `getSupportedCountries()` | Retrieves a list of supported countries | `Promise` |
#### `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](https://dev.moonpay.com/docs/ramps-sdk-buy-params) for the full list of parameters.
- The `apiKey` can be retrieved through [MoonPay dashboard](https://dashboard.moonpay.com/).
- It is highly recommended to test the entire buy/sell flow in the `sandbox` environment. Read more [here](https://dev.moonpay.com/docs/faq-sandbox-testing).
## 🔒 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
```bash
# Install dependencies
npm install
# Build TypeScript definitions
npm run build:types
# Lint code
npm run lint
# Fix linting issues
npm run lint:fix
```
### Testing
```bash
# 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.