{"_id":"@0x/wdk-protocol-swidge-0x","name":"@0x/wdk-protocol-swidge-0x","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@0x/wdk-protocol-swidge-0x","version":"0.1.0","description":"WDK swidge protocol module for EVM token swaps via the 0x Swap API v2.","keywords":["wdk","protocol","swidge","swap","0x","evm","defi"],"homepage":"https://0x.org","repository":{"type":"git","url":"git+https://github.com/0xProject/wdk-protocol-swidge-0x.git"},"bugs":{"url":"https://github.com/0xProject/wdk-protocol-swidge-0x/issues"},"author":{"name":"0x Labs"},"license":"Apache-2.0","main":"index.js","type":"module","types":"./types","publishConfig":{"access":"public"},"scripts":{"build:types":"tsc","lint":"standard","lint:fix":"standard --fix","test":"cross-env NODE_OPTIONS=--experimental-vm-modules jest","test:coverage":"cross-env NODE_OPTIONS=--experimental-vm-modules jest --coverage","e2e":"node tests/e2e/swap-base.js"},"dependencies":{"@tetherto/wdk-wallet":"^1.0.0-beta.15","bare-node-runtime":"^1.1.4"},"devDependencies":{"@tetherto/wdk-wallet-evm":"^1.0.0-beta.16","cross-env":"^7.0.3","jest":"^29.7.0","standard":"^17.1.2","typescript":"^5.8.3"},"exports":{".":{"types":"./types/index.d.ts","bare":"./bare.js","default":"./index.js"},"./package":{"default":"./package.json"}},"standard":{"ignore":["bare.js","tests/**/*.js"]},"_id":"@0x/wdk-protocol-swidge-0x@0.1.0","gitHead":"a0615159c116fd827533dfd3ab71adfc663d3312","_nodeVersion":"22.19.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-iGsOI5iyCVLisTYoYGsfnKKL1eiVTSTSZ4WlkzmMz7NU/GBrXjdEiRznStlEA9VqdilZTxb39NJq1ApdG09M4A==","shasum":"df5ca170f6bccc8554877b03196cdf782ee8de7f","tarball":"https://registry.npmjs.org/@0x/wdk-protocol-swidge-0x/-/wdk-protocol-swidge-0x-0.1.0.tgz","fileCount":14,"unpackedSize":89960,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIH/5f8VJ0aKO7Z4VGcYbmyJnKfD/5UcvIfM20KYPuqR0AiEAs2AOuP86NWdUtirC+64rh9g6DyxNsU014rmWXCBB2BY="}]},"_npmUser":{"name":"0xjess","email":"jessica@0xproject.com"},"directories":{},"maintainers":[{"name":"zeroextalal","email":"talalashraf@0xproject.com"},{"name":"dekz","email":"jacob@dekz.net"},{"name":"amirbandeali","email":"abandeali1@gmail.com"},{"name":"henryzhu","email":"hz@henryzhu.me"},{"name":"tobernguyen","email":"tobernguyen@gmail.com"},{"name":"mwelche","email":"mathieuwelche@gmail.com"},{"name":"0xpgrzesik","email":"piotr@0xproject.com"},{"name":"patrickat0x","email":"patrickw@0xproject.com"},{"name":"0xjess","email":"jessica@0xproject.com"},{"name":"cb44","email":"chrisbraun@0xproject.com"},{"name":"wojciechwasik","email":"wojciech@0xproject.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/wdk-protocol-swidge-0x_0.1.0_1786559860429_0.7022601597687277"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-12T18:37:40.194Z","0.1.0":"2026-08-12T18:37:40.569Z","modified":"2026-08-12T18:37:41.017Z"},"maintainers":[{"name":"zeroextalal","email":"talalashraf@0xproject.com"},{"name":"dekz","email":"jacob@dekz.net"},{"name":"amirbandeali","email":"abandeali1@gmail.com"},{"name":"henryzhu","email":"hz@henryzhu.me"},{"name":"tobernguyen","email":"tobernguyen@gmail.com"},{"name":"mwelche","email":"mathieuwelche@gmail.com"},{"name":"0xpgrzesik","email":"piotr@0xproject.com"},{"name":"patrickat0x","email":"patrickw@0xproject.com"},{"name":"0xjess","email":"jessica@0xproject.com"},{"name":"cb44","email":"chrisbraun@0xproject.com"},{"name":"wojciechwasik","email":"wojciech@0xproject.com"}],"description":"WDK swidge protocol module for EVM token swaps via the 0x Swap API v2.","homepage":"https://0x.org","keywords":["wdk","protocol","swidge","swap","0x","evm","defi"],"repository":{"type":"git","url":"git+https://github.com/0xProject/wdk-protocol-swidge-0x.git"},"author":{"name":"0x Labs"},"bugs":{"url":"https://github.com/0xProject/wdk-protocol-swidge-0x/issues"},"license":"Apache-2.0","readme":"# @0x/wdk-protocol-swidge-0x\n\n<a href=\"https://docs.wdk.tether.io\"><picture><source media=\"(prefers-color-scheme: dark)\" srcset=\"assets/built-with-wdk-dark.svg\"><img alt=\"Built with WDK\" height=\"28\" src=\"assets/built-with-wdk-light.svg\"></picture></a>\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n\nWDK **Swidge** protocol module for EVM token swaps via the [0x Swap API v2](https://0x.org/docs/api).\n\nThis module implements the [`SwidgeProtocol`](https://github.com/tetherto/wdk-wallet/blob/main/src/protocols/swidge-protocol.js) 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.\n\n> **Note:** Cross-chain bridging via 0x is not yet supported. `toChain` must equal the source chain.\n\n---\n\n## Installation\n\n```bash\nnpm install @0x/wdk-protocol-swidge-0x\n```\n\n---\n\n## Configuration\n\n| Option | Type | Required | Description |\n|---|---|---|---|\n| `chainId` | `number \\| string` | ✅ | EVM chain ID of the bound wallet account |\n| `apiKey` | `string` | ✅ | 0x API key — get one at [dashboard.0x.org](https://dashboard.0x.org/create-account) |\n| `baseUrl` | `string` | | API base URL. Defaults to `https://api.0x.org` |\n| `defaultSlippage` | `number` | | Default slippage as a decimal (e.g. `0.005` = 0.5%). Defaults to no slippage param sent |\n| `skipApproval` | `boolean` | | Skip automatic ERC-20 approval before swapping |\n| `maxNetworkFeeBps` | `number \\| bigint` | | Maximum network fee in basis points of the input amount |\n| `maxProtocolFeeBps` | `number \\| bigint` | | Maximum protocol fee in basis points of the input amount |\n\nStore your API key in an environment variable — never commit it to source control:\n\n```bash\n# .env\nZERO_EX_API_KEY=your_api_key_here\n```\n\n---\n\n## Usage\n\n```js\nimport ZeroExProtocol from '@0x/wdk-protocol-swidge-0x'\n\nconst USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'\nconst WETH = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2'\n\n// ── 1. Get an indicative quote (no wallet needed) ──────────────────────────\n\nconst protocol = new ZeroExProtocol(undefined, {\n  chainId: 1, // Ethereum mainnet\n  apiKey: process.env.ZERO_EX_API_KEY,\n  defaultSlippage: 0.005 // 0.5%\n})\n\nconst quote = await protocol.quoteSwidge({\n  fromToken: USDC,\n  toToken: WETH,\n  fromTokenAmount: 100_000_000n // 100 USDC (6 decimals)\n})\n\nconsole.log('Estimated WETH out:', quote.toTokenAmount)\nconsole.log('Minimum WETH out:  ', quote.toTokenAmountMin)\n\n// ── 2. Execute (requires a full WDK EVM wallet account) ───────────────────\n\n// import { WalletManager } from '@tetherto/wdk-wallet'\n// import EvmWallet from '@tetherto/wdk-wallet-evm'\n// const manager = new WalletManager({ wallets: [new EvmWallet()] })\n// await manager.load({ mnemonic: process.env.MNEMONIC })\n// const account = await manager.getWallet('evm').getAccount(0)\n\nconst execProtocol = new ZeroExProtocol(account, {\n  chainId: 1,\n  apiKey: process.env.ZERO_EX_API_KEY,\n  defaultSlippage: 0.005\n})\n\nconst result = await execProtocol.swidge({\n  fromToken: USDC,\n  toToken: WETH,\n  fromTokenAmount: 100_000_000n\n})\n\nconsole.log('Swap submitted:', result.hash)\n\n// ── 3. Poll for status ────────────────────────────────────────────────────\n\nlet status\ndo {\n  await new Promise(r => setTimeout(r, 3000))\n  const s = await execProtocol.getSwidgeStatus(result.id)\n  status = s.status\n  console.log('Status:', status)\n} while (status === 'pending')\n```\n\nSee [`examples/swap-usdc-to-weth.js`](examples/swap-usdc-to-weth.js) for a runnable example.\n\n---\n\n## Supported chains\n\n| Chain | Chain ID |\n|---|---|\n| Abstract | 2741 |\n| Arbitrum One | 42161 |\n| Avalanche C-Chain | 43114 |\n| Base | 8453 |\n| Berachain | 80094 |\n| BNB Smart Chain | 56 |\n| Ethereum | 1 |\n| HyperEVM | 999 |\n| Ink | 57073 |\n| Linea | 59144 |\n| Mantle | 5000 |\n| Monad | 143 |\n| OP Mainnet | 10 |\n| Plasma | 9745 |\n| Polygon | 137 |\n| Scroll | 534352 |\n| Sonic | 146 |\n| Tempo | 4217 |\n| Unichain | 130 |\n| World Chain | 480 |\n\nCall `getSupportedChains()` to retrieve the full list at runtime.\n\n---\n\n## Token discovery\n\nThe 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`.\n\nFor 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.\n\nNote 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.\n\n---\n\n## Status mapping\n\n| On-chain state | `SwidgeStatus` |\n|---|---|\n| Transaction unknown to the network | throws `ZeroExUnknownTransactionError` |\n| Transaction known, no receipt yet | `pending` |\n| Receipt with success status | `completed` |\n| Receipt with reverted status | `failed` |\n\n> The module has no server-side status endpoint; status is resolved from on-chain state via the bound wallet account.\n>\n> 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.\n>\n> **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`.\n\n---\n\n## Fee mapping\n\n| 0x response field | `SwidgeFeeType` | Notes | Legacy mapping |\n|---|---|---|---|\n| `totalNetworkFee` | `network` | Denominated in the chain's native token (e.g. ETH) | `fee` |\n| `fees.zeroExFee` | `protocol` | 0x protocol fee | `bridgeFee` |\n| `fees.integratorFee` | `affiliate` | Integrator / referral fee | not visible |\n\nFee 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`:\n\n- **`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.\n- **`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.\n\n---\n\n## Error types\n\n| Class | When thrown |\n|---|---|\n| `ZeroExApiError` | The 0x API returned a non-2xx response |\n| `ZeroExInsufficientLiquidityError` | `liquidityAvailable: false` in the price response |\n| `ZeroExFeeLimitExceededError` | A quoted fee exceeds a configured `maxNetworkFeeBps` / `maxProtocolFeeBps` cap, or a configured cap cannot be evaluated (fail-closed) |\n| `ZeroExReadOnlyError` | `swidge` is called without a full signing account |\n| `ZeroExValidationError` | Invalid or missing input parameters |\n| `ZeroExUnsupportedOperationError` | An unsupported operation is requested (e.g. cross-chain `toChain`) |\n| `ZeroExUnknownTransactionError` | `getSwidgeStatus` is called for a transaction the network has no record of |\n| `ZeroExTransactionRevertedError` | The swap transaction reverted on-chain |\n| `ZeroExTimeoutError` | Timed out waiting for transaction confirmation |\n| `NotImplementedError` | `getSupportedTokens()` is called |\n\n---\n\n## WDK interface\n\nThis module implements `SwidgeProtocol` from `@tetherto/wdk-wallet ^1.0.0-beta.11`.\n\nThe `swap`, `quoteSwap`, `bridge`, and `quoteBridge` methods are inherited from the base class and delegate to `swidge` / `quoteSwidge` respectively.\n\n---\n\n## Development\n\n```bash\nnpm install       # install dependencies\nnpm test          # run unit tests\nnpm run lint      # check code style (JavaScript Standard Style)\nnpm run build:types  # generate TypeScript declarations in types/\n```\n\nEnd-to-end test against the live 0x API (read-only, no wallet needed):\n\n```bash\nZERO_EX_API_KEY=... npm run e2e\n```\n\nTo test real swap execution, add a BIP-39 mnemonic:\n\n```bash\nZERO_EX_API_KEY=... MNEMONIC=\"word word ...\" npm run e2e\n```\n\n---\n\n## Verified on mainnet\n\nEnd-to-end tested against the live 0x API on Base mainnet (chain 8453):\n\n| Swap | Chain | Tx |\n|---|---|---|\n| 1 USDC → WETH | Base | [`0x87afe3…704ec`](https://basescan.org/tx/0x87afe381a625f1af33f7e4faec1f43fbbcb2dde569c2cf1471f37bb825b704ec) |\n\n---\n\n## Unsupported options\n\nThe following fields from `SwidgeCommonOptions` are accepted by the interface but not supported by this module:\n\n| Option | Reason |\n|---|---|\n| `toChain` | Cross-chain bridging is not implemented. Passing a `toChain` that differs from the configured `chainId` throws an error. |\n| `refundAddress` | The 0x AllowanceHolder flow has no refund path. This field is silently ignored. |\n\n---\n\n## Rate limits\n\nThe 0x Swap API enforces rate limits based on your plan tier:\n\n| Plan | Rate limit |\n|---|---|\n| Standard (free) | 5 requests per second |\n| Custom | Higher limits available on request |\n\nLimits are enforced on fixed 1-second windows across all endpoints combined. The API returns HTTP `429 Too Many Requests` when the limit is exceeded.\n\nSee the [0x rate limits documentation](https://docs.0x.org/docs/developer-resources/rate-limits) for details and to discuss higher limits.\n\n---\n\n## Support\n\nOpen an issue at [github.com/0xProject/wdk-protocol-swidge-0x/issues](https://github.com/0xProject/wdk-protocol-swidge-0x/issues).\n\n---\n\n## Security\n\nSee [SECURITY.md](SECURITY.md) for the vulnerability disclosure process.\n\n---\n\n## License\n\nApache 2.0 — see [LICENSE](LICENSE).\n","readmeFilename":"README.md","_rev":"1-57b5e06c3ca35836dbc7da3b3ea9e19e"}