@moonpay/wdk-protocol-swidge-moonpay-trade 0.0.0 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.1] - 2026-07-09
+
+### Fixed
+- Default `baseUrl` changed from testing URL `box-v2.api.decent.xyz` to public `api-v2.swaps.xyz`
+- Renamed env vars: `BOX_API_KEY` → `SWAPS_XYZ_KEY`, `BOX_API_BASE_URL` → `SWAPS_XYZ_BASE_URL`
+
+## [0.1.0] - 2026-07-07
+
+### Added
+- `MoonPayTradeSwidgeProtocol` — implements `ISwidgeProtocol` from `@tetherto/wdk-wallet`
+- `quoteSwidge` — non-binding quote via `GET /api/getQuote`
+- `swidge` — deposit-based swap via `POST /api/postQuote` + `POST /api/postSwap`
+- `getSwidgeStatus` — status polling via `GET /api/getStatus`
+- `getSupportedChains` — chain discovery via `GET /api/getChainList`
+- `getSupportedTokens` — token discovery via `GET /api/getTokenList` with optional `fromChain` filter
+- Fee guards (`maxProtocolFeeBps`, `maxNetworkFeeBps`) at constructor and per-call level
+- Module-level TTL cache (default 10 min) shared across instances pointing to the same base URL
+- Typed errors: `AccountRequiredError`, `FeeLimitExceededError`, `ProviderApiError`, `UnknownStatusError`, `InvalidTokenIdError`

package/README.md

