exchange.IO("api", ...)

Calls a smart contract method on a Web3 exchange object. Read-only methods return the decoded value. Write methods sign and broadcast a transaction.

    
    
    
exchange.IO(k, address, method)

    
    
    
exchange.IO(k, address, method, ...args)

    
    
    
exchange.IO(k, address, method, value, ...args)

    
    
    
exchange.IO(k, address, method, ...args, options)

Examples

• The decimals method is a constant method of ERC20. Calling it costs no gas. It returns the precision (number of decimals) of the specified token.

  The decimals method takes no parameters. Return value: the precision of the token.

  
      javascript
      
      
  function main(){
      var tokenAddress = "0x111111111117dC0aa78b770fA6A738034120C302"    // Contract address of the token; the token in this example is 1INCH
      Log(exchange.IO("api", tokenAddress, "decimals"))
      // Output: 18 (the precision of the 1INCH token)
  }
  

• The allowance method is a constant method of ERC20. Calling it costs no gas. It returns the amount of the specified token that a given contract address is approved to spend.

  The allowance method takes 2 parameters: the first is the wallet address and the second is the approved (spender) address. Return value: the token allowance.

  owner: the wallet address. The example uses the string "owner" as a placeholder; replace it with the actual address.

  spender: the approved contract address. The example uses the string "spender" as a placeholder; replace it with the actual address, such as the address of Uniswap V3 router v1.

  
      javascript
      
      
  function main(){
      // Contract address of the token; the token in this example is 1INCH
      var tokenAddress = "0x111111111117dC0aa78b770fA6A738034120C302"
  
      // If the query returns 1000000000000000000, dividing it by the token's precision unit 1e18 shows that the wallet bound to the current exchange object has approved the spender address for 1 1INCH
      Log(exchange.IO("api", tokenAddress, "allowance", "owner", "spender"))
  }
  

• The approve method is a non-constant method of ERC20. Calling it costs gas. It approves a specified contract address to spend a given amount of the token.

  The approve method takes 2 parameters: the first is the approved (spender) address and the second is the allowance amount. Return value: txid.

  spender: the approved contract address. The example uses the string "spender" as a placeholder; replace it with the actual address, such as the address of Uniswap V3 router v1.

  0xde0b6b3a7640000: the approved amount, written here as a hexadecimal string. Its decimal value is 1e18. Dividing it by the token's precision unit in the example (1e18) gives 1, so 1 token is approved.

  The third parameter of the exchange.IO() function is the method name approve. You can also pass the methodId, e.g. "0x095ea7b3", or the full standard method signature, e.g. "approve(address,uint256)".

  
      javascript
      
      
  function main(){
      // Contract address of the token; the token in this example is 1INCH
      var tokenAddress = "0x111111111117dC0aa78b770fA6A738034120C302"
  
      // Hexadecimal string of the allowance: 0xde0b6b3a7640000 , decimal value: 1e18 , 1e18 divided by the token's precision unit equals 1 token , so this approves 1 token
      Log(exchange.IO("api", tokenAddress, "approve", "spender", "0xde0b6b3a7640000"))
  }
  

