API integration

Dymension is an evm-compatible blockchain which is built using cometbft (used to be tendermint), cosmos-sdk and ethermint with the following versions:

1. cosmos-sdk : v0.46.15
2. CometBFT (previously tendermint): v0.34.29
3. Ethermint: v0.22.0

As such, every documentation relevant to those versions should be compatible with the Dymension blockchain.

Clients & APIS

Full API documentation for each version can be found here:

1. Cosmos SDK:
   1. GRPC
   2. REST (Based on GRPC using grpc-gateway)
2. CometBFT (previously tendermint)
   1. RPC
3. Ethermint
   1. JSON-RPC

Working with addresses

Though the dymension blockchain supports cosmos-style addresses (e.g dym1…), it aims for users to only use Ethereum-like hex addresses as such. Behind the scenes it’s recommended to subscribe to events and query the cosmos-style addresses and not the Ethereum API (more on that on the next section).

The translation between hex addresses and cosmos-style (bech32) addresses can be done using:

1. Bash - DYMD CLI

   1. dymd debug addr <address-to-convert>

2. Javascript - CosmJS encoding package

   1. Installation: yarn add [@cosmjs/encoding](https://github.com/cosmos/cosmjs/blob/main/packages/encoding)

   2. usage:

      import { fromBech32, fromHex, toBech32, toHex } from ‘cosmjs/packages/encoding’;
      export const convertToHexAddress = (bech32Address: string): string => {
          return ‘0x’ + toHex(fromBech32(bech32Address).data);
      };
      export const convertToBech32Address = (hexAddress: string, bech32Prefix: string): string => {
          return toBech32(bech32Prefix, fromHex(hexAddress.replaceAll(/^0x/g, ‘’)));
      };

Signing SDK

1. Ethers

   import { ethers } from 'ethers';
   const wallet = ethers.Wallet.fromPhrase('<mnemonic>');   wallet.signTransaction({
   
       from: '<from-address>‘,
       to: ‘<to-address>',
       value: <hex-amount>,
       gasLimit: <hex-gas-limit>,
       gasPrice: <hex-gas-price>,
       data: '0x',
       chainId: <hex-chain-id>,
       nonce: <currently-nonce>
   })

Subscribing to events

In order to keep up with the latest updates on an account state it is recommended to subscribe to events using Tendermint RPC’s subscribe method. When registering for account events it’s recommended to subscribe to the cosmos-style address (e.g dym1..) as not all events will be triggered in the Ethereum JSON-RPC.

For example, in order to subscribe to all the transfers which has been made to a specific account, one can use the Tendermint RPC’s subscribe method with the combination of the following filter: tm.event = 'Tx' AND transfer.recipient = 'dym10we8hmakhe360u25uwa0drxytgyh9dl83ev0hv'

API Examples

The following are examples on how to query the API. There are numerous api types and clients to do that and each provider should choose their preferred way based on the docs and information provided before.

Mainnet

chain-id: dymension_1100-1

Mainnet API public endpoints:

• RPC (tendermint): https://dymension-mainnet-tendermint.public.blastapi.io
• LCD (rest): https://dymension-mainnet-rest.public.blastapi.io
• JSON-RPC (EVM): https://dymension-mainnet.public.blastapi.io

Testnet

chain-id: blumbus_111-1

Testnet API public endpoints:

• RPC (tendermint): https://dymension-testnet-tendermint.public.blastapi.io
• LCD (rest): https://dymension-testnet-rest.public.blastapi.io
• JSON-RPC (EVM): https://dymension-testnet.public.blastapi.io

NOTE

The api is public and such may enforce certain rate limitations. In order to get a private endpoints which have better performance and rate limits please head to https://blastapi.io/

API	Description	URL/Type	Query
Get latest block height	Return latest block on the chain	RPC (tendermint)	curl -X GET <tendermint-rpc-url>/status -H "accept: application/json"
Get block info	Return block details by height	RPC (tendermint)	curl -X GET <tendermint-rpc-url>/block?height=<some-height> -H "accept: application/json"
Get transaction info	Return transaction details by transaction hash	RPC (tendermint)	curl -X GET <tendermint-rpc-url>/tx?hash=<hash>&prove=true -H "accept: application/json"
Get address balance	Return address balance by address, token and height	LCD (rest)	curl -X GET <lcd-url>/cosmos/bank/v1beta1/balances/<dym-address> -H "accept: application/json"
Broadcast transaction	Broadcast signed transaction	RPC (tendermint)	Curl -X GET <tendermint-rpc-url>/broadcast_tx_commit?tx=<tx-data>