MoonPay Trade Swidge API Reference

This reference covers @moonpay/wdk-protocol-swidge-moonpay-trade@0.2.0 and its @tetherto/wdk-wallet@1.0.0-beta.16 protocol types.

Exports

Import the default class, its named alias, and provider types from the package root:

import MoonPayTradeSwidgeProtocol, {
  type MoonPayTradeConfig,
  type MoonPayTradeSwidgeOptions,
  type SwidgeReadOnlyAccount,
  type SwidgeWritableAccount,
  type ISwidgeProtocol
} from '@moonpay/wdk-protocol-swidge-moonpay-trade'

The named class export is also MoonPayTradeSwidgeProtocol. All nine error classes are exported from this entrypoint. There are no public mapper or account-classification subpaths.

Constructor

The constructor has writable and read-only overloads:

new MoonPayTradeSwidgeProtocol(account: SwidgeWritableAccount, config: MoonPayTradeConfig)
new MoonPayTradeSwidgeProtocol(account: SwidgeReadOnlyAccount | undefined, config: MoonPayTradeConfig)

The account can be undefined for discovery, indicative quotes, and status lookups. config.apiKey is required. See constructor settings for all five configuration fields.

Account requirements

Execution recognizes these writable WDK account classes:

Install the wallet package for the account you use. The execution example pins the EVM wallet to 1.0.0-beta.16. The corresponding read-only account classes are accepted for read-only operations.

The 0.2.0 declarations import types from every optional wallet peer. TypeScript builds that check dependency declarations can therefore report missing-module errors when only one wallet is installed. Resolve those peer types or configure dependency-declaration checking according to your project policy; this does not change which wallet packages the JavaScript runtime needs.

Account recognition depends on constructor names in the prototype chain. Preserve these class names when bundling; a generic object with similarly named methods is not a supported writable account.

Account recognition does not verify network compatibility or establish that every deposit form works with every wallet version. The module forwards a single { to, value } object for native deposits and { token, recipient, amount } for token transfers. Verify that the chosen wallet accepts that shape, including any account-abstraction requirements. Native TON deposits can attach a memo through body; token deposits with a memo and non-TON native deposits with a memo throw UnsupportedDepositError. Sponsorship and relay policies belong to the wallet configuration.

Methods

Method summary

Method details

clearCache

clearCache(): void clears both caches for this instance. It does not cancel in-flight requests or affect another protocol instance.

quoteSwidge

quoteSwidge(options: MoonPayTradeSwidgeOptions): Promise<SwidgeQuote> calls GET /api/getQuote. Provide exactly one amount: fromTokenAmount for an exact-input preview or toTokenAmount for an exact-output preview.

The request includes token addresses, chain ids, amount, and direction. It does not forward recipient, refund address, slippage, or minimum-output options. If an account is bound, the module attempts to estimate deposit gas using a transfer to the account's own address; if estimation fails, it logs the raw wallet error to console.warn and returns the quote without that fee. Wallet errors can contain RPC request URLs, so configure credential redaction for captured console output before quoting.

swidge

swidge(options: MoonPayTradeSwidgeOptions, config?: SwidgeProtocolConfig): Promise<SwidgeResult> requires a recognized writable account. It requests a new decimal-amount quote from POST /api/postQuote, checks fees, minimum output, and the exact-input ceiling, creates a swap through POST /api/postSwap, and sends its deposit.

Use fromTokenAmount for execution. Although the type accepts toTokenAmount, the POST request does not send an exact-output direction selector; do not depend on exact-output execution semantics in this release.

The operation uses the provider's returned deposit address, rather than transaction calldata from the indicative quote. EVM token deposits use a direct token transfer, without a module-managed allowance or spender approval. The result does not wait for settlement.

getSwidgeStatus

getSwidgeStatus(id: string, options?: SwidgeStatusOptions): Promise<SwidgeStatusResult> calls GET /api/getStatus with txId: id. Pass the provider id returned by execution, not the source transaction hash. options.fromChain and options.toChain are accepted but ignored. An empty id throws a generic Error.

getSupportedChains

getSupportedChains(): Promise<SwidgeSupportedChain[]> fetches chain metadata and derives native symbols from provider token data. Each result has id, name, type, and nativeToken. The id is provider-specific; do not assume every non-EVM id uses an EVM chain-id standard.

