Add n.exchange centralized swap integration by MMrj9 · Pull Request #426 · EdgeApp/edge-exchange-plugins

MMrj9 · 2025-12-22T11:06:59Z

Add n.exchange centralized swap integration

Description

Integrate n.exchange as a centralized swap provider supporting multiple networks and tokens. The implementation uses contract addresses for token identification, eliminating the need for currency code mapping. This approach provides better support for tokens and aligns with API requirements.

The integration includes support for native currencies and ERC20 tokens across major networks including Ethereum, Polygon, Base, Arbitrum, Optimism, BSC, and others. The plugin handles rate queries, order creation, and payment processing through the n.exchange API v2.

Additional changes include mapctl tooling for automatic provider mappings and updates to existing swap plugins to use the new mapping system.

CHANGELOG

Does this branch warrant an entry to the CHANGELOG?

Yes
No

Dependencies

none

Changes

Add n.exchange centralized swap plugin implementation
Support for contract address-based token identification
Integration with n.exchange API v2 for rate queries and order management
Support for multiple networks: Ethereum, Polygon, Base, Arbitrum, Optimism, BSC, and others
Mapctl tooling for automatic provider mappings
Updates to existing swap plugins to use new mapping system

Testing

Unit tests added/updated (nexchange tests included in partnerJson.test.ts)
Manual testing completed

Checklist

Code follows project style guidelines
Commit message follows git commit guidelines
Branch is synced with upstream master
Tests pass locally (26 passing)
Documentation updated (CHANGELOG.md updated)
Linting passes
Type checking passes (nexchange-specific types fixed)

Note

Medium Risk
Introduces a new external swap integration that constructs spend targets and order metadata based on third-party API responses, so parsing/mapping errors could impact swap availability and correctness. Changes are additive and isolated to a new plugin plus wiring/tests.

Overview
Adds n.exchange as a new centralized swap provider (nexchange) and wires it into src/index.ts so it is available alongside existing swap plugins.

Implements a full API v2 integration that fetches fixed-rate quotes, enforces min/max limits, creates orders, and builds EdgeSpendInfo/swap metadata, using contract-address-based token identification (plus a pluginId→network-code transcription map) for native assets and tokens.

Updates test/config coverage by adding a nexchange partner mapping JSON, extending partnerJson.test.ts with nexchange cases, and adding NEXCHANGE_INIT options for API key/referral configuration; also documents the addition in CHANGELOG.md.

^{Written by Cursor Bugbot for commit 3148f31. This will update automatically on new commits. Configure here.}

src/swap/central/nexchange.ts

paullinator

n/a

paullinator

Review Summary

The implementation is generally well-structured and follows existing plugin patterns. However, there are 3 critical issues that should be addressed before merge.

Critical Issues (Must Fix)

JSON parsing errors not handled (line 269)
getContractAddress silently falls back to native currency (lines 141-149)
parseInt could return NaN, bypassing expiration check (lines 349-351)

Additional Note

Commit Message Inaccuracy: The commit body mentions "updates to existing swap plugins to use the new mapping system" but there are no modifications to existing swap plugins in this commit. Consider amending the commit message for accuracy.

Positive Observations

Good use of existing helpers (getMaxSwappable, makeSwapPluginQuote, etc.)
Clean cleaner definitions with asRateV2 and asOrderV2
Proper error handling with SwapCurrencyError, SwapAboveLimitError, SwapBelowLimitError
Good use of Promise.all for parallel address fetching
Appropriate use of ensureInFuture for expiration handling
Good memo handling for chains like XRP/XLM

See inline comments for specific issues and recommendations.

src/swap/central/nexchange.ts

cursor · 2026-01-28T17:47:59Z

src/swap/central/nexchange.ts

+    const expirationDate: Date =
+      order.fixed_rate_deadline != null
+        ? ensureInFuture(order.fixed_rate_deadline) ?? defaultExpiration
+        : ensureInFuture(defaultExpiration) ?? defaultExpiration


Redundant null coalescing on guaranteed non-null value

Low Severity

The expression ensureInFuture(defaultExpiration) ?? defaultExpiration on line 520 has a redundant null coalescing operator. Since defaultExpiration is always a non-null Date object (computed on lines 514-516), ensureInFuture will never return undefined for it per its implementation. The ?? defaultExpiration fallback can never be reached.

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

cursor · 2026-01-28T23:03:46Z

src/swap/central/nexchange.ts

+  asString,
+  asObject({ code: asString, network: asString }),
+  asObject({ contract_address: asString, network: asString })
+)


Cleaner doesn't handle null contract_address in API response

High Severity

The asNexchangeCurrencyResponse cleaner's third option expects contract_address to be a string via asString, but the formatCurrency function sends contract_address: null for native currencies. If the API echoes this format back in the order response, parsing will fail because neither option in asEither can handle { contract_address: null, network: "..." }. Other plugins like changehero, changenow, and letsexchange correctly use asEither(asString, asNull) for nullable contract addresses. This could break all native currency swaps.

paullinator

Review Summary

This PR adds n.exchange as a new centralized swap provider. The implementation uses contract addresses for token identification and integrates with the n.exchange API v2.

Previous Review Comments - All Addressed ✅

All critical and warning issues raised by Paul and Bug Bot have been addressed:

