Zaidan dealer clientGlobalsDealerClient

Class: DealerClient

A simple client for the Zaidan dealer server.


  • DealerClient







+ new DealerClient(dealerUri: string, provider: Provider, options: DealerOptions): DealerClient

Defined in DealerClient.ts:76

Instantiate a new DealerClient. Prior to use, client.init() should be called, which triggers a prompt for the user to allow MetaMask to connect to the site.

For usage in server-side applications, provide a second argument to the constructor with an Ethereum JSONRPC URL, which will override the default setting of attempting to load a web3 provider through the browser.


Name Type Default Description
dealerUri string - the base RPC API path for the dealer server
provider Provider - an ethereum provider
options DealerOptions {} optional configuration to allow non standard usages of the class

Returns: DealerClient



GAS_PRICE: BigNumber

Defined in DealerClient.ts:70

Default gas price to use for allowance transactions (in wei).


coinbase: string

Defined in DealerClient.ts:61

Stores the current user's coinbase address.


contractWrappers: ContractWrappers

Defined in DealerClient.ts:64

Initialized contract wrappers for interacting with the 0x system.


initialized: boolean

Defined in DealerClient.ts:67

Set to 'true' after a successful .init(), must be called before use.


networkId: number

Defined in DealerClient.ts:58

Stores the configured Ethereum network ID.


pairs: string[]

Defined in DealerClient.ts:44

An array of the currently supported pairs (as expected by getQuote).


provider: Provider | SupportedProvider | MetamaskSubprovider

Defined in DealerClient.ts:55

Provider instance used to interact with Ethereum.


tokens: object

Defined in DealerClient.ts:49

Maps tokenTicker => address for looking up common tokens.

Type declaration:

  • [ ticker: string]: string


txPriority: GasPriority

Defined in DealerClient.ts:76

Transaction priority (according to API), defaults to fast.


web3Wrapper: Web3Wrapper

Defined in DealerClient.ts:52

Provides convenience methods for interacting with Ethereum.


COMPATIBLE_VERSION: string = "3.0"

Defined in DealerClient.ts:30

The dealer API version this client is compatible with.


MAX_ALLOWANCE: BigNumber = new BigNumber(2).exponentiatedBy(256).minus(1)

Defined in DealerClient.ts:27

2^256 - 1 represents an effectively "unlimited" allowance



fromWei(weiAmount: string): string

Defined in DealerClient.ts:422

Convert a number of tokens, denominated in the smallest unit - "wei" - to "full" units, called "ether". One ether = 1*10^18 wei.

All contract calls require amounts in wei, but the user should be shown amounts in ether. All values are strings to avoid precision issues.


client.fromWei("100000000000000000000") // > "100"
client.fromWei("10000000000000000000")   // > "10"


Name Type Description
weiAmount string The token amount in wei to convert.

Returns: string

The same amount in ether, string returned for precision.


getAuthorizationStatus(takerAddress: string): Promise‹AuthorizationInfo

Defined in DealerClient.ts:142

Check if a taker's address will be allowed to trade with the dealer based on the dealer's configured whitelist/blacklist.


Name Type Default Description
takerAddress string this.coinbase specify the taker address to check status for.

Returns: Promise‹AuthorizationInfo

information about taker's authorization status (see [AuthorizationInfo]).


getBalance(tokenTicker: string): Promise‹string›

Defined in DealerClient.ts:372

Return the user's balance (in wei) of a specified supported token. Only supported tickers will work (see client.tokens).

Return balance is in base units (wei), and returned as a string. Convert to a BigNumber instance for math.


// return value is in 'wei', so convert if needed before displaying
await client.getBalance("WETH") // > "12597034312510000"


Name Type Description
tokenTicker string The token's short ticker (ex. "ZRX", "DAI").

Returns: Promise‹string›

The user's balance of the token in wei, as a string.

getEtherscanLink(txId: string): string

Defined in DealerClient.ts:456

Returns the URL of the Etherscan status page for the specified TX ID.

Useful for generating a link to show the user a transaction's status.


Name Type Description
txId string A valid Ethereum transaction ID.

Returns: string

A string that can be used as a hyperlink to etherscan.


getQuote(size: number, symbol: string, side: string, takerAddress: string): Promise‹QuoteResponse

Defined in DealerClient.ts:177

Request a price quote a signed order from the dealer server. The response includes price and fee information, as well as signed 0x order message for the quote

The order in the quote can be passed to client.handleTrade() which will request a signature from the client according to ZEIP-18, and will prepare a fill transaction for the dealer to fill.


const response = await client.getQuote(2, "WETH/DAI", "bid");

