Working with Tokens
What are Token Lists?¶
When trading on DEXs, you should understand how symbols map to addresses for each chain/network. Token symbols are not unique and may have duplicates or scammy clones on each network, so it's very important to be aware of which token address you are actually trading.
Hummingbot uses the Token Lists standard to define a token dictionary for each network. For example, here are the DAI and HBOT entries from the default Token List for Ethereum Mainnet:
When you reference the symbols DAI and HBOT in a strategy, transactions on the
ethereum_mainnet chain/network will use its Token List to
identify the corresponding address.
Where are lists stored?¶
Starting in v1.17.0, Token Lists for each chain are stored in the
/conf/lists directory of the root Gateway directory.
For the [default Docker installation]](https://github.com/hummingbot/deploy-examples/tree/main/hummingbot_gateway_compose) below, the lists are located in the
The folder location and list file is defined in each blockchain's config file (i.e.
/conf/ethereum.yml). It also defines a
tokenListSource (path to the designated file or URL) for each network. Note that
URL-based token lists may impact client latency, compared to accessing the Token List via
Users are free to change this setting by configuring the
tokenListSource parameters for each network - see Updating config parameters for more information.
You can replace any of the Token Lists in the
/conf/lists folder with updated versions. Go to Token Lists and look for a list that contains the tokens you wish to trade. You can download the list and change
tokenListSource to refer to it, or copy the token entries that you need into the default Token List.
Alternatively, you may add entries to the existing lists by following the convention above.
On Ethereum and EVM-compatible chains, wallets need to approve other addresses (such as DEXs) before transferring tokens to them. You can inspect the allowance for a spender address to see how much of a specific token you can tranfer to it.
start a strategy or script, Gateway automatically checks whether both base and quote tokens are approved for the DEX that you are using. If they are not approved or if allowance is insufficient, you will see an log message like "Waiting for allowances.." and the strategy will not start.
Here is how you can approve tokens:
Use this command to approve tokens to enable trading on DEXs:
Here is an example:
This command is a good way to test whether or not your network's Token List is resolving the symbol correctly. If so, the symbol should displayed in
balance along with the correct balance.
/evm/approve in Postman¶
Alternatively, you can call the
/evm/approve endpoint directly from Postman. Afterwards, you can paste the
hash value in the response in the
txHash parameter in
network/poll endpoint to check when the transaction is confirmed.
After it's confirmed, you can use the
/evm/allowances endpoint to check whether the approval was successful:
Displaying tokens in
connector-tokens command to display token balances for various networks. Afterwards, the tokens will be displayed when you run the
balance command. Note that you may append multiple tokens with commas.
Here is an example:
An testnet faucet is a tool that allows developers and users to obtain testnet ETH or other test assets for free. Testnet ETH is a cryptocurrency that is used exclusively for testing purposes on the Ethereum network and has no real-world value.
Using an Ethereum testnet faucet is a simple process that involves the following steps:
Enter your testnet wallet address where indicaated.
Complete any additional verification steps: Depending on the testnet faucet you are using, you may be required to complete additional verification steps, such as solving a captcha or proving that you are not a robot.
Receive your testnet ETH: After you have completed the verification steps, the testnet ETH will be sent to your Ethereum testnet address. You can then use this ETH to experiment with the Ethereum testnet network.
Decentralized exchanges (DEXs) such as Uniswap, Uniswap-Polygon, and TraderJoe have a built-in functionality that automatically converts, or "wraps", native tokens when used for swap trading. This wrapping process is hidden from the user and happens behind the scenes.
Gateway does not auto-wrap tokens by default so users need to wrap native tokens before using them with Gateway. For Uniswap,
ETH should be wrapped to
WETH and for Uniswap-Polygon,
MATIC should be wrapped for
WMATIC. Similarly, for TraderJoe which is an Avalanche blockchain DEX, its native
AVAX token should be wrapped to
WAVAX. It's crucial for users to familiarize themselves with the specific token wrapping requirements of the DEX they are using.
As of version
v1.4.0, Gateway does not provide an error message if a user attempts to use a token that hasn't been wrapped. Instead, it will simply display the message "Markets are not ready." However, we are actively working on integrating more informative error messages in future releases to improve user experience.
For reference check the Uniswap Docs here