getContractAddress now throws errors instead of silently falling back
parseInt NaN check added
JSON parsing wrapped in try/catch
Cleaner failures handled with try/catch
checkInvalidTokenIds called
ensureInFuture used for expiration dates

Remaining Items

Before merge:

Add checkWhitelistedMainnetCodes call for consistency with other plugins
Consider moving MAINNET_CODE_TRANSCRIPTION to src/mappings/nexchange.ts

Nice to have (can be deferred):

Add unit tests for getFixedQuote() business logic
Consolidate repetitive documentation comments

Git

⚠️ The PR contains a merge commit instead of a rebase. Consider rebasing onto master before merge:

git fetch origin master
git rebase origin/master
git push --force-with-lease

Ready for merge after adding checkWhitelistedMainnetCodes.

See inline comments for specific suggestions.

paullinator

Additional Inline Suggestions

See inline comments for specific code improvements. These are minor suggestions - the main review summary was posted earlier.

Key inline items:

Line 560: Add checkWhitelistedMainnetCodes call for consistency
Line 80: Consider using mapping file pattern
Various type safety and naming improvements

paullinator · 2026-02-05T01:51:50Z

src/swap/central/nexchange.ts

+// See https://api.n.exchange/en/api/v2/currency/ for list of supported currencies
+// Network codes map to Nexchange network identifiers
+// Based on supported networks: ALGO, ATOM, SOL, BCH, BTC, DASH, DOGE, DOT, EOS, TON, HBAR, LTC, XLM, XRP, XTZ, ZEC, TRON, ADA, BASE, MATIC/POL, ETH, AVAXC, BSC, ETC, ARB, OP, FTM, SONIC
+// eslint-disable-next-line @typescript-eslint/consistent-type-assertions


Suggestion: Other plugins use mapping files in src/mappings/ with mapToRecord(). Consider creating src/mappings/nexchange.ts for consistency:

import { mapToRecord } from '../utils' export const MAINNET_CODE_TRANSCRIPTION = mapToRecord([ ['ethereum', 'ETH'], // ... ])

paullinator · 2026-02-05T01:51:52Z

src/swap/central/nexchange.ts

+    ): Promise<EdgeSwapQuote> {
+      const request = convertRequest(req)
+
+      checkInvalidTokenIds(INVALID_TOKEN_IDS, request, swapInfo)


Warning: Other plugins (changenow, exolix, letsexchange, sideshift) call checkWhitelistedMainnetCodes in addition to checkInvalidTokenIds. Add this for consistent validation:

import { checkWhitelistedMainnetCodes } from './common/swapHelpers' checkWhitelistedMainnetCodes(allowedCurrencyCodes, request, swapInfo)

paullinator · 2026-02-05T01:51:53Z

src/swap/central/nexchange.ts

+    let rates
+    try {
+      rates = asArray(asRateV2)(rateResponse)
+    } catch (e) {


Nit: Convention is to use error instead of e for caught exceptions.

paullinator · 2026-02-05T01:51:55Z

src/swap/central/nexchange.ts

+    } catch (e) {
+      throw new Error(`Nexchange rate response parsing failed: ${String(e)}`)
+    }
+    const rate = rates[0] // Contract address query returns single rate


Suggestion: This assumes the API returns exactly one rate. Consider validating array length:

if (rates.length === 0) { throw new SwapCurrencyError(swapInfo, request) } const rate = rates[0]

paullinator · 2026-02-05T01:51:56Z

src/swap/central/nexchange.ts

+      headers?: { [key: string]: string }
+    } = {},
+    request?: EdgeSwapRequestPlugin
+  ): Promise<any> {


Suggestion: Consider Promise<unknown> instead of Promise<any> for better type safety, since the data is cleaned after retrieval.

paullinator · 2026-02-05T01:51:57Z

src/swap/central/nexchange.ts

+  const { fetchCors = io.fetch } = io
+  const { apiKey, referralCode } = asInitOptions(opts.initOptions)
+
+  const headers: { [key: string]: string } = {


Nit: Use the imported StringMap type instead of inline { [key: string]: string }.

paullinator · 2026-02-05T01:51:59Z

src/swap/central/nexchange.ts

+  referralCode: asString
+})
+
+const orderUri = 'https://n.exchange/order/'


Suggestion: Consider more descriptive constant names like ORDER_BASE_URL and API_BASE_URL for clarity.

paullinator

see comments

Integrate n.exchange as a centralized swap provider supporting multiple networks and tokens. The implementation uses contract addresses for token identification, eliminating the need for currency code mapping. Changes: - Add n.exchange swap plugin (src/swap/central/nexchange.ts) - Add n.exchange mapping file (src/mappings/nexchange.ts) - Register nexchange plugin in src/index.ts - Add partner mapping JSON and tests - Update CHANGELOG.md

MMrj9 · 2026-02-09T11:52:10Z

see comments

All comments addressed

Jon-edge · 2026-02-13T21:01:24Z

Superseded by #437. Rebased onto current master with build fix (export MAINNET_CODE_TRANSCRIPTION for test). Thank you @MMrj9 for the contribution!

Jon-edge · 2026-02-13T21:36:17Z

We are getting a 400 error when transacting from our San Diego office: User's IP has risk. @MMrj9

cursor bot reviewed Jan 6, 2026

View reviewed changes