@moonpay/wdk-protocol-swidge-moonpay-trade

WDK Swidge protocol module for MoonPay Trade. Implements ISwidgeProtocol from @tetherto/wdk-wallet v1.0.0-beta.9, wrapping MoonPay's SwapsXYZ API swap and bridge infrastructure.

Installation

npm install @moonpay/wdk-protocol-swidge-moonpay-trade

Usage

import MoonPayTradeSwidgeProtocol from '@moonpay/wdk-protocol-swidge-moonpay-trade';

const protocol = new MoonPayTradeSwidgeProtocol(account, {
  apiKey: process.env.SWAPS_XYZ_KEY,
});

// Discover supported tokens
const chains = await protocol.getSupportedChains();
const tokens = await protocol.getSupportedTokens({ fromChain: 1 }); // Ethereum

// Quote
const quote = await protocol.quoteSwidge({
  fromToken: '1:0xdAC17F958D2ee523a2206206994597C13D831ec7',   // USDT on Ethereum
  toToken: '8453:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC on Base
  fromTokenAmount: 10_000_000n, // 10 USDT (6 decimals)
});

// Execute (requires full IWalletAccount)
const result = await protocol.swidge({ /* same options */ });

// Poll status
const status = await protocol.getSwidgeStatus(result.id);

See examples/e2e.mjs for a complete runnable example.

Token identifiers

Tokens are identified as "<chainId>:<tokenAddress>". Use getSupportedTokens() to discover valid identifiers:

const tokens = await protocol.getSupportedTokens({ fromChain: 1 });
// e.g. { token: '1:0xA0b8...', chain: 1, symbol: 'USDC', decimals: 6 }

Configuration

| Option | Type | Required | Default | Description | |---|---|---|---|---| | apiKey | string | ✅ | — | x-api-key credential for SwapsXYZ API | | baseUrl | string | | https://api-v2.swaps.xyz | SwapsXYZ API base URL | | maxProtocolFeeBps | number \| bigint | | — | Reject swidge if protocol fee exceeds this bps | | maxNetworkFeeBps | number \| bigint | | — | Reject swidge if network fee exceeds this bps | | cacheTtlMs | number | | 600000 (10 min) | Token/chain list cache TTL. Set 0 to disable. |

Status mapping

| SwapsXYZ API status | SwidgeStatus | |---|---| | pending, submitted, approval_*, payout_created | pending | | success, completed | completed | | failed | failed | | requires refund, refund_requested | refund-pending | | refunded | refunded | | expired | expired | | cancelled | cancelled |

Fee mapping

| SwapsXYZ API field | SwidgeFeeType | Notes | |---|---|---| | applicationFee + protocolFee | protocol | MoonPay spread + underlying protocol fee (both summed) | | bridgeFee | network | Gas / bridge infrastructure cost |

Error types

| Class | Thrown when | |---|---| | AccountRequiredError | swidge() called without a full IWalletAccount | | FeeLimitExceededError | Fee guard (maxProtocolFeeBps / maxNetworkFeeBps) exceeded; .feeType, .actualBps, .limitBps available | | ProviderApiError | SwapsXYZ API returns a non-2xx response; .endpoint, .status, .responseBody available | | UnknownStatusError | getSwidgeStatus() receives an unrecognised status string; .rawStatus available | | InvalidTokenIdError | Token identifier is not in "<chainId>:<address>" format; .tokenId available |

Supported chains and tokens

Chains and tokens are dynamically discovered from the SwapsXYZ API at runtime:

const chains = await protocol.getSupportedChains(); // all chains
const tokens = await protocol.getSupportedTokens(); // all tokens
const ethTokens = await protocol.getSupportedTokens({ fromChain: 1 }); // Ethereum only

Results are cached for 10 minutes by default (configurable via cacheTtlMs).

Support

• Security vulnerabilities: see SECURITY.md
• General support: moonpay.com