0x Swidge Configuration

ZeroExProtocol requires a 0x API key and an EVM chain id even when no wallet account is bound.

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

const zeroEx = new ZeroExProtocol(account, {
  chainId: 1,
  apiKey: process.env.ZERO_EX_API_KEY,
  defaultSlippage: 0.005,
  maxNetworkFeeBps: 50,
  maxProtocolFeeBps: 30
})

The import specifier above resolves from @0x/wdk-protocol-swidge-0x@0.1.0.

Constructor

new ZeroExProtocol(account?, config)

Configuration options

The constructor checks only that apiKey is truthy and chainId is not nullish. Validate the chain id, API URL, slippage range, and fee-limit values at your application boundary.

Chain context

Create one ZeroExProtocol instance per chain and bind it to an account on that chain:

const zeroEx = new ZeroExProtocol(baseAccount, {
  chainId: 8453,
  apiKey: process.env.ZERO_EX_API_KEY
})

Passing a different toChain to quoteSwidge() or swidge() throws ZeroExUnsupportedOperationError. Quote and execution requests use the configured chainId; getSwidgeStatus() reads options.fromChain only when resolving a bare transaction hash.

API-key handling

The module sends the key directly to the configured API base URL. Keep it in secret-managed configuration and restrict custom base URLs to trusted endpoints. Do not log request headers or commit .env files.

The 0.1.0 API client uses the runtime's global fetch. It does not expose request-timeout, cancellation, or custom-fetch options. The package's bare export initializes bare-node-runtime/global; other runtimes must provide fetch. Handle transient errors and ZeroExApiError in the host application.

Rate limits

The 0x rate-limit documentation describes the free tier as approximately five requests per second across all endpoints, enforced in fixed one-second windows.

The module does not throttle or retry requests. For its primary /price and /quote requests, an HTTP 429 response surfaces as ZeroExApiError with status === 429; back off before retrying.

The additional /price request used to evaluate an ERC-20 network-fee limit is an exception. If that conversion request fails, including with HTTP 429, execution fails closed as ZeroExFeeLimitExceededError because the fee cannot be evaluated.

Slippage

Configure an instance default:

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

Override it per route with options.slippage. The route value takes precedence over defaultSlippage.

The source converts slippage with Math.round(slippage * 10000) and does not validate its range. Reject non-finite, negative, or application-disallowed values before calling the module.

Approval policy

Automatic approval runs when all of these conditions are true:

• The sell token is not treated as the chain's native token.
• skipApproval is not true.
• The firm quote contains issues.allowance.

The module approves the quoted sell amount for the spender returned by 0x. When the approval result contains a transaction hash and the account supports getTransactionReceipt(), it polls every two seconds for up to three minutes.

Fee limits

Set limits on the instance or override them for one swidge() call:

await zeroEx.swidge(options, {
  maxNetworkFeeBps: 40,
  maxProtocolFeeBps: 25
})

Per-call values take precedence over instance values.

These limits evaluate fields in the 0x firm quote. The module does not independently estimate or cap the network fee charged by a separate ERC-20 approval transaction.

Neither limit caps fees.integratorFee. Treat maxNetworkFeeBps and maxProtocolFeeBps as targeted checks, not as a cap on the total of every reported fee.

Fee-ratio calculations convert quoted amounts and fees to JavaScript number. Large base-unit values can lose precision, especially when a calculated ratio is close to a configured cap.