export const title = "Komodo DeFi SDK RPC Protocol v2.0"; export const description = "Starting with version beta-2.1.3434, the Komodo DeFi SDK supports the standardized protocol format called mmrpc 2.0.";

Komodo DeFi SDK Common Structures

The objects are in the request or response of multiple Komodo DeFi SDK methods have been grouped into the following sections:

Activation
Swaps
Lightning Network
Non-fungible Tokens
Wallet Operations

Structures which are used in more than one section are listed below:

AddressFormat

Structure	Type	Description
format	string (enum)	address format to which the input address should be converted. Possible values: `mixedcase` for ETH/ERC20 coins; `cashaddress` or `standard` for UTXO coins; `contract` or `wallet` for QTUM/QRC20
network	string (enum)	Optional, only used for UTXO coins. Network prefix for `cashaddress` format. Possible values: `bitcoincash` for BCH mainnet; `bchtest` for BCH testnet; `bchreg` for BCH regtest

#### Example

{
  "format": "mixedcase"
}

{
  "format": "cashaddress",
  "network": "bitcoincash"
}

AddressInfo

The AddressInfo object includes the following items for a given address:

Parameter	Type	Description
balances	object	A standard balanceInfos object. Not included in responses where `get_balances` is `false`
derivation_method	object	A standard DerivationMethod object
pubkey	string	The public key associated with the seed used to launch Komodo DeFi Framework
tickers	array	A list of tokens which were successfully activated. Only included in responses where `get_balances` is `false`

#### Example with balances

"bitcoincash:qrf5vpn78s7rjexrjhlwyzzeg7gw98k7t5qx64fztj": {
    "derivation_method": {
        "type": "Iguana"
    },
    "pubkey": "036879df230663db4cd083c8eeb0f293f46abc460ad3c299b0089b72e6d472202c",
    "balances": {
        "spendable": "0.11398301",
        "unspendable": "0.00001"
    }
}

Example without balances

"bitcoincash:qrf5vpn78s7rjexrjhlwyzzeg7gw98k7t5qx64fztj": {
    "derivation_method": {
        "type": "Iguana"
    },
    "pubkey": "036879df230663db4cd083c8eeb0f293f46abc460ad3c299b0089b72e6d472202c",
    "tickers": ["ASLP-SLP"]
}

BalanceInfos

The balanceInfos object includes the following items for a given coin or token:

Parameter	Type	Description
spendable	string (numeric)	The available amount of a coin or token which is ready to be traded or withdrawn.
unspendable	string (numeric)	The amount of a coin or token which is awaiting confirmation on the block chain for an incoming or outgoing transaction.

```json { "spendable": "12.11398301", "unspendable": "0.53" } ```

DerivationMethod

The DerivationMethod object includes the following items for a given coin or token:

Parameter	Type	Description
type	string	Defines how keypairs will be generated. Possible values: `Iguana` or `HDWallet`

Using the same seed or private key to generate keypairs using different derivation methods will result in a different address and private key for each method.

Where the value indicates:

Iguana: The coin or token is was activated using Iguana derivation (default).
HDWallet: The coin or token is was activated using a Heirarchical Deterministic (HD) Wallet derivation path.

```json { "type": "Iguana" } ```

EventStreamConfig

The EventStreamConfig object defines which events will be streamed to the client:

Parameter	Type	Description
access_control_allow_origin	string	Defines CORS whitelist. Use "*" to allow fromi any origin.
active_events	object	Events to be streamed to the client, along with configuration defineing frequency etc.
worker_path	string	WASM only. Path to a custom `worker.js` file.

Active events are defined as follows:

NETWORK: Network status changes. Requires stream_interval_seconds configuration.
HEARTBEAT: Allows clients to easily determine whether channels are functioning. Requires stream_interval_seconds configuration.
COIN_BALANCE: Balance changes. Does not require stream_interval_seconds configuration, as the event is triggered by the balance change.

The `COIN_BALANCE` event may not be available for all coins or tokens.

An example of the event stream output can then be viewed in https://github.com/KomodoPlatform/komodo-defi-framework/blob/main/examples/sse/index.html

```json "event_stream_configuration": { "access_control_allow_origin": "*", "active_events": { "NETWORK": { "stream_interval_seconds": 1.5, }, "COIN_BALANCE": {}, "HEATBEAT": { "stream_interval_seconds": 2.4, } }, "worker_path": "index.js" } ```

NumericFormatsValue

The NumericFormatsValue returns a price or amount in three different formats: fraction, rational, and decimal.

