Swap and Bridge

WDK CLI beta.6 can quote installed swap and bridge protocols, select a route, and execute it from an unlocked wallet. Use wdk token list to find the registered network and token names accepted by these commands.

Use this guide to Select The Account And Recipient, Prepare A Velora Token Allowance, Preview A Swap, Execute A Swap, Preview And Execute A Bridge, Choose A Protocol.

Before you begin, set up and unlock a wallet and check the source and destination token names with wdk token list. Built-in entries need no registration. If an entry is missing, add a custom token. Fund the source account with the tokens and native gas asset needed for execution.

If you register a custom or overriding native token, read Manage Tokens first: wdk token add cannot retain nativeId, so routing works only when the selected protocol discovers the asset by symbol or does not require a native route identifier. Custom native tokens are not guaranteed to swap or bridge.

Select The Account And Recipient

Choose the wallet and account index explicitly. Derive the address for the destination network before previewing; for a same-network swap, use the source network here:

wdk get address \
  --network DESTINATION_NETWORK \
  --wallet WALLET \
  --index 0

Pass the same --wallet, --index, and returned address as --recipient to the preview and execution commands. Beta.6 swap and bridge previews include the sender in from, but do not include the wallet name, account index, or resolved recipient in text or JSON output. Verify from against the intended source account and retain the separately verified recipient.

Prepare A Velora Token Allowance

For a Velora ERC-20 input, use the Market swap spender returned by Velora SDK 9's swap.getSpender(). The CLI's bundled adapter uses API version 6.2. The equivalent read-only lookup is:

curl --fail --silent --show-error \
  'https://api.paraswap.io/adapters/contracts?network=1&version=6.2'

This example looks up Ethereum (network=1). Set network to your source chain's numeric ID. Use the response's TokenTransferProxy field as the spender. The CLI and MCP do not expose this lookup; do not proceed if you cannot verify it for the selected chain.

1. With the same wallet, account index, and source network, read getAllowance and submit a bounded approve only if needed. See Call Module Methods, including the USD₮ allowance-reset case.
2. Approve no more than the intended exact-input amount in token base units. Wait for the approval to reach confirmed, require success: true, and read the allowance again before quoting.

Native-token input does not use an ERC-20 allowance, and other protocols can manage approvals differently. For an exact-output Velora request, beta.6 does not expose the required input before this prerequisite; do not guess an approval amount.

Preview A Swap

Provide exactly one of --amount-in and --amount-out.

wdk swap \
  --network SOURCE_NETWORK \
  --from-token SOURCE_TOKEN \
  --to-token DESTINATION_TOKEN \
  --amount-in 100 \
  --wallet WALLET \
  --index 0 \
  --recipient RECIPIENT_ADDRESS \
  --dry-run

An exact-input request selects the successful quote with the highest output. An exact-output request selects the quote with the lowest input:

wdk swap \
  --network SOURCE_NETWORK \
  --from-token SOURCE_TOKEN \
  --to-token DESTINATION_TOKEN \
  --amount-out 100 \
  --wallet WALLET \
  --index 0 \
  --recipient RECIPIENT_ADDRESS \
  --dry-run

Replace the uppercase placeholders with values from wdk network list, wdk token list, and the address check above.

The ranking compares token amounts only. Separate gas and bridge fees can use different denominations or already be included in a provider quote, so they do not affect route selection. Review both the on-top and included fee lines. A successful result can also list protocols under skipped when those protocols failed to quote.

Execute A Swap

Run the same command without --dry-run only if you accept a fresh quote with no CLI minimum-output, maximum-input, fee, or expiry bound relative to the preview:

wdk swap \
  --network SOURCE_NETWORK \
  --from-token SOURCE_TOKEN \
  --to-token DESTINATION_TOKEN \
  --amount-in 100 \
  --wallet WALLET \
  --index 0 \
  --recipient RECIPIENT_ADDRESS

Unless --protocol is set, execution can select a different protocol. Its amounts and fees can differ even when the provider is restricted. WDK CLI does not ask for another confirmation. Do not execute through beta.6 when your transaction policy requires enforceable output or fee bounds relative to the preview.

Preview And Execute A Bridge

wdk bridge moves the same registered token between different networks. It supports exact input only.

wdk bridge \
  --network SOURCE_NETWORK \
  --token TOKEN \
  --to-network DESTINATION_NETWORK \
  --amount 100 \
  --wallet WALLET \
  --index 0 \
  --recipient RECIPIENT_ADDRESS \
  --dry-run

The source and destination networks must differ. Removing --dry-run executes a fresh quote request, with the same identity omissions and lack of CLI limits bound to the preview described above.

Choose A Protocol

List provider routing names with wdk provider list, then inspect a provider's effective configuration:

wdk provider list
wdk provider info --name velora

Pass an enabled name as --protocol NAME. Its declared kind must support the operation: swap and swidge serve swaps; bridge and swidge serve bridges. Module chain and asset prerequisites still apply. A disabled backing module hides its providers.

To add a provider, install and review its package first, then use wdk provider add to register it. wdk module add alone does not create a routing entry. See Configuration for configuration precedence. Provider discovery and management have no MCP tools.

Next Steps

• API Reference
• Call Module Methods
• Use the MCP Server
• Handle Errors
• Security Model

Need Help?