0x Swidge API Reference

Version 0.1.0 declares ZeroExProtocol as the default and named export of @0x/wdk-protocol-swidge-0x.

import ZeroExProtocol, {
  ZeroExFeeLimitExceededError,
  ZeroExValidationError
} from '@0x/wdk-protocol-swidge-0x'

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

Class: ZeroExProtocol

ZeroExProtocol extends SwidgeProtocol from @tetherto/wdk-wallet/protocols.

Constructor

new ZeroExProtocol(
  account: IWalletAccount | IWalletAccountReadOnly | undefined,
  config: ZeroExProtocolConfig
)

apiKey and chainId are required. A writable account implementing sendTransaction() is required for swidge().

The generated declaration currently marks config optional even though construction without both required fields throws at runtime. Pass config explicitly.

quoteSwidge(options)

quoteSwidge(options: SwidgeOptions): Promise<SwidgeQuote>

Calls the 0x AllowanceHolder /price endpoint and returns an indicative quote. It accepts exact-input and exact-output requests.

The method can run without an account. When a bound account's address resolves, it is sent as the 0x taker. If no account address is available, options.recipient is used as the taker when provided.

swidge(options, config?)

swidge(
  options: SwidgeOptions,
  config?: SwidgeProtocolConfig
): Promise<SwidgeResult>

Calls the 0x AllowanceHolder /quote endpoint, evaluates configured fee limits, performs an ERC-20 approval when required, and submits the transaction returned by 0x.

config supports per-call maxNetworkFeeBps and maxProtocolFeeBps overrides.

getSwidgeStatus(id, options?)

getSwidgeStatus(
  id: string,
  options?: SwidgeStatusOptions
): Promise<SwidgeStatusResult>

Accepts:

• The '<chainId>:<transactionHash>' id returned by swidge().
• A bare transaction hash with options.fromChain.
• A bare transaction hash without options.fromChain, which falls back to the configured chainId.

The method maps a successful receipt to completed, a reverted receipt to failed, and an unresolved lookup to pending. If getTransactionByHash() exists and returns null, it throws ZeroExUnknownTransactionError.

getSupportedChains()

getSupportedChains(): Promise<SwidgeSupportedChain[]>

Returns a static list defined by the 0.1.0 package source:

This method does not call 0x or prove that a requested token pair has live liquidity.

getSupportedTokens()

getSupportedTokens(): Promise<never>

Throws NotImplementedError. Pass chain-specific ERC-20 contract addresses or a documented native-token alias to quoteSwidge() and swidge().

SwidgeOptions behavior

Use token amounts in the token's smallest unit. Pass positive bigint values when possible. Although the interface also accepts number, values above Number.MAX_SAFE_INTEGER can lose precision before conversion, and the module does not reject zero or negative amounts before calling 0x.

Native-token aliases

Five identifiers resolve to the chain's native token in the v0.1.0 source:

• native
• eth
• '' (an empty string)
• 0x0000000000000000000000000000000000000000
• 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE

The module matches these identifiers case-insensitively and rewrites each one to the 0x sentinel address before sending the request. eth and '' identify the native token on every supported chain; for example, eth means POL on Polygon, not ether.

Any other token string is forwarded to 0x unchanged. The module does not trim, validate, or checksum non-native token addresses.

ZeroExProtocolConfig

type ZeroExProtocolConfig = {
  chainId: number | string
  apiKey: string
  baseUrl?: string
  defaultSlippage?: number
  skipApproval?: boolean
  maxNetworkFeeBps?: number | bigint
  maxProtocolFeeBps?: number | bigint
}

See Configuration for validation, approval, and fee-limit caveats.

Quote and result fields

quoteSwidge() returns:

When 0x omits minBuyAmount for an exact-input quote, the fallback converts the buy amount to number before applying slippage. Large base-unit values can therefore lose precision.

swidge() returns:

Fee mapping

Runtime exports

The 0.1.0 package entrypoint exports:

• ZeroExProtocol as the default and a named export.
• ISwidgeProtocol.
• ZeroExApiError.
• ZeroExInsufficientLiquidityError.
• ZeroExFeeLimitExceededError.
• ZeroExReadOnlyError.
• ZeroExValidationError.
• ZeroExUnsupportedOperationError.
• ZeroExTransactionRevertedError.
• ZeroExTimeoutError.

The package also ships TypeScript declarations for ZeroExProtocolConfig and the inherited Swap, Bridge, and Swidge type aliases exposed by its entrypoint.

The package also declares a bare export condition that initializes bare-node-runtime/global before re-exporting the main entrypoint.

Errors