// response object example:
response = {
  expiration: 1559170656.0712497,
  id: "e68b5aa8-f84c-45b8-a312-eef35bba480f",
  size: 2,
  price: 3,
  order: {}, // will be a full signed 0x order object
  fee: 0.2156,


Name Type Default Description
size number - the amount of tokens the user is selling/buying (in units of base asset)
symbol string - the token pair the swap is for (ex: "WETH/DAI")
side string - either 'bid' or 'ask' depending on desired quote side
takerAddress string this.coinbase optionally override the default (must be able to sign)

Returns: Promise‹QuoteResponse

a price quote and signed maker order from the dealer server


getSwapQuote(size: number, clientAsset: string, dealerAsset: string, takerAddress: string): Promise‹SwapResponse

Defined in DealerClient.ts:220

An alternative interface for fetching a price quote using the concept of an asset "swap" as opposed to a conventional base/quote bid/ask interface.

Conceptually, the method allows you to swap size of clientAsset for an equivalent amount of dealerAsset, based on the price returned by the dealer server.

Under the hood, the request still goes through as a bid/ask, but allows for users to swap for specific amounts of assets that may only be served as a quote asset. For example, you can swap 100 DAI for wrapped ETH even if only the WETH/DAI pair is supported. Normally the quote would have to be requested in terms of WETH.


// fetch a quote to swap 100 DAI for WETH
const quote = await dealer.getSwapQuote(100, "DAI", "WETH");

// request for the trade to be filled
const txId = await dealer.handleTrade(quote);


Name Type Default Description
size number - the amount of takerAsset to swap for
clientAsset string - the ticker of the asset being sold (swapping for dealerAsset)
dealerAsset string - the ticker of the asset being bought that a price is quoted for
takerAddress string this.coinbase -

Returns: Promise‹SwapResponse

A price quote and signed maker order from the dealer server.


handleTrade(quote: SwapResponse | QuoteResponse, takerAddress: string): Promise‹string›

Defined in DealerClient.ts:268

Sign a 0x fillOrder transaction message, and submit it back to the server for settlement. Signs a fill transaction for the entire specified takerAssetAmount. Implements ZEIP-18 signing of the provided order object.

Allowances should be checked prior to calling this method.


// load a signed order from a quote
const quote = await dealer.getQuote(10, "WETH/DAI", "bid");

// many fields available in the quote
const { order, id, price, size } = quote;

// submit the trade for settlement
const txId = await dealer.handleTrade(quote);

// get a link to the transaction on Etherscan
const link = dealer.getEtherscanLink(txId);

// wait for trade to complete (throws if fails)
await dealer.waitForTransactionSuccessOrThrow(txId);


Name Type Default
quote SwapResponse | QuoteResponse -
takerAddress string this.coinbase

Returns: Promise‹string›

A promise that resolves to txId of the trade.


hasAllowance(tokenTicker: string): Promise‹boolean›

Defined in DealerClient.ts:314

Check if the user has set an allowance for the specified token. If the method returns false, allowance can be set with client.setAllowance.

Only works with supported tokens (see client.tokens).


// no allowance is set
await client.hasAllowance("DAI") // > false

// will be `true` after setting allowance
await client.setAllowance("DAI")
await client.hasAllowance("DAI") // > true


Name Type Description
tokenTicker string The token's short ticker (ex. "ZRX", "DAI").

Returns: Promise‹boolean›

Resolves to true if the user has a non-0 allowance for the token.


init(): Promise‹void›

Defined in DealerClient.ts:116

Initialize a DealerClient instance. A call to client.init() will trigger a MetaMask pop-up prompting the user to sign in, or allow the site access.

If the user has already allowed site access, the prompt will be skipped.

Returns: Promise‹void›

A promise that resolves when initialization is complete.


makeBigNumber(n: number | string): BigNumber

Defined in DealerClient.ts:401

Turn a string or primitive number into a BigNumber for math reasons.


let bigNum = client.makeBigNumber("10") // use any BigNumber methods
bigNum = client.makeBigNumber(10)       // works with strings or numbers


Name Type Description
n number | string the primitive number value to convert.

Returns: BigNumber

The number as a BigNumber instance.


setAllowance(tokenTicker: string): Promise‹TransactionReceiptWithDecodedLogs›

Defined in DealerClient.ts:348

Set an unlimited proxy allowance for the 0x ERC20 Proxy contract for the specified token ticker.

Only works with supported ERC20 tickers (see client.tokens).


try {
  // can take a long time (~1 min), resolves after tx is mined
  await client.setAllowance("DAI");

  console.log("failed to set allowance");
} catch {
  console.log("allowance is set");


Name Type Description
tokenTicker string The token's short ticker (ex. "ZRX", "DAI").

Returns: Promise‹TransactionReceiptWithDecodedLogs›

A promise that resolve when TX is mined, rejects if it fails.


supportedTickers(): string[]

Defined in DealerClient.ts:479

Return an array containing the list of supported token tickers.


client.supportedTickers() // > [ "DAI", "WETH", "ZRX ]

Returns: string[]

The supported token tickers.


toWei(etherAmount: string): string

Defined in DealerClient.ts:443

Convert a number of tokens (full units, called "ether") to "wei", the smallest denomination of most ERC-20 tokens with 18 decimals.

All contract calls require amounts in wei, but the user should be shown amounts in ether. All values are strings to avoid precision issues.


client.toWei("10")  // > "10000000000000000000"
client.toWei("1") // > "1000000000000000000"


Name Type Description
etherAmount string The token amount to convert.

Returns: string

The same amount in wei, string used for precision.


waitForTransactionSuccessOrThrow(txId: string): Promise‹void›

Defined in DealerClient.ts:384

Wait for a specific Ethereum transaction to be successfully mined.


Name Type Description
txId string A valid Ethereum transaction ID to wait for.

Returns: Promise‹void›

Resolves when mined successfully, rejects if the TX failed.