0x Swidge Overview
Overview of @0x/wdk-protocol-swidge-0x 0.1.0 for same-chain EVM token swaps.
The 0x Swidge module connects a WDK EVM wallet account to the 0x Swap API v2 for same-chain token swaps through the AllowanceHolder flow.
Use @0x/wdk-protocol-swidge-0x@0.1.0. The released source is maintained by 0x Labs and tagged v0.1.0.
When to use it
Use this module when your application needs:
- Indicative exact-input or exact-output quotes for same-chain EVM swaps.
- Firm 0x quotes and transaction submission through a writable WDK EVM account.
- Automatic ERC-20 approval through the WDK account when the 0x quote reports insufficient allowance.
- On-chain status checks for submitted swap transactions.
- Optional network-fee and protocol-fee limits before execution.
Do not use this module for cross-chain routes. A toChain value that differs from the configured chainId causes quoteSwidge() and swidge() to reject the request.
Responsibility model
| Area | Owner |
|---|---|
| Wallet account, key material, transaction signing, RPC access, and ERC-20 approval | WDK wallet module and host application |
| Route calculation, indicative prices, firm quotes, and transaction calldata | 0x Swap API |
| User confirmation, token allowlists, API-key handling, fee policy, retries, and status polling | Host application |
Execution model
quoteSwidge() calls the 0x AllowanceHolder /price endpoint and returns an indicative SwidgeQuote. It does not submit an approval or swap transaction.
swidge() requests a new firm quote. For an ERC-20 sell token, it can submit an approval transaction and wait for its receipt before submitting the swap transaction. It then returns a WDK SwidgeResult containing a source transaction hash and a tracking id in the form '<chainId>:<transactionHash>'.
The indicative result from quoteSwidge() is not the firm quote executed by swidge(). The 0.1.0 API obtains that firm quote inside swidge(), so treat the indicative quote as a preview rather than a locked execution result. Apply fee limits and show the token pair, recipient, available amounts, slippage, and disclosed fees before requesting confirmation.
Version 0.1.0 limitations
- The module supports same-chain EVM swaps only.
getSupportedTokens()is not implemented. Pass a chain-specific ERC-20 contract address or a documented native-token alias directly.getSupportedChains()returns a static list from the package source; it does not verify live liquidity for a token pair.refundAddressandminAmountOutare not consumed byquoteSwidge()orswidge(). Route execution always uses the configuredchainId.fromChainis a status-only option.getSwidgeStatus()reads it when resolving a bare transaction hash.quoteSwidge()does not expose an expiry.- Fallback minimum-output and fee-limit calculations convert token-sized values to JavaScript
number; large base-unit values can lose precision. - API requests have no module-level retry, timeout, or cancellation configuration.
- Status is derived from the bound account's transaction and receipt methods, not from a 0x status endpoint.
Next steps
Usage
Review the quote, confirmation, execution, approval, and status flows.
Configuration
Review required API, chain, slippage, approval, and fee-limit settings.
API Reference
Review the 0.1.0 constructor, methods, options, results, chains, and errors.
Version 0.1.0 Source
Inspect the released source and release notes maintained by 0x Labs.