Parameter	Type	Description
decimal	numeric string	A decimal number as a string.
rational	object	A standard RationalValue object.
fraction	object	A standard FractionalValue object.

```json { "decimal": "0.0001", "rational": [ [1, [1]], [1, [10000]] ], "fraction": { "numer": "1", "denom": "10000" } } ```

FeeInfo

The FeeInfo response object includes the following items for withdraw (v2) requests:

Parameter	Type	Description
type	string	Type of transaction fee. Possible values: `UtxoFixed`, `UtxoPerKbyte`, `UtxoPriority`, `EthGas`, `Qrc20Gas`, `CosmosGas`
amount	string (numeric)	Fee amount in coin units, used only when type is `UtxoFixed` (fixed amount not depending on tx size) or `UtxoPerKbyte` (amount per Kbyte)
priority	string	Used only when type is `UtxoPriority`. Possible values: 'Low', 'Normal', 'High'.
gas_price	string (numeric)	Used only when fee type is `Qrc20Gas` or `EthGas`; sets the gas price in `gwei` units.
gas_price	number (double)	Used only when fee type is `CosmosGas`; sets the gas price.
gas	number (integer)	Used only when fee type is `EthGas`; sets the gas limit for transaction
gas_limit	number (integer)	Used only when fee type is `Qrc20Gas` or `CosmosGas`; sets the gas limit for transaction

#### Examples

{
  "type": "UtxoFixed",
  "amount": "0.0001"
}

{
  "type": "UtxoPerKbyte",
  "amount": "0.0001"
}

{
  "type": "UtxoPriority",
  "priority": "Low"
}

{
  "type": "EthGas",
  "gas_price": "10",
  "gas": 21000
}

{
  "type": "Qrc20Gas",
  "gas_price": "10",
  "gas_limit": 21000
}

{
  "type": "CosmosGas",
  "gas_price": 0.05,
  "gas_limit": 21000
}

ExtendedFeeInfo

Structure	Type	Description
coin	string	the fee is paid from the user's balance of this coin. This coin name may differ from the `base` or `rel` coins. For example, ERC20 fees are paid by ETH (gas)
amount	string (numeric)	fee amount (in decimal representation)
amount_rat	rational	fee amount (in rational representation)
amount_fraction	fraction	fee amount (in fraction representation)
amount_fraction	fraction	fee amount (in fraction representation)
paid_from_trading_vol	bool	whether the fee is paid from trading volume and not use actual `coin` balance

TotalFeeInfo

Structure	Type	Description
coin	string	the fee is paid from the user's balance of this coin. This coin name may differ from the `base` or `rel` coins. For example, ERC20 fees are paid by ETH (gas)
amount	string (numeric)	fee amount (in decimal representation)
amount_rat	rational	fee amount (in rational representation)
amount_fraction	fraction	fee amount (in fraction representation)
required_balance	string (numeric)	the required `coin` balance to pay the fee
required_balance_rat	rational	`required_balance` in rational representation
required_balance_fraction	fraction	`required_balance` in fraction representation

FractionalValue

The FractionalValue object includes a numerator and denominator values for a given price or amount:

Parameter	Type	Description
numer	string (numeric)	The numerator of the fractional value.
denom	string (numeric)	The denominator of the fractional value.

```json { "numer": "4561782244811", "denom": "4000000" } ```

Pagination

For requests which return many results, pagination offsets may be applied. ** Use either value, not both. **

Parameter	Type	Description
PageNumber	integer	Optional, defaults to `1`. Offset for paginated results
FromId	integer	Optional. Ignores any results prior to this UUID

#### Example

{
    "PageNumber": 1
}

{
    "FromId": 4
}

RationalValue

The Komodo DeFi SDK now offers the num-rational crate feature which allows for higher precision numeric values to represent order volumes and prices in a unique format as explained below:

[
  [1, [0, 1]],
  [1, [1]]
]

In the above unique format, the first item [1,[0,1]] is the numerator and the second item [1,[1]] is the denominator.

The numerator and denominator are BigInteger numbers represented as a sign and a uint32 array (where numbers are 32-bit parts of big integer in little-endian order).

[1,[0,1]] represents +0000000000000000000000000000000010000000000000000000000000000000 = 4294967296

[-1,[1,1]] represents -1000000000000000000000000000000010000000000000000000000000000000 = -4294967297

SyncStatus

Parameter	Type	Description
state	string	current state of sync; possible values: `NotEnabled`, `NotStarted`, `InProgress`, `Error`, `Finished`
additional_info	object	A standard SyncStatusExtended object. Additional info that helps to track the progress; present for `InProgress` and `Error` states only.

SyncStatusExtended