Discovery is cached by instance. nativeToken can be empty when no native entry exists or caching is disabled. Listing a chain does not establish route liquidity or wallet compatibility.

getSupportedTokens

getSupportedTokens(options?: { fromChain?: string | number; fromToken?: string; toChain?: string | number }): Promise<SwidgeSupportedToken[]> fetches token metadata. Only fromChain filters the request; the other option fields are ignored.

Each result has token, chain, symbol, decimals, and address; name is included when supplied by the provider. token is an exact chainId:address identifier. Entries without a symbol are omitted. The result does not expose the provider's native-token flag.

A call without a filter requests all tokens each time. Chain-filtered calls reuse the cache. Token identity and decimal validation remain the application's responsibility.

swap

The inherited swap(options: SwapOptions): Promise<SwapResult> maps tokenIn, tokenOut, tokenInAmount or tokenOutAmount, to, and minAmountOut to execution. It does not supply fromChain, so token identifiers need an embedded chain. Its result uses the provider tracking id as hash and sums all itemized fee amounts into fee, even when their units differ.

Use swidge() to retain the actual transaction hash and itemized fees.

quoteSwap

The inherited quoteSwap(options: SwapOptions): Promise<Omit<SwapResult, 'hash'>> maps the same swap options to indicative quoting. It also sums fee amounts without denomination conversion. Use quoteSwidge() when displaying fees or working with explicit chains.

bridge

The inherited bridge(options: BridgeOptions): Promise<BridgeResult> passes options.token as both source and destination token, targetChain as toChain, and amount as the input. It cannot express different source and destination token identifiers.

A plain token lacks the required source chain, while an embedded token chain overrides the destination fallback. Use swidge() with independently discovered source and destination identifiers for cross-chain operations. The inherited result places the tracking id in hash, sums network fees into fee, and sums protocol fees into bridgeFee without converting denominations.

quoteBridge

The inherited quoteBridge(options: BridgeOptions): Promise<Omit<BridgeResult, 'hash'>> applies the same token mapping and fee aggregation to indicative quoting. The same chain-resolution limitation applies; use quoteSwidge() for an explicit cross-chain route.

Route options

MoonPayTradeSwidgeOptions extends the core SwidgeOptions with optional fromChain.

The application must enforce positive amounts, exactly one amount field, valid recipient addresses, a supported token pair, and an accepted slippage range. JavaScript runtime calls do not enforce the type's mutually exclusive amount fields: when both exist, fromTokenAmount wins.

Results and fees

Quote

SwidgeQuote contains fromTokenAmount, toTokenAmount, toTokenAmountMin, and fees. Token amounts and fee amounts are bigint. Optional estimatedDuration, priceImpact, and expiry pass through provider values. The core contract defines duration in seconds, impact as a decimal, and expiry as Unix seconds.

Execution result

SwidgeResult contains the tracking id, source hash, fees, input amount, expected output amount, and a transactions array with the source transaction. This release does not populate toTokenAmountMin in the execution result, even though the core type allows it.

Fee categories

Fee token values are plain addresses, with the chain in the separate chain field. Deposit gas uses the zero address as its native-token marker. Previews can omit this gas entry if no account is bound, estimation fails, or the reported value is zero. Execution uses the fee value returned by the wallet; the EVM wallet used in the guide returns an estimate, not a receipt-derived final gas cost.

Do not add fee amounts across different tokens or chains. The module does not establish a total cost in a common currency, and provider fee entries do not specify the optional included flag.

Status

SwidgeStatusResult contains status and optional source/destination transactions when the provider reports their hashes.

Status matching is case-insensitive. Unmapped statuses normally throw UnknownStatusError, but version 0.2.0 does not validate every malformed response. Validate the returned status against the values in this table before updating an operation, as shown in the execution guide. The wider core enum also contains partial and action-required, but this module has no mapping to those values in 0.2.0.

Errors

All error classes below are public root exports.

Network failures, invalid JSON, malformed amounts, invalid configuration conversions, and wallet errors can propagate as other errors. These classes do not guarantee that a provider swap or wallet transaction was never created. Use the recovery guidance before retrying execution.

Next Steps

Need Help?