@0x/wdk-protocol-swidge-0x

@0x/wdk-protocol-swidge-0x

WDK Swidge protocol module for EVM token swaps via the 0x Swap API v2.

This module implements the SwidgeProtocol interface from @tetherto/wdk-wallet, letting any WDK-based wallet perform same-chain EVM swaps through 0x's aggregated liquidity — with automatic ERC-20 approval handling and on-chain status tracking.

Note: Cross-chain bridging via 0x is not yet supported. toChain must equal the source chain.

---

Installation

npm install @0x/wdk-protocol-swidge-0x

---

Configuration

Store your API key in an environment variable — never commit it to source control:

# .env
ZERO_EX_API_KEY=your_api_key_here

---

Usage

import ZeroExProtocol from '@0x/wdk-protocol-swidge-0x'

const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
const WETH = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2'

// ── 1. Get an indicative quote (no wallet needed) ──────────────────────────

const protocol = new ZeroExProtocol(undefined, {
  chainId: 1, // Ethereum mainnet
  apiKey: process.env.ZERO_EX_API_KEY,
  defaultSlippage: 0.005 // 0.5%
})

const quote = await protocol.quoteSwidge({
  fromToken: USDC,
  toToken: WETH,
  fromTokenAmount: 100_000_000n // 100 USDC (6 decimals)
})

console.log('Estimated WETH out:', quote.toTokenAmount)
console.log('Minimum WETH out:  ', quote.toTokenAmountMin)

// ── 2. Execute (requires a full WDK EVM wallet account) ───────────────────

// import { WalletManager } from '@tetherto/wdk-wallet'
// import EvmWallet from '@tetherto/wdk-wallet-evm'
// const manager = new WalletManager({ wallets: [new EvmWallet()] })
// await manager.load({ mnemonic: process.env.MNEMONIC })
// const account = await manager.getWallet('evm').getAccount(0)

const execProtocol = new ZeroExProtocol(account, {
  chainId: 1,
  apiKey: process.env.ZERO_EX_API_KEY,
  defaultSlippage: 0.005
})

const result = await execProtocol.swidge({
  fromToken: USDC,
  toToken: WETH,
  fromTokenAmount: 100_000_000n
})

console.log('Swap submitted:', result.hash)

// ── 3. Poll for status ────────────────────────────────────────────────────

let status
do {
  await new Promise(r => setTimeout(r, 3000))
  const s = await execProtocol.getSwidgeStatus(result.id)
  status = s.status
  console.log('Status:', status)
} while (status === 'pending')

See examples/swap-usdc-to-weth.js for a runnable example.

---

Supported chains

Call getSupportedChains() to retrieve the full list at runtime.

---

Token discovery

The 0x Swap API accepts any liquid ERC-20 token by contract address. There is no supported token list — getSupportedTokens() throws NotImplementedError. Pass token addresses directly to quoteSwidge and swidge.

For native ETH (or any chain's native token), use 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE or one of the aliases 'native', 'eth', '', or the zero address. Aliases are matched case-insensitively and rewritten to the sentinel before the request is sent. Native tokens are supported as both the sell token and the buy token.

Note that 'eth' and '' mean the chain's native token on every supported chain — on Polygon, 'eth' resolves to POL. Any other value is forwarded to the 0x API unchanged; the module does not validate or checksum non-native token addresses.

---

Status mapping

The module has no server-side status endpoint; status is resolved from on-chain state via the bound wallet account.

When the account exposes getTransactionByHash, transaction existence is checked first so a well-formed id that the network has no record of throws ZeroExUnknownTransactionError instead of reporting pending forever. The receipt then resolves completed / failed, or pending while in-flight.

Fallback: if the account exposes only getTransactionReceipt, an unknown transaction cannot be distinguished from an in-flight one, so status is derived from the receipt alone and reported as pending when no receipt exists yet. If the account exposes neither method, status is always pending.

---

Fee mapping

Fee caps (maxNetworkFeeBps, maxProtocolFeeBps) are expressed in basis points of the sell-token input amount and enforced fail-closed — a configured cap that cannot be evaluated rejects the swap with ZeroExFeeLimitExceededError:

• maxNetworkFeeBps — the network fee is always denominated in the chain's native token. When the sell token is the native token the comparison is direct; otherwise the fee is converted into sell-token terms via one extra 0x /price request (native → sell token). If no conversion route is available, the swap is rejected.
• maxProtocolFeeBps — compared directly when the protocol fee token matches the sell token (the common case). If the fee comes back denominated in another token it cannot be compared and the swap is rejected.

---

Error types

---

WDK interface

This module implements SwidgeProtocol from @tetherto/wdk-wallet ^1.0.0-beta.11.

The swap, quoteSwap, bridge, and quoteBridge methods are inherited from the base class and delegate to swidge / quoteSwidge respectively.

---

Development

npm install       # install dependencies
npm test          # run unit tests
npm run lint      # check code style (JavaScript Standard Style)
npm run build:types  # generate TypeScript declarations in types/

End-to-end test against the live 0x API (read-only, no wallet needed):

ZERO_EX_API_KEY=... npm run e2e

To test real swap execution, add a BIP-39 mnemonic:

ZERO_EX_API_KEY=... MNEMONIC="word word ..." npm run e2e

---

Verified on mainnet

End-to-end tested against the live 0x API on Base mainnet (chain 8453):

---

Unsupported options

The following fields from SwidgeCommonOptions are accepted by the interface but not supported by this module:

---

Rate limits

The 0x Swap API enforces rate limits based on your plan tier:

Limits are enforced on fixed 1-second windows across all endpoints combined. The API returns HTTP 429 Too Many Requests when the limit is exceeded.

See the 0x rate limits documentation for details and to discuss higher limits.

---

Support

Open an issue at github.com/0xProject/wdk-protocol-swidge-0x/issues.

---

Security

See SECURITY.md for the vulnerability disclosure process.

---

License

Apache 2.0 — see LICENSE.