Parameter	Type	Description
blocks_left	number	present for ETH/ERC20 coins only; displays the number of blocks left to be processed for `InProgress` state
transactions_left	number	present for UTXO coins only; displays the number of transactions left to be processed for `InProgress` state
code	number	displays the error code for `Error` state
message	number	displays the error message for `Error` state

#### Example

{
    "sync_status": {
      "state": "NotStarted"
    }
}

{
    "sync_status": {
      "additional_info": {
        "transactions_left": 126
      },
      "state": "InProgress"
    }
}

{
    "sync_status": {
      "state": "Finished"
    }
}

WithdrawFee

The WithdrawFee object varies depending on the coin or token type. Refer to the examples to view the object structure for each type.

Parameter	Type	Description
type	string	The fee type. Either `Utxo`, `Tendermint`, `Qrc20` or `Eth`.
amount	numeric string	`Utxo` or `Tendermint` type only. The fee amount.
coin	string	The coin which will be used to pay the transaction fee.
gas	integer	`Eth` type only. The amount of gas to be used for the transaction.
gas_price	numeric string	`Eth` or `Qrc20` type only. Price per unit of gas to be used for the transaction.
gas_limit	numeric string	`Tendermint` or `Qrc20` type only. Maximum gas to be used for the transaction.
miner_fee	numeric string	`Tendermint` type only. Fee to mine the transaction.
total_fee	numeric string	`Eth` type only. Gas price multiplied by gas amount.
total_gas_fee	numeric string	`Qrc20` type only. Gas price multiplied by gas amount.

#### Example of Eth type

{
  "type": "Eth",
  "coin": "BNB",
  "gas": 109739,
  "gas_price": "0.000000003",
  "total_fee": "0.000329217"
}

Example of Qrc20 type

{
  "type": "Qrc20",
  "coin": "tQTUM",
  "miner_fee": "0.00000447",
  "gas_limit": 100000,
  "gas_price": 40,
  "total_gas_fee": "0.04"
}

Example of Tendermint type

{
  "type": "Tendermint",
  "coin": "IRIS",
  "amount": "0.038553",
  "gas_limit": 100000
}

Example of Utxo type

{
  "type": "Utxo",
  "amount": "0.00001"
}

FilterCriteria

The 'FilterCriteria' object allows you to filter the results based on specific parameters.

Parameter	Type	Description
status	string	Status of the transactions (e.g., "completed")
date_from	string	`Start date in ISO 8601 format
date_to	string	End date in ISO 8601 format
my_coin	string	Coin being used by you for the swap/trade.
other_coin	string	Coin you are trading against
from_timestamp	number	Start timestamp in UNIX format
to_timestamp	number	End timestamp in UNIX format

#### Example

{
  "filter": {
    "status": "completed",
    "date_from": "2024-01-01T00:00:00Z",
    "date_to": "2024-07-01T00:00:00Z",
    "my_coin": "BTC",
    "other_coin": "ETH",
    "from_timestamp": 1672531200,
    "to_timestamp": 1704067200
  }
}

PagingOptions

The PagingOptions object includes options of page selection to consult when looking for recent swaps:

Parameter	Type	Description
from_uuid	string (or null)	Skips records until this UUID, excluding the record with this UUID. Convenient for infinite scrolling implementations.
limit	number	Limits the number of returned swaps.
page_number	number	Returns limit swaps from the selected page. This parameter is ignored if from_uuid is set.

#### Example

{
  "paging_options": {
    "from_uuid": null,
    "limit": 10,
    "page_number": 1
  }
}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

index.mdx

index.mdx

Komodo DeFi SDK Common Structures

AddressFormat

AddressInfo

Example without balances

BalanceInfos

DerivationMethod

EventStreamConfig

NumericFormatsValue

FeeInfo

ExtendedFeeInfo

TotalFeeInfo

FractionalValue

Pagination

RationalValue

SyncStatus

SyncStatusExtended

WithdrawFee

Example of Qrc20 type

Example of Tendermint type

Example of Utxo type

FilterCriteria

PagingOptions

Files

index.mdx

Latest commit

History

index.mdx

File metadata and controls

Komodo DeFi SDK Common Structures

AddressFormat

AddressInfo

Example without balances

BalanceInfos

DerivationMethod

EventStreamConfig

NumericFormatsValue

FeeInfo

ExtendedFeeInfo

TotalFeeInfo

FractionalValue

Pagination

RationalValue

SyncStatus

SyncStatusExtended

WithdrawFee

Example of Qrc20 type

Example of Tendermint type

Example of Utxo type

FilterCriteria

PagingOptions