How to add crypto swaps to an existing wallet

Worked example: a linked web-wallet experience

Illustrative scope, grounded in the current application: a wallet product adds a Swap entry that opens a separately branded web deployment. Use 100 USDC to ETH on Ethereum as an evaluation case, subject to the configured token catalogue, provider eligibility and a fresh available route. This is not evidence of a customer deployment, verified wallet connector or real transaction test.

Entry: your product opens the deployment's /swap page. The existing link parser accepts source/destination network IDs, token identifiers and an amount in base units. For a six-decimal token, 100 units is 100000000 base units. These are starting inputs, not a reserved price, signed transaction or permission to spend. A wallet connection in your product is not automatically shared with a different web origin.

Review and approval: the user connects a compatible wallet, checks the selected pair and recipient, and requests a current quote. The review distinguishes expected output, minimum received, fees and gas. The wallet handles any required allowance and swap approvals; saved history uses a separate sign-in. Rejected or expired requests must not be presented as completed swaps.

Return: after the wallet prompt, the user returns to the web swap screen to inspect progress. Mobile handoff behavior needs testing with the specific wallet/browser. Returning onward to your product requires an agreed navigation integration: the current application does not expose a customer returnUrl callback or cross-origin completion message. A future return link must not treat navigation as proof of settlement.

• Use the acceptance checklist for this example

Who owns each part of that example?

The linked deployment reuses the application, not the wallet's private-key system. Responsibilities stay separate:

• Frontend: token/network and recipient inputs, wallet connection, quote and fee review, approval guidance and transaction progress. Users approve ordinary spending in their wallet.
• Application servers: Next.js validates quote requests and calls configured eligible providers with server-side credentials. Spring Boot/PostgreSQL handle authenticated history, preferences, notifications and protected operational evidence.
• Provider and networks: available routes, transaction-building interfaces and chain/delivery observations. A provider quote or source-chain receipt is not a universal guarantee of destination delivery or fee payout.
• Customer team: the product entry/return integration, connector acceptance, isolated infrastructure and accounts, branding rights, provider approvals, secret handling and operating permissions.

Separate reuse from integration work

Classify the scope before treating the example as a delivery commitment:

• Included application capability, subject to the agreed license: existing web wallet selection, token inputs, quote review, recipient handling, transaction progress and saved-history workflow.
• Configuration: brand assets and names, site/backend origins, wallet-connection project, eligible providers, networks, fee settings and customer-owned receive addresses. Preflight checks configuration; it does not provision customer accounts.
• Custom scope: a return-to-product action or result callback, native embedding, shared account/session behavior and a new wallet connector. None is assumed compatible merely because a wallet brand is listed.
• Unsupported in this example: custody or signing with users' keys, a ready-made public SDK, arbitrary tokens/networks, guaranteed routes or payouts, and commercial live Radar data without approved rights.

• Compare delivery approaches without assuming the same scope

1. Define the wallet and network contract

Identify the account selected by the user, supported signing methods and the current network. Review what happens when that account changes during a quote or approval. A token symbol is not enough to identify an asset: use its network and contract identifier, or the network's native-asset convention.

For a cross-chain destination, the source wallet may not provide a suitable receiving address. Recipient collection and validation are a separate part of the workflow. Do not silently substitute an address on a different network.

2. Request a route and normalize the review

Convert the entered amount using the asset's decimals. Treat the provider response as data that still needs validation. Present the asset, amount, destination, fee denomination, gas estimate, slippage bound and quote expiry together before asking for a signature.

Expected output and minimum received serve different purposes. Network gas is also not necessarily paid in the same token as a platform fee. A meaningful review preserves these distinctions rather than collapsing everything into a misleading single number.

3. Separate connection, sign-in and spending approval

Connecting exposes public wallet/account information. A sign-in message proves control for saved history or preferences. Neither should be described as approval to spend. A token allowance and the swap transaction are separate wallet actions when the selected route requires them.

The existing Swap Assistant workflow keeps provider credentials server-side and asks the user's wallet to sign ordinary swaps. Exact provider-verifiable limit orders are a separate flow; do not mix their advance authorization into an ordinary login explanation.

4. Design the non-happy paths

For a source amount of 100 USDC and a synthetic quote of 0.04 ETH, the interface can demonstrate amount, fee and minimum-received review without moving funds. In a real integration, the returned amounts come from a fresh route, not from that illustration.

Your tests should deliberately reject a wallet prompt, expire the quote, switch account, use an incompatible recipient and simulate an unavailable provider. Each should leave the user with an accurate state and a bounded retry, not a success banner.

• A rejected signature must not become a submitted transaction
• A refreshed route must be reviewed before approval
• Source confirmation must not imply cross-chain destination completion
• Repeated save requests must not double-count fee revenue

An acceptance checklist your product team can run

Record the selected wallet, network, token identifiers and software revision for each test. Use fixtures or a safe agreed test environment first; never put private keys, seed phrases or full signing payloads into a shared bug report.

For the worked example, attach the input fixture, expected state, actual result and a sanitized screenshot or assertion to each case below. Record entry/prefill and return navigation separately from transaction status. Mocked results prove the tested UI behavior, not real connector compatibility, settlement or payout. Mark unexecuted cases as unverified.

• Account switch: request a quote with account A, then switch to B. The old quote must not authorize a transaction for the wrong owner; request and review a fresh quote.
• User rejection: reject the allowance or swap request. Show a cancelled request, preserve editable inputs and do not record a transaction hash that was never broadcast.
• Expired quote: delay approval beyond its deadline. Do not retry obsolete calldata automatically; fetch a new quote and ask for review again.
• Allowance completed, swap rejected: report those as separate actions. Do not imply cancelling the swap revoked a previously granted allowance.
• Cross-chain delay: simulate a confirmed source transaction and pending destination delivery. Keep delivery pending; a source receipt alone is not completion.
• Duplicate notification: replay the same chain and transaction hash. Retain a single transaction identity, while allowing distinct genuine transactions to reconcile independently.
• Provider failure: simulate rate limiting or no route. Bound retries, retain clear unavailable states and never synthesize an executable route from a display price.

5. Agree ownership after launch

Decide who monitors provider outages, tests dependency updates, maintains wallet connectors and investigates delivery issues. Provider documentation describes its interface; your acceptance tests describe the behavior users actually depend on.

A branded deployment can reuse the existing application workflow. Native embedding and a particular wallet's signing interface still need explicit scoping. Use the no-wallet demo to review the customer journey before a technical compatibility test.

• See the sample pilot deliverables and handover package

Questions before a pilot

Further technical reading

Official references for integration responsibilities. These links are not endorsements, and do not imply that every referenced provider is enabled in Swap Assistant.

• Uniswap's official integration and transaction troubleshooting guide