@@ -0,0 +1,107 @@
+# @moonpay/wdk-protocol-swidge-moonpay-trade
+
+[![Powered by WDK](https://img.shields.io/badge/Powered%20by-WDK-purple)](https://docs.wdk.tether.io)
+[![npm](https://img.shields.io/npm/v/@moonpay/wdk-protocol-swidge-moonpay-trade)](https://www.npmjs.com/package/@moonpay/wdk-protocol-swidge-moonpay-trade)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
+
+WDK Swidge protocol module for MoonPay Trade. Implements [`ISwidgeProtocol`](https://github.com/tetherto/wdk-wallet/blob/main/src/protocols/swidge-protocol.js) from `@tetherto/wdk-wallet` v1.0.0-beta.9, wrapping MoonPay's SwapsXYZ API swap and bridge infrastructure.
+
+## Installation
+
+```bash
+npm install @moonpay/wdk-protocol-swidge-moonpay-trade
+```
+
+## Usage
+
+```js
+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`](examples/e2e.mjs) for a complete runnable example.
+
+## Token identifiers
+
+Tokens are identified as `"<chainId>:<tokenAddress>"`. Use `getSupportedTokens()` to discover valid identifiers:
+
+```js
+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:
+
+```js
+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](SECURITY.md)
+- General support: [moonpay.com](https://www.moonpay.com)

package/SECURITY.md

@@ -0,0 +1,9 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+To report a security vulnerability, please email security@moonpay.com.
+
+Do not open a public GitHub issue for security vulnerabilities.
+
+We will respond within 5 business days and aim to publish a fix within 30 days.

package/dist/MoonPayTradeSwidgeProtocol.d.ts

@@ -0,0 +1,124 @@
+import type { IWalletAccount, IWalletAccountReadOnly } from '@tetherto/wdk-wallet';
+import type { SwidgeOptions, SwidgeProtocolConfig, SwidgeQuote, SwidgeResult, SwidgeStatusOptions, SwidgeStatusResult, SwidgeSupportedChain, SwidgeSupportedToken } from '@tetherto/wdk-wallet/protocols';
+import { SwidgeProtocol } from '@tetherto/wdk-wallet/protocols';
+/** Configuration passed to the MoonPayTradeSwidgeProtocol constructor. */
+export interface MoonPayTradeConfig {
+    /** Required. The `x-api-key` credential for SwapsXYZ API. */
+    apiKey: string;
+    /**
+     * Base URL for SwapsXYZ API requests.
+     * @default https://api-v2.swaps.xyz
+     */
+    baseUrl?: string;
+    /**
+     * Maximum acceptable protocol fee in basis points of the input amount.
+     * Overrides the per-call `config.maxProtocolFeeBps` when not set per call.
+     */
+    maxProtocolFeeBps?: number | bigint;
+    /**
+     * Maximum acceptable network fee in basis points of the input amount.
+     * Overrides the per-call `config.maxNetworkFeeBps` when not set per call.
+     */
+    maxNetworkFeeBps?: number | bigint;
+    /**
+     * TTL for the token/chain list cache in milliseconds.
+     * Set to 0 to disable caching.
+     * @default 600000 (10 minutes)
+     */
+    cacheTtlMs?: number;
+}
+/**
+ * WDK Swidge protocol implementation for MoonPay Trade (SwapsXYZ API).
+ *
+ * Token identifiers use the format `"<chainId>:<tokenAddress>"`,
+ * e.g. `"1:0xdAC17F958D2ee523a2206206994597C13D831ec7"` for USDT on Ethereum.
+ *
+ * @example
+ * ```js
+ * import MoonPayTradeSwidgeProtocol from '@moonpay/wdk-protocol-swidge-moonpay-trade';
+ *
+ * const protocol = new MoonPayTradeSwidgeProtocol(account, { apiKey: process.env.SWAPS_XYZ_KEY });
+ * const quote = await protocol.quoteSwidge({ fromToken: '1:0x...', toToken: '10:0x...', fromTokenAmount: 1000000n });
+ * const result = await protocol.swidge({ fromToken: '1:0x...', toToken: '10:0x...', fromTokenAmount: 1000000n });
+ * const status = await protocol.getSwidgeStatus(result.id);
+ * ```
+ */
+export default class MoonPayTradeSwidgeProtocol extends SwidgeProtocol {
+    #private;
+    /**
+     * @param account - Wallet account. Pass `IWalletAccount` for full access (required by
+     *   `swidge`), `IWalletAccountReadOnly` for quote/status/discovery only, or `undefined`
+     *   for quote and discovery only.
+     * @param config - Provider configuration including the required SwapsXYZ API key.
+     */
+    constructor(account: IWalletAccount | IWalletAccountReadOnly | undefined, config: MoonPayTradeConfig);
+    /** Clear the shared module-level cache. Useful in tests or to force a refresh. */
+    static clearCache(): void;
+    /**
+     * Returns a non-binding quote for a swap or bridge operation.
+     *
+     * Can be called without a wallet account.
+     *
+     * @param options - Source/destination tokens, amount, and optional routing hints.
+     * @returns Quote including `fromTokenAmount`, `toTokenAmount`, `toTokenAmountMin`, and
+     *   a non-empty `fees` array.
+     * @throws {InvalidTokenIdError} If `fromToken` or `toToken` is not in `"<chainId>:<address>"` format.
+     * @throws {ProviderApiError} If the SwapsXYZ API request fails.
+     */
+    quoteSwidge(options: SwidgeOptions): Promise<SwidgeQuote>;
+    /**
+     * Executes a swap or bridge operation using the deposit-address flow.
+     *
+     * Internally calls POST /api/postQuote (expects decimal amounts) then POST /api/postSwap.
+     * Token decimals are fetched from GET /api/getTokenList and cached to convert
+     * WDK base-unit bigint amounts ↔ the decimal strings postQuote requires.
+     *
+     * @param options - Same shape as `quoteSwidge`. No quote object is accepted.
+     * @param config - Optional per-call fee overrides.
+     * @returns Execution result including `id` (swapId) to pass to `getSwidgeStatus`.
+     * @throws {AccountRequiredError} If no account or a read-only account was given at construction.
+     * @throws {FeeLimitExceededError} If a fee guard is exceeded.
+     * @throws {InvalidTokenIdError} If `fromToken` or `toToken` is not in `"<chainId>:<address>"` format.
+     * @throws {ProviderApiError} If a SwapsXYZ API request fails.
+     */
+    swidge(options: SwidgeOptions, config?: SwidgeProtocolConfig): Promise<SwidgeResult>;
+    /**
+     * Returns the current status of an in-flight swap or bridge.
+     *
+     * Poll until the returned `status` is terminal:
+     * `completed`, `failed`, `refunded`, `cancelled`, `expired`, or `partial`.
+     *
+     * @param id - The `id` returned by `swidge`.
+     * @param _options - Optional chain hints (currently unused).
+     * @returns Current status and any associated on-chain transaction hashes.
+     * @throws {UnknownStatusError} If the provider returns an unrecognised status.
+     * @throws {ProviderApiError} If the SwapsXYZ API request fails or the id is not found.
+     */
+    getSwidgeStatus(id: string, _options?: SwidgeStatusOptions): Promise<SwidgeStatusResult>;
+    /**
+     * Returns the chains supported by MoonPay Trade for swidge operations.
+     *
+     * Calls GET /api/getChainList and enriches each entry with the native token symbol
+     * sourced from box-common static data (no extra API call needed).
+     * Results are cached with TTL (default 10 min).
+     *
+     * @throws {ProviderApiError} If the getChainList request fails.
+     */
+    getSupportedChains(): Promise<SwidgeSupportedChain[]>;
+    /**
+     * Returns the tokens supported by MoonPay Trade for swidge operations.
+     *
+     * When `options.fromChain` is provided, fetches only that chain's tokens.
+     * Otherwise fetches all chains in a single request.
+     * Results are cached with TTL (default 10 min).
+     *
+     * @param options - Optional `fromChain` filter (other fields are not used by this provider).
+     * @throws {ProviderApiError} If the getTokenList request fails.
+     */
+    getSupportedTokens(options?: {
+        fromChain?: string | number;
+        fromToken?: string;
+        toChain?: string | number;
+    }): Promise<SwidgeSupportedToken[]>;
+}
+//# sourceMappingURL=MoonPayTradeSwidgeProtocol.d.ts.map

package/dist/MoonPayTradeSwidgeProtocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MoonPayTradeSwidgeProtocol.d.ts","sourceRoot":"","sources":["../src/MoonPayTradeSwidgeProtocol.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AACnF,OAAO,KAAK,EACV,aAAa,EACb,oBAAoB,EACpB,WAAW,EACX,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACrB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AA6BhE,0EAA0E;AAC1E,MAAM,WAAW,kBAAkB;IACjC,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACpC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACnC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,OAAO,OAAO,0BAA2B,SAAQ,cAAc;;IAOpE;;;;;OAKG;gBAED,OAAO,EAAE,cAAc,GAAG,sBAAsB,GAAG,SAAS,EAC5D,MAAM,EAAE,kBAAkB;IAkB5B,kFAAkF;IAClF,MAAM,CAAC,UAAU,IAAI,IAAI;IA0DzB;;;;;;;;;;OAUG;IACY,WAAW,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,CAAC;IAoBxE;;;;;;;;;;;;;;OAcG;IACY,MAAM,CACnB,OAAO,EAAE,aAAa,EACtB,MAAM,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,YAAY,CAAC;IAoFxB;;;;;;;;;;;OAWG;IACY,eAAe,CAC5B,EAAE,EAAE,MAAM,EACV,QAAQ,CAAC,EAAE,mBAAmB,GAC7B,OAAO,CAAC,kBAAkB,CAAC;IAM9B;;;;;;;;OAQG;IACY,kBAAkB,IAAI,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAkBpE;;;;;;;;;OASG;IACY,kBAAkB,CAAC,OAAO,CAAC,EAAE;QAC1C,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;KAC3B,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;CA4BpC"}

package/dist/errors.d.ts

@@ -0,0 +1,35 @@
+/** Thrown when swidge() is called without a full (signing-capable) wallet account. */
+export declare class AccountRequiredError extends Error {
+    readonly name = "AccountRequiredError";
+    constructor();
+}
+/** Thrown when a fee guard (maxProtocolFeeBps or maxNetworkFeeBps) is exceeded. */
+export declare class FeeLimitExceededError extends Error {
+    readonly feeType: 'protocol' | 'network';
+    readonly actualBps: bigint;
+    readonly limitBps: bigint;
+    readonly name = "FeeLimitExceededError";
+    constructor(feeType: 'protocol' | 'network', actualBps: bigint, limitBps: bigint);
+}
+/** Thrown when the provider returns a status value that cannot be mapped to SwidgeStatus. */
+export declare class UnknownStatusError extends Error {
+    readonly rawStatus: string;
+    readonly name = "UnknownStatusError";
+    constructor(rawStatus: string);
+}
+/** Thrown when a token identifier does not match the expected "<chainId>:<address>" format. */
+export declare class InvalidTokenIdError extends Error {
+    readonly tokenId: string;
+    readonly name = "InvalidTokenIdError";
+    constructor(tokenId: string);
+}
+/** Thrown when the provider API returns a non-2xx response. */
+export declare class ProviderApiError extends Error {
+    readonly endpoint: string;
+    readonly status: number;
+    readonly name = "ProviderApiError";
+    /** Truncated response body — inspect this field for debugging, not error.message. */
+    readonly responseBody: string;
+    constructor(endpoint: string, status: number, body: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAcA,sFAAsF;AACtF,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,SAAkB,IAAI,0BAA0B;;CAIjD;AAED,mFAAmF;AACnF,qBAAa,qBAAsB,SAAQ,KAAK;aAG5B,OAAO,EAAE,UAAU,GAAG,SAAS;aAC/B,SAAS,EAAE,MAAM;aACjB,QAAQ,EAAE,MAAM;IAJlC,SAAkB,IAAI,2BAA2B;gBAE/B,OAAO,EAAE,UAAU,GAAG,SAAS,EAC/B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM;CAInC;AAED,6FAA6F;AAC7F,qBAAa,kBAAmB,SAAQ,KAAK;aAEf,SAAS,EAAE,MAAM;IAD7C,SAAkB,IAAI,wBAAwB;gBAClB,SAAS,EAAE,MAAM;CAG9C;AAED,+FAA+F;AAC/F,qBAAa,mBAAoB,SAAQ,KAAK;aAEhB,OAAO,EAAE,MAAM;IAD3C,SAAkB,IAAI,yBAAyB;gBACnB,OAAO,EAAE,MAAM;CAG5C;AAED,+DAA+D;AAC/D,qBAAa,gBAAiB,SAAQ,KAAK;aAKvB,QAAQ,EAAE,MAAM;aAChB,MAAM,EAAE,MAAM;IALhC,SAAkB,IAAI,sBAAsB;IAC5C,qFAAqF;IACrF,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;gBAEZ,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EAC9B,IAAI,EAAE,MAAM;CAMf"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type { ISwidgeProtocol } from '@tetherto/wdk-wallet/protocols';
+export { AccountRequiredError, FeeLimitExceededError, InvalidTokenIdError, ProviderApiError, UnknownStatusError, } from './errors.js';
+export type { MoonPayTradeConfig } from './MoonPayTradeSwidgeProtocol.js';
+export { default, default as MoonPayTradeSwidgeProtocol } from './MoonPayTradeSwidgeProtocol.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAeA,YAAY,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACtE,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,EAAE,OAAO,EAAE,OAAO,IAAI,0BAA0B,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/index.js

@@ -0,0 +1,448 @@
+import { getNativeTokenInfo } from '@decent.xyz/box-common';
+import { formatUnits, parseUnits } from 'viem';
+import { SwidgeProtocol } from '@tetherto/wdk-wallet/protocols';
+
+// src/errors.ts
+var AccountRequiredError = class extends Error {
+  name = "AccountRequiredError";
+  constructor() {
+    super("swidge requires a full wallet account \u2014 pass an IWalletAccount at construction");
+  }
+};
+var FeeLimitExceededError = class extends Error {
+  constructor(feeType, actualBps, limitBps) {
+    super(`${feeType} fee ${actualBps}bps exceeds configured maximum ${limitBps}bps`);
+    this.feeType = feeType;
+    this.actualBps = actualBps;
+    this.limitBps = limitBps;
+  }
+  feeType;
+  actualBps;
+  limitBps;
+  name = "FeeLimitExceededError";
+};
+var UnknownStatusError = class extends Error {
+  constructor(rawStatus) {
+    super(`Unknown swap status: "${rawStatus}"`);
+    this.rawStatus = rawStatus;
+  }
+  rawStatus;
+  name = "UnknownStatusError";
+};
+var InvalidTokenIdError = class extends Error {
+  constructor(tokenId) {
+    super(`Invalid SwapsXYZ token identifier: "${tokenId}" (expected "<chainId>:<address>")`);
+    this.tokenId = tokenId;
+  }
+  tokenId;
+  name = "InvalidTokenIdError";
+};
+var ProviderApiError = class extends Error {
+  constructor(endpoint, status, body) {
+    super(`SwapsXYZ ${endpoint} failed [${status}]`);
+    this.endpoint = endpoint;
+    this.status = status;
+    this.responseBody = body.slice(0, 500);
+  }
+  endpoint;
+  status;
+  name = "ProviderApiError";
+  /** Truncated response body — inspect this field for debugging, not error.message. */
+  responseBody;
+};
+function formatBaseUnitsToDecimal(baseUnits, decimals) {
+  const value = typeof baseUnits === "string" ? BigInt(baseUnits) : baseUnits;
+  return formatUnits(value, decimals);
+}
+function parseDecimalFeeToBaseUnits(decimalAmount, decimals) {
+  const trimmed = decimalAmount.trim();
+  if (!trimmed || !/^[0-9.]+$/.test(trimmed)) {
+    throw new Error(`Invalid decimal amount: "${decimalAmount}"`);
+  }
+  return parseUnits(trimmed, decimals);
+}
+function parseTokenId(tokenId) {
+  const colon = tokenId.indexOf(":");
+  if (colon < 1) throw new InvalidTokenIdError(tokenId);
+  const chainId = Number(tokenId.slice(0, colon));
+  if (!Number.isInteger(chainId) || chainId <= 0) throw new InvalidTokenIdError(tokenId);
+  return { chainId, address: tokenId.slice(colon + 1) };
+}
+function paymentAmountToBigInt(amount) {
+  const dot = amount.indexOf(".");
+  return BigInt(dot >= 0 ? amount.slice(0, dot) : amount);
+}
+function paymentToFeeFromQuote(payment, type) {
+  return {
+    type,
+    amount: paymentAmountToBigInt(payment.amount),
+    token: `${payment.chainId}:${payment.address}`,
+    chain: payment.chainId
+  };
+}
+function toSwidgeQuote(response) {
+  const fees = [
+    paymentToFeeFromQuote(response.applicationFee, "protocol")
+    // our spread
+  ];
+  if (response.bridgeFee) {
+    fees.push(paymentToFeeFromQuote(response.bridgeFee, "network"));
+  }
+  const protocolFeeAmount = paymentAmountToBigInt(response.protocolFee.amount);
+  if (protocolFeeAmount > 0n) {
+    fees.push(paymentToFeeFromQuote(response.protocolFee, "other"));
+  }
+  return {
+    fromTokenAmount: paymentAmountToBigInt(response.amountIn.amount),
+    toTokenAmount: paymentAmountToBigInt(response.amountOut.amount),
+    toTokenAmountMin: paymentAmountToBigInt(response.amountOutMin.amount),
+    fees,
+    estimatedDuration: response.estimatedTxTime,
+    priceImpact: response.estimatedPriceImpact,
+    expiry: response.expiryUnix
+  };
+}
+function toSwidgeResult(quote, swap, srcChainId, srcTokenAddress, fromDecimals, toDecimals) {
+  const fromToken = `${srcChainId}:${srcTokenAddress}`;
+  const fees = [
+    {
+      type: "protocol",
+      amount: parseDecimalFeeToBaseUnits(quote.applicationFee, fromDecimals),
+      token: fromToken,
+      chain: srcChainId
+    },
+    {
+      type: "network",
+      amount: parseDecimalFeeToBaseUnits(quote.bridgeFee, fromDecimals),
+      token: fromToken,
+      chain: srcChainId
+    }
+  ];
+  const protocolFeeAmount = parseDecimalFeeToBaseUnits(quote.protocolFee, fromDecimals);
+  if (protocolFeeAmount > 0n) {
+    fees.push({ type: "other", amount: protocolFeeAmount, token: fromToken, chain: srcChainId });
+  }
+  return {
+    id: swap.swapId,
+    fees,
+    fromTokenAmount: parseDecimalFeeToBaseUnits(quote.amount, fromDecimals),
+    toTokenAmount: parseDecimalFeeToBaseUnits(quote.amountTo, toDecimals),
+    transactions: [{ hash: swap.swapId, type: "source", chain: srcChainId }]
+  };
+}
+var STATUS_MAP = {
+  // box-backend StatusMessage values
+  pending: "pending",
+  submitted: "pending",
+  rent_gas_submitted: "pending",
+  rent_gas_completed: "pending",
+  approval_submitted: "pending",
+  approval_success: "pending",
+  success: "completed",
+  completed: "completed",
+  failed: "failed",
+  "requires refund": "refund-pending",
+  refunded: "refunded",
+  expired: "expired",
+  // altvm TransactionStatus values
+  payout_created: "pending",
+  refund_requested: "refund-pending",
+  cancelled: "cancelled"
+};
+function toSwidgeSupportedChain(chain, nativeSymbol) {
+  return {
+    id: chain.chainId,
+    name: chain.name,
+    type: chain.vmId,
+    nativeToken: nativeSymbol
+  };
+}
+function toSwidgeSupportedToken(token, chainId) {
+  if (!token.symbol) return null;
+  return {
+    token: `${chainId}:${token.address}`,
+    chain: chainId,
+    symbol: token.symbol,
+    decimals: token.decimals,
+    address: token.address,
+    ...token.name ? { name: token.name } : {}
+  };
+}
+function toSwidgeStatusResult(response) {
+  const rawStatus = response.status?.toLowerCase?.() ?? "";
+  const mapped = STATUS_MAP[rawStatus];
+  if (!mapped) throw new UnknownStatusError(response.status ?? "");
+  const transactions = [];
+  if (response.srcTxHash) {
+    transactions.push({ hash: response.srcTxHash, type: "source", chain: response.srcChainId });
+  }
+  if (response.dstTxHash) {
+    transactions.push({
+      hash: response.dstTxHash,
+      type: "destination",
+      chain: response.dstChainId
+    });
+  }
+  return {
+    status: mapped,
+    transactions: transactions.length > 0 ? transactions : void 0
+  };
+}
+var DEFAULT_BASE_URL = "https://api-v2.swaps.xyz";
+var DEFAULT_SLIPPAGE = 5e-3;
+var DEFAULT_DECIMALS = 18;
+var DEFAULT_CACHE_TTL_MS = 10 * 60 * 1e3;
+var _tokenCache = /* @__PURE__ */ new Map();
+var _chainCache = /* @__PURE__ */ new Map();
+var MoonPayTradeSwidgeProtocol = class extends SwidgeProtocol {
+  #apiKey;
+  #baseUrl;
+  #maxProtocolFeeBps;
+  #maxNetworkFeeBps;
+  #cacheTtlMs;
+  /**
+   * @param account - Wallet account. Pass `IWalletAccount` for full access (required by
+   *   `swidge`), `IWalletAccountReadOnly` for quote/status/discovery only, or `undefined`
+   *   for quote and discovery only.
+   * @param config - Provider configuration including the required SwapsXYZ API key.
+   */
+  constructor(account, config) {
+    super(void 0, {
+      maxNetworkFeeBps: config.maxNetworkFeeBps,
+      maxProtocolFeeBps: config.maxProtocolFeeBps
+    });
+    this._account = account;
+    this.#apiKey = config.apiKey;
+    this.#baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.#maxProtocolFeeBps = config.maxProtocolFeeBps !== void 0 ? BigInt(config.maxProtocolFeeBps) : void 0;
+    this.#maxNetworkFeeBps = config.maxNetworkFeeBps !== void 0 ? BigInt(config.maxNetworkFeeBps) : void 0;
+    this.#cacheTtlMs = config.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
+  }
+  /** Clear the shared module-level cache. Useful in tests or to force a refresh. */
+  static clearCache() {
+    _tokenCache.clear();
+    _chainCache.clear();
+  }
+  async #get(path, params) {
+    const url = new URL(path, this.#baseUrl);
+    for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
+    const res = await fetch(url.toString(), {
+      headers: { "x-api-key": this.#apiKey }
+    });
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      throw new ProviderApiError(path, res.status, body);
+    }
+    return res.json();
+  }
+  async #post(path, body) {
+    const res = await fetch(`${this.#baseUrl}${path}`, {
+      method: "POST",
+      headers: {
+        "x-api-key": this.#apiKey,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(body)
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new ProviderApiError(path, res.status, text);
+    }
+    return res.json();
+  }
+  async #getTokenList(chainId) {
+    const key = `${this.#baseUrl}:${chainId}`;
+    const entry = _tokenCache.get(key);
+    if (entry && (this.#cacheTtlMs === 0 || entry.exp > Date.now())) return entry.data;
+    const response = await this.#get("/api/getTokenList", {
+      chainId: String(chainId)
+    });
+    if (this.#cacheTtlMs > 0) {
+      _tokenCache.set(key, { data: response.tokens, exp: Date.now() + this.#cacheTtlMs });
+    }
+    return response.tokens;
+  }
+  /**
+   * Returns the decimal precision for a token on a given chain.
+   * Falls back to 18 decimals if the token is not found.
+   */
+  async #fetchTokenDecimals(chainId, address) {
+    const tokens = await this.#getTokenList(chainId);
+    const normalizedAddress = address.toLowerCase();
+    const token = tokens.find((t) => t.address.toLowerCase() === normalizedAddress);
+    return token?.decimals ?? DEFAULT_DECIMALS;
+  }
+  /**
+   * Returns a non-binding quote for a swap or bridge operation.
+   *
+   * Can be called without a wallet account.
+   *
+   * @param options - Source/destination tokens, amount, and optional routing hints.
+   * @returns Quote including `fromTokenAmount`, `toTokenAmount`, `toTokenAmountMin`, and
+   *   a non-empty `fees` array.
+   * @throws {InvalidTokenIdError} If `fromToken` or `toToken` is not in `"<chainId>:<address>"` format.
+   * @throws {ProviderApiError} If the SwapsXYZ API request fails.
+   */
+  async quoteSwidge(options) {
+    const { chainId: srcChainId, address: srcToken } = parseTokenId(options.fromToken);
+    const { chainId: dstChainId, address: dstToken } = parseTokenId(options.toToken);
+    const exactIn = options.fromTokenAmount !== void 0;
+    const amount = String(exactIn ? options.fromTokenAmount : options.toTokenAmount);
+    const swapDirection = exactIn ? "exact-amount-in" : "exact-amount-out";
+    const response = await this.#get("/api/getQuote", {
+      srcToken,
+      srcChainId: String(srcChainId),
+      dstToken,
+      dstChainId: String(dstChainId),
+      amount,
+      swapDirection
+    });
+    return toSwidgeQuote(response);
+  }
+  /**
+   * Executes a swap or bridge operation using the deposit-address flow.
+   *
+   * Internally calls POST /api/postQuote (expects decimal amounts) then POST /api/postSwap.
+   * Token decimals are fetched from GET /api/getTokenList and cached to convert
+   * WDK base-unit bigint amounts ↔ the decimal strings postQuote requires.
+   *
+   * @param options - Same shape as `quoteSwidge`. No quote object is accepted.
+   * @param config - Optional per-call fee overrides.
+   * @returns Execution result including `id` (swapId) to pass to `getSwidgeStatus`.
+   * @throws {AccountRequiredError} If no account or a read-only account was given at construction.
+   * @throws {FeeLimitExceededError} If a fee guard is exceeded.
+   * @throws {InvalidTokenIdError} If `fromToken` or `toToken` is not in `"<chainId>:<address>"` format.
+   * @throws {ProviderApiError} If a SwapsXYZ API request fails.
+   */
+  async swidge(options, config) {
+    if (!this._account || !("sendTransaction" in this._account)) {
+      throw new AccountRequiredError();
+    }
+    const { chainId: srcChainId, address: srcToken } = parseTokenId(options.fromToken);
+    const { chainId: dstChainId, address: dstToken } = parseTokenId(options.toToken);
+    const senderAddress = await this._account.getAddress();
+    const recipient = options.recipient ?? senderAddress;
+    const [fromDecimals, toDecimals] = await Promise.all([
+      this.#fetchTokenDecimals(srcChainId, srcToken),
+      this.#fetchTokenDecimals(dstChainId, dstToken)
+    ]);
+    const exactIn = options.fromTokenAmount !== void 0;
+    const rawAmount = exactIn ? options.fromTokenAmount ?? 0n : options.toTokenAmount ?? 0n;
+    const decimalAmount = formatBaseUnitsToDecimal(
+      BigInt(rawAmount),
+      exactIn ? fromDecimals : toDecimals
+    );
+    const quote = await this.#post("/api/postQuote", {
+      fromChainId: srcChainId,
+      fromToken: srcToken,
+      toChainId: dstChainId,
+      toToken: dstToken,
+      amount: decimalAmount,
+      tradeMethod: "float",
+      slippage: options.slippage ?? DEFAULT_SLIPPAGE,
+      senderAddress,
+      receiverAddress: recipient,
+      ...options.refundAddress ? { refundAddress: options.refundAddress } : {}
+    });
+    const maxProtocolBps = config?.maxProtocolFeeBps !== void 0 ? BigInt(config.maxProtocolFeeBps) : this.#maxProtocolFeeBps;
+    const maxNetworkBps = config?.maxNetworkFeeBps !== void 0 ? BigInt(config.maxNetworkFeeBps) : this.#maxNetworkFeeBps;
+    if (maxProtocolBps !== void 0 || maxNetworkBps !== void 0) {
+      const inputBigInt = exactIn ? BigInt(rawAmount) : parseDecimalFeeToBaseUnits(quote.amount, fromDecimals);
+      const bps = (fee) => parseDecimalFeeToBaseUnits(fee, fromDecimals) * 10000n / inputBigInt;
+      if (maxProtocolBps !== void 0) {
+        const actual = bps(quote.applicationFee);
+        if (actual > maxProtocolBps)
+          throw new FeeLimitExceededError("protocol", actual, maxProtocolBps);
+      }
+      if (maxNetworkBps !== void 0) {
+        const actual = bps(quote.bridgeFee);
+        if (actual > maxNetworkBps)
+          throw new FeeLimitExceededError("network", actual, maxNetworkBps);
+      }
+    }
+    const swap = await this.#post("/api/postSwap", {
+      quoteId: quote.quoteId,
+      senderAddress,
+      receiverAddress: recipient,
+      ...options.refundAddress ? { refundAddress: options.refundAddress } : {},
+      slippage: options.slippage ?? DEFAULT_SLIPPAGE
+    });
+    return toSwidgeResult(quote, swap, srcChainId, srcToken, fromDecimals, toDecimals);
+  }
+  /**
+   * Returns the current status of an in-flight swap or bridge.
+   *
+   * Poll until the returned `status` is terminal:
+   * `completed`, `failed`, `refunded`, `cancelled`, `expired`, or `partial`.
+   *
+   * @param id - The `id` returned by `swidge`.
+   * @param _options - Optional chain hints (currently unused).
+   * @returns Current status and any associated on-chain transaction hashes.
+   * @throws {UnknownStatusError} If the provider returns an unrecognised status.
+   * @throws {ProviderApiError} If the SwapsXYZ API request fails or the id is not found.
+   */
+  async getSwidgeStatus(id, _options) {
+    if (!id) throw new Error("getSwidgeStatus: id is required");
+    const response = await this.#get("/api/getStatus", { txId: id });
+    return toSwidgeStatusResult(response);
+  }
+  /**
+   * Returns the chains supported by MoonPay Trade for swidge operations.
+   *
+   * Calls GET /api/getChainList and enriches each entry with the native token symbol
+   * sourced from box-common static data (no extra API call needed).
+   * Results are cached with TTL (default 10 min).
+   *
+   * @throws {ProviderApiError} If the getChainList request fails.
+   */
+  async getSupportedChains() {
+    const key = `${this.#baseUrl}:chains`;
+    const entry = _chainCache.get(key);
+    const chains = entry && (this.#cacheTtlMs === 0 || entry.exp > Date.now()) ? entry.data : await this.#get("/api/getChainList", {}).then((data) => {
+      if (this.#cacheTtlMs > 0) {
+        _chainCache.set(key, { data, exp: Date.now() + this.#cacheTtlMs });
+      }
+      return data;
+    });
+    return chains.map((chain) => {
+      const native = getNativeTokenInfo(chain.chainId);
+      return toSwidgeSupportedChain(chain, native?.symbol ?? "");
+    });
+  }
+  /**
+   * Returns the tokens supported by MoonPay Trade for swidge operations.
+   *
+   * When `options.fromChain` is provided, fetches only that chain's tokens.
+   * Otherwise fetches all chains in a single request.
+   * Results are cached with TTL (default 10 min).
+   *
+   * @param options - Optional `fromChain` filter (other fields are not used by this provider).
+   * @throws {ProviderApiError} If the getTokenList request fails.
+   */
+  async getSupportedTokens(options) {
+    if (options?.fromChain !== void 0) {
+      const chainId = Number(options.fromChain);
+      const tokens = await this.#getTokenList(chainId);
+      return tokens.flatMap((token) => {
+        const mapped = toSwidgeSupportedToken(token, chainId);
+        return mapped ? [mapped] : [];
+      });
+    }
+    const allTokens = await this.#get("/api/getTokenList", {});
+    const exp = Date.now() + this.#cacheTtlMs;
+    const result = [];
+    for (const [chainIdStr, { tokens }] of Object.entries(allTokens)) {
+      const chainId = Number(chainIdStr);
+      if (this.#cacheTtlMs > 0) {
+        _tokenCache.set(`${this.#baseUrl}:${chainId}`, { data: tokens, exp });
+      }
+      for (const token of tokens) {
+        const mapped = toSwidgeSupportedToken(token, chainId);
+        if (mapped) result.push(mapped);
+      }
+    }
+    return result;
+  }
+};
+
+export { AccountRequiredError, FeeLimitExceededError, InvalidTokenIdError, MoonPayTradeSwidgeProtocol, ProviderApiError, UnknownStatusError, MoonPayTradeSwidgeProtocol as default };

package/dist/mappers.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Convert a base-unit bigint to a human-readable decimal string.
+ * e.g. 1500000n with 6 decimals → "1.5"
+ */
+export declare function formatBaseUnitsToDecimal(baseUnits: bigint | string, decimals: number): string;
+/**
+ * Convert a decimal fee string to base-unit bigint, accepting zero.
+ * e.g. "0.003" with 6 decimals → 3000n, "0" → 0n
+ */
+export declare function parseDecimalFeeToBaseUnits(decimalAmount: string, decimals: number): bigint;
+import type { SwidgeQuote, SwidgeResult, SwidgeStatusResult, SwidgeSupportedChain, SwidgeSupportedToken } from '@tetherto/wdk-wallet/protocols';
+/** Parse our provider-specific token identifier into chainId + address components. */
+export declare function parseTokenId(tokenId: string): {
+    chainId: number;
+    address: string;
+};
+/**
+ * Serialised Payment field from ActionResponse (bigints become strings after JSON).
+ * Used by GET /api/getQuote response.
+ */
+interface SerializedPayment {
+    amount: string;
+    address: string;
+    chainId: number;
+    symbol?: string;
+    [key: string]: unknown;
+}
+/** Shape returned by GET /api/getQuote (ActionResponse minus tx/txId). */
+interface GetQuoteResponse {
+    amountIn: SerializedPayment;
+    amountOut: SerializedPayment;
+    amountOutMin: SerializedPayment;
+    applicationFee: SerializedPayment;
+    protocolFee: SerializedPayment;
+    bridgeFee?: SerializedPayment;
+    estimatedTxTime: number;
+    estimatedPriceImpact: number;
+    expiryUnix?: number;
+    requiresTokenApproval?: boolean;
+}
+/**
+ * Decimal-format response from POST /api/postQuote.
+ * All amounts are human-readable decimal strings (e.g. "1.5"), not base-unit integers.
+ * Use parseDecimalFeeToBaseUnits with the appropriate token decimals to convert.
+ */
+interface PostQuoteResponse {
+    quoteId: string;
+    amount: string;
+    amountTo: string;
+    applicationFee: string;
+    protocolFee: string;
+    bridgeFee: string;
+    expiryUnix: number;
+}
+/** Shape returned by POST /api/postSwap. */
+interface PostSwapResponse {
+    swapId: string;
+    depositAddress: string;
+    depositAddressMemo?: string;
+    protocolFee: string;
+    applicationFee: string;
+    bridgeFee: string;
+    expiryUnix: number;
+}
+/** Shape returned by GET /api/getStatus. */
+interface GetStatusResponse {
+    status: string;
+    srcTxHash?: string;
+    dstTxHash?: string;
+    srcChainId?: number;
+    dstChainId?: number;
+    [key: string]: unknown;
+}
+/** A single token entry from GET /api/getTokenList?chainId=<id>. */
+export interface GetTokenListItem {
+    address: string;
+    decimals: number;
+    isNative: boolean;
+    symbol?: string;
+    name?: string;
+}
+/** Shape returned by GET /api/getChainList. */
+export interface GetChainListItem {
+    chainId: number;
+    name: string;
+    vmId: string;
+}
+/** Shape returned by GET /api/getTokenList (no chainId filter): keyed by chainId string. */
+export type GetAllTokensResponse = Record<string, {
+    tokens: GetTokenListItem[];
+}>;
+export type { GetQuoteResponse, GetStatusResponse, PostQuoteResponse, PostSwapResponse };
+export declare function toSwidgeQuote(response: GetQuoteResponse): SwidgeQuote;
+/**
+ * Map POST /api/postQuote + POST /api/postSwap responses to SwidgeResult.
+ *
+ * postQuote returns decimal strings for all amounts; decimalStringToBigInt converts
+ * them back to base-unit bigints using the token's decimals.
+ *
+ * Note: transactions[].hash is set to swapId (the deposit-flow tracking ID), not an
+ * on-chain transaction hash. Confirmed on-chain hashes are available via getSwidgeStatus
+ * after the wallet submits the transfer.
+ *
+ * @param fromDecimals - Decimals of the source token (used to parse fee strings).
+ * @param toDecimals - Decimals of the destination token (used to parse amountTo).
+ */
+export declare function toSwidgeResult(quote: PostQuoteResponse, swap: PostSwapResponse, srcChainId: number, srcTokenAddress: string, fromDecimals: number, toDecimals: number): SwidgeResult;
+/**
+ * Map a getChainList entry + native token symbol to SwidgeSupportedChain.
+ * `nativeSymbol` comes from getNativeTokenInfo(chainId).symbol in box-common (static data).
+ */
+export declare function toSwidgeSupportedChain(chain: GetChainListItem, nativeSymbol: string): SwidgeSupportedChain;
+/**
+ * Map a getTokenList entry to SwidgeSupportedToken.
+ * Returns null for tokens without a symbol (invalid/incomplete entries).
+ *
+ * Token identifier format: "<chainId>:<address>" — consistent with quoteSwidge/swidge.
+ */
+export declare function toSwidgeSupportedToken(token: GetTokenListItem, chainId: number): SwidgeSupportedToken | null;
+export declare function toSwidgeStatusResult(response: GetStatusResponse): SwidgeStatusResult;
+//# sourceMappingURL=mappers.d.ts.map

package/dist/mappers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mappers.d.ts","sourceRoot":"","sources":["../src/mappers.ts"],"names":[],"mappings":"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"}

package/examples/e2e.mjs

@@ -0,0 +1,106 @@
+/**
+ * End-to-end example: discover tokens → quote → swidge → poll status.
+ *
+ * Prerequisites:
+ *   1. npm run build
+ *   2. Set env vars in .env (or export them):
+ *        SWAPS_XYZ_KEY=<your-key>
+ *        SWAPS_XYZ_BASE_URL=http://localhost:4000   # or omit for production
+ *        TEST_WALLET_ADDRESS=0x<address>          # required for swidge
+ *
+ * Run:
+ *   node examples/e2e.mjs
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import MoonPayTradeSwidgeProtocol from '../dist/index.js';
+
+// Load .env from the package root if present
+const envPath = join(dirname(fileURLToPath(import.meta.url)), '..', '.env');
+if (existsSync(envPath)) {
+  for (const line of readFileSync(envPath, 'utf8').split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eq = trimmed.indexOf('=');
+    if (eq < 1) continue;
+    const key = trimmed.slice(0, eq).trim();
+    const value = trimmed.slice(eq + 1).trim();
+    if (process.env[key] === undefined) process.env[key] = value;
+  }
+}
+
+if (!process.env.SWAPS_XYZ_KEY) {
+  console.error('SWAPS_XYZ_KEY is required');
+  process.exit(1);
+}
+
+// ─── Discovery-only protocol (no account required for quotes) ─────────────────
+
+const protocol = new MoonPayTradeSwidgeProtocol(undefined, {
+  apiKey: process.env.SWAPS_XYZ_KEY,
+  baseUrl: process.env.SWAPS_XYZ_BASE_URL,
+});
+
+console.log('\n── Supported chains (sample) ────────────────────────────────');
+const chains = await protocol.getSupportedChains();
+console.log(`${chains.length} chains`);
+console.log(chains.slice(0, 3).map((c) => `  ${c.id} ${c.name} (${c.nativeToken})`).join('\n'));
+
+console.log('\n── Supported tokens on Ethereum (sample) ────────────────────');
+const ethTokens = await protocol.getSupportedTokens({ fromChain: 1 });
+console.log(`${ethTokens.length} tokens`);
+console.log(ethTokens.slice(0, 3).map((t) => `  ${t.token} ${t.symbol}`).join('\n'));
+
+// Use USDT on Ethereum → USDC on Base as the example pair
+const fromToken = '1:0xdAC17F958D2ee523a2206206994597C13D831ec7';  // USDT on Ethereum
+const toToken   = '8453:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'; // USDC on Base
+const fromTokenAmount = 10_000_000n; // 10 USDT (6 decimals)
+
+console.log(`\n── Quote: ${fromToken} → ${toToken} ─────────────────────────`);
+const quote = await protocol.quoteSwidge({ fromToken, toToken, fromTokenAmount });
+console.log(`  from:       ${quote.fromTokenAmount}`);
+console.log(`  to:         ${quote.toTokenAmount}`);
+console.log(`  toMin:      ${quote.toTokenAmountMin}`);
+console.log(`  fees:       [${quote.fees.map((f) => `${f.type}=${f.amount}`).join(', ')}]`);
+console.log(`  duration:   ${quote.estimatedDuration}s`);
+
+// ─── E2E: swidge + poll status (requires TEST_WALLET_ADDRESS) ─────────────────
+
+if (!process.env.TEST_WALLET_ADDRESS) {
+  console.log('\n── Skipping swidge (set TEST_WALLET_ADDRESS to run) ─────────');
+  process.exit(0);
+}
+
+// Minimal account — provides address only; sendTransaction not called in deposit flow
+const account = {
+  getAddress: async () => process.env.TEST_WALLET_ADDRESS,
+  sendTransaction: async () => { throw new Error('not required for deposit-based swaps'); },
+};
+
+const e2eProtocol = new MoonPayTradeSwidgeProtocol(account, {
+  apiKey: process.env.SWAPS_XYZ_KEY,
+  baseUrl: process.env.SWAPS_XYZ_BASE_URL,
+});
+
+console.log(`\n── Swidge (sender: ${process.env.TEST_WALLET_ADDRESS.slice(0, 10)}…) ────────────────────`);
+const result = await e2eProtocol.swidge({ fromToken, toToken, fromTokenAmount });
+console.log(`  swapId:     ${result.id}`);
+console.log(`  fromAmount: ${result.fromTokenAmount}`);
+console.log(`  toAmount:   ${result.toTokenAmount}`);
+
+console.log('\n── Polling getSwidgeStatus ───────────────────────────────────');
+let statusResult;
+for (let i = 1; i <= 5; i++) {
+  try {
+    statusResult = await e2eProtocol.getSwidgeStatus(result.id);
+    break;
+  } catch {
+    if (i < 5) {
+      console.log(`  not ready yet, retrying in 3s... (${i}/5)`);
+      await new Promise((r) => setTimeout(r, 3000));
+    }
+  }
+}
+console.log(`  status: ${statusResult?.status ?? 'unavailable after 5 retries'}`);

package/package.json

@@ -1,8 +1,55 @@
 {
   "name": "@moonpay/wdk-protocol-swidge-moonpay-trade",
-  "version": "0.0.0",
-  "description": "",
-  "publishConfig": {
-    "access": "public"
+  "version": "0.1.1",
+  "description": "WDK Swidge protocol implementation for MoonPay Trade",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "examples"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/swaps-xyz/wdk-protocol-swidge-moonpay-trade"
+  },
+  "homepage": "https://github.com/swaps-xyz/wdk-protocol-swidge-moonpay-trade",
+  "keywords": [
+    "wdk",
+    "swidge",
+    "moonpay",
+    "swap",
+    "bridge",
+    "tether"
+  ],
+  "scripts": {
+    "build": "tsup && tsc --project tsconfig.build.json",
+    "dev": "tsup --watch",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@decent.xyz/box-common": "5.0.130",
+    "@tetherto/wdk-wallet": "1.0.0-beta.9",
+    "viem": "2.54.6"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "@vitest/coverage-v8": "4.1.10",
+    "tsup": "8.5.1",
+    "typescript": "5.9.3",
+    "vitest": "4.1.10"
   }
 }