• The multicall method is a non-constant method of Uniswap V3. Calling it consumes gas. Use it to swap tokens across multiple paths.
  multicall can accept parameters in several ways; check the ABI that contains the method for details. Register the ABI before calling it. Return value: txid.
  For swaps on Uniswap or PancakeSwap, you can use the Uniswap or PancakeSwap exchange object directly instead of encoding the call yourself.

  The pseudocode below shows some of the details:

  
              javascript
              
              
  exchange.IO("api", ContractV3SwapRouterV2, "multicall(uint256,bytes[])", value, deadline, data)
  

  ContractV3SwapRouterV2: the address of the Uniswap V3 router v2 contract.
  value: the amount of native coin sent with the transaction, in wei (an on-chain integer; use exchange.IO("toUnits", "0.01", 18) to convert). Set it to 0 when the tokenIn token being swapped is not ETH.
  deadline: deadline is a parameter of the multicall method. You can set it to (new Date().getTime() / 1000) + 3600, which makes the transaction valid for one hour.
  data: data is a parameter of the multicall method, of type bytes[]. It is an array of the call data (hexadecimal strings starting with 0x) for each operation to run. As with exchange.IO("api", "eth", "send", "toAddress", toAmount), you can set gasLimit/gasPrice/nonce for a multicall call. Pseudocode again:

  
              javascript
              
              
  exchange.IO("api", ContractV3SwapRouterV2, "multicall(uint256,bytes[])", value, deadline, data, {gasPrice: 123456, gasLimit: 300000})
  

  Set the {gasPrice: 11, gasLimit: 111, nonce: 111} parameter to suit your needs, and pass it as the last argument of the exchange.IO() function.
  You can omit nonce to use the system default, or leave out gasLimit/gasPrice/nonce entirely to use the system defaults for all of them.

  With dryRun: true in this parameter, the transaction is signed but not broadcast, and the call returns an object with fields such as hash and raw (the signed transaction). To check in advance whether the call will succeed, replace api with call and simulate it with exchange.IO("call", ...), which does not sign and consumes no gas. For details, see exchange.IO("call", ...).

  
      javascript
      
      
  function main() {
      var ContractV3SwapRouterV2 = "0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45"
      // multicall(uint256,bytes[]) is not an ERC20 method: register the ABI first (built-in template)
      exchange.IO("abi", ContractV3SwapRouterV2, "uniswapV3SwapRouter02")
      var tokenInName = "ETH"
      // Convert 0.01 ETH to wei: value for a payable method is an on-chain integer
      var amountIn = exchange.IO("toUnits", "0.01", 18)
      var options = {gasPrice: 5000000000, gasLimit: 300000, nonce: 100}   // Example values only; set them for your actual use case
      // bytes[]: encoded call data for each operation (hex strings starting with 0x); an empty array here, set it for your actual use case
      var data = []
      var tx = exchange.IO("api", ContractV3SwapRouterV2, "multicall(uint256,bytes[])",
          (tokenInName == 'ETH' ? amountIn : 0), (new Date().getTime() / 1000) + 3600, data,
          options || {})
  }
  

Returns

Arguments

See Also

Remarks

Read-only methods run via eth_call on the latest block. They are not signed and use no gas.

Write methods are signed with the configured private key and then broadcast. When gasPrice is not set, chains that support EIP-1559 send an EIP-1559 (type 2) transaction. The priority fee is the larger of the node's suggested value (eth_maxPriorityFeePerGas) and the median of the actual priority fees over the last 20 blocks (eth_feeHistory). The max fee is 2 × baseFee + priority fee. Chains that do not support EIP-1559 bid at the eth_gasPrice returned by the node.

When nonce is not set, it is assigned automatically and kept in sync with the on-chain pending transaction count, so consecutive sends never reuse a nonce; see exchange.IO("nonce", ...). After a transaction is sent, use exchange.IO("waitReceipt", ...) to wait for it to be confirmed on-chain. If it stays unconfirmed for a long time, use exchange.IO("speedUp", ...) to resend it with a higher fee, or exchange.IO("cancelTx", ...) to cancel it.

Quote methods declared as nonpayable (such as Uniswap QuoterV2) are treated as write methods, so a transaction is signed and sent. To get only the return value or to dry-run a write operation, use exchange.IO("call", ...) to simulate the call.

Calls to read-only methods (view, pure) return the decoded value. If there is a single return value, it is returned directly. If there are several, an object keyed by output parameter names is returned, and unnamed outputs are named ret0, ret1, and so on. Integers of uint64 width or smaller are returned as numbers, and larger integers as decimal strings (in JavaScript and Python, integers with an absolute value of 2^53 or more are also returned as decimal strings to avoid losing precision). address is returned as a lowercase address starting with 0x (on TRON, an address starting with T). bytes is returned as a hex string without the 0x prefix. Fixed-length bytesN types such as bytes32 are returned as arrays of byte values (e.g. [17, 17, ...]).

Calls to write methods return the transaction hash (on Ethereum, a string starting with 0x; on TRON, a transaction ID without the 0x prefix). When dryRun is set, an object is returned with hash, raw (the signed transaction), from, to, value, data, nonce, gasLimit, chainId, type, gasPrice, maxFeePerGas and maxPriorityFeePerGas. If the call fails, a null value is returned; use GetLastError() to get the error message.