diff --git a/.gitignore b/.gitignore index dac4b2ae..a467e373 100644 --- a/.gitignore +++ b/.gitignore @@ -34,5 +34,6 @@ Thumbs.db *.pid *.sublime-* -#custom +# custom +filepathSlugs.json links-to-manually-check diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index cd08f5bf..4d4e4fca 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -71,7 +71,7 @@ For example: | Parameter | Type | Description | | --------- | ------- | --------------------------------------------------------------------------------------- | | coin | string | The name of the coin the user desires to activate. | -| fee | object | Optional. A standard [FeeInfo](/atomicdex/api/v20/#FeeInfo) object. | +| fee | object | Optional. A standard [FeeInfo](/atomicdex/api/common_structures/#FeeInfo) object. | | amount | float | Required, unless `max` is `true`. The amount of balance to send. | | max | boolean | Optional, defaults to `false`. Send whole balance. | | memo | string | Optional, used for ZHTLC and Tendermint coins only. Attaches a memo to the transaction. | @@ -142,6 +142,22 @@ For example, when method and title are the same: We've got a few **MDX** components we use across the Docs. Below is a walkthrough of how to start writing and using the components that make up the Docs. +IMPORTANT: Alwats use double quotes inside mdx tags. + +Example: + +Correct: + +``` + +``` + +Wrong: + +``` + +``` + MDX supports standard markdown by default [CommonMark](https://commonmark.org/). However, this project also has [GFM](https://github.github.com/gfm/) installed. > Many of the components mentioned here are simplified and possibly do more than **explicitly pointed out**. diff --git a/data-for-gpts/all-content.txt b/data-for-gpts/all-content.txt index b6bc7096..89aaadfb 100644 --- a/data-for-gpts/all-content.txt +++ b/data-for-gpts/all-content.txt @@ -27388,7 +27388,7 @@ export const description = "Starting with version beta-2.1.3434, the Komodo DeFi ### TokensRequest -The `TokensRequest` object includes the following items for a given coin or token: +The `TokensRequest` object includes the following items for a given token: | Parameter | Type | Description | | ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ | @@ -27403,6 +27403,74 @@ The `TokensRequest` object includes the following items for a given coin or toke } ``` + +### NftInfo + +The `NftInfo` object includes the following items for a given token: + +| Parameter | Type | Description | +| ---------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| amount | string | The amount of this NFT the user owns (used by `ERC1155`). | +| block\_number\_minted | integer | The block height when the NFT was minted. May be `null`. | +| block\_number | integer | The block height when the amount or owner changed. | +| chain | string | Chain name. One of `AVALANCHE`, `BSC`, `ETH`, `FANTOM`, or `POLYGON`. | +| name | string | May be `null`. An NFT collection name. | +| contract\_type | string | The type of NFT contract standard. One of `ERC721` or `ERC1155`. | +| last\_token\_uri\_sync | string | When the token\_uri was last updated. | +| last\_metadata\_sync | string | When the metadata was last updated. | +| metadata | string | The metadata of the token. May be `null`. | +| minter\_address | string | Minter address. May be `null`. | +| owner\_of | string | The wallet address of the owner of the NFT. | +| possible\_spam | boolean | If `true`, the contract address has [been identified](https://docs.moralis.io/web3-data-api/evm/nft-spam-detection) as associated with spam or suspicious activities. | +| possible\_phishing | boolean | If `true`, the token has been identified as associated with phishing, as at least one of domain fields is found in database with phishing domains. | +| symbol | string | May be `null`. The symbol of the NFT contract. | +| token\_address | string | The address of the NFT contract. | +| token\_id | string | The token ID of the NFT. | +| token\_hash | string | The token hash. May be `null`. | +| token\_uri | string | The URI to the metadata of the token. May be `null`. | +| token\_domain | string | Token domain. May be `null`. | +| uri\_meta | object | A standard [NftMetadata](/atomicdex/api/v20/#token-metadata) object. | + +### NftTransfer + +The `NftTransfer` object includes the following items for each token transaction: + +| Parameter | Type | Description | +| ------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| amount | string | Amount of tokens transferred. | +| block\_hash | string | May be `null`. Hash of block in which transfer occurred. | +| block\_number | integer | Height of block in which transfer occurred. | +| block\_timestamp | integer | Block time in [unix epoch format](https://www.epochconverter.com/). | +| chain | string | Chain name. One of `AVALANCHE`, `BSC`, `ETH`, `FANTOM`, or `POLYGON`. | +| token\_uri | string | May be `null`. The URI to the metadata of the token. | +| token\_domain | string | May be `null`. Extracted domain from the `token_uri`, if valid. | +| collection\_name | string | May be `null`. Name of collection which token belongs to. | +| image\_url | string | May be `null`. The URI to the token image. | +| image\_domain | string | May be `null`. Extracted domain from the `image_url`, if valid. | +| token\_name | string | May be `null`. Name of the token. | +| contract\_type | string | Contract type. `ERC721` or `ERC1155`. | +| token\_address | string | Address of token transferred. | +| token\_id | string | Token ID. | +| possible\_spam | boolean | If `true`, the contract address has [been identified](https://docs.moralis.io/web3-data-api/evm/nft-spam-detection) as associated with spam or suspicious activities. | +| possible\_phishing | boolean | If `true`, the token has been identified as associated with phishing, as at least one of domain fields is found in database with phishing domains. | +| transaction\_hash | string | Transaction ID of the transfer. | +| transaction\_index | string | May be `null`. Transaction index of the transfer. | +| log\_index | string | Log index of the transfer. | +| value | string | May be `null`. Tranfer value. | +| transaction\_type | string | May be `null`. Transaction type. Possible values are `Single`. | +| from\_address | string | Address of previous owner which sent the token(s). | +| to\_address | string | Address of new owner which received the token(s). | +| status | string | Transfer status. Will be either `Send` or `Receive`. When the `from_address` and `to_address` are the same (i.e. sending to yourself), this value will be `Receive`. | +| verified | integer | May be `null`. A deprecated field which will be removed in future. | +| operator | string | May be `null`. | +| fee\_details | object | Optional. A standard [WithdrawFee](/atomicdex/api/v20/#withdraw-fee) object. | + + + `verified` has no description. Related to [https://cointelegraph.com/news/nft-whale-pranksy-pranked-by-fake-banksy-for-97-7-eth](https://cointelegraph.com/news/nft-whale-pranksy-pranked-by-fake-banksy-for-97-7-eth)? Who verifies it? I can see there are ways to verify on opensea etc, I assume Moralis incormoprates this. + What are the other possible values for `transaction_type`? + What is `operator`? + What does `verified` mean? + export const title = "Komodo DeFi SDK Common Structures: Orders"; export const description = "Each order on the Komodo Defi oderbook can be queried to view full details of each order for a pair, or the best orders for a ticker."; @@ -28902,6 +28970,9 @@ Below is a table of the currently available legacy, v2.0 and v2.0 (Dev) methods: | | | [get\_locked\_amount](/atomicdex/api/v20-dev/get_locked_amount/#get-locked-amount) | | [get\_my\_peer\_id](/atomicdex/api/legacy/get_my_peer_id/#get-my-peer-id) | | | | | | [get\_new\_address](/atomicdex/api/v20-dev/hd_address_management/#get-new-address) | +| | | [get\_nft\_list](/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_list/#get-a-list-of-nfts) | +| | | [get\_nft\_metadata](/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_metadata/#get-nft-metadata) | +| | | [get\_nft\_transfers](/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_transfers/#get-a-list-of-nft-transfers) | | [get\_peers\_info](/atomicdex/api/legacy/get_peers_info/#get-peers-info) | | | | | [get\_public\_key](/atomicdex/api/v20/get_public_key/#get-public-key) | | | | [get\_public\_key\_hash](/atomicdex/api/v20/get_public_key_hash/#get-public-key-hash) | | @@ -28938,6 +29009,7 @@ Below is a table of the currently available legacy, v2.0 and v2.0 (Dev) methods: | [orders\_history\_by\_filter](/atomicdex/api/legacy/orders_history_by_filter/#orders-history-by-filter) | | | | [recover\_funds\_of\_swap](/atomicdex/api/legacy/recover_funds_of_swap/#recover-funds-of-swap) | | | | | [recreate\_swap\_data](/atomicdex/api/v20/recreate_swap_data/#recreate-swap-data) | | +| | | [refresh\_nft\_metadata](/atomicdex/api/v20-dev/non_fungible_tokens/refresh_nft_metadata/#refresh-nft-metadata) | | | [remove\_delegation](/atomicdex/api/v20/remove_delegation/#remove-delegation) | | | | [remove\_node\_from\_version\_stat](/atomicdex/api/v20/remove_node_from_version_stat/#remove-node-from-version-stat) | | | [sell](/atomicdex/api/legacy/sell/#sell) | | | @@ -28977,11 +29049,13 @@ Below is a table of the currently available legacy, v2.0 and v2.0 (Dev) methods: | [unban\_pubkeys](/atomicdex/api/legacy/unban_pubkeys/#unban-pubkeys) | | | | | | [update\_channel](/atomicdex/api/v20-dev/lightning/channels/#update-channel) | | [update\_maker\_order](/atomicdex/api/legacy/update_maker_order/#update-maker-order) | | | +| | | [update\_nft](/atomicdex/api/v20-dev/non_fungible_tokens/update_nft/#update-nft) | | | [update\_version\_stat\_collection](/atomicdex/api/v20/update_version_stat_collection/#update-version-stat-collection) | | | [validateaddress](/atomicdex/api/legacy/validateaddress/#validateaddress) | | | | | [verify\_message](/atomicdex/api/v20/message_signing/#verify-message) | | | [version](/atomicdex/api/legacy/version/#version) | | | | [withdraw](/atomicdex/api/legacy/withdraw/#withdraw) | [withdraw](/atomicdex/api/v20/withdraw/#withdraw) | | +| | | [withdraw\_nft](/atomicdex/api/v20-dev/non_fungible_tokens/withdraw_nft/#withdraw-nfts) | | | | [z\_coin\_tx\_history](/atomicdex/api/v20-dev/task_enable_z_coin/#z-coin-transaction-history) | export const title = "AtomicDEX Method: Active Swaps"; export const description = @@ -40511,603 +40585,1247 @@ It includes a uniform request, successful and error response formats. At the mom } ``` -export const title = "AtomicDEX: Signing and Verifying Messages"; -export const description = "The methods in this document allow you to sign and verify messages for all coins supported by AtomicDEX."; -# Signing\_and\_Verifying\_Messages +## Common Komodo DeFi SDK Request / Response Objects -Cryptographically signed messages are a useful feature which can be used to [prove ownership of an address](https://www.coindesk.com/policy/2020/05/25/craig-wright-called-fraud-in-message-signed-with-bitcoin-addresses-he-claims-to-own/). +The folowing objects are used in the request or response of multiple Komodo DeFi SDK methods. -If your [`coins`](https://github.com/KomodoPlatform/coins) file contains the correct [`sign_message_prefix`](https://bitcoin.stackexchange.com/questions/77324/how-are-bitcoin-signed-messages-generated/77325#77325) parameter value for a coin, you can sign messages with the [AtomicDEX API](https://github.com/KomodoPlatform/komodo-defi-framework). +### ActivationParams -```json -{ - "coin": "DOC", - "asset": "DOC", - "fname": "DOC (TESTCOIN)", - "sign_message_prefix": "Komodo Signed Message:\n", - "rpcport": 25435, - "txversion": 4, - "overwintered": 1, - "mm2": 1, - "protocol": { - "type": "UTXO" - } -} -``` +The `ActivationParams` object defines additional parameters used for activation. These params may vary depending on the coin type. -## Sign Message +| Parameter | Type | Description | +| ---------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| required\_confirmations | integer | Optional. Confirmations to wait for steps in swap. Defaults to value in the coins file if not set. | +| requires\_notarization | boolean | Optional, defaults to `false`. For [dPoW](https://komodoplatform.com/en/blog/dpow-demystified/) protected coins, a `true` value will wait for transactions to be notarised when doing swaps. Overrides value if set in `coins` file. | +| priv\_key\_policy | string | Defaults to `ContextPrivkey`. Set as `Trezor` to activate in Trezor mode. | +| min\_addresses\_number | integer | HD wallets only. How many additional addreesses to generate at a minimum. | +| scan\_policy | string | HD wallets only. Whether or not to scan for new addresses. Select from `do_not_scan`, `scan_if_new_wallet` or `scan`. Note that `scan` will result in multple requests to the Komodo DeFi SDK. | +| gap\_limit | integer | HD wallets only. The max number of empty addresses in a row. If transactions were sent to an address outside the `gap_limit`, they will not be identified when scanning. | +| zcash\_params\_path | string | ZHTLC coins only. Path to folder containing Zcash parameters. Optional, defaults to standard location as defined in [this guide](https://forum.komodoplatform.com/t/installing-zcash-params/603) | +| scan\_blocks\_per\_iteration | integer | ZHTLC coins only. Sets the number of scanned blocks per iteration during `BuildingWalletDb` state. Optional, default value is 1000. | +| scan\_interval\_ms | integer | ZHTLC coins only. Sets the interval in milliseconds between iterations of `BuildingWalletDb` state. Optional, default value is 0. | +| mode | object | QTUM, UTXO & ZHTLC coins only. A standard [ActivationMode](/atomicdex/api/v20/#activation-mode) object. | -### Arguments + + For ZHTLC coins, older wallets need to set the `sync_params` field to a date before its + first transaction to see all balance and history. This may take a long time on the first + activation, but subsequent activations will be much faster. + Using a smaller `scan_blocks_per_iteration` and larger `scan_interval_ms`, + will reduce the average CPU load during ZHTLC coin activation (at the cost of a + longer activation time). These optional fields are recommended when developing + for iOS, where a high CPU load may kill the activation process. Android & + desktop operating systems do not appear to have any problems with high CPU + load during ZHTLC coin activation. + -| Structure | Type | Description | -| --------- | ------ | ------------------------------- | -| coin | string | The coin to sign a message with | -| message | string | The message you want to sign | +### ActivationMode -### Response +Defines the activation mode for QTUM, BCH, UTXO & ZHTLC coins. -| Structure | Type | Description | -| --------- | ------ | --------------------------------------- | -| signature | string | The signature generated for the message | +| Parameter | Type | Description | +| --------- | ------ | ---------------------------------------------------------------------------------------------------------------- | +| rpc | string | `Native` if running a native blockchain node, `Electrum` if using electrum servers or `Light` for ZHTLC coins. | +| rpc\_data | object | `Electrum` or `Light` mode only. A standard [ActivationRpcData](/atomicdex/api/v20/#activation-rpc-data) object. | -#### Command +### ActivationRpcData + +Contains information about electrum & lightwallet\_d servers for coins being used in `Electrum` or `Light` mode. + +| Parameter | Type | Description | +| ------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| light\_wallet\_d\_servers | list | ZHTLC only. A list of urls which are hosting lightwallet\_d servers for a coin. | +| electrum\_servers | list of objects | ZHTLC only. A list of standard [ActivationServers](/atomicdex/api/v20/#activation-servers) objects. | +| electrum | list of objects | QTUM, BCH & UTXO coins only. A list of standard [ActivationServers](/atomicdex/api/v20/#activation-servers) objects. | +| sync\_params | integer or string | ZHTLC coins only. Optional, defaults to two days ago. Defines where to start scanning blockchain data upon initial activation. Options: `"earliest"` (the coin's sapling\_activation\_height), `height` (a specific block height) or `date` (a timestamp in [unix epoch format](https://www.epochconverter.com/)). | + +### ActivationServers + +Contains information electrum servers for coins being used in `Electrum` or `Light` mode. + +| Parameter | Type | Description | +| --------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| url | string | The URL and port for an electrum server. | +| ws\_url | string | Optional, for WSS only. The URL and port for an electrum server's WSS port. | +| protocol | string | Optional, defaults to `TCP`. Transport protocol used to connect to the server. Options: `TCP` or `SSL` | +| disable\_cert\_verification | boolean | Optional, defaults to `false`. If `true`, this disables server SSL/TLS certificate verification (e.g. for self-signed certificates). Use at your own risk! | + + + #### ZHTLC Example - ```json { - "userpass": "testpsw", - "method": "sign_message", - "mmrpc": "2.0", - "id": 0, - "params": { - "coin": "DOC", - "message": "Between subtle shading and the absence of light lies the nuance illusion" + "activation_params": { + "mode": { + "rpc": "Light", + "rpc_data": { + "electrum_servers": [ + { + "url":"zombie.dragonhound.info:10033" + } + ], + "light_wallet_d_servers": [ + "http://zombie.dragonhound.info:443" + ] + }, + "sync_params": { + "height": 2528700 + } + }, + "zcash_params_path": "/home/username/path_to/.zcash-params", + "scan_blocks_per_iteration": 100, + "scan_interval_ms": 200 } } ``` - -#### Response (success) + #### HD UTXO Activation (v2) -```json -{ - "mmrpc": "2.0", - "result": { - "signature": "H43eTmJxBKEPiHkrCe/8NsRidkKCIkXDxLyp30Ez/RwoApGdg89Hlvj9mTMSPGp8om5297zvdL8EVx3IdIe2swY=" - }, - "id": 0 -} -``` + ```json + { + "activation_params": { + "mode": { + "rpc": "Electrum", + "rpc_data": { + "servers": [ + { + "url": "electrum2.cipig.net:10001" + }, + { + "url": "electrum3.cipig.net:20001", + "ws_url": "electrum3.cipig.net:30001", + "protocol": "SSL" + } + ] + } + }, + "scan_policy": "scan_if_new_wallet", + "priv_key_policy": "Trezor", + "min_addresses_number": 3, + "gap_limit": 20 + } + } + ``` + -### โš  Error types +### AddressInfos -**PrefixNotFound:** sign\_message\_prefix is not set in coin config file -**CoinIsNotFound:** Specified coin is not found -**InvalidRequest:** Message signing is not supported by the given coin type -**InternalError:** An internal error occured during the signing process +The `addressInfos` object includes the following items for a given address: -## Verify Message +| Parameter | Type | Description | +| ------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------ | +| balances | object | A standard [balanceInfos](/atomicdex/api/v20/#balance-infos) object. Not included in responses where `get_balances` is `false` | +| derivation\_method | object | A standard [DerivationMethod](/atomicdex/api/v20/#derivation-method) object | +| pubkey | string | The public key associated with the seed used to launch AtomicDEX | +| tickers | array | A list of tokens which were successfully activated. Only included in responses where `get_balances` is `false` | -### Arguments + + #### Example with balances -| Structure | Type | Description | -| --------- | ------ | ---------------------------------------------------- | -| coin | string | The coin to sign a message with | -| message | string | The message input via the `sign_message` method sign | -| signature | string | The signature generated for the message | -| address | string | The address used to sign the message | + ```json + "bitcoincash:qrf5vpn78s7rjexrjhlwyzzeg7gw98k7t5qx64fztj": { + "derivation_method": { + "type": "Iguana" + }, + "pubkey": "036879df230663db4cd083c8eeb0f293f46abc460ad3c299b0089b72e6d472202c", + "balances": { + "spendable": "0.11398301", + "unspendable": "0.00001" + } + } + ``` -### Response + #### Example without balances -| Structure | Type | Description | -| --------- | ------- | ----------------------------------------------------------- | -| is\_valid | boolean | `true` is message signature is valid; `false` if it is not. | + ```json + "bitcoincash:qrf5vpn78s7rjexrjhlwyzzeg7gw98k7t5qx64fztj": { + "derivation_method": { + "type": "Iguana" + }, + "pubkey": "036879df230663db4cd083c8eeb0f293f46abc460ad3c299b0089b72e6d472202c", + "tickers": ["ASLP-SLP"] + } + ``` + -#### Command +### 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 { - "userpass": "testpsw", - "method": "verify_message", - "mmrpc": "2.0", - "id": 0, - "params": { - "coin": "DOC", - "message": "Between subtle shading and the absence of light lies the nuance illusion", - "signature": "H43eTmJxBKEPiHkrCe/8NsRidkKCIkXDxLyp30Ez/RwoApGdg89Hlvj9mTMSPGp8om5297zvdL8EVx3IdIe2swY=", - "address": "RUYJYSTuCKm9gouWzQN1LirHFEYThwzA2d" - } + "spendable": "12.11398301", + "unspendable": "0.53" } ``` - - -#### Response (valid) + -```json -{ - "mmrpc": "2.0", - "result": { - "is_valid": true - }, - "id": 0 -} -``` +### DerivationMethod -#### Response (not valid) +The `DerivationMethod` object includes the following items for a given coin or token: -```json -{ - "mmrpc": "2.0", - "result": { - "is_valid": false - }, - "id": 0 -} -``` +| Parameter | Type | Description | +| --------- | ------ | ------------------------------------------------------------------------------- | +| type | string | Defines how keypairs will be generated. Possible values: `Iguana` or `HDWallet` | -### โš  Error types + + 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. + -**PrefixNotFound:** sign\_message\_prefix is not set in coin config -**CoinIsNotFound:** Specified coin is not found -**InvalidRequest:** Message verification is not supported by the given coin type -**InternalError:** An internal error occured during the verification process -**SignatureDecodingError:** Given signature could not be decoded -**AddressDecodingError:** Given address could not be decoded -export const title = "AtomicDEX Method: My TX History"; -export const description = "The my_tx_history method allows you to view the transaction history of coins."; +Where the value indicates: -# my\_tx\_history +* `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. -To use this method, you must activate your coin with `"tx_history": true`. The response will vary depending on the coin. -Currently only BCH & SLP tokens are supported in the master/release API. In the latest dev API, UTXO coins, QTUM, and Tendermint/Tendermint tokens are also supported. -For ZHTLC coins, you must use the [z\_coin\_tx\_history](/atomicdex/api/v20-dev/task_enable_z_coin/#z-coin-transaction-history) method. -For all other coins, use the legacy [my\_tx\_history](/atomicdex/api/legacy/my_tx_history/#my-tx-history) method. - -## Arguments - -| parameter | Type | Description | -| --------------- | ------- | ------------------------------------------------------------------------------------------------ | -| coin | string | Ticker of the coin to get history for. | -| limit | integer | Optional. Limits the number of returned transactions. Defaults to `10`. Ignored if `max = true`. | -| paging\_options | object | Optional. A standard [Pagination](/atomicdex/api/common_structures/#pagination) object. | - -#### Response - -| Structure | Type | Description | -| -------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| transactions | array of objects | transactions data | -| from\_id | string | the from\_id specified in the request; this value is null if from\_id was not set | -| skipped | number | the number of skipped records (i.e. the position of `from_id` in the list + 1); this value is 0 if `from_id` was not set | -| limit | number | the limit that was set in the request; note that the actual number of transactions can differ from the specified limit (e.g. on the last page) | -| total | number | the total number of transactions available | -| page\_number | number | the page\_number that was set in the request | -| total\_pages | number | total pages available with the selected limit | -| current\_block | number | the number of the latest block of coin blockchain | -| sync\_status | object | A standard [SyncStatus](/atomicdex/api/common_structures/#sync-status/) object. Provides the information that helps to track the progress of transaction history preloading at background | - -## Request (BCH from page 2) - - + ```json { - "userpass": "testpsw", - "method": "my_tx_history", - "mmrpc": "2.0", - "params": { - "coin": "BCH", - "limit": 2, - "paging_options": { - "PageNumber": 2 - } - } + "type": "Iguana" } ``` - + - - ### Response +### EvmNode + +The `EvmNode` object includes the following items for a given coin or token: + +| Parameter | Type | Description | +| --------- | ------- | ------------------------------------------------------------------------------------------------------------------- | +| url | string | URL of an RPC node | +| gui\_auth | boolean | Optional, defaults to `false`. Must be set to `true` to access RPC nodes run officially by the Komodo Platform team | + ```json { - "mmrpc": "2.0", - "result": { - "coin": "BCH", - "target": { - "type": "iguana" - }, - "current_block": 772607, - "transactions": [ - { - "tx_hex": "0100000001b7b45d92f8f3413a0e5656258e0a51f5c7e8230c0a08cef2ebec1ddbb8f7c28200000000d747304402203ca957fdfcfbba6123d78afe28b17fd4103cc04f6ada4110eb61c2a0350c29b802204215f203d583e8bcc79bd70f33af4f4e27500b5a5375efe75a1c31ec112f3c344120b3f71dbea00eeace7f09b0911de31e46f76a48036b86ccc207dac55540912e01004c6b6304dbf67563b175210315d9c51c657ab1be4ae9d3ab6e76a619d3bccfe830d5363fa168424c0d044732ac6782012088a914dde61fe24ea3cfa39379c475702692fa2f080900882103ed00156316c46094c0cbcf21a5ee549a1b3a50938c43096ef499ca28059edca6ac68ffffffff0133980200000000001976a91411a1563bfa55ae05fa621b2e245abe5a358c852e88acdbf67563", - "tx_hash": "e2167df56142bccdb8c620297f1b6ca3f7c8a955332838430d4d0f62530870f9", - "from": [ - "bitcoincash:ppaa62685yaucdf2a54g3rgtyc9g7yawrvvmqsfumc" - ], - "to": [ - "bitcoincash:qqg6z43mlf26up06vgdjufz6hedrtry99cvk5dgcnt" - ], - "total_amount": "0.00171035", - "spent_by_me": "0", - "received_by_me": "0.00170035", - "my_balance_change": "0.00170035", - "block_height": 766923, - "timestamp": 1668615553, - "fee_details": { - "type": "Utxo", - "coin": "BCH", - "amount": "0.00001" - }, - "coin": "BCH", - "internal_id": "e2167df56142bccdb8c620297f1b6ca3f7c8a955332838430d4d0f62530870f9", - "transaction_type": "StandardTransfer", - "confirmations": 5685 - }, - { - "tx_hex": "0100000001eccfa8c296e7b3e229be28a8ca6a5e5a7e89ee07a2d9441faaf5905679286a3c00000000d7473044022077d38ae45bb7257b152d4cb803aab62ca879cab60e9b3a7ca05ef099078e000402203106be31513c6526c14bdf40b28b4d38f78bb1958fc995e040ac4b2165d9d79141203bffadbc5bf035674f0d0f6e1d1a121fc6d404720679ff9b6610b298b41375a3004c6b6304bc847463b175210315d9c51c657ab1be4ae9d3ab6e76a619d3bccfe830d5363fa168424c0d044732ac6782012088a91457c7ce14c0444edc37ee52ed32b68890b0647cd3882103ed00156316c46094c0cbcf21a5ee549a1b3a50938c43096ef499ca28059edca6ac68ffffffff0163b10200000000001976a91411a1563bfa55ae05fa621b2e245abe5a358c852e88acbc847463", - "tx_hash": "98ddc27aa161967519f53cb3e91146a23b76ac4e33605f8e827c69f4d9b6de37", - "from": [ - "bitcoincash:ppnzkha52y53d7r7qn6mq4mcmaadmxzj4clfgneaxv" - ], - "to": [ - "bitcoincash:qqg6z43mlf26up06vgdjufz6hedrtry99cvk5dgcnt" - ], - "total_amount": "0.00177483", - "spent_by_me": "0", - "received_by_me": "0.00176483", - "my_balance_change": "0.00176483", - "block_height": 766752, - "timestamp": 1668519015, - "fee_details": { - "type": "Utxo", - "coin": "BCH", - "amount": "0.00001" - }, - "coin": "BCH", - "internal_id": "98ddc27aa161967519f53cb3e91146a23b76ac4e33605f8e827c69f4d9b6de37", - "transaction_type": "StandardTransfer", - "confirmations": 5856 - } - ], - "sync_status": { - "state": "Finished" - }, - "limit": 2, - "skipped": 2, - "total": 16, - "total_pages": 8, - "paging_options": { - "PageNumber": 2 - } - }, - "id": null + "url": "http://eth1.cipig.net:8555", + "gui_auth": false } ``` -## Request (TTT-SLP with FromId) +### CoinProtocol - - ```json - { - "userpass": "testpsw", - "method": "my_tx_history", - "mmrpc": "2.0", - "params": { - "coin": "TTT-SLP", - "limit": 2, - "paging_options": { - "FromId": "433b641bc89e1b59c22717918583c60ec98421805c8e85b064691705d9aeb970" - } - } - } - ``` - +| Parameter | Type | Description | +| -------------- | ------- | ----------------------------------------------------------------------------- | +| type | integer | One of the supported \[coin types]\(link TBA) | +| protocol\_data | object | A standard [CoinProtocolData](/atomicdex/api/v20/#coin-protocol-data) object. | - - ### Response +### CoinProtocolData - ```json - { - "mmrpc": "2.0", - "result": { - "coin": "TTT-SLP", - "target": { - "type": "iguana" - }, - "current_block": 772612, - "transactions": [ - { - "tx_hex": "0200000002365a29eb638da7fc57720ad6c99fdbc6cfb9c957920cfb62fd69e494b412c1c1020000006b483045022100de81bca8cfef2f95b3da8aa89edf4f5cc6cf489c565d0965b8142380ef3986f1022062d6ed47f2cd281f4860a27e835949aafbab89eeb0865fbf2280a283dfb7c417412102b9fdfedefde71b21523974b9f24a4b6a1b83c5640b839baa6eb14418cae08191ffffffffc1f73b403f893f93d95b8c7dfa1b59bb5445109d4c51107da1e08fb770e54136010000006a47304402203658375dac3b84ae17e72cf3f5157b8ad25e7caee0629fa8708868974f8d58b402206f38d016ed4e390d783627441685692d21b889d83919abd39368cba28f43f544412102b9fdfedefde71b21523974b9f24a4b6a1b83c5640b839baa6eb14418cae08191ffffffff040000000000000000406a04534c500001010453454e44205321508197ffed321c5fc9a1427e5c68b31d2c1ec92ae1c495f8acb08d8d66cd080000000000002710080000002278c569d322020000000000001976a914d346067e3c3c3964c395fee208594790e29ede5d88ac22020000000000001976a914580af35e3553d57b4b3a2036f4959f10246e98c788ac68955e03000000001976a914580af35e3553d57b4b3a2036f4959f10246e98c788ac00000000", - "tx_hash": "7b58248f3486079951a57d6dbd41c019a83f2b876c9fa3afa6fcc5a7c595b837", - "from": ["simpleledger:qpvq4u67x4fa276t8gsrday4nugzgm5ccu4usawss8"], - "to": [ - "simpleledger:qpvq4u67x4fa276t8gsrday4nugzgm5ccu4usawss8", - "simpleledger:qrf5vpn78s7rjexrjhlwyzzeg7gw98k7t5va3wuz4v" - ], - "total_amount": "1480551016.67", - "spent_by_me": "0", - "received_by_me": "100", - "my_balance_change": "100", - "block_height": 772211, - "timestamp": 1671817336, - "fee_details": { - "type": "Utxo", - "coin": "BCH", - "amount": "0.00000482" - }, - "coin": "TTT-SLP", - "internal_id": "57b78eb912a704921640a589d8bb42bb147dfb88c3d1b4b2e3df910be6b9ab31", - "transaction_type": { - "TokenTransfer": "5321508197ffed321c5fc9a1427e5c68b31d2c1ec92ae1c495f8acb08d8d66cd" - }, - "confirmations": 402 - } - ], - "sync_status": { - "state": "Finished" - }, - "limit": 10, - "skipped": 0, - "total": 1, - "total_pages": 1, - "paging_options": { - "FromId": "433b641bc89e1b59c22717918583c60ec98421805c8e85b064691705d9aeb970" - } - }, - "id": null - } - ``` - +| Parameter | Type | Description | +| --------------------- | ------ | ------------------------------------------------------------------------------------------------ | +| platform | string | Indicates the platform parent coin for EMV-like protocols, or the coin used for lightning nodes. | +| network | string | Either `mainnet` or \`testnet | +| confirmation\_targets | object | A standard [ConfirmationTargets](/atomicdex/api/v20/#confirmation-targets) object. | -## Request (IRIS with limit = 50) +### ConfirmationTargets - - ```json - { - "userpass": "testpsw", - "method": "my_tx_history", - "mmrpc": "2.0", - "params": { - "coin": "IRIS", - "limit": 50 - } - } - ``` - +This object represents the number of blocks required for an on-chain lightning-related transaction to be confirmed. +It is used for estimating the transaction fee rate (`feerate`) for different transaction types in the context of permissionless transactions performed by the node. Different target types are `background`, `normal`, and `high_priority`. - - ### Response +| Parameter | Type | Description | +| -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| background | integer | Used for transactions that can tolerate slower confirmation times when the transaction fee rate decreases. These transactions are not time-sensitive and can afford to wait longer for confirmation. The recommended range is `12` to `144` blocks to ensure a low `feerate`. | +| normal | integer | Used for transactions that we want to confirm promptly, without significant delay (e.g, transactions for opening payment channels). These transactions are important but not critical. Suggested value is `6` blocks to ensure a moderate `feerate`. | +| high\_priority | integer | Used for transactions that require quick confirmation to prevent potential loss of funds (e.g. redeeming a Hashed Time Lock Contract (HTLC) on the blockchain before it times out). These transactions are time-critical and must be confirmed promptly to ensure the security of funds. Recommended value for `high_priority` is 1-2 blocks to ensure a high `feerate`. | - ```json - { - "mmrpc": "2.0", - "result": { - "coin": "IRIS", - "target": { - "type": "iguana" - }, - "current_block": 18120346, - "transactions": [ - { - "tx_hex": "0a2a6961613136647271766c33753873756b667375346c6d3371736b32386a72336661686a6139767376366b122a6961613136647271766c33753873756b667375346c6d3371736b32386a72336661686a6139767376366b1a110a05756972697312083130303030303030", - "tx_hash": "B34A8D5AD74067F01A0207DF1851A14673C859D8A6F4FB0CBE292D2104C143CA", - "from": ["iaa16drqvl3u8sukfsu4lm3qsk28jr3fahja9vsv6k"], - "to": ["iaa16drqvl3u8sukfsu4lm3qsk28jr3fahja9vsv6k"], - "total_amount": "10.044559", - "spent_by_me": "10.044559", - "received_by_me": "10", - "my_balance_change": "-0.044559", - "block_height": 18120218, - "timestamp": 1673016440, - "fee_details": { - "type": "Tendermint", - "coin": "IRIS", - "amount": "0.044559", - "gas_limit": 100000 - }, - "coin": "IRIS", - "internal_id": "4644373032304131304637363034374441354438413433420000000000000000", - "transaction_type": "StandardTransfer", - "memo": "while you are out, buy milk", - "confirmations": 129 - }, - { - "tx_hex": "0a2a6961613136647271766c33753873756b667375346c6d3371736b32386a72336661686a6139767376366b122a696161317a78733476776c36326b687174376e7a7276687a676b34377467366365706677707a673537711a4d0a446962632f3237333934464230393244324543434435363132334337344633364534433146393236303031434541444139434139374541363232423235463431453545423212053130303030", - "tx_hash": "09ADDD3427A3BA4B0A94023456DF534DB5B9B6821EC17C7C1B2C168EFCF49F26", - "from": ["iaa16drqvl3u8sukfsu4lm3qsk28jr3fahja9vsv6k"], - "to": [], - "total_amount": "0.051788", - "spent_by_me": "0.051788", - "received_by_me": "0", - "my_balance_change": "-0.051788", - "block_height": 17996530, - "timestamp": 1672232661, - "fee_details": { - "type": "Tendermint", - "coin": "IRIS", - "amount": "0.051788", - "gas_limit": 100000 - }, - "coin": "IRIS", - "internal_id": "0000000000000000303941444444333432374133424134423041393430323334", - "transaction_type": "FeeForTokenTx", - "memo": null, - "confirmations": 123817 - }, - { - "tx_hex": "0a2a6961613136647271766c33753873756b667375346c6d3371736b32386a72336661686a6139767376366b1240343133433843414333434142363945454632344432423643414238314146454344383044413745323731433237343637453142324635463337314446353241441a4061353539343834666536316665383630326465383632353964643263663031613865393437306437666635346262323536336233393035646462366238366535", - "tx_hash": "4E30C074CED6825F3E1B6584C376A426C20FDEFC9A22EB17D8E7DA4139FA0AEB", - "from": ["iaa16drqvl3u8sukfsu4lm3qsk28jr3fahja9vsv6k"], - "to": [], - "total_amount": "182.742425", - "spent_by_me": "0.053103", - "received_by_me": "182.689322", - "my_balance_change": "182.636219", - "block_height": 17981793, - "timestamp": 1672138900, - "fee_details": { - "type": "Tendermint", - "coin": "IRIS", - "amount": "0.053103", - "gas_limit": 100000 - }, - "coin": "IRIS", - "internal_id": "3438353642314533463532383644454334373043303345340000000000000000", - "transaction_type": { - "CustomTendermintMsg": { - "msg_type": "SignClaimHtlc", - "token_id": null - } - }, - "memo": null, - "confirmations": 138554 - } - ], - "sync_status": { - "state": "NotStarted" - }, - "limit": 50, - "skipped": 0, - "total": 3, - "total_pages": 1, - "paging_options": { - "PageNumber": 1 - } - }, - "id": null - } - ``` - + + Using the recommended values in the above table with a coin that has a block time of 10 minutes, the equivalent time in minutes is: -## Error cases + * `background`: 120 minutes to 1440 minutes (2 hours to 1 day). + * `normal`: 60 minutes (one hour). + * `high_priority`: 10 to 20 minutes. + -### Error - Coin not active +### CounterpartyChannelConfig -```json -{ - "mmrpc": "2.0", - "error": "TTT-SLP", - "error_path": "my_tx_history_v2.lp_coins", - "error_trace": "my_tx_history_v2:389] lp_coins:2847]", - "error_type": "CoinIsNotActive", - "error_data": "TTT-SLP", - "id": null -} -``` +| Parameter | Type | Description | +| --------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| allow\_outbound\_0conf | boolean | Optional, defaults to `true`. When setting an outbound channel, it can be used straight away [without waiting](https://docs.rs/lightning/latest/lightning/util/config/struct.ChannelHandshakeLimits.html#structfield.trust_own_funding_0conf) for any on-chain confirmations. | +| force\_announced\_channel\_preference | boolean | Optional, defaults to `true`. Set to force an incoming channel to match our announced channel preference in ChannelOptions announced\_channel. | +| outbound\_channels\_confirmations | integer | Optional, defaults to `144`. Confirmations we will wait for before considering an inbound channel locked in. | +| our\_locktime\_limit | boolean | Optional, defaults to `2016`. Set to the amount of blocks we're willing to wait to claim money back to us. | +| min\_funding\_sats | boolean | Optional, defaults to `0`. Minimum allowed satoshis when an inbound channel is funded. | +| max\_funding\_sats | boolean | Optional, defaults to `16777215`. Maximum allowed satoshis when an inbound channel is funded. | +| max\_htlc\_minimum\_msat | boolean | Optional, defaults to `18446744073709551615`. The remote node sets a limit on the minimum size of HTLCs we can send to them. This allows us to limit the maximum minimum-size they can require. | +| min\_max\_htlc\_value\_in\_flight\_msat | boolean | Optional, defaults to `0`. The remote node sets a limit on the maximum value of pending HTLCs to them at any given time to limit their funds exposure to [HTLCs](https://academy.binance.com/en/glossary/hashed-timelock-contract). This allows us to set a minimum such value. | +| max\_channel\_reserve\_sats | boolean | Optional, defaults to `18446744073709551615`. The remote node will require us to keep a certain amount in direct payment to ourselves at all time, ensuring that we are able to be punished if we broadcast an old state. This allows us to limit the amount which we will have to keep to ourselves (and cannot use for [HTLCs](https://academy.binance.com/en/glossary/hashed-timelock-contract)). | +| min\_max\_accepted\_htlcs | boolean | Optional, defaults to `0`. The remote node sets a limit on the maximum number of pending HTLCs to them at any given time. This allows us to set a minimum such value. | -### Error - Coin not compatible +### FeeInfo -```json -{ - "mmrpc": "2.0", - "error": "TTT-SLP", - "error_path": "my_tx_history_v2", - "error_trace": "my_tx_history_v2:336]", - "error_type": "NotSupportedFor", - "error_data": "TTT-SLP", - "id": null -} -``` +The `FeeInfo` response object includes the following items for [withdraw (v2)](/atomicdex/api/v20/withdraw/) requests: -### Error - Coin enabled without tx\_history = true +| Parameter | Type | Description | +| ---------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| type | string | Type of transaction fee; possible values: `UtxoFixed`, `UtxoPerKbyte`, `EthGas` | +| 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) | +| gas\_price | string (numeric) | Used only when fee type is EthGas; sets the gas price in `gwei` units | +| gas | number (integer) | Used only when fee type is EthGas; sets the gas limit for transaction | -```json -{ - "mmrpc": "2.0", - "error": "Storage is not initialized for TTT-SLP", - "error_path": "my_tx_history_v2", - "error_trace": "my_tx_history_v2:343]", - "error_type": "StorageIsNotInitialized", - "error_data": "Storage is not initialized for TTT-SLP", - "id": null -} -``` +### LightningActivationParams -### Error - Local database failed +| Parameter | Type | Description | +| ---------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| name | string | The name of the node that will be used in [lightning explorers](https://mempool.space/testnet/lightning/node/024e2a940e0cbeda84a0d5e00fa8e83b3f4e7f98382eedb488d058e0f5636dd164/r/n) | +| listening port | integer | Optional, defaults to `9735`. The port that this node listens for incoming connections on. | +| color | string | Optional, defaults to `2b6680`. A hexidecimal color string which will be used in network graphs on [lightning explorers](https://mempool.space/testnet/lightning/node/024e2a940e0cbeda84a0d5e00fa8e83b3f4e7f98382eedb488d058e0f5636dd164/r/n) | +| payment\_retries | integer | Optional, defaults to `5`. Number of times a payment will be retried if it fails. | +| backup\_path | string | Optional. The backup path for channel backups, preferably on an external drive. | -```json -{ - "mmrpc": "2.0", - "error": "SqliteFailure(Error { code: Unknown, extended_code: 1 }, Some(\"no such column: block_height\"))", - "error_path": "my_tx_history_v2.sql_tx_history_storage", - "error_trace": "my_tx_history_v2:351] sql_tx_history_storage:472]", - "error_type": "StorageError", - "error_data": "SqliteFailure(Error { code: Unknown, extended_code: 1 }, Some(\"no such column: block_height\"))", - "id": null -} -``` -export const title = "AtomicDEX Method: Orderbook v2"; -export const description = "The orderbook method requests from the network the currently available orders for the specified trading pair."; +### LightningChannelAmount -# orderbook +| Parameter | Type | Description | +| --------- | ------ | -------------------------------------------------------------------------------------- | +| type | string | `Exact` for a specific amount or `Max` for whole balance. | +| value | object | Only required if type is `Exact`. The amount in BTC you want to open the channel with. | -**orderbook base rel** +### LightningChannelConfig -The v2 `orderbook` method requests from the network the currently available orders for the specified trading pair. + + The values in this object are only used if the channel is being opened by the user. If the channel is being opened by the counterparty, the values in this object are ignored. + If not specified when using the [open\_channel](/atomicdex/api/v20-dev/lightning/channels/#open-channel) or [update\_channel](/atomicdex/api/v20-dev/lightning/channels/#update-channel) methods, the values in this object will default to the values set in the `coins` configuration file. + -## Arguments +| Parameter | Type | Description | +| --------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| inbound\_channels\_confirmations | string | Optional, defaults to `6`. Should be set in coins file, and applies to all channels. Confirmations we will wait for before considering an inbound channel locked in. | +| max\_inbound\_in\_flight\_htlc\_percent | integer | Optional, defaults to `10`. Should be set in coins file, and applies to all channels. Sets the percentage of the channel value we will cap the total value of outstanding inbound HTLCs to. | +| our\_htlc\_minimum\_msat | integer | Optional, defaults to `1`. The smallest value HTLC we will accept to process. The channel gets closed any time our counterparty misbehaves by sending us an HTLC with a value smaller than this. | +| announced\_channel | boolean | Optional, defaults to `false`. Set to announce the channel publicly and notify all nodes that they can route via this channel. GUIs and wallet apps should be set to `false`. | +| commit\_upfront\_shutdown\_pubkey | boolean | Optional, defaults to `true`. When `true` (and the counterparty agrees), the user must use the same key for cooperative closing. This prevents a user from changing the destination address in a cooperative close, which slightly increases security (however, this option is not required if the counterparty does not support it and a channel can be accepted regardless). **Note that the key for forced closing is always fixed when opening a channel and is different from shutdown\_pubkey.** | +| counterparty\_locktime | integer | Optional, defaults to `144`. The number of blocks we require our counterparty to wait to claim their money on chainif they broadcast a revoked transaction. We have to be online at least once during this time to punish our counterparty for broadcasting a revoked transaction. We have to account also for the time to broadcast and confirm our transaction, possibly with time in between to [RBF (Replace-By-Fee)](https://bitcoinops.org/en/topics/replace-by-fee/) the spending transaction. | +| negotiate\_scid\_privacy | integer | Optional, defaults to `false`. If `true`, we attempt to negotiate the `scid_privacy` (referred to as `scid_alias` in the [BOLTs](https://github.com/lightning/bolts)) option for outbound private channels. This provides better privacy by not including our real on-chain channel UTXO in each invoice and requiring that our counterparty only relay HTLCs to us using the channel's SCID alias. | +| their\_channel\_reserve\_sats | boolean | Optional, defaults to `10000` or 1% of channel value. The minimum balance that the other node has to maintain on their side, at all times. This ensures that if our counterparty broadcasts a revoked state, we can punish them by claiming at least this value on chain. | -| Structure | Type | Description | -| --------- | ------ | ---------------------------------------------------- | -| base | string | Base currency of a pair | -| rel | string | Related currency, also known as the "quote currency" | + + For GUIs and wallet apps, it is recommended to set `announced_channel` to + `false` (the default value), as the node is not expected to be reliably + online. + -## Response +### LightningChannelOptions -| Structure | Type | Description | -| ---------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------ | -| base | string | The name of the coin the user desires to receive | -| rel | string | The name of the coin the user will trade | -| numasks | integer | The number of outstanding asks | -| numbids | integer | The number of outstanding bids | -| netid | integer | The id of the network on which the request is made (default is `8762`) | -| asks | array of objects | An array of standard [OrderDataV2](/atomicdex/api/common_structures/orders/#order-data-v2) objects containing outstanding asks | -| bids | array of objects | An array of standard [OrderDataV2](/atomicdex/api/common_structures/orders/#order-data-v2) objects containing outstanding bids | -| timestamp | integer | A UNIX timestamp representing when the orderbook was requested | -| total\_asks\_base\_vol | object | A standard [NumericFormatsValue](/atomicdex/api/common_structures/#numeric-formats-value) object. | -| total\_asks\_rel\_vol | object | A standard [NumericFormatsValue](/atomicdex/api/common_structures/#numeric-formats-value) object. | -| total\_bids\_base\_vol | object | A standard [NumericFormatsValue](/atomicdex/api/common_structures/#numeric-formats-value) object. | -| total\_bids\_rel\_vol | object | A standard [NumericFormatsValue](/atomicdex/api/common_structures/#numeric-formats-value) object. | +| Parameter | Type | Description | +| --------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| proportional\_fee\_in\_millionths\_sats | integer | Optional, defaults to `0`. Amount (in milli-satoshi) charged for payments forwarded outbound over the channel, in excess of proportional\_fee\_in\_millionths\_sats. | +| base\_fee\_msat | integer | Optional, defaults to `1000`. Amount (in milli-satoshi) charged for payments forwarded outbound over the channel, in excess of proportional\_fee\_in\_millionths\_sats. | +| cltv\_expiry\_delta | integer | Optional, defaults to `72`. Blocks until [CheckLockTimeVerify (CLTV)](https://academy.bit2me.com/en/que-es-cltv-bitcoin/) expiry. | +| max\_dust\_htlc\_exposure\_msat | integer | Optional, defaults to `5000000`. Limit our total exposure to in-flight [HTLCs](https://academy.binance.com/en/glossary/hashed-timelock-contract) which are burned to fees as they are too small to claim on-chain. | +| force\_close\_avoidance\_max\_fee\_sats | integer | Optional, defaults to `1000`. The additional fee we're willing to pay to avoid waiting for the counterparty's locktime to reclaim funds. | -#### ๐Ÿ“Œ Examples +### LightningClosedChannelsFilter -#### Command +| Parameter | Type | Description | +| ---------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| channel\_id | string | Optional. Unique string identifying a channel by its ID. | +| counterparty\_node\_id | string | Optional. A hexidecimal string identifying a counterparty node. | +| funding\_tx | string | Optional. A transaction ID which added funds. | +| from\_funding\_value | integer | Optional. The minimum value of channel funding in satoshis. | +| to\_funding\_value | integer | Optional. The maximum value of channel funding in satoshis. | +| channel\_type | string | Optional. `Inbound` or `Outbound`. | +| closing\_tx | integer | Optional. A transaction ID which closed the channel. | +| closure\_reason | integer | Optional. The reason a channel was closed. | +| claiming\_tx | integer | Optional. The ID of the transaction that returned the remaining outbound funds when the channel was closed to our on-chain address. | +| from\_claimed\_balance | integer | Optional. The minimum balance of channel funds claimed in satoshis. | +| to\_claimed\_balance | integer | Optional. The maximum balance of channel funds claimed in satoshis. | +| channel\_visibility | integer | Optional. `Public` or `Private`. | - - ```json - { - "mmrpc": "2.0", - "userpass": "testpsw", - "method": "orderbook", - "params": { - "base": "DGB", - "rel": "DASH" - }, - "id": 42 - } - ``` - + + Response may change to be more consistent in future. + [https://github.com/KomodoPlatform/komodo-docs-mdx/pull/31#discussion\\\_r1206446309](https://github.com/KomodoPlatform/komodo-docs-mdx/pull/31#discussion\\_r1206446309) + - - #### Response +### LightningOpenChannelsFilter - ```json - { - "mmrpc": "2.0", - "result": { - "asks": [ - { - "coin": "DGB", - "address": { - "address_type": "Transparent", - "address_data": "DEsCggcN3WNmaTkF2WpqoMQqx4JGQrLbPS" - }, - "price": { - "decimal": "0.0002658065", - "rational": [ - [1, [531613]], +| Parameter | Type | Description | +| ------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| channel\_id | string | Optional. Unique string identifying a channel by its ID. | +| counterparty\_node\_id | string | Optional. A hexidecimal string identifying a counterparty node. | +| funding\_tx | string | Optional. A transaction ID which added funds. | +| from\_funding\_value\_sats | integer | Optional. The minimum value of channel funding in satoshis. | +| to\_funding\_value\_sats | integer | Optional. The maximum value of channel funding in satoshis. | +| is\_outbound | boolean | Optional. If `true`, limits the response to outbound channels only. | +| from\_balance\_msat | integer | Optional. The minimum channel balance in millisatoshis. | +| to\_balance\_msat | integer | Optional. The maximum channel balance in millisatoshis. | +| from\_outbound\_capacity\_msat | integer | Optional. The minimum outbound capacity of the channel balance in millisatoshis. | +| to\_outbound\_capacity\_msat | integer | Optional. The maximum outbound capacity of the channel balance in millisatoshis. | +| from\_inbound\_capacity\_msat | integer | Optional. The minimum inbound capacity of the channel balance in millisatoshis. | +| to\_inbound\_capacity\_msat | integer | Optional. The maximum inbound capacity of the channel balance in millisatoshis. | +| confirmed | boolean | Optional. If `true`, only channels with channel opening transactions that passed the number of confirmations required for the channel to be usable will be returned. | +| is\_usable | boolean | Optional. If `true`, only channels that are confirmed and the counterparty is online, meaning that these channels can be used for payments will be returned. | +| is\_public | boolean | Optional. If `true`, only channels that our node announces to the lightning network, these channels are visible on lightning explorers will be returned. | + +### LightningPayment + +| Parameter | Type | Description | +| ---------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| type | string | The payment type. Accepted values are `invoice` or [`keysend`](https://cdecker-lightning.readthedocs.io/lightning-keysend.7.html). | +| invoice | string | Only used if `type` is `invoice`. An identifying string which represents the invoice. | +| destination | string | Only used if `type` is `keysend`. A `node_pubkey` (which is also the node address in lightning context). Not to be confused with an onchain address. | +| amount\_in\_msat | string | Only used if `type` is `keysend`. Amount to be paid, in [millisatoshis](https://bitcoindata.science/bitcoin-units-converter) (A thousandth of a satoshi; the same as 0.00000000001 bitcoin). | +| expiry | string | Only used if `type` is `keysend`. Optional, defaults to `3600`. Seconds until the payment expires. | + +### LightningPaymentFilter + +| Parameter | Type | Description | +| --------------------- | ------- | ----------------------------------------------------------------------------------------------------------------- | +| payment\_type | object | A standard `LightningPaymentType` object. | +| description | string | Optional. A note to indicate the purpose of the invoice. | +| status | string | Optional. Accepted values: `pending`, `succeeded`, `failed`. | +| from\_amount\_msat | integer | Optional. Minimum amount sent in [millisatoshis](https://bitcoindata.science/bitcoin-units-converter) | +| to\_amount\_msat | integer | Optional. Maximum amount sent in [millisatoshis](https://bitcoindata.science/bitcoin-units-converter) | +| from\_fee\_paid\_msat | integer | Optional. Minimum transaction fee paid in [millisatoshis](https://bitcoindata.science/bitcoin-units-converter) | +| to\_fee\_paid\_msat | integer | Optional. Maximum transaction fee paid in [millisatoshis](https://bitcoindata.science/bitcoin-units-converter) | +| from\_timestamp | string | Optional. Minimum timestamp in [unix epoch format](https://www.epochconverter.com/) of payment results to return. | +| to\_timestamp | string | Optional. Maximum timestamp in [unix epoch format](https://www.epochconverter.com/) of payment results to return. | + +### LightningPaymentType + +| Parameter | Type | Description | +| ----------- | ------ | ----------------------------------------------------------------------------------- | +| type | object | Accepted values are `Outbound Payment` or `Inbound Payment`. | +| destination | string | Only used if `type` is `Outbound Payment`. A pubkey which will receive the payment. | + + + Response may change in future. See + [https://github.com/KomodoPlatform/komodo-docs-mdx/pull/31#discussion\\\_r1206176530](https://github.com/KomodoPlatform/komodo-docs-mdx/pull/31#discussion\\_r1206176530) + + +### 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 + + ```json + { + "PageNumber": 1 + } + ``` + + ```json + { + "FromId": 4 + } + ``` + + +### TokenFilter + +The `TokenFilter` object includes the following items for a given coin or token: + +| Parameter | Type | Description | +| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ | +| exclude\_spam | boolean | Optional, defaults to `false`. If `true`, only tokens which have param `possible_spam:false` are included in the response. | +| exclude\_phishing | boolean | Optional, defaults to `false`. If `true`, only tokens which have param `possible_phishing:false` are included in the response. | + +### TokenTransferFilter + +The `TokenTransferFilter` object includes the following items for a transfer of given coin or token: + +| Parameter | Type | Description | +| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| receive | boolean | Optional, defaults to `false`. If `true`, only transfers where user received NFTs are included in the response. | +| send | boolean | Optional, defaults to `false`. If `true`, only transfers where user sent NFTs are included in the response. | +| from\_date | integer | Optional. A timestamp in [unix epoch format](https://www.epochconverter.com/). If `true`, filter includes transfers from this date onwards (inclusive). | +| to\_date | integer | Optional. A timestamp in [unix epoch format](https://www.epochconverter.com/). If `true`, filter includes transfers up to this date (inclusive). | +| exclude\_spam | boolean | Optional, defaults to `false`. If `true`, only transfers which have param `possible_spam:false` are included in the response. | +| exclude\_phishing | boolean | Optional, defaults to `false`. If `true`, only transfers which have param `possible_phishing:false` are included in the response. | + + + ```json + { + "ticker": "MINDS-ERC20", + "required_confirmations": 4 + } + ``` + + +### NftMetadata + +The `NftMetadata` object includes the following items for a given coin or token: + +| Parameter | Type | Description | +| ----------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| image | string | Optional. Direct URL to the NFT's image. | +| image\_url | string | Optional. Optional. Url to the NFT's image. Derived from the `image` or `image_url` fields to prioritize the non-null value. Can be null if neither is provided. | +| image\_domain | string | Optional. Extracted domain from the 'image\_url', if valid. | +| name | string | Optional. Name of the token. | +| description | string | Optional. Description of the token. | +| attributes | object or array of objects | Optional. The values within this parameter will vary, and are set by the creator. Often used to store traits. | +| animation\_url | string | Optional. Url to an animation to be displayed instead of a static image. | +| animation\_domain | string | Optional. Extracted domain from the `animation_url`, if valid. | +| external\_url | string | Optional. URL to the external source related to the token. | +| external\_domain | string | Optional. Extracted domain from the `external_url`, if valid. | +| image\_details | object | Optional. JSON containing additional details or attributes of the image. | + + + ```json + [ + { + "trait_type": "Specialization", + "value": "Thief" + }, + { + "trait_type": "Skin Tone", + "value": "#0013b0" + }, + { + "trait_type": "Weapon", + "value": "Crossbow" + }, + { + "trait_type": "Species", + "value": "Dark Elf" + }, + { + "trait_type": "Gender", + "value": "Female" + }, + { + "trait_type": "Strength", + "value": "8" + }, + { + "trait_type": "Dexterity", + "value": "12" + }, + { + "trait_type": "Intelligence", + "value": "10" + }, + { + "trait_type": "Perks", + "value": ["Steath", "Eagle Eye", "Lockpicking", "Pickpocketing", "Fire resistance"] + }, + { + "trait_type": "Weakness", + "value": ["Slow healing", "Elfbark Addict", "Lockpicking", "Fear of cats", "Unconvincing liar"] + }, + { + "trait_type": "Personality", + "value": "Aggressive" + } + ] + ``` + + +### TokensRequest + +The `TokensRequest` object includes the following items for a given coin or token: + +| Parameter | Type | Description | +| ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ | +| ticker | string | Ticker of the token to be enabled | +| required\_confirmations | integer | How many confirmations to wait during the transaction steps of an atomic swap. Overwrites value in coins file; defaults to `3` | + + + ```json + { + "ticker": "MINDS-ERC20", + "required_confirmations": 4 + } + ``` + + +### 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 + + ```json + { + "type": "Eth", + "coin": "BNB", + "gas": 109739, + "gas_price": "0.000000003", + "total_fee": "0.000329217" + } + ``` + + #### Example of Qrc20 type + + ```json + { + "type": "Qrc20", + "coin": "tQTUM", + "miner_fee": "0.00000447", + "gas_limit": 100000, + "gas_price": 40, + "total_gas_fee": "0.04" + } + ``` + + #### Example of Tendermint type + + ```json + { + "type": "Tendermint", + "coin": "IRIS", + "amount": "0.038553", + "gas_limit": 100000 + } + ``` + + #### Example of Utxo type + + ```json + { + "type": "Utxo", + "amount": "0.00001" + } + ``` + + +### WithdrawNftData + +The `WithdrawNftData` object is used for withdrawals of NFTs on ERC721 and ERC1155 contracts. It includes the following items for a given coin or token: + +| Parameter | Type | Description | +| -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| chain | string | The token chain. Chain must be [activated](/atomicdex/api/legacy/coin_activation/) first. | +| to | string | Destination address to withdraw the token to. | +| token\_address | string | Token address. | +| token\_id | string | Token ID. | +| fee | object | A standard [WithdrawFee](/atomicdex/api/v20/#withdraw-fee) object. May be missing for older transfers. | +| amount | string | Optional, ERC1155 only. Defaults to `1`. Amount of NFTs to withdraw. Ignored if `max` is true. | +| max | boolean | Optional, ERC1155 only. Defaults to `false`. If `true`, amount parameter will be ignored and all NFTs with this `token_id` will be sent. | + + + When the `type` parameter in a [withdraw\_nft](/atomicdex/api/v20-dev/non_fungible_tokens/withdraw_nft/) request is `withdraw_erc721`, it means the NFT is absolutely unique, + and it has only 1 owner and the owner can own only 1 NFT with this `token_id` + in its `token_address` (also referred to as contract address). + When the `type` parameter in a [withdraw\_nft](/atomicdex/api/v20-dev/non_fungible_tokens/withdraw_nft/) request is `withdraw_erc1155`, it means that it is possible for more + than 1 user to own one or more of the same NFT (with an identical `token_id`). + Due to this difference, the `amount` and `max` fields are only used the when + the `type` value is `withdraw_erc1155`. + +export const title = "AtomicDEX: Signing and Verifying Messages"; +export const description = "The methods in this document allow you to sign and verify messages for all coins supported by AtomicDEX."; + +# Signing\_and\_Verifying\_Messages + +Cryptographically signed messages are a useful feature which can be used to [prove ownership of an address](https://www.coindesk.com/policy/2020/05/25/craig-wright-called-fraud-in-message-signed-with-bitcoin-addresses-he-claims-to-own/). + +If your [`coins`](https://github.com/KomodoPlatform/coins) file contains the correct [`sign_message_prefix`](https://bitcoin.stackexchange.com/questions/77324/how-are-bitcoin-signed-messages-generated/77325#77325) parameter value for a coin, you can sign messages with the [AtomicDEX API](https://github.com/KomodoPlatform/komodo-defi-framework). + +```json +{ + "coin": "DOC", + "asset": "DOC", + "fname": "DOC (TESTCOIN)", + "sign_message_prefix": "Komodo Signed Message:\n", + "rpcport": 25435, + "txversion": 4, + "overwintered": 1, + "mm2": 1, + "protocol": { + "type": "UTXO" + } +} +``` + +## Sign Message + +### Arguments + +| Structure | Type | Description | +| --------- | ------ | ------------------------------- | +| coin | string | The coin to sign a message with | +| message | string | The message you want to sign | + +### Response + +| Structure | Type | Description | +| --------- | ------ | --------------------------------------- | +| signature | string | The signature generated for the message | + +#### Command + + + ```json + { + "userpass": "testpsw", + "method": "sign_message", + "mmrpc": "2.0", + "id": 0, + "params": { + "coin": "DOC", + "message": "Between subtle shading and the absence of light lies the nuance illusion" + } + } + ``` + + +#### Response (success) + +```json +{ + "mmrpc": "2.0", + "result": { + "signature": "H43eTmJxBKEPiHkrCe/8NsRidkKCIkXDxLyp30Ez/RwoApGdg89Hlvj9mTMSPGp8om5297zvdL8EVx3IdIe2swY=" + }, + "id": 0 +} +``` + +### โš  Error types + +**PrefixNotFound:** sign\_message\_prefix is not set in coin config file +**CoinIsNotFound:** Specified coin is not found +**InvalidRequest:** Message signing is not supported by the given coin type +**InternalError:** An internal error occured during the signing process + +## Verify Message + +### Arguments + +| Structure | Type | Description | +| --------- | ------ | ---------------------------------------------------- | +| coin | string | The coin to sign a message with | +| message | string | The message input via the `sign_message` method sign | +| signature | string | The signature generated for the message | +| address | string | The address used to sign the message | + +### Response + +| Structure | Type | Description | +| --------- | ------- | ----------------------------------------------------------- | +| is\_valid | boolean | `true` is message signature is valid; `false` if it is not. | + +#### Command + + + ```json + { + "userpass": "testpsw", + "method": "verify_message", + "mmrpc": "2.0", + "id": 0, + "params": { + "coin": "DOC", + "message": "Between subtle shading and the absence of light lies the nuance illusion", + "signature": "H43eTmJxBKEPiHkrCe/8NsRidkKCIkXDxLyp30Ez/RwoApGdg89Hlvj9mTMSPGp8om5297zvdL8EVx3IdIe2swY=", + "address": "RUYJYSTuCKm9gouWzQN1LirHFEYThwzA2d" + } + } + ``` + + +#### Response (valid) + +```json +{ + "mmrpc": "2.0", + "result": { + "is_valid": true + }, + "id": 0 +} +``` + +#### Response (not valid) + +```json +{ + "mmrpc": "2.0", + "result": { + "is_valid": false + }, + "id": 0 +} +``` + +### โš  Error types + +**PrefixNotFound:** sign\_message\_prefix is not set in coin config +**CoinIsNotFound:** Specified coin is not found +**InvalidRequest:** Message verification is not supported by the given coin type +**InternalError:** An internal error occured during the verification process +**SignatureDecodingError:** Given signature could not be decoded +**AddressDecodingError:** Given address could not be decoded +export const title = "AtomicDEX Method: My TX History"; +export const description = "The my_tx_history method allows you to view the transaction history of coins."; + +# my\_tx\_history + +To use this method, you must activate your coin with `"tx_history": true`. The response will vary depending on the coin. +Currently only BCH & SLP tokens are supported in the master/release API. In the latest dev API, UTXO coins, QTUM, and Tendermint/Tendermint tokens are also supported. +For ZHTLC coins, you must use the [z\_coin\_tx\_history](/atomicdex/api/v20-dev/task_enable_z_coin/#z-coin-transaction-history) method. +For all other coins, use the legacy [my\_tx\_history](/atomicdex/api/legacy/my_tx_history/#my-tx-history) method. + +## Arguments + +| parameter | Type | Description | +| --------------- | ------- | ------------------------------------------------------------------------------------------------ | +| coin | string | Ticker of the coin to get history for. | +| limit | integer | Optional. Limits the number of returned transactions. Defaults to `10`. Ignored if `max = true`. | +| paging\_options | object | Optional. A standard [Pagination](/atomicdex/api/common_structures/#pagination) object. | + +#### Response + +| Structure | Type | Description | +| -------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| transactions | array of objects | transactions data | +| from\_id | string | the from\_id specified in the request; this value is null if from\_id was not set | +| skipped | number | the number of skipped records (i.e. the position of `from_id` in the list + 1); this value is 0 if `from_id` was not set | +| limit | number | the limit that was set in the request; note that the actual number of transactions can differ from the specified limit (e.g. on the last page) | +| total | number | the total number of transactions available | +| page\_number | number | the page\_number that was set in the request | +| total\_pages | number | total pages available with the selected limit | +| current\_block | number | the number of the latest block of coin blockchain | +| sync\_status | object | A standard [SyncStatus](/atomicdex/api/common_structures/#sync-status/) object. Provides the information that helps to track the progress of transaction history preloading at background | + +## Request (BCH from page 2) + + + ```json + { + "userpass": "testpsw", + "method": "my_tx_history", + "mmrpc": "2.0", + "params": { + "coin": "BCH", + "limit": 2, + "paging_options": { + "PageNumber": 2 + } + } + } + ``` + + + + ### Response + + ```json + { + "mmrpc": "2.0", + "result": { + "coin": "BCH", + "target": { + "type": "iguana" + }, + "current_block": 772607, + "transactions": [ + { + "tx_hex": "0100000001b7b45d92f8f3413a0e5656258e0a51f5c7e8230c0a08cef2ebec1ddbb8f7c28200000000d747304402203ca957fdfcfbba6123d78afe28b17fd4103cc04f6ada4110eb61c2a0350c29b802204215f203d583e8bcc79bd70f33af4f4e27500b5a5375efe75a1c31ec112f3c344120b3f71dbea00eeace7f09b0911de31e46f76a48036b86ccc207dac55540912e01004c6b6304dbf67563b175210315d9c51c657ab1be4ae9d3ab6e76a619d3bccfe830d5363fa168424c0d044732ac6782012088a914dde61fe24ea3cfa39379c475702692fa2f080900882103ed00156316c46094c0cbcf21a5ee549a1b3a50938c43096ef499ca28059edca6ac68ffffffff0133980200000000001976a91411a1563bfa55ae05fa621b2e245abe5a358c852e88acdbf67563", + "tx_hash": "e2167df56142bccdb8c620297f1b6ca3f7c8a955332838430d4d0f62530870f9", + "from": [ + "bitcoincash:ppaa62685yaucdf2a54g3rgtyc9g7yawrvvmqsfumc" + ], + "to": [ + "bitcoincash:qqg6z43mlf26up06vgdjufz6hedrtry99cvk5dgcnt" + ], + "total_amount": "0.00171035", + "spent_by_me": "0", + "received_by_me": "0.00170035", + "my_balance_change": "0.00170035", + "block_height": 766923, + "timestamp": 1668615553, + "fee_details": { + "type": "Utxo", + "coin": "BCH", + "amount": "0.00001" + }, + "coin": "BCH", + "internal_id": "e2167df56142bccdb8c620297f1b6ca3f7c8a955332838430d4d0f62530870f9", + "transaction_type": "StandardTransfer", + "confirmations": 5685 + }, + { + "tx_hex": "0100000001eccfa8c296e7b3e229be28a8ca6a5e5a7e89ee07a2d9441faaf5905679286a3c00000000d7473044022077d38ae45bb7257b152d4cb803aab62ca879cab60e9b3a7ca05ef099078e000402203106be31513c6526c14bdf40b28b4d38f78bb1958fc995e040ac4b2165d9d79141203bffadbc5bf035674f0d0f6e1d1a121fc6d404720679ff9b6610b298b41375a3004c6b6304bc847463b175210315d9c51c657ab1be4ae9d3ab6e76a619d3bccfe830d5363fa168424c0d044732ac6782012088a91457c7ce14c0444edc37ee52ed32b68890b0647cd3882103ed00156316c46094c0cbcf21a5ee549a1b3a50938c43096ef499ca28059edca6ac68ffffffff0163b10200000000001976a91411a1563bfa55ae05fa621b2e245abe5a358c852e88acbc847463", + "tx_hash": "98ddc27aa161967519f53cb3e91146a23b76ac4e33605f8e827c69f4d9b6de37", + "from": [ + "bitcoincash:ppnzkha52y53d7r7qn6mq4mcmaadmxzj4clfgneaxv" + ], + "to": [ + "bitcoincash:qqg6z43mlf26up06vgdjufz6hedrtry99cvk5dgcnt" + ], + "total_amount": "0.00177483", + "spent_by_me": "0", + "received_by_me": "0.00176483", + "my_balance_change": "0.00176483", + "block_height": 766752, + "timestamp": 1668519015, + "fee_details": { + "type": "Utxo", + "coin": "BCH", + "amount": "0.00001" + }, + "coin": "BCH", + "internal_id": "98ddc27aa161967519f53cb3e91146a23b76ac4e33605f8e827c69f4d9b6de37", + "transaction_type": "StandardTransfer", + "confirmations": 5856 + } + ], + "sync_status": { + "state": "Finished" + }, + "limit": 2, + "skipped": 2, + "total": 16, + "total_pages": 8, + "paging_options": { + "PageNumber": 2 + } + }, + "id": null + } + ``` + + +## Request (TTT-SLP with FromId) + + + ```json + { + "userpass": "testpsw", + "method": "my_tx_history", + "mmrpc": "2.0", + "params": { + "coin": "TTT-SLP", + "limit": 2, + "paging_options": { + "FromId": "433b641bc89e1b59c22717918583c60ec98421805c8e85b064691705d9aeb970" + } + } + } + ``` + + + + ### Response + + ```json + { + "mmrpc": "2.0", + "result": { + "coin": "TTT-SLP", + "target": { + "type": "iguana" + }, + "current_block": 772612, + "transactions": [ + { + "tx_hex": "0200000002365a29eb638da7fc57720ad6c99fdbc6cfb9c957920cfb62fd69e494b412c1c1020000006b483045022100de81bca8cfef2f95b3da8aa89edf4f5cc6cf489c565d0965b8142380ef3986f1022062d6ed47f2cd281f4860a27e835949aafbab89eeb0865fbf2280a283dfb7c417412102b9fdfedefde71b21523974b9f24a4b6a1b83c5640b839baa6eb14418cae08191ffffffffc1f73b403f893f93d95b8c7dfa1b59bb5445109d4c51107da1e08fb770e54136010000006a47304402203658375dac3b84ae17e72cf3f5157b8ad25e7caee0629fa8708868974f8d58b402206f38d016ed4e390d783627441685692d21b889d83919abd39368cba28f43f544412102b9fdfedefde71b21523974b9f24a4b6a1b83c5640b839baa6eb14418cae08191ffffffff040000000000000000406a04534c500001010453454e44205321508197ffed321c5fc9a1427e5c68b31d2c1ec92ae1c495f8acb08d8d66cd080000000000002710080000002278c569d322020000000000001976a914d346067e3c3c3964c395fee208594790e29ede5d88ac22020000000000001976a914580af35e3553d57b4b3a2036f4959f10246e98c788ac68955e03000000001976a914580af35e3553d57b4b3a2036f4959f10246e98c788ac00000000", + "tx_hash": "7b58248f3486079951a57d6dbd41c019a83f2b876c9fa3afa6fcc5a7c595b837", + "from": ["simpleledger:qpvq4u67x4fa276t8gsrday4nugzgm5ccu4usawss8"], + "to": [ + "simpleledger:qpvq4u67x4fa276t8gsrday4nugzgm5ccu4usawss8", + "simpleledger:qrf5vpn78s7rjexrjhlwyzzeg7gw98k7t5va3wuz4v" + ], + "total_amount": "1480551016.67", + "spent_by_me": "0", + "received_by_me": "100", + "my_balance_change": "100", + "block_height": 772211, + "timestamp": 1671817336, + "fee_details": { + "type": "Utxo", + "coin": "BCH", + "amount": "0.00000482" + }, + "coin": "TTT-SLP", + "internal_id": "57b78eb912a704921640a589d8bb42bb147dfb88c3d1b4b2e3df910be6b9ab31", + "transaction_type": { + "TokenTransfer": "5321508197ffed321c5fc9a1427e5c68b31d2c1ec92ae1c495f8acb08d8d66cd" + }, + "confirmations": 402 + } + ], + "sync_status": { + "state": "Finished" + }, + "limit": 10, + "skipped": 0, + "total": 1, + "total_pages": 1, + "paging_options": { + "FromId": "433b641bc89e1b59c22717918583c60ec98421805c8e85b064691705d9aeb970" + } + }, + "id": null + } + ``` + + +## Request (IRIS with limit = 50) + + + ```json + { + "userpass": "testpsw", + "method": "my_tx_history", + "mmrpc": "2.0", + "params": { + "coin": "IRIS", + "limit": 50 + } + } + ``` + + + + ### Response + + ```json + { + "mmrpc": "2.0", + "result": { + "coin": "IRIS", + "target": { + "type": "iguana" + }, + "current_block": 18120346, + "transactions": [ + { + "tx_hex": "0a2a6961613136647271766c33753873756b667375346c6d3371736b32386a72336661686a6139767376366b122a6961613136647271766c33753873756b667375346c6d3371736b32386a72336661686a6139767376366b1a110a05756972697312083130303030303030", + "tx_hash": "B34A8D5AD74067F01A0207DF1851A14673C859D8A6F4FB0CBE292D2104C143CA", + "from": ["iaa16drqvl3u8sukfsu4lm3qsk28jr3fahja9vsv6k"], + "to": ["iaa16drqvl3u8sukfsu4lm3qsk28jr3fahja9vsv6k"], + "total_amount": "10.044559", + "spent_by_me": "10.044559", + "received_by_me": "10", + "my_balance_change": "-0.044559", + "block_height": 18120218, + "timestamp": 1673016440, + "fee_details": { + "type": "Tendermint", + "coin": "IRIS", + "amount": "0.044559", + "gas_limit": 100000 + }, + "coin": "IRIS", + "internal_id": "4644373032304131304637363034374441354438413433420000000000000000", + "transaction_type": "StandardTransfer", + "memo": "while you are out, buy milk", + "confirmations": 129 + }, + { + "tx_hex": "0a2a6961613136647271766c33753873756b667375346c6d3371736b32386a72336661686a6139767376366b122a696161317a78733476776c36326b687174376e7a7276687a676b34377467366365706677707a673537711a4d0a446962632f3237333934464230393244324543434435363132334337344633364534433146393236303031434541444139434139374541363232423235463431453545423212053130303030", + "tx_hash": "09ADDD3427A3BA4B0A94023456DF534DB5B9B6821EC17C7C1B2C168EFCF49F26", + "from": ["iaa16drqvl3u8sukfsu4lm3qsk28jr3fahja9vsv6k"], + "to": [], + "total_amount": "0.051788", + "spent_by_me": "0.051788", + "received_by_me": "0", + "my_balance_change": "-0.051788", + "block_height": 17996530, + "timestamp": 1672232661, + "fee_details": { + "type": "Tendermint", + "coin": "IRIS", + "amount": "0.051788", + "gas_limit": 100000 + }, + "coin": "IRIS", + "internal_id": "0000000000000000303941444444333432374133424134423041393430323334", + "transaction_type": "FeeForTokenTx", + "memo": null, + "confirmations": 123817 + }, + { + "tx_hex": "0a2a6961613136647271766c33753873756b667375346c6d3371736b32386a72336661686a6139767376366b1240343133433843414333434142363945454632344432423643414238314146454344383044413745323731433237343637453142324635463337314446353241441a4061353539343834666536316665383630326465383632353964643263663031613865393437306437666635346262323536336233393035646462366238366535", + "tx_hash": "4E30C074CED6825F3E1B6584C376A426C20FDEFC9A22EB17D8E7DA4139FA0AEB", + "from": ["iaa16drqvl3u8sukfsu4lm3qsk28jr3fahja9vsv6k"], + "to": [], + "total_amount": "182.742425", + "spent_by_me": "0.053103", + "received_by_me": "182.689322", + "my_balance_change": "182.636219", + "block_height": 17981793, + "timestamp": 1672138900, + "fee_details": { + "type": "Tendermint", + "coin": "IRIS", + "amount": "0.053103", + "gas_limit": 100000 + }, + "coin": "IRIS", + "internal_id": "3438353642314533463532383644454334373043303345340000000000000000", + "transaction_type": { + "CustomTendermintMsg": { + "msg_type": "SignClaimHtlc", + "token_id": null + } + }, + "memo": null, + "confirmations": 138554 + } + ], + "sync_status": { + "state": "NotStarted" + }, + "limit": 50, + "skipped": 0, + "total": 3, + "total_pages": 1, + "paging_options": { + "PageNumber": 1 + } + }, + "id": null + } + ``` + + +## Error cases + +### Error - Coin not active + +```json +{ + "mmrpc": "2.0", + "error": "TTT-SLP", + "error_path": "my_tx_history_v2.lp_coins", + "error_trace": "my_tx_history_v2:389] lp_coins:2847]", + "error_type": "CoinIsNotActive", + "error_data": "TTT-SLP", + "id": null +} +``` + +### Error - Coin not compatible + +```json +{ + "mmrpc": "2.0", + "error": "TTT-SLP", + "error_path": "my_tx_history_v2", + "error_trace": "my_tx_history_v2:336]", + "error_type": "NotSupportedFor", + "error_data": "TTT-SLP", + "id": null +} +``` + +### Error - Coin enabled without tx\_history = true + +```json +{ + "mmrpc": "2.0", + "error": "Storage is not initialized for TTT-SLP", + "error_path": "my_tx_history_v2", + "error_trace": "my_tx_history_v2:343]", + "error_type": "StorageIsNotInitialized", + "error_data": "Storage is not initialized for TTT-SLP", + "id": null +} +``` + +### Error - Local database failed + +```json +{ + "mmrpc": "2.0", + "error": "SqliteFailure(Error { code: Unknown, extended_code: 1 }, Some(\"no such column: block_height\"))", + "error_path": "my_tx_history_v2.sql_tx_history_storage", + "error_trace": "my_tx_history_v2:351] sql_tx_history_storage:472]", + "error_type": "StorageError", + "error_data": "SqliteFailure(Error { code: Unknown, extended_code: 1 }, Some(\"no such column: block_height\"))", + "id": null +} +``` +export const title = "AtomicDEX Method: Orderbook v2"; +export const description = "The orderbook method requests from the network the currently available orders for the specified trading pair."; + +# orderbook + +**orderbook base rel** + +The v2 `orderbook` method requests from the network the currently available orders for the specified trading pair. + +## Arguments + +| Structure | Type | Description | +| --------- | ------ | ---------------------------------------------------- | +| base | string | Base currency of a pair | +| rel | string | Related currency, also known as the "quote currency" | + +## Response + +| Structure | Type | Description | +| ---------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------ | +| base | string | The name of the coin the user desires to receive | +| rel | string | The name of the coin the user will trade | +| numasks | integer | The number of outstanding asks | +| numbids | integer | The number of outstanding bids | +| netid | integer | The id of the network on which the request is made (default is `8762`) | +| asks | array of objects | An array of standard [OrderDataV2](/atomicdex/api/common_structures/orders/#order-data-v2) objects containing outstanding asks | +| bids | array of objects | An array of standard [OrderDataV2](/atomicdex/api/common_structures/orders/#order-data-v2) objects containing outstanding bids | +| timestamp | integer | A UNIX timestamp representing when the orderbook was requested | +| total\_asks\_base\_vol | object | A standard [NumericFormatsValue](/atomicdex/api/common_structures/#numeric-formats-value) object. | +| total\_asks\_rel\_vol | object | A standard [NumericFormatsValue](/atomicdex/api/common_structures/#numeric-formats-value) object. | +| total\_bids\_base\_vol | object | A standard [NumericFormatsValue](/atomicdex/api/common_structures/#numeric-formats-value) object. | +| total\_bids\_rel\_vol | object | A standard [NumericFormatsValue](/atomicdex/api/common_structures/#numeric-formats-value) object. | + +#### ๐Ÿ“Œ Examples + +#### Command + + + ```json + { + "mmrpc": "2.0", + "userpass": "testpsw", + "method": "orderbook", + "params": { + "base": "DGB", + "rel": "DASH" + }, + "id": 42 + } + ``` + + + + #### Response + + ```json + { + "mmrpc": "2.0", + "result": { + "asks": [ + { + "coin": "DGB", + "address": { + "address_type": "Transparent", + "address_data": "DEsCggcN3WNmaTkF2WpqoMQqx4JGQrLbPS" + }, + "price": { + "decimal": "0.0002658065", + "rational": [ + [1, [531613]], [1, [2000000000]] ], "fraction": { @@ -41150,368 +41868,925 @@ The v2 `orderbook` method requests from the network the currently available orde "numer": "375967744654276467", "denom": "15625000000000000" } - }, - "rel_min_volume": { - "decimal": "0.0001", - "rational": [ - [1, [1]], - [1, [10000]] - ], - "fraction": { - "numer": "1", - "denom": "10000" + }, + "rel_min_volume": { + "decimal": "0.0001", + "rational": [ + [1, [1]], + [1, [10000]] + ], + "fraction": { + "numer": "1", + "denom": "10000" + } + }, + "conf_settings": { + "base_confs": 7, + "base_nota": false, + "rel_confs": 2, + "rel_nota": false + }, + "base_max_volume_aggr": { + "decimal": "133319.023345413", + "rational": [ + [1, [3238477573, 31040]], + [1, [1000000000]] + ], + "fraction": { + "numer": "133319023345413", + "denom": "1000000000" + } + }, + "rel_max_volume_aggr": { + "decimal": "35.2500366381728643576", + "rational": [ + [1, [473921343, 1669176307, 2]], + [1, [2436694016, 291038304]] + ], + "fraction": { + "numer": "44062545797716080447", + "denom": "1250000000000000000" + } + } + } + ], + "base": "DGB", + "bids": [ + { + "coin": "DASH", + "address": { + "address_type": "Transparent", + "address_data": "XcYdfQgeuM5f5V2LNo9g8o8p3rPPbKwwCg" + }, + "price": { + "decimal": "0.0002544075418788651605521516540338523799763700988224165198319218986992534200426899830070024093907274001", + "rational": [ + [1, [1410065408, 2]], + [1, [3765089107, 9151]] + ], + "fraction": { + "numer": "10000000000", + "denom": "39307010814803" + } + }, + "pubkey": "0315d9c51c657ab1be4ae9d3ab6e76a619d3bccfe830d5363fa168424c0d044732", + "uuid": "e9e4feb2-60b4-4184-8294-591687171e6b", + "is_mine": false, + "base_max_volume": { + "decimal": "15449.5309493280527473176", + "rational": [ + [1, [161102659, 3869502237, 1046]], + [1, [2436694016, 291038304]] + ], + "fraction": { + "numer": "19311913686660065934147", + "denom": "1250000000000000000" + } + }, + "base_min_volume": { + "decimal": "0.39307010814803", + "rational": [ + [1, [3765089107, 9151]], + [1, [276447232, 23283]] + ], + "fraction": { + "numer": "39307010814803", + "denom": "100000000000000" + } + }, + "rel_max_volume": { + "decimal": "3.930477192", + "rational": [ + [1, [491309649]], + [1, [125000000]] + ], + "fraction": { + "numer": "491309649", + "denom": "125000000" + } + }, + "rel_min_volume": { + "decimal": "0.0001", + "rational": [ + [1, [1]], + [1, [10000]] + ], + "fraction": { + "numer": "1", + "denom": "10000" + } + }, + "conf_settings": { + "base_confs": 7, + "base_nota": false, + "rel_confs": 2, + "rel_nota": false + }, + "base_max_volume_aggr": { + "decimal": "15449.5309493280527473176", + "rational": [ + [1, [161102659, 3869502237, 1046]], + [1, [2436694016, 291038304]] + ], + "fraction": { + "numer": "19311913686660065934147", + "denom": "1250000000000000000" + } + }, + "rel_max_volume_aggr": { + "decimal": "3.930477192", + "rational": [ + [1, [491309649]], + [1, [125000000]] + ], + "fraction": { + "numer": "491309649", + "denom": "125000000" + } + } + } + ], + "net_id": 8762, + "num_asks": 3, + "num_bids": 3, + "rel": "DASH", + "timestamp": 1694183345, + "total_asks_base_vol": { + "decimal": "133319.023345413", + "rational": [ + [1, [3238477573, 31040]], + [1, [1000000000]] + ], + "fraction": { + "numer": "133319023345413", + "denom": "1000000000" + } + }, + "total_asks_rel_vol": { + "decimal": "35.2500366381728643576", + "rational": [ + [1, [473921343, 1669176307, 2]], + [1, [2436694016, 291038304]] + ], + "fraction": { + "numer": "44062545797716080447", + "denom": "1250000000000000000" + } + }, + "total_bids_base_vol": { + "decimal": "59100.6554157135128550633", + "rational": [ + [1, [1422777577, 2274178813, 32038]], + [1, [2313682944, 2328306436]] + ], + "fraction": { + "numer": "591006554157135128550633", + "denom": "10000000000000000000" + } + }, + "total_bids_rel_vol": { + "decimal": "14.814675225", + "rational": [ + [1, [592587009]], + [1, [40000000]] + ], + "fraction": { + "numer": "592587009", + "denom": "40000000" + } + } + }, + "id": 42 + } + ``` + +export const title = "AtomicDEX Method: Recreate Swap Data"; +export const description = "The recreate_swap_data method helps recover lost swap data due to storage errors or hardware failure."; + +# recreate\_swap\_data + +The `recreate_swap_data` can assist in the event of local stored swap data being lost due to storage errors related to low disk space or hardware failure, and if required, aid with the refunding of failed swaps. + +To source the opposite side of the trade, please [contact the Komodo Support team on Discord](https://discord.com/invite/RRZ8hzc). You will need to provide details about the trade you are trying to recover, such as the coins and amounts being traded, the approximate time of the trade, any known transaction IDs involved in the trade, and if available the UUID of the trade. + +## Arguments + +| Structure | Type | Description | +| --------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- | +| swap | object | Swap data from other side of trade. For example to recreate a Maker's swap data, the input would be the corresponding Taker's swap data | + +#### Response + +| Structure | Type | Description | +| --------- | ------ | --------------------------------------------------------------------------------------------------------------------------------- | +| result | object | Opposite side's swap data. For example if a Taker's swap data is input, the reponse would be the corresponding Maker's swap data. | + +#### ๐Ÿ“Œ Examples + +#### Command + + + ```json + { + "userpass": "testpsw", + "mmrpc": "2.0", + "method": "recreate_swap_data", + "params": { + "swap": { + "type": "Taker", + "uuid": "f87fa9ce-0820-4675-b85d-db18c7bc9fb4", + "my_order_uuid": "f87fa9ce-0820-4675-b85d-db18c7bc9fb4", + "events": [ + { + "timestamp": 1638984440546, + "event": { + "type": "Started", + "data": { + "taker_coin": "MARTY", + "maker_coin": "DOC", + "maker": "15d9c51c657ab1be4ae9d3ab6e76a619d3bccfe830d5363fa168424c0d044732", + "my_persistent_pub": "03b1e544ce2d860219bc91314b5483421a553a7b33044659eff0be9214ed58addd", + "lock_duration": 7800, + "maker_amount": "0.9090909090909090909090909090909090909090909090909090909090909090909090909090909090909090909090909091", + "taker_amount": "1", + "maker_payment_confirmations": 1, + "maker_payment_requires_nota": false, + "taker_payment_confirmations": 1, + "taker_payment_requires_nota": false, + "taker_payment_lock": 1638992240, + "uuid": "f87fa9ce-0820-4675-b85d-db18c7bc9fb4", + "started_at": 1638984440, + "maker_payment_wait": 1638987560, + "maker_coin_start_block": 1207822, + "taker_coin_start_block": 1222573, + "fee_to_send_taker_fee": { + "coin": "MARTY", + "amount": "0.00001", + "paid_from_trading_vol": false + }, + "taker_payment_trade_fee": { + "coin": "MARTY", + "amount": "0.00001", + "paid_from_trading_vol": false + }, + "maker_payment_spend_trade_fee": { + "coin": "DOC", + "amount": "0.00001", + "paid_from_trading_vol": true + } + } + } + }, + { + "timestamp": 1638984456603, + "event": { + "type": "Negotiated", + "data": { + "maker_payment_locktime": 1639000040, + "maker_pubkey": "0315d9c51c657ab1be4ae9d3ab6e76a619d3bccfe830d5363fa168424c0d044732", + "secret_hash": "4da9e7080175e8e10842e0e161b33cd298cab30b", + "maker_coin_swap_contract_addr": null, + "taker_coin_swap_contract_addr": null + } + } + }, + { + "timestamp": 1638984456814, + "event": { + "type": "TakerFeeSent", + "data": { + "tx_hex": "0400008085202f89016383e8aced2256378bb126a1ca1a41e2f344d9295f65b3ea4b99055c5eb4a6cb000000006a47304402201c7e661e0dbeb9b3eb6e4e9e3194010e5772227017772b2e48c1b8d48ed3b21f02201c2eda64e74455fa1878a5c221f25d22fe626abd0078a26a9fc0f829e0921639012103b1e544ce2d860219bc91314b5483421a553a7b33044659eff0be9214ed58adddffffffff02bcf60100000000001976a914ca1e04745e8ca0c60d8c5881531d51bec470743f88ac74c3e90b000000001976a91483762a373935ca241d557dfce89171d582b486de88ac08ebb061000000000000000000000000000000", + "tx_hash": "fcb49167c79e8e014143643b94878866f7e80b26c5a5dcf693010543da70b5bc" + } + } + }, + { + "timestamp": 1638984457822, + "event": { + "type": "MakerPaymentReceived", + "data": { + "tx_hex": "0400008085202f8901c41fdf6b9d8aea4b472f83e4fa0d99dfafc245e897d681fd2ca7df30707fbf48020000006b483045022100c7b294bd46cbf3b13530879a43c5cf67414047266d8b64c3c7263b5e75b989ba02201974f38d688b184bc44e628806c6ab2ac9092f394729d0ce838f14e1e76117c001210315d9c51c657ab1be4ae9d3ab6e76a619d3bccfe830d5363fa168424c0d044732ffffffff03a2296b050000000017a91491c45f69e1760c12a1f90fb2a811f6dfde35cc35870000000000000000166a144da9e7080175e8e10842e0e161b33cd298cab30bac503d64000000001976a9141462c3dd3f936d595c9af55978003b27c250441f88ac09ebb061000000000000000000000000000000", + "tx_hash": "6287e0d30951cd859bfb837eb1e5409f7596e75ffeb2e61fd6df1843bfd0203d" + } + } + }, + { + "timestamp": 1638984457826, + "event": { + "type": "MakerPaymentWaitConfirmStarted" + } + }, + { + "timestamp": 1638984503611, + "event": { + "type": "MakerPaymentWaitConfirmFailed", + "data": { + "error": "An error" + } + } + }, + { + "timestamp": 1638984503615, + "event": { + "type": "Finished" + } + } + ], + "maker_amount": "0.9090909090909090909090909090909090909090909090909090909090909090909090909090909090909090909090909091", + "maker_coin": "DOC", + "taker_amount": "1", + "taker_coin": "MARTY", + "gui": "atomicDEX 0.5.1 iOS", + "mm_version": "1b065636a", + "success_events": [ + "Started", + "Negotiated", + "TakerFeeSent", + "MakerPaymentReceived", + "MakerPaymentWaitConfirmStarted", + "MakerPaymentValidatedAndConfirmed", + "TakerPaymentSent", + "TakerPaymentSpent", + "MakerPaymentSpent", + "Finished" + ], + "error_events": [ + "StartFailed", + "NegotiateFailed", + "TakerFeeSendFailed", + "MakerPaymentValidateFailed", + "MakerPaymentWaitConfirmFailed", + "TakerPaymentTransactionFailed", + "TakerPaymentWaitConfirmFailed", + "TakerPaymentDataSendFailed", + "TakerPaymentWaitForSpendFailed", + "MakerPaymentSpendFailed", + "TakerPaymentWaitRefundStarted", + "TakerPaymentRefunded", + "TakerPaymentRefundFailed" + ] + } + }, + "id": 0 + } + ``` + + + + #### Response (success) + + ```json + { + "mmrpc": "2.0", + "result": { + "swap": { + "type": "Maker", + "uuid": "f87fa9ce-0820-4675-b85d-db18c7bc9fb4", + "my_order_uuid": "f87fa9ce-0820-4675-b85d-db18c7bc9fb4", + "events": [ + { + "timestamp": 1638984440546, + "event": { + "type": "Started", + "data": { + "taker_coin": "MARTY", + "maker_coin": "DOC", + "taker": "b1e544ce2d860219bc91314b5483421a553a7b33044659eff0be9214ed58addd", + "secret": "0000000000000000000000000000000000000000000000000000000000000000", + "secret_hash": "4da9e7080175e8e10842e0e161b33cd298cab30b", + "my_persistent_pub": "0315d9c51c657ab1be4ae9d3ab6e76a619d3bccfe830d5363fa168424c0d044732", + "lock_duration": 7800, + "maker_amount": "0.9090909090909090909090909090909090909090909090909090909090909090909090909090909090909090909090909091", + "taker_amount": "1", + "maker_payment_confirmations": 1, + "maker_payment_requires_nota": false, + "taker_payment_confirmations": 1, + "taker_payment_requires_nota": false, + "maker_payment_lock": 1639000040, + "uuid": "f87fa9ce-0820-4675-b85d-db18c7bc9fb4", + "started_at": 1638984440, + "maker_coin_start_block": 1207822, + "taker_coin_start_block": 1222573, + "maker_payment_trade_fee": null, + "taker_payment_spend_trade_fee": null + } + } + }, + { + "timestamp": 1638984456603, + "event": { + "type": "Negotiated", + "data": { + "taker_payment_locktime": 1638992240, + "taker_pubkey": "03b1e544ce2d860219bc91314b5483421a553a7b33044659eff0be9214ed58addd", + "maker_coin_swap_contract_addr": null, + "taker_coin_swap_contract_addr": null + } + } + }, + { + "timestamp": 1638984457822, + "event": { + "type": "TakerFeeValidated", + "data": { + "tx_hex": "0400008085202f89016383e8aced2256378bb126a1ca1a41e2f344d9295f65b3ea4b99055c5eb4a6cb000000006a47304402201c7e661e0dbeb9b3eb6e4e9e3194010e5772227017772b2e48c1b8d48ed3b21f02201c2eda64e74455fa1878a5c221f25d22fe626abd0078a26a9fc0f829e0921639012103b1e544ce2d860219bc91314b5483421a553a7b33044659eff0be9214ed58adddffffffff02bcf60100000000001976a914ca1e04745e8ca0c60d8c5881531d51bec470743f88ac74c3e90b000000001976a91483762a373935ca241d557dfce89171d582b486de88ac08ebb061000000000000000000000000000000", + "tx_hash": "fcb49167c79e8e014143643b94878866f7e80b26c5a5dcf693010543da70b5bc" + } + } + }, + { + "timestamp": 1638984457822, + "event": { + "type": "MakerPaymentSent", + "data": { + "tx_hex": "0400008085202f8901c41fdf6b9d8aea4b472f83e4fa0d99dfafc245e897d681fd2ca7df30707fbf48020000006b483045022100c7b294bd46cbf3b13530879a43c5cf67414047266d8b64c3c7263b5e75b989ba02201974f38d688b184bc44e628806c6ab2ac9092f394729d0ce838f14e1e76117c001210315d9c51c657ab1be4ae9d3ab6e76a619d3bccfe830d5363fa168424c0d044732ffffffff03a2296b050000000017a91491c45f69e1760c12a1f90fb2a811f6dfde35cc35870000000000000000166a144da9e7080175e8e10842e0e161b33cd298cab30bac503d64000000001976a9141462c3dd3f936d595c9af55978003b27c250441f88ac09ebb061000000000000000000000000000000", + "tx_hash": "6287e0d30951cd859bfb837eb1e5409f7596e75ffeb2e61fd6df1843bfd0203d" + } + } + }, + { + "timestamp": 1638984503611, + "event": { + "type": "TakerPaymentValidateFailed", + "data": { + "error": "Origin Taker error event: MakerPaymentWaitConfirmFailed(SwapError { error: \"An error\" })" + } + } + }, + { + "timestamp": 1638984503611, + "event": { + "type": "MakerPaymentWaitRefundStarted", + "data": { + "wait_until": 1639003740 + } + } } - }, - "conf_settings": { - "base_confs": 7, + ], + "maker_amount": "0.9090909090909090909090909090909090909090909090909090909090909090909090909090909090909090909090909091", + "maker_coin": "DOC", + "taker_amount": "1", + "taker_coin": "MARTY", + "gui": "nogui", + "mm_version": "", + "success_events": [ + "Started", + "Negotiated", + "TakerFeeValidated", + "MakerPaymentSent", + "TakerPaymentReceived", + "TakerPaymentWaitConfirmStarted", + "TakerPaymentValidatedAndConfirmed", + "TakerPaymentSpent", + "TakerPaymentSpendConfirmStarted", + "TakerPaymentSpendConfirmed", + "Finished" + ], + "error_events": [ + "StartFailed", + "NegotiateFailed", + "TakerFeeValidateFailed", + "MakerPaymentTransactionFailed", + "MakerPaymentDataSendFailed", + "MakerPaymentWaitConfirmFailed", + "TakerPaymentValidateFailed", + "TakerPaymentWaitConfirmFailed", + "TakerPaymentSpendFailed", + "TakerPaymentSpendConfirmFailed", + "MakerPaymentWaitRefundStarted", + "MakerPaymentRefunded", + "MakerPaymentRefundFailed" + ] + } + }, + "id": null + } + ``` + +export const title = "AtomicDEX Method: Remove Delegation"; +export const description = + "The remove_delegation method stops your node's staking of a compatible coin."; + +# remove\_delegation + +The `remove_delegation` method stops your node's staking of a compatible coin. Currently QTUM and tQTUM (test tokens avalable at `https://testnet-faucet.qtum.info/`) have been integrated, but this functionality will be expanded to more coins in future. + +Note: After running `remove_delegation`, you will need to broadcast the returned hex via [`send_raw_transaction`](/atomicdex/api/legacy/send_raw_transaction/) to complete the process. + +## Arguments + +| Structure | Type | Description | +| --------- | ------ | --------------------- | +| coin | string | the coin being staked | + +#### ๐Ÿ“Œ Examples + +#### Command + + + ```json + { + "userpass": "testpsw", + "mmrpc": "2.0", + "method": "remove_delegation", + "params": { + "coin": "tQTUM" + }, + "id": 0 + } + ``` + + + + #### Response (success) + + ```json + { + "mmrpc": "2.0", + "result": { + "tx_hex": "01000000015c7f32b1b3396ce1bed4f6c161bcc3a5bf5c58e4338c66a24c9de1deffc5b94e000000006a47304402203fcdf1e48f6e43fd718b4aab79c56a7ff81b12304339ddf6d871a3f26f217a7502200c22fa8e2bcc33d16f4bf62feb71f637acbefdd34135314e6aa526e6655cba73012102641b541e35bc915e375c8038f1099a977bc6736aa7265e9f65b7270b70d34366ffffffff020000000000000000225403a086010128043d666e8b140000000000000000000000000000000000000086c280584f00000000001976a914c36ac1020b1eae632079692e7bef350d279489c988acb8d98061", + "tx_hash": "3564859a7ff902e8d65387c44f6049943582e0b9e29161bf1075a00097e535ae", + "from": ["qbNeoqCbBu4hySDUzgmo666faYH3qgaeKz"], + "to": ["qbNeoqCbBu4hySDUzgmo666faYH3qgaeKz"], + "total_amount": "0.096", + "spent_by_me": "0.096", + "received_by_me": "0.052", + "my_balance_change": "-0.044", + "block_height": 0, + "timestamp": 1635834296, + "fee_details": { + "type": "Qrc20", + "coin": "tQTUM", + "miner_fee": "0.004", + "gas_limit": 100000, + "gas_price": 40, + "total_gas_fee": "0.04" + }, + "coin": "tQTUM", + "internal_id": "", + "transaction_type": "RemoveDelegation" + }, + "id": 0 + } + ``` + +export const title = "AtomicDEX Method: Remove Node from Version Stat"; +export const description = "The remove_node_from_version_stat method removes a Node from the local database that tracks which version of MM2 it is running."; + +# remove\_node\_from\_version\_stat + +The `remove_node_from_version_stat` method removes a Node (by name) from the local database which tracks which version of MM2 it is running. The name parameter is an arbitrary identifying string, such as "seed\_alpha" or "dragonhound\_DEV". + +## Arguments + +| Structure | Type | Description | +| --------- | ------ | ----------------------------- | +| name | string | the name assigned to the node | + +#### ๐Ÿ“Œ Examples + +#### Command + + + ```json + { + "mmrpc": "2.0", + "method": "remove_node_from_version_stat", + "userpass": "testpsw", + "params": { + "name": "dragonhound_DEV" + } + } + ``` + + + + #### Response (success) + + ```json + { + "mmrpc": "2.0", + "result": "success", + "id": null + } + ``` + +export const title = "AtomicDEX Method: Start Simple Market Maker Bot"; +export const description = "The AtomicDEX API allows for simple bot trading via the start_simple_market_maker_bot method."; + +# start\_simple\_market\_maker\_bot + +The AtomicDEX API allows for simple bot trading via the `start_simple_market_maker_bot` method. This method takes as input a url to a price service, and configuration parameters of the pair to trade at a defined spread percentage value. It will update orders every 30 seconds (or higher values if defined with the `bot_refresh_rate` parameter). + +Note: If using a custom prices API endpoint, please ensure it conforms to the same schema as the url in the example. + +For convenience, an online [tool for generating configs](https://stats.kmd.io/atomicdex/makerbot_config_form/) is available. + +## Arguments + +| Structure | Type | Description | +| -------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| price\_url | string | Link to a price service API | +| bot\_refresh\_rate | float | Bot loop interval in seconds (optional, 30 sec default) | +| cfg.name | string | The name assigned to this configuration (e.g. the pair being configured) | +| cfg.name.base | string | Ticker of the coin you wish to sell | +| cfg.name.rel | string | Ticker of the coin you wish to buy | +| cfg.name.max | boolean | Set to `true` if you would like to trade your whole balance (optional) | +| cfg.name.max\_volume.percentage | string | Percentage of balance to trade (optional; can not use at same time as `max_volume.usd`; if greater than 1.0 `max=true` is implied) | +| cfg.name.max\_volume.usd | string | Maximum USD trade volume value to trade (optional; can not use at same time as `max_volume.percentage`; if greater than full balance `max=true` is implied) | +| cfg.name.min\_volume.percentage | string | Minimum percentage of balance to accept in trade (optional, can not use at same time as `min_volume.usd`) | +| cfg.name.min\_volume.usd | float | Minimum USD trade volume of trades accepted for order (optional, can not use at same time as `min_volume.percentage`) | +| cfg.name.min\_base\_price | float | Minimum USD price of base coin to accept in trade (optional) | +| cfg.name.min\_rel\_price | float | Minimum USD price of rel coin to accept in trade (optional) | +| cfg.name.min\_pair\_price | float | Minimum USD price of pair (base/rel) to accept in trade (optional) | +| cfg.name.spread\*\* | string | Target price in relation to prices API value | +| cfg.name.base\_confs | integer | number of required blockchain confirmations for base coin atomic swap transaction; default to base coin configuration if not set | +| cfg.name.base\_nota | boolean | whether dPoW notarization is required for base coin atomic swap transaction; default to base coin configuration if not set | +| cfg.name.rel\_confs | integer | number of required blockchain confirmations for rel coin atomic swap transaction; default to rel coin configuration if not set | +| cfg.name.rel\_nota | boolean | whether dPoW notarization is required for rel coin atomic swap transaction; default to base coin configuration if not set | +| cfg.name.enable | boolean | Bot will ignore this config entry if set to false | +| cfg.name.price\_elapsed\_validity | float | Will cancel current orders for this pair and not submit a new order if last price update time has been longer than this value in seconds (optional; defaults to 5 minutes) | +| cfg.name.check\_last\_bidirectional\_trade\_thresh\_hold | boolean | Will readjust the calculated cex price if a precedent trade exists for the pair (or reversed pair), applied via a [VWAP logic](https://www.investopedia.com/terms/v/vwap.asp) (optional; defaults to false) | + +* Percentage values are within the range of 0-1, such that 0.25 = 25% +* For spread, a value of 1.05 equates to 5% over the value returned from the prices API url. +* At least one of the optional fields `max`, `max_volume.usd` or `max_volume.percentage` must be present, or orders will not be placed. + +#### ๐Ÿ“Œ Examples + +As demonstrated below, multiple configs can be included within the same command. It is recommended to not exceed 500-1000 simultaneous orders placed to avoid decreased performance. + +In the example below, the first config lets the bot know we want to: + +* Sell DASH in exchange for KMD +* Use whole of available DASH balance, with minimum trade volume accepted as 25% of your balance +* Sets the sell price at 2.5% over the value returned from the prices API (spread). +* Only accepts values from the prices API that have been updated within the last 30 seconds +* Waits for 3 confirmations and does not wait for a notarisation to progress to the next steps in the atomic swap process +* Checks trade history within the local AtomicDEX API database to never create trades with a sell price that is less than the average trading price. + +The second config tells the bot to: + +* Sell DASH in exchange for DGB +* Trade at most 50% of your DASH balance, with minimum trade volume accepted at least $20 USD. +* Only place an order when the DASH price is $250 USD or more. +* Sets the sell price at 4% over the value returned from the prices API (spread). +* Only accepts values from the prices API that have been updated within the last 60 seconds +* Waits for 1 confirmation and does not wait for a notarisation to progress to the next steps in the atomic swap process +* Ignores your trade history and average trading price, creating/updating orders regardless. + +The third config tells the bot to: + +* Sell DASH in exchange for LTC +* Trade at most $500 USD worth of DASH, with minimum trade volume accepted at least $50 USD. +* Only place an order when the DASH price is $250 USD or more. +* Sets the sell price at 5% over the value returned from the prices API (spread). +* Only accepts values from the prices API that have been updated within the last 60 seconds +* Waits for 1 confirmation and does not wait for a notarisation to progress to the next steps in the atomic swap process +* Ignores your trade history and average trading price, creating/updating orders regardless. + +#### Command + + + ```json + { + "userpass": "testpsw", + "mmrpc": "2.0", + "method": "start_simple_market_maker_bot", + "params": { + "price_url": "https://prices.komodo.earth/api/v2/tickers?expire_at=600", + "bot_refresh_rate": 60, + "cfg": { + "DASH/KMD": { + "base": "DASH", + "rel": "KMD", + "max": true, + "min_volume": { + "percentage": "0.25" + }, + "spread": "1.025", + "base_confs": 3, "base_nota": false, - "rel_confs": 2, - "rel_nota": false - }, - "base_max_volume_aggr": { - "decimal": "133319.023345413", - "rational": [ - [1, [3238477573, 31040]], - [1, [1000000000]] - ], - "fraction": { - "numer": "133319023345413", - "denom": "1000000000" - } - }, - "rel_max_volume_aggr": { - "decimal": "35.2500366381728643576", - "rational": [ - [1, [473921343, 1669176307, 2]], - [1, [2436694016, 291038304]] - ], - "fraction": { - "numer": "44062545797716080447", - "denom": "1250000000000000000" - } - } - } - ], - "base": "DGB", - "bids": [ - { - "coin": "DASH", - "address": { - "address_type": "Transparent", - "address_data": "XcYdfQgeuM5f5V2LNo9g8o8p3rPPbKwwCg" - }, - "price": { - "decimal": "0.0002544075418788651605521516540338523799763700988224165198319218986992534200426899830070024093907274001", - "rational": [ - [1, [1410065408, 2]], - [1, [3765089107, 9151]] - ], - "fraction": { - "numer": "10000000000", - "denom": "39307010814803" - } - }, - "pubkey": "0315d9c51c657ab1be4ae9d3ab6e76a619d3bccfe830d5363fa168424c0d044732", - "uuid": "e9e4feb2-60b4-4184-8294-591687171e6b", - "is_mine": false, - "base_max_volume": { - "decimal": "15449.5309493280527473176", - "rational": [ - [1, [161102659, 3869502237, 1046]], - [1, [2436694016, 291038304]] - ], - "fraction": { - "numer": "19311913686660065934147", - "denom": "1250000000000000000" - } - }, - "base_min_volume": { - "decimal": "0.39307010814803", - "rational": [ - [1, [3765089107, 9151]], - [1, [276447232, 23283]] - ], - "fraction": { - "numer": "39307010814803", - "denom": "100000000000000" - } - }, - "rel_max_volume": { - "decimal": "3.930477192", - "rational": [ - [1, [491309649]], - [1, [125000000]] - ], - "fraction": { - "numer": "491309649", - "denom": "125000000" - } - }, - "rel_min_volume": { - "decimal": "0.0001", - "rational": [ - [1, [1]], - [1, [10000]] - ], - "fraction": { - "numer": "1", - "denom": "10000" - } + "rel_confs": 3, + "rel_nota": false, + "enable": true, + "price_elapsed_validity": 30, + "check_last_bidirectional_trade_thresh_hold": true }, - "conf_settings": { - "base_confs": 7, + "DASH/DGB": { + "base": "DASH", + "rel": "DGB", + "min_volume": { + "usd": "20" + }, + "min_base_price": "250", + "spread": "1.04", + "base_confs": 1, "base_nota": false, - "rel_confs": 2, - "rel_nota": false - }, - "base_max_volume_aggr": { - "decimal": "15449.5309493280527473176", - "rational": [ - [1, [161102659, 3869502237, 1046]], - [1, [2436694016, 291038304]] - ], - "fraction": { - "numer": "19311913686660065934147", - "denom": "1250000000000000000" - } + "rel_confs": 1, + "rel_nota": false, + "enable": true, + "price_elapsed_validity": 60, + "check_last_bidirectional_trade_thresh_hold": false }, - "rel_max_volume_aggr": { - "decimal": "3.930477192", - "rational": [ - [1, [491309649]], - [1, [125000000]] - ], - "fraction": { - "numer": "491309649", - "denom": "125000000" - } - } - } - ], - "net_id": 8762, - "num_asks": 3, - "num_bids": 3, - "rel": "DASH", - "timestamp": 1694183345, - "total_asks_base_vol": { - "decimal": "133319.023345413", - "rational": [ - [1, [3238477573, 31040]], - [1, [1000000000]] - ], - "fraction": { - "numer": "133319023345413", - "denom": "1000000000" - } - }, - "total_asks_rel_vol": { - "decimal": "35.2500366381728643576", - "rational": [ - [1, [473921343, 1669176307, 2]], - [1, [2436694016, 291038304]] - ], - "fraction": { - "numer": "44062545797716080447", - "denom": "1250000000000000000" - } - }, - "total_bids_base_vol": { - "decimal": "59100.6554157135128550633", - "rational": [ - [1, [1422777577, 2274178813, 32038]], - [1, [2313682944, 2328306436]] - ], - "fraction": { - "numer": "591006554157135128550633", - "denom": "10000000000000000000" - } - }, - "total_bids_rel_vol": { - "decimal": "14.814675225", - "rational": [ - [1, [592587009]], - [1, [40000000]] - ], - "fraction": { - "numer": "592587009", - "denom": "40000000" + "DASH/LTC": { + "base": "DASH", + "rel": "LTC", + "max_volume": { + "usd": "500" + }, + "min_volume": { + "usd": "50" + }, + "min_base_price": "250", + "spread": "1.04", + "base_confs": 1, + "base_nota": false, + "rel_confs": 1, + "rel_nota": false, + "enable": true, + "price_elapsed_validity": 60, + "check_last_bidirectional_trade_thresh_hold": false } } }, - "id": 42 + "id": 0 + } + ``` + + +As we have `\"bot_refresh_rate\": 60,` in the above command, our bot loop will update order prices every 60 seconds, as long as the price service returns data that is no more than 30 seconds old (for DASH/KMD) or no more than 60 seconds old (for DASH/DGB). + + + #### Response (success) {{class : 'text-green-500'}} + + ```json + { + "mmrpc": "2.0", + "result": { + "result": "Success" + }, + "id": 0 } ``` - -export const title = "AtomicDEX Method: Recreate Swap Data"; -export const description = "The recreate_swap_data method helps recover lost swap data due to storage errors or hardware failure."; -# recreate\_swap\_data + #### Response (error - bot already started) {{class : 'text-red-500'}} -The `recreate_swap_data` can assist in the event of local stored swap data being lost due to storage errors related to low disk space or hardware failure, and if required, aid with the refunding of failed swaps. + ```json + { + "mmrpc": "2.0", + "error": "The bot is already started", + "error_path": "simple_market_maker", + "error_trace": "simple_market_maker:770]", + "error_type": "AlreadyStarted", + "id": 0 + } + ``` + +export const title = "AtomicDEX Method: Start Version Stat Collection"; +export const description = "The start_version_stat_collection method initiates storing version statistics for nodes previously registered via the add_node_to_version_stat method."; -To source the opposite side of the trade, please [contact the Komodo Support team on Discord](https://discord.com/invite/RRZ8hzc). You will need to provide details about the trade you are trying to recover, such as the coins and amounts being traded, the approximate time of the trade, any known transaction IDs involved in the trade, and if available the UUID of the trade. +# start\_version\_stat\_collection + +The `start_version_stat_collection` method initiates storing version statistics for nodes previously registered via the `add_node_to_version_stat` method. ## Arguments -| Structure | Type | Description | -| --------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- | -| swap | object | Swap data from other side of trade. For example to recreate a Maker's swap data, the input would be the corresponding Taker's swap data | +| Structure | Type | Description | +| --------- | ------- | ------------------------------------------------ | +| interval | integer | polling rate (in seconds) to check node versions | -#### Response +#### ๐Ÿ“Œ Examples -| Structure | Type | Description | -| --------- | ------ | --------------------------------------------------------------------------------------------------------------------------------- | -| result | object | Opposite side's swap data. For example if a Taker's swap data is input, the reponse would be the corresponding Maker's swap data. | +#### Command + + + ```json + { + "mmrpc": "2.0", + "method": "start_version_stat_collection", + "userpass": "testpsw", + "params": { + "interval": 600 + } + } + ``` + + + + #### Response (success) + + ```json + { + "mmrpc": "2.0", + "result": "success", + "id": null + } + ``` + + #### Response (error - invalid peer id unable to parse) + + ```json + { + "mmrpc": "2.0", + "error": "Database error: UNIQUE constraint failed: nodes.peer_id", + "error_path": "lp_stats", + "error_trace": "lp_stats:124]", + "error_type": "DatabaseError", + "error_data": "UNIQUE constraint failed: nodes.peer_id", + "id": null + } + ``` + +export const title = "AtomicDEX Method: Stop Simple Market Maker Bot"; +export const description = "The stop_simple_market_maker_bot method tells the bot to finish placing orders at the end of the current loop 30 seconds minimum and 30 seconds by default."; + +# stop\_simple\_market\_maker\_bot + +The `stop_simple_market_maker_bot` method tells the bot to finish placing orders at the end of the current loop (30 seconds minimum & 30 seconds by default). This method takes as input a url to a price service, and configuration parameters of the pairs to trade at a defined spread percentage value. + +At the end of the final loop, orders placed by the bot will be cancelled. Users should wait until the loop ends before exiting the AtomicDEX API, otherwise orders will not cancel, and will reappear on the orderbook next time AtomicDEX API starts. + +## Arguments + +| Structure | Type | Description | +| --------- | ---- | ----------- | +| (none ) | | | #### ๐Ÿ“Œ Examples #### Command - + ```json { "userpass": "testpsw", "mmrpc": "2.0", - "method": "recreate_swap_data", - "params": { - "swap": { - "type": "Taker", - "uuid": "f87fa9ce-0820-4675-b85d-db18c7bc9fb4", - "my_order_uuid": "f87fa9ce-0820-4675-b85d-db18c7bc9fb4", - "events": [ - { - "timestamp": 1638984440546, - "event": { - "type": "Started", - "data": { - "taker_coin": "MARTY", - "maker_coin": "DOC", - "maker": "15d9c51c657ab1be4ae9d3ab6e76a619d3bccfe830d5363fa168424c0d044732", - "my_persistent_pub": "03b1e544ce2d860219bc91314b5483421a553a7b33044659eff0be9214ed58addd", - "lock_duration": 7800, - "maker_amount": "0.9090909090909090909090909090909090909090909090909090909090909090909090909090909090909090909090909091", - "taker_amount": "1", - "maker_payment_confirmations": 1, - "maker_payment_requires_nota": false, - "taker_payment_confirmations": 1, - "taker_payment_requires_nota": false, - "taker_payment_lock": 1638992240, - "uuid": "f87fa9ce-0820-4675-b85d-db18c7bc9fb4", - "started_at": 1638984440, - "maker_payment_wait": 1638987560, - "maker_coin_start_block": 1207822, - "taker_coin_start_block": 1222573, - "fee_to_send_taker_fee": { - "coin": "MARTY", - "amount": "0.00001", - "paid_from_trading_vol": false - }, - "taker_payment_trade_fee": { - "coin": "MARTY", - "amount": "0.00001", - "paid_from_trading_vol": false - }, - "maker_payment_spend_trade_fee": { - "coin": "DOC", - "amount": "0.00001", - "paid_from_trading_vol": true - } - } - } - }, - { - "timestamp": 1638984456603, - "event": { - "type": "Negotiated", - "data": { - "maker_payment_locktime": 1639000040, - "maker_pubkey": "0315d9c51c657ab1be4ae9d3ab6e76a619d3bccfe830d5363fa168424c0d044732", - "secret_hash": "4da9e7080175e8e10842e0e161b33cd298cab30b", - "maker_coin_swap_contract_addr": null, - "taker_coin_swap_contract_addr": null - } - } - }, - { - "timestamp": 1638984456814, - "event": { - "type": "TakerFeeSent", - "data": { - "tx_hex": "0400008085202f89016383e8aced2256378bb126a1ca1a41e2f344d9295f65b3ea4b99055c5eb4a6cb000000006a47304402201c7e661e0dbeb9b3eb6e4e9e3194010e5772227017772b2e48c1b8d48ed3b21f02201c2eda64e74455fa1878a5c221f25d22fe626abd0078a26a9fc0f829e0921639012103b1e544ce2d860219bc91314b5483421a553a7b33044659eff0be9214ed58adddffffffff02bcf60100000000001976a914ca1e04745e8ca0c60d8c5881531d51bec470743f88ac74c3e90b000000001976a91483762a373935ca241d557dfce89171d582b486de88ac08ebb061000000000000000000000000000000", - "tx_hash": "fcb49167c79e8e014143643b94878866f7e80b26c5a5dcf693010543da70b5bc" - } - } - }, - { - "timestamp": 1638984457822, - "event": { - "type": "MakerPaymentReceived", - "data": { - "tx_hex": "0400008085202f8901c41fdf6b9d8aea4b472f83e4fa0d99dfafc245e897d681fd2ca7df30707fbf48020000006b483045022100c7b294bd46cbf3b13530879a43c5cf67414047266d8b64c3c7263b5e75b989ba02201974f38d688b184bc44e628806c6ab2ac9092f394729d0ce838f14e1e76117c001210315d9c51c657ab1be4ae9d3ab6e76a619d3bccfe830d5363fa168424c0d044732ffffffff03a2296b050000000017a91491c45f69e1760c12a1f90fb2a811f6dfde35cc35870000000000000000166a144da9e7080175e8e10842e0e161b33cd298cab30bac503d64000000001976a9141462c3dd3f936d595c9af55978003b27c250441f88ac09ebb061000000000000000000000000000000", - "tx_hash": "6287e0d30951cd859bfb837eb1e5409f7596e75ffeb2e61fd6df1843bfd0203d" - } - } - }, - { - "timestamp": 1638984457826, - "event": { - "type": "MakerPaymentWaitConfirmStarted" - } - }, - { - "timestamp": 1638984503611, - "event": { - "type": "MakerPaymentWaitConfirmFailed", - "data": { - "error": "An error" - } - } - }, - { - "timestamp": 1638984503615, - "event": { - "type": "Finished" - } - } - ], - "maker_amount": "0.9090909090909090909090909090909090909090909090909090909090909090909090909090909090909090909090909091", - "maker_coin": "DOC", - "taker_amount": "1", - "taker_coin": "MARTY", - "gui": "atomicDEX 0.5.1 iOS", - "mm_version": "1b065636a", - "success_events": [ - "Started", - "Negotiated", - "TakerFeeSent", - "MakerPaymentReceived", - "MakerPaymentWaitConfirmStarted", - "MakerPaymentValidatedAndConfirmed", - "TakerPaymentSent", - "TakerPaymentSpent", - "MakerPaymentSpent", - "Finished" - ], - "error_events": [ - "StartFailed", - "NegotiateFailed", - "TakerFeeSendFailed", - "MakerPaymentValidateFailed", - "MakerPaymentWaitConfirmFailed", - "TakerPaymentTransactionFailed", - "TakerPaymentWaitConfirmFailed", - "TakerPaymentDataSendFailed", - "TakerPaymentWaitForSpendFailed", - "MakerPaymentSpendFailed", - "TakerPaymentWaitRefundStarted", - "TakerPaymentRefunded", - "TakerPaymentRefundFailed" - ] - } + "method": "stop_simple_market_maker_bot", + "params": {}, + "id": 0 + } + ``` + + + + #### Response (success) {{class : 'text-green-500'}} + + ```json + { + "mmrpc": "2.0", + "result": { + "result": "Success" }, "id": 0 } ``` + + #### Response (error - bot already stopped) {{class : 'text-red-500'}} + + ```json + { + "mmrpc": "2.0", + "error": "The bot is already stopped", + "error_path": "simple_market_maker", + "error_trace": "simple_market_maker:813]", + "error_type": "AlreadyStopped", + "id": 0 + } + ``` + +export const title = "AtomicDEX Method: Stop Version Stat Collection"; +export const description = "The stop_version_stat_collection method stops the collection of version stats at the end of the current loop interval."; + +# stop\_version\_stat\_collection + +The `stop_version_stat_collection` method stops the collection of version stats at the end of the current loop interval. + +#### Arguments + +| Structure | Type | Description | +| --------- | ---- | ----------- | +| (none) | | | + +#### Response + +| Structure | Type | Description | +| --------- | ------ | ---------------- | +| result | string | success or error | + +#### ๐Ÿ“Œ Examples + +#### Command + + + ```json + { + "mmrpc": "2.0", + "method": "stop_version_stat_collection", + "userpass": "testpsw", + "params": {} + } + ``` @@ -41520,553 +42795,773 @@ To source the opposite side of the trade, please [contact the Komodo Support tea ```json { "mmrpc": "2.0", - "result": { - "swap": { - "type": "Maker", - "uuid": "f87fa9ce-0820-4675-b85d-db18c7bc9fb4", - "my_order_uuid": "f87fa9ce-0820-4675-b85d-db18c7bc9fb4", - "events": [ - { - "timestamp": 1638984440546, - "event": { - "type": "Started", - "data": { - "taker_coin": "MARTY", - "maker_coin": "DOC", - "taker": "b1e544ce2d860219bc91314b5483421a553a7b33044659eff0be9214ed58addd", - "secret": "0000000000000000000000000000000000000000000000000000000000000000", - "secret_hash": "4da9e7080175e8e10842e0e161b33cd298cab30b", - "my_persistent_pub": "0315d9c51c657ab1be4ae9d3ab6e76a619d3bccfe830d5363fa168424c0d044732", - "lock_duration": 7800, - "maker_amount": "0.9090909090909090909090909090909090909090909090909090909090909090909090909090909090909090909090909091", - "taker_amount": "1", - "maker_payment_confirmations": 1, - "maker_payment_requires_nota": false, - "taker_payment_confirmations": 1, - "taker_payment_requires_nota": false, - "maker_payment_lock": 1639000040, - "uuid": "f87fa9ce-0820-4675-b85d-db18c7bc9fb4", - "started_at": 1638984440, - "maker_coin_start_block": 1207822, - "taker_coin_start_block": 1222573, - "maker_payment_trade_fee": null, - "taker_payment_spend_trade_fee": null - } - } - }, - { - "timestamp": 1638984456603, - "event": { - "type": "Negotiated", - "data": { - "taker_payment_locktime": 1638992240, - "taker_pubkey": "03b1e544ce2d860219bc91314b5483421a553a7b33044659eff0be9214ed58addd", - "maker_coin_swap_contract_addr": null, - "taker_coin_swap_contract_addr": null - } - } - }, - { - "timestamp": 1638984457822, - "event": { - "type": "TakerFeeValidated", - "data": { - "tx_hex": "0400008085202f89016383e8aced2256378bb126a1ca1a41e2f344d9295f65b3ea4b99055c5eb4a6cb000000006a47304402201c7e661e0dbeb9b3eb6e4e9e3194010e5772227017772b2e48c1b8d48ed3b21f02201c2eda64e74455fa1878a5c221f25d22fe626abd0078a26a9fc0f829e0921639012103b1e544ce2d860219bc91314b5483421a553a7b33044659eff0be9214ed58adddffffffff02bcf60100000000001976a914ca1e04745e8ca0c60d8c5881531d51bec470743f88ac74c3e90b000000001976a91483762a373935ca241d557dfce89171d582b486de88ac08ebb061000000000000000000000000000000", - "tx_hash": "fcb49167c79e8e014143643b94878866f7e80b26c5a5dcf693010543da70b5bc" - } - } - }, - { - "timestamp": 1638984457822, - "event": { - "type": "MakerPaymentSent", - "data": { - "tx_hex": "0400008085202f8901c41fdf6b9d8aea4b472f83e4fa0d99dfafc245e897d681fd2ca7df30707fbf48020000006b483045022100c7b294bd46cbf3b13530879a43c5cf67414047266d8b64c3c7263b5e75b989ba02201974f38d688b184bc44e628806c6ab2ac9092f394729d0ce838f14e1e76117c001210315d9c51c657ab1be4ae9d3ab6e76a619d3bccfe830d5363fa168424c0d044732ffffffff03a2296b050000000017a91491c45f69e1760c12a1f90fb2a811f6dfde35cc35870000000000000000166a144da9e7080175e8e10842e0e161b33cd298cab30bac503d64000000001976a9141462c3dd3f936d595c9af55978003b27c250441f88ac09ebb061000000000000000000000000000000", - "tx_hash": "6287e0d30951cd859bfb837eb1e5409f7596e75ffeb2e61fd6df1843bfd0203d" - } - } - }, - { - "timestamp": 1638984503611, - "event": { - "type": "TakerPaymentValidateFailed", - "data": { - "error": "Origin Taker error event: MakerPaymentWaitConfirmFailed(SwapError { error: \"An error\" })" - } - } - }, - { - "timestamp": 1638984503611, - "event": { - "type": "MakerPaymentWaitRefundStarted", - "data": { - "wait_until": 1639003740 - } - } - } - ], - "maker_amount": "0.9090909090909090909090909090909090909090909090909090909090909090909090909090909090909090909090909091", - "maker_coin": "DOC", - "taker_amount": "1", - "taker_coin": "MARTY", - "gui": "nogui", - "mm_version": "", - "success_events": [ - "Started", - "Negotiated", - "TakerFeeValidated", - "MakerPaymentSent", - "TakerPaymentReceived", - "TakerPaymentWaitConfirmStarted", - "TakerPaymentValidatedAndConfirmed", - "TakerPaymentSpent", - "TakerPaymentSpendConfirmStarted", - "TakerPaymentSpendConfirmed", - "Finished" - ], - "error_events": [ - "StartFailed", - "NegotiateFailed", - "TakerFeeValidateFailed", - "MakerPaymentTransactionFailed", - "MakerPaymentDataSendFailed", - "MakerPaymentWaitConfirmFailed", - "TakerPaymentValidateFailed", - "TakerPaymentWaitConfirmFailed", - "TakerPaymentSpendFailed", - "TakerPaymentSpendConfirmFailed", - "MakerPaymentWaitRefundStarted", - "MakerPaymentRefunded", - "MakerPaymentRefundFailed" - ] - } - }, + "result": "success", "id": null } ``` -export const title = "AtomicDEX Method: Remove Delegation"; -export const description = - "The remove_delegation method stops your node's staking of a compatible coin."; -# remove\_delegation + + #### Response (error - stats collection not running) + + ```json + { + "mmrpc": "2.0", + "error": "start_version_stat_collection is not running", + "error_path": "lp_stats", + "error_trace": "lp_stats:395]", + "error_type": "NotRunning", + "id": null + } + ``` + +export const title = "AtomicDEX Method: Telegram Alerts for MM Bot"; +export const description = "The AtomicDEX API Market Maker bot can be configured to send status update alerts via Telegram."; + +# Telegram Alerts for Market Maker Bot + +The AtomicDEX API Market Maker bot can be configured to send status update alerts via [Telegram!](https://telegram.org/) + +To set this up, you can add some additional parameters to your MM2.json as shown in the example below + +```json +{ + "gui": "MarketMakerBot", + "netid": 8762, + "rpc_password": "YOUR_PASSWORD", + "passphrase": "YOUR SEED PHRASE", + "dbdir": "/path/to/your/atomicdex/DB", + "message_service_cfg": { + "telegram": { + "api_key": "YOUR:TELEGRAM_API_TOKEN", + "chat_registry": { + "default": "YOUR_TELEGRAM_CHAT_ID", + "maker_bot": "YOUR_TELEGRAM_CHAT_ID", + "swap_events": "YOUR_TELEGRAM_CHAT_ID" + } + } + } +} +``` + +The extra fields required are: + +| Parameter | Type | Description | +| --------------------------- | ------ | ------------------------ | +| api\_key | string | A Telegram bot API token | +| chat\_registry.default | string | A Telegram Chat ID | +| chat\_registry.maker\_bot | string | A Telegram Chat ID | +| chat\_registry.swap\_events | string | A Telegram Chat ID | + +You can use the same Telegram chat ID for all three `chat_registry` subfields, or sent your alerts to a different chat ID if you want to separate the alerts by type. + +To get a Telegram bot API token, you need to [have chat with the BotFather](https://sean-bradley.medium.com/get-telegram-chat-id-80b575520659) + +To get a Telegram chat ID, check out [this guide](https://sean-bradley.medium.com/get-telegram-chat-id-80b575520659) +export const title = "AtomicDEX Method: Trade Preimage"; +export const description = "The trade_preimage method returns the approximate fee amounts that are paid per the whole swap."; + +# trade\_preimage + +The `trade_preimage` method returns the approximate fee amounts that are paid per the whole swap. +Depending on the parameters, the function returns different results: + +* If the `swap_method` is `buy` or `sell`, then the result will include the `taker_fee` and the `fee_to_send_taker_fee`. + The `taker_fee` amount is paid from the `base` coin balance if the `swap_method` is `sell`, else it is paid from the `rel` coin balance; +* If the `max` field is true, then the result will include the `volume`. + + + This method can be used instead of **max\_taker\_vol**, if the `max` field is true and the `swap_method` is `buy` or `sell`. + Use the resulting `volume` as an argument of the `buy` or `sell` requests. + + + + Use the `trade_preimage` request with `max = true` and `swap_method = "setprice"` arguments to approximate the fee amounts **only**. Do not use the resulting `volume` as an argument of the `setprice`. + + +## Arguments + +| Structure | Type | Description | +| ------------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| base | string | the base currency of the request | +| rel | string | the rel currency of the request | +| swap\_method | string | the name of the method whose preimage is requested. Possible values: `buy`, `sell`, `setprice` | +| price | numeric string or rational | the price in `rel` the user is willing to pay per one unit of the `base` coin | +| volume | numeric string or rational (optional) | the amount the user is willing to trade; ignored if `max = true` **and** `swap_method = setprice`, otherwise, it must be set | +| max | bool (optional) | whether to return the maximum available volume for `setprice` method; must not be set or `false` if `swap_method` is `buy` or `sell` | + +### Result + +| Structure | Type | Description | +| ------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| base\_coin\_fee | object | A standard [ExtendedFeeInfo](/atomicdex/api/common_structures/#extended-fee-info) object. The approximate miner fee is paid per the whole swap concerning the `base` coin | +| rel\_coin\_fee | object | A standard [ExtendedFeeInfo](/atomicdex/api/common_structures/#extended-fee-info) object. The approximate miner fee is paid per the whole swap concerning the `rel` coin | +| volume | string (numeric) | Optional. The max available volume that can be traded (in decimal representation); empty if the `max` argument is missing or false | +| volume\_rat | rational | Optional. The max available volume that can be traded represented as a standard [RationalValue](/atomicdex/api/common_structures/#rational-value) object.; empty if the `max` argument is missing or false | +| volume\_fraction | fraction | Optional. The max available volume that can be traded represented as a standard [fractionalValue](/atomicdex/api/common_structures/#fractional-value) object.; empty if the `max` argument is missing or false | +| taker\_fee | object | A standard [ExtendedFeeInfo](/atomicdex/api/common_structures/#extended-fee-info) object. The dex fee to be paid by Taker; empty if `swap_method` is `setprice` | +| fee\_to\_send\_taker\_fee | object | A standard [ExtendedFeeInfo](/atomicdex/api/common_structures/#extended-fee-info) object. The approximate miner fee is paid to send the dex fee; empty if `swap_method` is `setprice` | +| total\_fees | array of objects | A standard [TotalFeeInfo](/atomicdex/api/common_structures/#total-fee-info) object. Each element is a sum of fees required to be paid from user's balance of corresponding `ExtendedFeeInfo.coin`; the elements are unique by coin | + +### โš  Error types -The `remove_delegation` method stops your node's staking of a compatible coin. Currently QTUM and tQTUM (test tokens avalable at `https://testnet-faucet.qtum.info/`) have been integrated, but this functionality will be expanded to more coins in future. +#### NotSufficientBalance -Note: After running `remove_delegation`, you will need to broadcast the returned hex via [`send_raw_transaction`](/atomicdex/api/legacy/send_raw_transaction/) to complete the process. +The `available` balance of the `coin` is not sufficient to start the swap. -## Arguments +| Structure | Type | Description | +| ----------------- | -------------------------- | ----------------------------------------------------------------------------------------- | +| coin | string | the name of the coin which balance is not sufficient | +| available | string (numeric) | the balance available for swap, including the amount locked by other swaps | +| required | string (numeric) | the amount required to start the swap. This amount is necessary but may not be sufficient | +| locked\_by\_swaps | string (numeric, optional) | the amount locked by other swaps | -| Structure | Type | Description | -| --------- | ------ | --------------------- | -| coin | string | the coin being staked | +#### NotSufficientBaseCoinBalance -#### ๐Ÿ“Œ Examples +The available balance of the base `coin` is not sufficient to pay transaction fees. -#### Command +For example, ERC20 fees are paid by ETH (gas), and this error type is returned if the ETH coin balance is not sufficient to start the swap. - - ```json - { - "userpass": "testpsw", - "mmrpc": "2.0", - "method": "remove_delegation", - "params": { - "coin": "tQTUM" - }, - "id": 0 - } - ``` - +| Structure | Type | Description | +| ----------------- | -------------------------- | ----------------------------------------------------------------------------------------- | +| coin | string | the name of the base coin which balance is not sufficient | +| available | string (numeric) | the balance available for swap, including the amount locked by other swaps | +| required | string (numeric) | the amount required to start the swap. This amount is necessary but may not be sufficient | +| locked\_by\_swaps | string (numeric, optional) | the amount is locked by other swaps | - - #### Response (success) +#### VolumeTooLow - ```json - { - "mmrpc": "2.0", - "result": { - "tx_hex": "01000000015c7f32b1b3396ce1bed4f6c161bcc3a5bf5c58e4338c66a24c9de1deffc5b94e000000006a47304402203fcdf1e48f6e43fd718b4aab79c56a7ff81b12304339ddf6d871a3f26f217a7502200c22fa8e2bcc33d16f4bf62feb71f637acbefdd34135314e6aa526e6655cba73012102641b541e35bc915e375c8038f1099a977bc6736aa7265e9f65b7270b70d34366ffffffff020000000000000000225403a086010128043d666e8b140000000000000000000000000000000000000086c280584f00000000001976a914c36ac1020b1eae632079692e7bef350d279489c988acb8d98061", - "tx_hash": "3564859a7ff902e8d65387c44f6049943582e0b9e29161bf1075a00097e535ae", - "from": ["qbNeoqCbBu4hySDUzgmo666faYH3qgaeKz"], - "to": ["qbNeoqCbBu4hySDUzgmo666faYH3qgaeKz"], - "total_amount": "0.096", - "spent_by_me": "0.096", - "received_by_me": "0.052", - "my_balance_change": "-0.044", - "block_height": 0, - "timestamp": 1635834296, - "fee_details": { - "type": "Qrc20", - "coin": "tQTUM", - "miner_fee": "0.004", - "gas_limit": 100000, - "gas_price": 40, - "total_gas_fee": "0.04" - }, - "coin": "tQTUM", - "internal_id": "", - "transaction_type": "RemoveDelegation" - }, - "id": 0 - } - ``` - -export const title = "AtomicDEX Method: Remove Node from Version Stat"; -export const description = "The remove_node_from_version_stat method removes a Node from the local database that tracks which version of MM2 it is running."; +The specified `volume` is too low. Required at least `threshold`. -# remove\_node\_from\_version\_stat + + If the `coin` field returned in Response is the same as the `rel` argument in Request, then the base volume threshold can be calculated as follows: + `base_coin_threshold = rel_vol_threshold / price` + -The `remove_node_from_version_stat` method removes a Node (by name) from the local database which tracks which version of MM2 it is running. The name parameter is an arbitrary identifying string, such as "seed\_alpha" or "dragonhound\_DEV". +| Structure | Type | Description | +| --------- | ---------------- | -------------------------------------------------- | +| coin | string | either `base` or `rel` coin specified in Request | +| volume | string (numeric) | the amount the user was willing to trade in `coin` | +| threshold | string (numeric) | the `volume` has not to be less than this amount | -## Arguments +#### NoSuchCoin -| Structure | Type | Description | -| --------- | ------ | ----------------------------- | -| name | string | the name assigned to the node | +The specified coin was not found or is not activated yet. -#### ๐Ÿ“Œ Examples +| Structure | Type | Description | +| --------- | ------ | ------------------------------------------------ | +| coin | string | either `base` or `rel` coin specified in Request | -#### Command +#### CoinIsWalletOnly - +The specified coin is wallet only and cannot be participated in the swap. + +| Structure | Type | Description | +| --------- | ------ | ------------------------------------------------ | +| coin | string | either `base` or `rel` coin specified in Request | + +#### BaseEqualRel + +The coin is wallet only and cannot be participated in the swap. + +| Structure | Type | Description | +| --------- | ---- | ----------- | +| (none) | | | + +#### InvalidParam + +Incorrect use of the `param` parameter in Request. + +| Structure | Type | Description | +| --------- | ------ | ------------------------------------------------ | +| param | string | the name of the parameter in Request | +| reason | string | the reason why the parameter is used incorrectly | + +#### PriceTooLow + +The specified `price` is too low. + +| Structure | Type | Description | +| --------- | ---------------- | ---------------------------------------------------------------------------------- | +| price | string (numeric) | the price in `rel` the user was willing to receive per one unit of the `base` coin | +| threshold | string (numeric) | the `price` has not to be less than this amount | + +#### Transport + +The request was failed due to a network error. + +| Structure | Type | Description | +| --------- | ------ | ------------------------------- | +| (none) | string | the transport error description | + +#### InternalError + +The request was failed due to a AtomicDEX API internal error. + +| Structure | Type | Description | +| --------- | ------ | ------------------------------ | +| (none) | string | the internal error description | + +### ๐Ÿ“Œ Examples + +#### Command (setprice) + + ```json { "mmrpc": "2.0", - "method": "remove_node_from_version_stat", "userpass": "testpsw", + "method": "trade_preimage", "params": { - "name": "dragonhound_DEV" - } + "base": "BTC", + "rel": "DOC", + "price": "1", + "volume": "0.1", + "swap_method": "setprice" + }, + "id": 0 } ``` - - #### Response (success) +#### Response + +```json +{ + "mmrpc": "2.0", + "result": { + "base_coin_fee": { + "coin": "KMD", + "amount": "0.00001", + "amount_fraction": { + "numer": "1", + "denom": "100000" + }, + "amount_rat": [ + [1, [1]], + [1, [100000]] + ], + "paid_from_trading_vol": false + }, + "rel_coin_fee": { + "coin": "DGB", + "amount": "0.00030782", + "amount_fraction": { + "numer": "15391", + "denom": "50000000" + }, + "amount_rat": [ + [1, [15391]], + [1, [50000000]] + ], + "paid_from_trading_vol": true + }, + "volume": "1138.46868712", + "volume_fraction": { + "numer": "14230858589", + "denom": "12500000" + }, + "volume_rat": [ + [1, [1345956701, 3]], + [1, [12500000]] + ], + "total_fees": [ + { + "coin": "KMD", + "amount": "0.00001", + "amount_fraction": { + "numer": "1", + "denom": "100000" + }, + "amount_rat": [ + [1, [1]], + [1, [100000]] + ], + "required_balance": "0.00001", + "required_balance_fraction": { + "numer": "1", + "denom": "100000" + }, + "required_balance_rat": [ + [1, [1]], + [1, [100000]] + ] + }, + { + "coin": "DGB", + "amount": "0.00030782", + "amount_fraction": { + "numer": "15391", + "denom": "50000000" + }, + "amount_rat": [ + [1, [15391]], + [1, [50000000]] + ], + "required_balance": "0", + "required_balance_fraction": { + "numer": "0", + "denom": "1" + }, + "required_balance_rat": [ + [0, []], + [1, [1]] + ] + } + ] + }, + "id": 0 +} +``` + +#### Command (buy) + ```json { "mmrpc": "2.0", - "result": "success", - "id": null - } - ``` - -export const title = "AtomicDEX Method: Start Simple Market Maker Bot"; -export const description = "The AtomicDEX API allows for simple bot trading via the start_simple_market_maker_bot method."; - -# start\_simple\_market\_maker\_bot - -The AtomicDEX API allows for simple bot trading via the `start_simple_market_maker_bot` method. This method takes as input a url to a price service, and configuration parameters of the pair to trade at a defined spread percentage value. It will update orders every 30 seconds (or higher values if defined with the `bot_refresh_rate` parameter). - -Note: If using a custom prices API endpoint, please ensure it conforms to the same schema as the url in the example. - -For convenience, an online [tool for generating configs](https://stats.kmd.io/atomicdex/makerbot_config_form/) is available. - -## Arguments - -| Structure | Type | Description | -| -------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| price\_url | string | Link to a price service API | -| bot\_refresh\_rate | float | Bot loop interval in seconds (optional, 30 sec default) | -| cfg.name | string | The name assigned to this configuration (e.g. the pair being configured) | -| cfg.name.base | string | Ticker of the coin you wish to sell | -| cfg.name.rel | string | Ticker of the coin you wish to buy | -| cfg.name.max | boolean | Set to `true` if you would like to trade your whole balance (optional) | -| cfg.name.max\_volume.percentage | string | Percentage of balance to trade (optional; can not use at same time as `max_volume.usd`; if greater than 1.0 `max=true` is implied) | -| cfg.name.max\_volume.usd | string | Maximum USD trade volume value to trade (optional; can not use at same time as `max_volume.percentage`; if greater than full balance `max=true` is implied) | -| cfg.name.min\_volume.percentage | string | Minimum percentage of balance to accept in trade (optional, can not use at same time as `min_volume.usd`) | -| cfg.name.min\_volume.usd | float | Minimum USD trade volume of trades accepted for order (optional, can not use at same time as `min_volume.percentage`) | -| cfg.name.min\_base\_price | float | Minimum USD price of base coin to accept in trade (optional) | -| cfg.name.min\_rel\_price | float | Minimum USD price of rel coin to accept in trade (optional) | -| cfg.name.min\_pair\_price | float | Minimum USD price of pair (base/rel) to accept in trade (optional) | -| cfg.name.spread\*\* | string | Target price in relation to prices API value | -| cfg.name.base\_confs | integer | number of required blockchain confirmations for base coin atomic swap transaction; default to base coin configuration if not set | -| cfg.name.base\_nota | boolean | whether dPoW notarization is required for base coin atomic swap transaction; default to base coin configuration if not set | -| cfg.name.rel\_confs | integer | number of required blockchain confirmations for rel coin atomic swap transaction; default to rel coin configuration if not set | -| cfg.name.rel\_nota | boolean | whether dPoW notarization is required for rel coin atomic swap transaction; default to base coin configuration if not set | -| cfg.name.enable | boolean | Bot will ignore this config entry if set to false | -| cfg.name.price\_elapsed\_validity | float | Will cancel current orders for this pair and not submit a new order if last price update time has been longer than this value in seconds (optional; defaults to 5 minutes) | -| cfg.name.check\_last\_bidirectional\_trade\_thresh\_hold | boolean | Will readjust the calculated cex price if a precedent trade exists for the pair (or reversed pair), applied via a [VWAP logic](https://www.investopedia.com/terms/v/vwap.asp) (optional; defaults to false) | - -* Percentage values are within the range of 0-1, such that 0.25 = 25% -* For spread, a value of 1.05 equates to 5% over the value returned from the prices API url. -* At least one of the optional fields `max`, `max_volume.usd` or `max_volume.percentage` must be present, or orders will not be placed. - -#### ๐Ÿ“Œ Examples - -As demonstrated below, multiple configs can be included within the same command. It is recommended to not exceed 500-1000 simultaneous orders placed to avoid decreased performance. - -In the example below, the first config lets the bot know we want to: - -* Sell DASH in exchange for KMD -* Use whole of available DASH balance, with minimum trade volume accepted as 25% of your balance -* Sets the sell price at 2.5% over the value returned from the prices API (spread). -* Only accepts values from the prices API that have been updated within the last 30 seconds -* Waits for 3 confirmations and does not wait for a notarisation to progress to the next steps in the atomic swap process -* Checks trade history within the local AtomicDEX API database to never create trades with a sell price that is less than the average trading price. - -The second config tells the bot to: - -* Sell DASH in exchange for DGB -* Trade at most 50% of your DASH balance, with minimum trade volume accepted at least $20 USD. -* Only place an order when the DASH price is $250 USD or more. -* Sets the sell price at 4% over the value returned from the prices API (spread). -* Only accepts values from the prices API that have been updated within the last 60 seconds -* Waits for 1 confirmation and does not wait for a notarisation to progress to the next steps in the atomic swap process -* Ignores your trade history and average trading price, creating/updating orders regardless. - -The third config tells the bot to: - -* Sell DASH in exchange for LTC -* Trade at most $500 USD worth of DASH, with minimum trade volume accepted at least $50 USD. -* Only place an order when the DASH price is $250 USD or more. -* Sets the sell price at 5% over the value returned from the prices API (spread). -* Only accepts values from the prices API that have been updated within the last 60 seconds -* Waits for 1 confirmation and does not wait for a notarisation to progress to the next steps in the atomic swap process -* Ignores your trade history and average trading price, creating/updating orders regardless. - -#### Command - - - ```json - { "userpass": "testpsw", - "mmrpc": "2.0", - "method": "start_simple_market_maker_bot", + "method": "trade_preimage", "params": { - "price_url": "https://prices.komodo.earth/api/v2/tickers?expire_at=600", - "bot_refresh_rate": 60, - "cfg": { - "DASH/KMD": { - "base": "DASH", - "rel": "KMD", - "max": true, - "min_volume": { - "percentage": "0.25" - }, - "spread": "1.025", - "base_confs": 3, - "base_nota": false, - "rel_confs": 3, - "rel_nota": false, - "enable": true, - "price_elapsed_validity": 30, - "check_last_bidirectional_trade_thresh_hold": true - }, - "DASH/DGB": { - "base": "DASH", - "rel": "DGB", - "min_volume": { - "usd": "20" - }, - "min_base_price": "250", - "spread": "1.04", - "base_confs": 1, - "base_nota": false, - "rel_confs": 1, - "rel_nota": false, - "enable": true, - "price_elapsed_validity": 60, - "check_last_bidirectional_trade_thresh_hold": false - }, - "DASH/LTC": { - "base": "DASH", - "rel": "LTC", - "max_volume": { - "usd": "500" - }, - "min_volume": { - "usd": "50" - }, - "min_base_price": "250", - "spread": "1.04", - "base_confs": 1, - "base_nota": false, - "rel_confs": 1, - "rel_nota": false, - "enable": true, - "price_elapsed_validity": 60, - "check_last_bidirectional_trade_thresh_hold": false - } - } + "base": "BTC", + "rel": "DOC", + "price": "1", + "volume": "0.1", + "swap_method": "buy" }, "id": 0 } ``` -As we have `\"bot_refresh_rate\": 60,` in the above command, our bot loop will update order prices every 60 seconds, as long as the price service returns data that is no more than 30 seconds old (for DASH/KMD) or no more than 60 seconds old (for DASH/DGB). +#### Response + +```json +{ + "mmrpc": "2.0", + "result": { + "base_coin_fee": { + "amount": "0.00042049", + "amount_fraction": { + "denom": "100000000", + "numer": "42049" + }, + "amount_rat": [ + [1, [42049]], + [1, [100000000]] + ], + "coin": "BTC", + "paid_from_trading_vol": true + }, + "rel_coin_fee": { + "amount": "0.0001", + "amount_fraction": { + "denom": "10000", + "numer": "1" + }, + "amount_rat": [ + [1, [1]], + [1, [10000]] + ], + "coin": "DOC", + "paid_from_trading_vol": false + }, + "taker_fee": { + "amount": "0.00012870012870012872", + "amount_fraction": { + "denom": "7770", + "numer": "1" + }, + "amount_rat": [ + [1, [1]], + [1, [7770]] + ], + "coin": "DOC", + "paid_from_trading_vol": false + }, + "fee_to_send_taker_fee": { + "amount": "0.0001", + "amount_fraction": { + "denom": "10000", + "numer": "1" + }, + "amount_rat": [ + [1, [1]], + [1, [10000]] + ], + "coin": "DOC", + "paid_from_trading_vol": false + }, + "total_fees": [ + { + "coin": "DOC", + "amount": "0.001307001287001287001287001287001287001287001287001287001287001287001287001287001287001287001287001287", + "amount_fraction": { + "numer": "50777", + "denom": "38850000" + }, + "amount_rat": [ + [1, [50777]], + [1, [38850000]] + ], + "required_balance": "0.001307001287001287001287001287001287001287001287001287001287001287001287001287001287001287001287001287", + "required_balance_fraction": { + "numer": "50777", + "denom": "38850000" + }, + "required_balance_rat": [ + [1, [50777]], + [1, [38850000]] + ] + }, + { + "coin": "tBTC", + "amount": "0.00042049", + "amount_fraction": { + "denom": "100000000", + "numer": "42049" + }, + "amount_rat": [ + [1, [42049]], + [1, [100000000]] + ], + "required_balance": "0", + "required_balance_fraction": { + "numer": "0", + "denom": "1" + }, + "required_balance_rat": [ + [0, []], + [1, [1]] + ] + } + ] + }, + "id": 0 +} +``` - - #### Response (success) {{class : 'text-green-500'}} +#### Command (sell, max) + ```json { "mmrpc": "2.0", - "result": { - "result": "Success" + "userpass": "testpsw", + "method": "trade_preimage", + "params": { + "base": "BTC", + "rel": "DOC", + "price": "1", + "volume": "2.21363478", + "swap_method": "sell" }, "id": 0 } ``` + - #### Response (error - bot already started) {{class : 'text-red-500'}} - - ```json - { - "mmrpc": "2.0", - "error": "The bot is already started", - "error_path": "simple_market_maker", - "error_trace": "simple_market_maker:770]", - "error_type": "AlreadyStarted", - "id": 0 - } - ``` - -export const title = "AtomicDEX Method: Start Version Stat Collection"; -export const description = "The start_version_stat_collection method initiates storing version statistics for nodes previously registered via the add_node_to_version_stat method."; - -# start\_version\_stat\_collection - -The `start_version_stat_collection` method initiates storing version statistics for nodes previously registered via the `add_node_to_version_stat` method. - -## Arguments - -| Structure | Type | Description | -| --------- | ------- | ------------------------------------------------ | -| interval | integer | polling rate (in seconds) to check node versions | +#### Response -#### ๐Ÿ“Œ Examples +```json +{ + "mmrpc": "2.0", + "result": { + "base_coin_fee": { + "amount": "0.00042049", + "amount_fraction": { + "denom": "100000000", + "numer": "42049" + }, + "amount_rat": [ + [1, [42049]], + [1, [100000000]] + ], + "coin": "BTC", + "paid_from_trading_vol": false + }, + "rel_coin_fee": { + "coin": "DOC", + "amount": "0.00001", + "amount_fraction": { + "numer": "1", + "denom": "100000" + }, + "amount_rat": [ + [1, [1]], + [1, [100000]] + ], + "paid_from_trading_vol": true + }, + "taker_fee": { + "amount": "0.0028489508108108107", + "amount_fraction": { + "denom": "1850000000", + "numer": "5270559" + }, + "amount_rat": [ + [1, [5270559]], + [1, [1850000000]] + ], + "coin": "BTC", + "paid_from_trading_vol": false + }, + "fee_to_send_taker_fee": { + "amount": "0.00033219", + "amount_fraction": { + "denom": "100000000", + "numer": "33219" + }, + "amount_rat": [ + [1, [33219]], + [1, [100000000]] + ], + "coin": "BTC", + "paid_from_trading_vol": false + }, + "total_fees": [ + { + "coin": "DOC", + "amount": "0.00001", + "amount_fraction": { + "numer": "1", + "denom": "100000" + }, + "amount_rat": [ + [1, [1]], + [1, [100000]] + ], + "required_balance": "0", + "required_balance_fraction": { + "numer": "0", + "denom": "1" + }, + "required_balance_rat": [ + [0, []], + [1, [1]] + ] + }, + { + "coin": "BTC", + "amount": "0.0036016308108108106", + "amount_fraction": { + "denom": "1850000000", + "numer": "6663017" + }, + "amount_rat": [ + [1, [6663017]], + [1, [1850000000]] + ], + "required_balance": "0.0036016308108108106", + "required_balance_fraction": { + "denom": "1850000000", + "numer": "6663017" + }, + "required_balance_rat": [ + [1, [6663017]], + [1, [1850000000]] + ] + } + ] + }, + "id": 0 +} +``` -#### Command +#### Command (ERC20 and QRC20) - + ```json { "mmrpc": "2.0", - "method": "start_version_stat_collection", "userpass": "testpsw", + "method": "trade_preimage", "params": { - "interval": 600 - } + "base": "BAT", + "rel": "QC", + "price": "1", + "volume": "2.21363478", + "swap_method": "setprice" + }, + "id": 0 } ``` - - #### Response (success) - - ```json - { - "mmrpc": "2.0", - "result": "success", - "id": null - } - ``` - - #### Response (error - invalid peer id unable to parse) - - ```json - { - "mmrpc": "2.0", - "error": "Database error: UNIQUE constraint failed: nodes.peer_id", - "error_path": "lp_stats", - "error_trace": "lp_stats:124]", - "error_type": "DatabaseError", - "error_data": "UNIQUE constraint failed: nodes.peer_id", - "id": null - } - ``` - -export const title = "AtomicDEX Method: Stop Simple Market Maker Bot"; -export const description = "The stop_simple_market_maker_bot method tells the bot to finish placing orders at the end of the current loop 30 seconds minimum and 30 seconds by default."; - -# stop\_simple\_market\_maker\_bot - -The `stop_simple_market_maker_bot` method tells the bot to finish placing orders at the end of the current loop (30 seconds minimum & 30 seconds by default). This method takes as input a url to a price service, and configuration parameters of the pairs to trade at a defined spread percentage value. - -At the end of the final loop, orders placed by the bot will be cancelled. Users should wait until the loop ends before exiting the AtomicDEX API, otherwise orders will not cancel, and will reappear on the orderbook next time AtomicDEX API starts. - -## Arguments - -| Structure | Type | Description | -| --------- | ---- | ----------- | -| (none ) | | | +#### Response -#### ๐Ÿ“Œ Examples +```json +{ + "mmrpc": "2.0", + "result": { + "base_coin_fee": { + "amount": "0.0045", + "amount_fraction": { + "denom": "2000", + "numer": "9" + }, + "amount_rat": [ + [1, [9]], + [1, [2000]] + ], + "coin": "ETH", + "paid_from_trading_vol": false + }, + "rel_coin_fee": { + "amount": "0.00325", + "amount_fraction": { + "denom": "4000", + "numer": "13" + }, + "amount_rat": [ + [0, [13]], + [1, [4000]] + ], + "coin": "QTUM", + "paid_from_trading_vol": false + }, + "total_fees": [ + { + "amount": "0.003", + "amount_fraction": { + "denom": "1000", + "numer": "3" + }, + "amount_rat": [ + [1, [3]], + [1, [1000]] + ], + "required_balance": "0.003", + "required_balance_fraction": { + "denom": "1000", + "numer": "3" + }, + "required_balance_rat": [ + [1, [3]], + [1, [1000]] + ], + "coin": "ETH" + }, + { + "amount": "0.00325", + "amount_fraction": { + "denom": "4000", + "numer": "13" + }, + "amount_rat": [ + [0, [13]], + [1, [4000]] + ], + "required_balance": "0.00325", + "required_balance_fraction": { + "denom": "4000", + "numer": "13" + }, + "required_balance_rat": [ + [0, [13]], + [1, [4000]] + ], + "coin": "QTUM" + } + ] + }, + "id": 0 +} +``` -#### Command +#### Response (NotSufficientBalance error) - - ```json - { - "userpass": "testpsw", - "mmrpc": "2.0", - "method": "stop_simple_market_maker_bot", - "params": {}, - "id": 0 - } - ``` - +```json +{ + "mmrpc": "2.0", + "error": "Not enough BTC for swap: available 0.000015, required at least 0.10012, locked by swaps None", + "error_path": "maker_swap", + "error_trace": "maker_swap:1540] maker_swap:1641]", + "error_type": "NotSufficientBalance", + "error_data": { + "coin": "BTC", + "available": "0.000015", + "required": "0.10012", + "locked_by_swaps": "0" + }, + "id": 0 +} +``` - - #### Response (success) {{class : 'text-green-500'}} +#### Response (VolumeTooLow error) - ```json - { - "mmrpc": "2.0", - "result": { - "result": "Success" - }, - "id": 0 - } - ``` +```json +{ + "mmrpc": "2.0", + "error": "The volume 0.00001 of the DOC coin less than minimum transaction amount 0.0001", + "error_path": "maker_swap", + "error_trace": "maker_swap:1599]", + "error_type": "VolumeTooLow", + "error_data": { + "coin": "DOC", + "volume": "0.00001", + "threshold": "0.0001" + }, + "id": 0 +} +``` - #### Response (error - bot already stopped) {{class : 'text-red-500'}} +#### Response (Transport error) - ```json - { - "mmrpc": "2.0", - "error": "The bot is already stopped", - "error_path": "simple_market_maker", - "error_trace": "simple_market_maker:813]", - "error_type": "AlreadyStopped", - "id": 0 - } - ``` - -export const title = "AtomicDEX Method: Stop Version Stat Collection"; -export const description = "The stop_version_stat_collection method stops the collection of version stats at the end of the current loop interval."; +```json +{ + "mmrpc": "2.0", + "error": "Transport error: JsonRpcError { client_info: 'coin: tBTC', request: JsonRpcRequest { jsonrpc: '2.0', id: '31', method: 'blockchain.estimatefee', params: [Number(1), String('ECONOMICAL')] }, error: Transport('rpc_clients:1237] rpc_clients:1239] ['rpc_clients:2047] common:1385] future timed out']') }", + "error_path": "taker_swap.utxo_common", + "error_trace": "taker_swap:1599] utxo_common:1990] utxo_common:166]", + "error_type": "Transport", + "error_data": "JsonRpcError { client_info: 'coin: tBTC', request: JsonRpcRequest { jsonrpc: '2.0', id: '31', method: 'blockchain.estimatefee', params: [Number(1), String('ECONOMICAL')] }, error: Transport('rpc_clients:1237] rpc_clients:1239] ['rpc_clients:2047] common:1385] future timed out']') }", + "id": 0 +} +``` -# stop\_version\_stat\_collection +#### Response (incorrect use of "max" error) -The `stop_version_stat_collection` method stops the collection of version stats at the end of the current loop interval. +```json +{ + "mmrpc": "2.0", + "error": "Incorrect use of the 'max' parameter: 'max' cannot be used with 'sell' or 'buy' method", + "error_path": "taker_swap", + "error_trace": "taker_swap:1602]", + "error_type": "InvalidParam", + "error_data": { + "param": "max", + "reason": "'max' cannot be used with 'sell' or 'buy' method" + }, + "id": 0 +} +``` +export const title = "AtomicDEX Method: Update Version Stat Collection"; +export const description = "The update_version_stat_collection method updates the polling interval for version stats collection."; -#### Arguments +# update\_version\_stat\_collection -| Structure | Type | Description | -| --------- | ---- | ----------- | -| (none) | | | +The `update_version_stat_collection` method updates the polling interval for version stats collection. Note: the new interval will take effect after the current interval loop has completed. -#### Response +## Arguments -| Structure | Type | Description | -| --------- | ------ | ---------------- | -| result | string | success or error | +| Structure | Type | Description | +| --------- | ------- | ------------------------------------------------ | +| interval | integer | polling rate (in seconds) to query node versions | #### ๐Ÿ“Œ Examples #### Command - + ```json { "mmrpc": "2.0", - "method": "stop_version_stat_collection", + "method": "update_version_stat_collection", "userpass": "testpsw", - "params": {} + "params": { + "interval": 900 + } } ``` @@ -42077,196 +43572,116 @@ The `stop_version_stat_collection` method stops the collection of version stats ```json { "mmrpc": "2.0", - "result": "success", - "id": null - } - ``` - - - - #### Response (error - stats collection not running) - - ```json - { - "mmrpc": "2.0", - "error": "start_version_stat_collection is not running", - "error_path": "lp_stats", - "error_trace": "lp_stats:395]", - "error_type": "NotRunning", - "id": null - } - ``` - -export const title = "AtomicDEX Method: Telegram Alerts for MM Bot"; -export const description = "The AtomicDEX API Market Maker bot can be configured to send status update alerts via Telegram."; - -# Telegram Alerts for Market Maker Bot - -The AtomicDEX API Market Maker bot can be configured to send status update alerts via [Telegram!](https://telegram.org/) - -To set this up, you can add some additional parameters to your MM2.json as shown in the example below - -```json -{ - "gui": "MarketMakerBot", - "netid": 8762, - "rpc_password": "YOUR_PASSWORD", - "passphrase": "YOUR SEED PHRASE", - "dbdir": "/path/to/your/atomicdex/DB", - "message_service_cfg": { - "telegram": { - "api_key": "YOUR:TELEGRAM_API_TOKEN", - "chat_registry": { - "default": "YOUR_TELEGRAM_CHAT_ID", - "maker_bot": "YOUR_TELEGRAM_CHAT_ID", - "swap_events": "YOUR_TELEGRAM_CHAT_ID" - } - } - } -} -``` - -The extra fields required are: - -| Parameter | Type | Description | -| --------------------------- | ------ | ------------------------ | -| api\_key | string | A Telegram bot API token | -| chat\_registry.default | string | A Telegram Chat ID | -| chat\_registry.maker\_bot | string | A Telegram Chat ID | -| chat\_registry.swap\_events | string | A Telegram Chat ID | - -You can use the same Telegram chat ID for all three `chat_registry` subfields, or sent your alerts to a different chat ID if you want to separate the alerts by type. - -To get a Telegram bot API token, you need to [have chat with the BotFather](https://sean-bradley.medium.com/get-telegram-chat-id-80b575520659) - -To get a Telegram chat ID, check out [this guide](https://sean-bradley.medium.com/get-telegram-chat-id-80b575520659) -export const title = "AtomicDEX Method: Trade Preimage"; -export const description = "The trade_preimage method returns the approximate fee amounts that are paid per the whole swap."; - -# trade\_preimage - -The `trade_preimage` method returns the approximate fee amounts that are paid per the whole swap. -Depending on the parameters, the function returns different results: - -* If the `swap_method` is `buy` or `sell`, then the result will include the `taker_fee` and the `fee_to_send_taker_fee`. - The `taker_fee` amount is paid from the `base` coin balance if the `swap_method` is `sell`, else it is paid from the `rel` coin balance; -* If the `max` field is true, then the result will include the `volume`. - - - This method can be used instead of **max\_taker\_vol**, if the `max` field is true and the `swap_method` is `buy` or `sell`. - Use the resulting `volume` as an argument of the `buy` or `sell` requests. - - - - Use the `trade_preimage` request with `max = true` and `swap_method = "setprice"` arguments to approximate the fee amounts **only**. Do not use the resulting `volume` as an argument of the `setprice`. - - -## Arguments - -| Structure | Type | Description | -| ------------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -| base | string | the base currency of the request | -| rel | string | the rel currency of the request | -| swap\_method | string | the name of the method whose preimage is requested. Possible values: `buy`, `sell`, `setprice` | -| price | numeric string or rational | the price in `rel` the user is willing to pay per one unit of the `base` coin | -| volume | numeric string or rational (optional) | the amount the user is willing to trade; ignored if `max = true` **and** `swap_method = setprice`, otherwise, it must be set | -| max | bool (optional) | whether to return the maximum available volume for `setprice` method; must not be set or `false` if `swap_method` is `buy` or `sell` | - -### Result - -| Structure | Type | Description | -| ------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| base\_coin\_fee | object | A standard [ExtendedFeeInfo](/atomicdex/api/common_structures/#extended-fee-info) object. The approximate miner fee is paid per the whole swap concerning the `base` coin | -| rel\_coin\_fee | object | A standard [ExtendedFeeInfo](/atomicdex/api/common_structures/#extended-fee-info) object. The approximate miner fee is paid per the whole swap concerning the `rel` coin | -| volume | string (numeric) | Optional. The max available volume that can be traded (in decimal representation); empty if the `max` argument is missing or false | -| volume\_rat | rational | Optional. The max available volume that can be traded represented as a standard [RationalValue](/atomicdex/api/common_structures/#rational-value) object.; empty if the `max` argument is missing or false | -| volume\_fraction | fraction | Optional. The max available volume that can be traded represented as a standard [fractionalValue](/atomicdex/api/common_structures/#fractional-value) object.; empty if the `max` argument is missing or false | -| taker\_fee | object | A standard [ExtendedFeeInfo](/atomicdex/api/common_structures/#extended-fee-info) object. The dex fee to be paid by Taker; empty if `swap_method` is `setprice` | -| fee\_to\_send\_taker\_fee | object | A standard [ExtendedFeeInfo](/atomicdex/api/common_structures/#extended-fee-info) object. The approximate miner fee is paid to send the dex fee; empty if `swap_method` is `setprice` | -| total\_fees | array of objects | A standard [TotalFeeInfo](/atomicdex/api/common_structures/#total-fee-info) object. Each element is a sum of fees required to be paid from user's balance of corresponding `ExtendedFeeInfo.coin`; the elements are unique by coin | + "result": "success", + "id": null + } + ``` + -### โš  Error types + + #### Response (error - stats collection not running) -#### NotSufficientBalance + ```json + { + "mmrpc": "2.0", + "error": "start_version_stat_collection is not running", + "error_path": "lp_stats", + "error_trace": "lp_stats:374]", + "error_type": "NotRunning", + "id": null + } + ``` + +export const title = "AtomicDEX Method: Withdraw"; +export const description = "The withdraw method generates, signs, and returns a transaction that transfers the amount of coin to the address indicated in the to argument."; -The `available` balance of the `coin` is not sufficient to start the swap. +# withdraw -| Structure | Type | Description | -| ----------------- | -------------------------- | ----------------------------------------------------------------------------------------- | -| coin | string | the name of the coin which balance is not sufficient | -| available | string (numeric) | the balance available for swap, including the amount locked by other swaps | -| required | string (numeric) | the amount required to start the swap. This amount is necessary but may not be sufficient | -| locked\_by\_swaps | string (numeric, optional) | the amount locked by other swaps | +The `withdraw` method generates, signs, and returns a transaction that transfers the `amount` of `coin` to the address indicated in the `to` argument. -#### NotSufficientBaseCoinBalance +This method generates a raw transaction which should then be broadcast using [send\_raw\_transaction](/atomicdex/api/legacy/send_raw_transaction/). -The available balance of the base `coin` is not sufficient to pay transaction fees. +## Arguments -For example, ERC20 fees are paid by ETH (gas), and this error type is returned if the ETH coin balance is not sufficient to start the swap. +| Structure | Type | Description | +| --------- | ---------------- | ----------------------------------------------------------------------------------- | +| coin | string | the name of the coin the user desires to withdraw | +| to | string | coins are withdrawn to this address | +| amount | string (numeric) | the amount the user desires to withdraw, ignored when `max=true` | +| memo | string | Optional. Adds a transaction memo for compatible coins (e.g. Tendermint ecosystem). | +| max | bool | withdraw the maximum available amount | +| fee | object | Optional. A standard [FeeInfo](/atomicdex/api/common_structures/#fee-info) object. | -| Structure | Type | Description | -| ----------------- | -------------------------- | ----------------------------------------------------------------------------------------- | -| coin | string | the name of the base coin which balance is not sufficient | -| available | string (numeric) | the balance available for swap, including the amount locked by other swaps | -| required | string (numeric) | the amount required to start the swap. This amount is necessary but may not be sufficient | -| locked\_by\_swaps | string (numeric, optional) | the amount is locked by other swaps | +### Response -#### VolumeTooLow +| Structure | Type | Description | +| ---------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| from | array of strings | coins are withdrawn from this address; the array contains a single element, but transactions may be sent from several addresses (UTXO coins) | +| to | array of strings | coins are withdrawn to this address; this may contain the `my_address` address, where change from UTXO coins is sent | +| my\_balance\_change | string (numeric) | the expected balance of change in `my_address` after the transaction broadcasts | +| received\_by\_me | string (numeric) | the amount of coins received by `my_address` after the transaction broadcasts; the value may be above zero when the transaction requires that the AtomicDEX API send change to `my_address` | +| spent\_by\_me | string (numeric) | the amount of coins spent by `my_address`; this value differ from the request amount, as the transaction fee is added here | +| total\_amount | string (numeric) | the total amount of coins transferred | +| fee\_details | object | the fee details of the generated transaction; this value differs for utxo and ETH/ERC20 coins, check the examples for more details | +| tx\_hash | string | the hash of the generated transaction | +| tx\_hex | string | transaction bytes in hexadecimal format; use this value as input for the `send_raw_transaction` method | +| coin | string | the name of the coin the user wants to withdraw | +| kmd\_rewards | object (optional) | an object containing information about accrued rewards; always exists if the coin is `KMD` | +| kmd\_rewards.amount | string (numeric, optional) | the amount of accrued rewards | +| kmd\_rewards.claimed\_by\_me | bool (optional) | whether the rewards been claimed by me | -The specified `volume` is too low. Required at least `threshold`. +### โš  Error types - - If the `coin` field returned in Response is the same as the `rel` argument in Request, then the base volume threshold can be calculated as follows: - `base_coin_threshold = rel_vol_threshold / price` - +#### NotSufficientBalance -| Structure | Type | Description | -| --------- | ---------------- | -------------------------------------------------- | -| coin | string | either `base` or `rel` coin specified in Request | -| volume | string (numeric) | the amount the user was willing to trade in `coin` | -| threshold | string (numeric) | the `volume` has not to be less than this amount | +The `available` balance is not sufficient to transfer the specified amount. -#### NoSuchCoin +| Structure | Type | Description | +| --------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| coin | string | the name of the coin which balance is not sufficient. This coin name may differ from the requested coin. For example, ERC20 fees are paid by ETH (gas) | +| available | string (numeric) | the balance available for transfer | +| required | string (numeric) | the amount required to transfer the specified amount. This amount is necessary but may not be sufficient | -The specified coin was not found or is not activated yet. +#### ZeroBalanceToWithdrawMax -| Structure | Type | Description | -| --------- | ------ | ------------------------------------------------ | -| coin | string | either `base` or `rel` coin specified in Request | +The available balance is zero. -#### CoinIsWalletOnly +| Structure | Type | Description | +| --------- | ---- | ----------- | +| (none) | | | -The specified coin is wallet only and cannot be participated in the swap. +#### AmountTooLow -| Structure | Type | Description | -| --------- | ------ | ------------------------------------------------ | -| coin | string | either `base` or `rel` coin specified in Request | +The specified amount is too low. Required at least `threshold`. -#### BaseEqualRel +| Structure | Type | Description | +| --------- | ---------------- | ---------------------------------------------------- | +| amount | string (numeric) | the amount the user was willing to transfer | +| threshold | string (numeric) | the `amount` has not to be less than the `threshold` | -The coin is wallet only and cannot be participated in the swap. +#### InvalidAddress -| Structure | Type | Description | -| --------- | ---- | ----------- | -| (none) | | | +The specified `to` address is not valid. -#### InvalidParam +| Structure | Type | Description | +| --------- | ------ | --------------------- | +| (none) | string | the error description | -Incorrect use of the `param` parameter in Request. +#### InvalidFeePolicy -| Structure | Type | Description | -| --------- | ------ | ------------------------------------------------ | -| param | string | the name of the parameter in Request | -| reason | string | the reason why the parameter is used incorrectly | +The specified `fee` is not valid. -#### PriceTooLow +| Structure | Type | Description | +| --------- | ------ | --------------------- | +| (none) | string | the error description | -The specified `price` is too low. +#### NoSuchCoin -| Structure | Type | Description | -| --------- | ---------------- | ---------------------------------------------------------------------------------- | -| price | string (numeric) | the price in `rel` the user was willing to receive per one unit of the `base` coin | -| threshold | string (numeric) | the `price` has not to be less than this amount | +The specified coin was not found or is not activated yet. + +| Structure | Type | Description | +| --------- | ------ | --------------------------------------------- | +| coin | string | the not found `coin` specified in the Request | #### Transport @@ -42278,7 +43693,7 @@ The request was failed due to a network error. #### InternalError -The request was failed due to a AtomicDEX API internal error. +The request was failed due to an AtomicDEX API internal error. | Structure | Type | Description | | --------- | ------ | ------------------------------ | @@ -42286,564 +43701,189 @@ The request was failed due to a AtomicDEX API internal error. ### ๐Ÿ“Œ Examples -#### Command (setprice) - - - ```json - { - "mmrpc": "2.0", - "userpass": "testpsw", - "method": "trade_preimage", - "params": { - "base": "BTC", - "rel": "DOC", - "price": "1", - "volume": "0.1", - "swap_method": "setprice" - }, - "id": 0 - } - ``` - - -#### Response - -```json -{ - "mmrpc": "2.0", - "result": { - "base_coin_fee": { - "coin": "KMD", - "amount": "0.00001", - "amount_fraction": { - "numer": "1", - "denom": "100000" - }, - "amount_rat": [ - [1, [1]], - [1, [100000]] - ], - "paid_from_trading_vol": false - }, - "rel_coin_fee": { - "coin": "DGB", - "amount": "0.00030782", - "amount_fraction": { - "numer": "15391", - "denom": "50000000" - }, - "amount_rat": [ - [1, [15391]], - [1, [50000000]] - ], - "paid_from_trading_vol": true - }, - "volume": "1138.46868712", - "volume_fraction": { - "numer": "14230858589", - "denom": "12500000" - }, - "volume_rat": [ - [1, [1345956701, 3]], - [1, [12500000]] - ], - "total_fees": [ - { - "coin": "KMD", - "amount": "0.00001", - "amount_fraction": { - "numer": "1", - "denom": "100000" - }, - "amount_rat": [ - [1, [1]], - [1, [100000]] - ], - "required_balance": "0.00001", - "required_balance_fraction": { - "numer": "1", - "denom": "100000" - }, - "required_balance_rat": [ - [1, [1]], - [1, [100000]] - ] - }, - { - "coin": "DGB", - "amount": "0.00030782", - "amount_fraction": { - "numer": "15391", - "denom": "50000000" - }, - "amount_rat": [ - [1, [15391]], - [1, [50000000]] - ], - "required_balance": "0", - "required_balance_fraction": { - "numer": "0", - "denom": "1" - }, - "required_balance_rat": [ - [0, []], - [1, [1]] - ] - } - ] - }, - "id": 0 -} -``` - -#### Command (buy) +#### Withdraw BTC, KMD, and other BTC-based forks - + ```json { - "mmrpc": "2.0", "userpass": "testpsw", - "method": "trade_preimage", + "mmrpc": "2.0", + "method": "withdraw", "params": { - "base": "BTC", - "rel": "DOC", - "price": "1", - "volume": "0.1", - "swap_method": "buy" + "coin": "KMD", + "to": "RJTYiYeJ8eVvJ53n2YbrVmxWNNMVZjDGLh", + "amount": "10" }, "id": 0 } ``` -#### Response - -```json -{ - "mmrpc": "2.0", - "result": { - "base_coin_fee": { - "amount": "0.00042049", - "amount_fraction": { - "denom": "100000000", - "numer": "42049" - }, - "amount_rat": [ - [1, [42049]], - [1, [100000000]] - ], - "coin": "BTC", - "paid_from_trading_vol": true - }, - "rel_coin_fee": { - "amount": "0.0001", - "amount_fraction": { - "denom": "10000", - "numer": "1" - }, - "amount_rat": [ - [1, [1]], - [1, [10000]] - ], - "coin": "DOC", - "paid_from_trading_vol": false - }, - "taker_fee": { - "amount": "0.00012870012870012872", - "amount_fraction": { - "denom": "7770", - "numer": "1" - }, - "amount_rat": [ - [1, [1]], - [1, [7770]] - ], - "coin": "DOC", - "paid_from_trading_vol": false - }, - "fee_to_send_taker_fee": { - "amount": "0.0001", - "amount_fraction": { - "denom": "10000", - "numer": "1" - }, - "amount_rat": [ - [1, [1]], - [1, [10000]] - ], - "coin": "DOC", - "paid_from_trading_vol": false - }, - "total_fees": [ - { - "coin": "DOC", - "amount": "0.001307001287001287001287001287001287001287001287001287001287001287001287001287001287001287001287001287", - "amount_fraction": { - "numer": "50777", - "denom": "38850000" - }, - "amount_rat": [ - [1, [50777]], - [1, [38850000]] - ], - "required_balance": "0.001307001287001287001287001287001287001287001287001287001287001287001287001287001287001287001287001287", - "required_balance_fraction": { - "numer": "50777", - "denom": "38850000" - }, - "required_balance_rat": [ - [1, [50777]], - [1, [38850000]] - ] - }, - { - "coin": "tBTC", - "amount": "0.00042049", - "amount_fraction": { - "denom": "100000000", - "numer": "42049" - }, - "amount_rat": [ - [1, [42049]], - [1, [100000000]] - ], - "required_balance": "0", - "required_balance_fraction": { - "numer": "0", - "denom": "1" - }, - "required_balance_rat": [ - [0, []], - [1, [1]] - ] - } - ] - }, - "id": 0 -} -``` - -#### Command (sell, max) + + #### Response (KMD success) - ```json { "mmrpc": "2.0", - "userpass": "testpsw", - "method": "trade_preimage", - "params": { - "base": "BTC", - "rel": "DOC", - "price": "1", - "volume": "2.21363478", - "swap_method": "sell" + "result": { + "block_height": 0, + "coin": "KMD", + "fee_details": { + "type": "Utxo", + "amount": "0.00001" + }, + "from": ["R9o9xTocqr6CeEDGDH6mEYpwLoMz6jNjMW"], + "my_balance_change": "-10.00001", + "received_by_me": "0.34417325", + "spent_by_me": "10.34418325", + "to": ["RJTYiYeJ8eVvJ53n2YbrVmxWNNMVZjDGLh"], + "total_amount": "10.34418325", + "tx_hash": "3a1c382c50a7d12e4675d12ed7e723ce9f0167693dd75fd772bae8524810e605", + "tx_hex": "0400008085202f890207a8e96978acfb8f0d002c3e4390142810dc6568b48f8cd6d8c71866ad8743c5010000006a47304402201960a7089f2d93480fff68ce0b7ca7bb7a32a52915753ac7ae780abd6162cb1d02202c9b11d442e5f72a532f44ceb10122898d486b1474a10eb981c60c5538b9c82d012102031d4256c4bc9f99ac88bf3dba21773132281f65f9bf23a59928bce08961e2f3ffffffff97f56bf3b0f815bb737b7867e71ddb8198bba3574bb75737ba9c389a4d08edc6000000006a473044022055199d80bd7e2d1b932e54f097c6a15fc4b148d21299dc50067c1da18045f0ed02201d26d85333df65e6daab40a07a0e8a671af9d9b9d92fdf7d7ef97bd868ca545a012102031d4256c4bc9f99ac88bf3dba21773132281f65f9bf23a59928bce08961e2f3ffffffff0200ca9a3b000000001976a91464ae8510aac9546d5e7704e31ce177451386455588acad2a0d02000000001976a91405aab5342166f8594baf17a7d9bef5d56744332788ac00000000000000000000000000000000000000", + "kmd_rewards": { + "amount": "0.0791809", + "claimed_by_my": true + } }, "id": 0 } ``` - -#### Response + #### Response (NotSufficientBalance error) -```json -{ - "mmrpc": "2.0", - "result": { - "base_coin_fee": { - "amount": "0.00042049", - "amount_fraction": { - "denom": "100000000", - "numer": "42049" - }, - "amount_rat": [ - [1, [42049]], - [1, [100000000]] - ], - "coin": "BTC", - "paid_from_trading_vol": false - }, - "rel_coin_fee": { - "coin": "DOC", - "amount": "0.00001", - "amount_fraction": { - "numer": "1", - "denom": "100000" - }, - "amount_rat": [ - [1, [1]], - [1, [100000]] - ], - "paid_from_trading_vol": true - }, - "taker_fee": { - "amount": "0.0028489508108108107", - "amount_fraction": { - "denom": "1850000000", - "numer": "5270559" - }, - "amount_rat": [ - [1, [5270559]], - [1, [1850000000]] - ], - "coin": "BTC", - "paid_from_trading_vol": false - }, - "fee_to_send_taker_fee": { - "amount": "0.00033219", - "amount_fraction": { - "denom": "100000000", - "numer": "33219" - }, - "amount_rat": [ - [1, [33219]], - [1, [100000000]] - ], - "coin": "BTC", - "paid_from_trading_vol": false - }, - "total_fees": [ - { - "coin": "DOC", - "amount": "0.00001", - "amount_fraction": { - "numer": "1", - "denom": "100000" - }, - "amount_rat": [ - [1, [1]], - [1, [100000]] - ], - "required_balance": "0", - "required_balance_fraction": { - "numer": "0", - "denom": "1" - }, - "required_balance_rat": [ - [0, []], - [1, [1]] - ] - }, - { - "coin": "BTC", - "amount": "0.0036016308108108106", - "amount_fraction": { - "denom": "1850000000", - "numer": "6663017" - }, - "amount_rat": [ - [1, [6663017]], - [1, [1850000000]] - ], - "required_balance": "0.0036016308108108106", - "required_balance_fraction": { - "denom": "1850000000", - "numer": "6663017" - }, - "required_balance_rat": [ - [1, [6663017]], - [1, [1850000000]] - ] - } - ] - }, - "id": 0 -} -``` + ```json + { + "mmrpc": "2.0", + "error": "Not enough DOC to withdraw: available 69.75066225, required at least 1000.00001", + "error_path": "utxo_common", + "error_trace": "utxo_common:1379] utxo_common:449]", + "error_type": "NotSufficientBalance", + "error_data": { + "coin": "DOC", + "available": "69.75066225", + "required": "1000.00001" + }, + "id": 0 + } + ``` + -#### Command (ERC20 and QRC20) +#### Withdraw BTC, KMD, and other BTC-based forks, fixed fee - + ```json { "mmrpc": "2.0", "userpass": "testpsw", - "method": "trade_preimage", + "method": "withdraw", "params": { - "base": "BAT", - "rel": "QC", - "price": "1", - "volume": "2.21363478", - "swap_method": "setprice" + "coin": "DOC", + "to": "R9o9xTocqr6CeEDGDH6mEYpwLoMz6jNjMW", + "amount": "1.0", + "fee": { + "type": "UtxoFixed", + "amount": "0.1" + } }, "id": 0 } ``` -#### Response + + #### Response (success) -```json -{ - "mmrpc": "2.0", - "result": { - "base_coin_fee": { - "amount": "0.0045", - "amount_fraction": { - "denom": "2000", - "numer": "9" - }, - "amount_rat": [ - [1, [9]], - [1, [2000]] - ], - "coin": "ETH", - "paid_from_trading_vol": false - }, - "rel_coin_fee": { - "amount": "0.00325", - "amount_fraction": { - "denom": "4000", - "numer": "13" + ```json + { + "mmrpc": "2.0", + "result": { + "tx_hex": "0400008085202f8901ef25b1b7417fe7693097918ff90e90bba1351fff1f3a24cb51a9b45c5636e57e010000006b483045022100b05c870fcd149513d07b156e150a22e3e47fab4bb4776b5c2c1b9fc034a80b8f022038b1bf5b6dad923e4fb1c96e2c7345765ff09984de12bbb40b999b88b628c0f9012102031d4256c4bc9f99ac88bf3dba21773132281f65f9bf23a59928bce08961e2f3ffffffff0200e1f505000000001976a91405aab5342166f8594baf17a7d9bef5d56744332788ac8cbaae5f010000001976a91405aab5342166f8594baf17a7d9bef5d56744332788ace87a5e5d000000000000000000000000000000", + "tx_hash": "1ab3bc9308695960bc728fa427ac00d1812c4ae89aaa714c7618cb96d111be58", + "from": ["R9o9xTocqr6CeEDGDH6mEYpwLoMz6jNjMW"], + "to": ["R9o9xTocqr6CeEDGDH6mEYpwLoMz6jNjMW"], + "total_amount": "60.10253836", + "spent_by_me": "60.10253836", + "received_by_me": "60.00253836", + "my_balance_change": "-0.1", + "block_height": 0, + "timestamp": 1566472936, + "fee_details": { + "type": "Utxo", + "amount": "0.1" }, - "amount_rat": [ - [0, [13]], - [1, [4000]] - ], - "coin": "QTUM", - "paid_from_trading_vol": false + "coin": "DOC", + "internal_id": "" }, - "total_fees": [ - { - "amount": "0.003", - "amount_fraction": { - "denom": "1000", - "numer": "3" - }, - "amount_rat": [ - [1, [3]], - [1, [1000]] - ], - "required_balance": "0.003", - "required_balance_fraction": { - "denom": "1000", - "numer": "3" - }, - "required_balance_rat": [ - [1, [3]], - [1, [1000]] - ], - "coin": "ETH" - }, - { - "amount": "0.00325", - "amount_fraction": { - "denom": "4000", - "numer": "13" - }, - "amount_rat": [ - [0, [13]], - [1, [4000]] - ], - "required_balance": "0.00325", - "required_balance_fraction": { - "denom": "4000", - "numer": "13" - }, - "required_balance_rat": [ - [0, [13]], - [1, [4000]] - ], - "coin": "QTUM" - } - ] - }, - "id": 0 -} -``` - -#### Response (NotSufficientBalance error) - -```json -{ - "mmrpc": "2.0", - "error": "Not enough BTC for swap: available 0.000015, required at least 0.10012, locked by swaps None", - "error_path": "maker_swap", - "error_trace": "maker_swap:1540] maker_swap:1641]", - "error_type": "NotSufficientBalance", - "error_data": { - "coin": "BTC", - "available": "0.000015", - "required": "0.10012", - "locked_by_swaps": "0" - }, - "id": 0 -} -``` - -#### Response (VolumeTooLow error) - -```json -{ - "mmrpc": "2.0", - "error": "The volume 0.00001 of the DOC coin less than minimum transaction amount 0.0001", - "error_path": "maker_swap", - "error_trace": "maker_swap:1599]", - "error_type": "VolumeTooLow", - "error_data": { - "coin": "DOC", - "volume": "0.00001", - "threshold": "0.0001" - }, - "id": 0 -} -``` - -#### Response (Transport error) - -```json -{ - "mmrpc": "2.0", - "error": "Transport error: JsonRpcError { client_info: 'coin: tBTC', request: JsonRpcRequest { jsonrpc: '2.0', id: '31', method: 'blockchain.estimatefee', params: [Number(1), String('ECONOMICAL')] }, error: Transport('rpc_clients:1237] rpc_clients:1239] ['rpc_clients:2047] common:1385] future timed out']') }", - "error_path": "taker_swap.utxo_common", - "error_trace": "taker_swap:1599] utxo_common:1990] utxo_common:166]", - "error_type": "Transport", - "error_data": "JsonRpcError { client_info: 'coin: tBTC', request: JsonRpcRequest { jsonrpc: '2.0', id: '31', method: 'blockchain.estimatefee', params: [Number(1), String('ECONOMICAL')] }, error: Transport('rpc_clients:1237] rpc_clients:1239] ['rpc_clients:2047] common:1385] future timed out']') }", - "id": 0 -} -``` - -#### Response (incorrect use of "max" error) - -```json -{ - "mmrpc": "2.0", - "error": "Incorrect use of the 'max' parameter: 'max' cannot be used with 'sell' or 'buy' method", - "error_path": "taker_swap", - "error_trace": "taker_swap:1602]", - "error_type": "InvalidParam", - "error_data": { - "param": "max", - "reason": "'max' cannot be used with 'sell' or 'buy' method" - }, - "id": 0 -} -``` -export const title = "AtomicDEX Method: Update Version Stat Collection"; -export const description = "The update_version_stat_collection method updates the polling interval for version stats collection."; - -# update\_version\_stat\_collection + "id": 0 + } + ``` + -The `update_version_stat_collection` method updates the polling interval for version stats collection. Note: the new interval will take effect after the current interval loop has completed. +#### Withdraw BTC, KMD, and other BTC-based forks, 1 coin per Kbyte fee -## Arguments + + ```json + { + "mmrpc": "2.0", + "userpass": "testpsw", + "method": "withdraw", + "params": { + "coin": "DOC", + "to": "R9o9xTocqr6CeEDGDH6mEYpwLoMz6jNjMW", + "amount": "1.0", + "fee": { + "type": "UtxoPerKbyte", + "amount": "1" + } + }, + "id": 0 + } + ``` + -| Structure | Type | Description | -| --------- | ------- | ------------------------------------------------ | -| interval | integer | polling rate (in seconds) to query node versions | + + #### Response (success) -#### ๐Ÿ“Œ Examples + ```json + { + "mmrpc": "2.0", + "result": { + "tx_hex": "0400008085202f890258be11d196cb18764c71aa9ae84a2c81d100ac27a48f72bc6059690893bcb31a000000006b483045022100ef11280e981be280ca5d24c947842ca6a8689d992b73e3a7eb9ff21070b0442b02203e458a2bbb1f2bf8448fc47c51485015904a5271bb17e14be5afa6625d67b1e8012102031d4256c4bc9f99ac88bf3dba21773132281f65f9bf23a59928bce08961e2f3ffffffff58be11d196cb18764c71aa9ae84a2c81d100ac27a48f72bc6059690893bcb31a010000006b483045022100daaa10b09e7abf9d4f596fc5ac1f2542b8ecfab9bb9f2b02201644944ddc0280022067aa1b91ec821aa48f1d06d34cd26fb69a9f27d59d5eecdd451006940d9e83db012102031d4256c4bc9f99ac88bf3dba21773132281f65f9bf23a59928bce08961e2f3ffffffff0200e1f505000000001976a91405aab5342166f8594baf17a7d9bef5d56744332788acf31c655d010000001976a91405aab5342166f8594baf17a7d9bef5d56744332788accd7c5e5d000000000000000000000000000000", + "tx_hash": "fd115190feec8c0c14df2696969295c59c674886344e5072d64000379101b78c", + "from": ["R9o9xTocqr6CeEDGDH6mEYpwLoMz6jNjMW"], + "to": ["R9o9xTocqr6CeEDGDH6mEYpwLoMz6jNjMW"], + "total_amount": "60.00253836", + "spent_by_me": "60.00253836", + "received_by_me": "59.61874931", + "my_balance_change": "-0.38378905", + "block_height": 0, + "timestamp": 1566473421, + "fee_details": { + "type": "Utxo", + "amount": "0.38378905" + }, + "coin": "DOC", + "internal_id": "" + }, + "id": 0 + } + ``` + -#### Command +#### Withdraw ETH, ERC20, and other ETH-based forks - + ```json { "mmrpc": "2.0", - "method": "update_version_stat_collection", "userpass": "testpsw", + "method": "withdraw", "params": { - "interval": 900 - } + "coin": "ETH", + "to": "0xbab36286672fbdc7b250804bf6d14be0df69fa28", + "amount": 10 + }, + "id": 0 } ``` @@ -42854,147 +43894,111 @@ The `update_version_stat_collection` method updates the polling interval for ver ```json { "mmrpc": "2.0", - "result": "success", - "id": null + "result": { + "block_height": 0, + "coin": "ETH", + "fee_details": { + "type": "Eth", + "coin": "ETH", + "gas": 21000, + "gas_price": "0.000000001", + "total_fee": "0.000021" + }, + "from": ["0xbab36286672fbdc7b250804bf6d14be0df69fa29"], + "my_balance_change": "-10.000021", + "received_by_me": "0", + "spent_by_me": "10.000021", + "to": ["0xbab36286672fbdc7b250804bf6d14be0df69fa28"], + "total_amount": "10.000021", + "tx_hash": "8fbc5538679e4c4b78f8b9db0faf9bf78d02410006e8823faadba8e8ae721d60", + "tx_hex": "f86d820a59843b9aca0082520894bab36286672fbdc7b250804bf6d14be0df69fa28888ac7230489e80000801ba0fee87414a3b40d58043a1ae143f7a75d7f47a24e872b638281c448891fd69452a05b0efcaed9dee1b6d182e3215d91af317d53a627404b0efc5102cfe714c93a28" + }, + "id": 0 } ``` - - #### Response (error - stats collection not running) +#### ETH/ERC20 and other ETH-based forks, with gas fee + ```json { "mmrpc": "2.0", - "error": "start_version_stat_collection is not running", - "error_path": "lp_stats", - "error_trace": "lp_stats:374]", - "error_type": "NotRunning", - "id": null + "userpass": "testpsw", + "method": "withdraw", + "params": { + "coin": "COIN_NAME", + "to": "RECIPIENT_ADDRESS", + "amount": "AMOUNT", + "fee": { + "type": "EthGas", + "gas_price": "3.5", + "gas": 55000 + } + }, + "id": 0 } ``` - -export const title = "AtomicDEX Method: Withdraw"; -export const description = "The withdraw method generates, signs, and returns a transaction that transfers the amount of coin to the address indicated in the to argument."; - -# withdraw - -The `withdraw` method generates, signs, and returns a transaction that transfers the `amount` of `coin` to the address indicated in the `to` argument. - -This method generates a raw transaction which should then be broadcast using [send\_raw\_transaction](/atomicdex/api/legacy/send_raw_transaction/). - -## Arguments - -| Structure | Type | Description | -| --------- | ---------------- | ----------------------------------------------------------------------------------- | -| coin | string | the name of the coin the user desires to withdraw | -| to | string | coins are withdrawn to this address | -| amount | string (numeric) | the amount the user desires to withdraw, ignored when `max=true` | -| memo | string | Optional. Adds a transaction memo for compatible coins (e.g. Tendermint ecosystem). | -| max | bool | withdraw the maximum available amount | -| fee | object | Optional. A standard [FeeInfo](/atomicdex/api/common_structures/#fee-info) object. | - -### Response - -| Structure | Type | Description | -| ---------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| from | array of strings | coins are withdrawn from this address; the array contains a single element, but transactions may be sent from several addresses (UTXO coins) | -| to | array of strings | coins are withdrawn to this address; this may contain the `my_address` address, where change from UTXO coins is sent | -| my\_balance\_change | string (numeric) | the expected balance of change in `my_address` after the transaction broadcasts | -| received\_by\_me | string (numeric) | the amount of coins received by `my_address` after the transaction broadcasts; the value may be above zero when the transaction requires that the AtomicDEX API send change to `my_address` | -| spent\_by\_me | string (numeric) | the amount of coins spent by `my_address`; this value differ from the request amount, as the transaction fee is added here | -| total\_amount | string (numeric) | the total amount of coins transferred | -| fee\_details | object | the fee details of the generated transaction; this value differs for utxo and ETH/ERC20 coins, check the examples for more details | -| tx\_hash | string | the hash of the generated transaction | -| tx\_hex | string | transaction bytes in hexadecimal format; use this value as input for the `send_raw_transaction` method | -| coin | string | the name of the coin the user wants to withdraw | -| kmd\_rewards | object (optional) | an object containing information about accrued rewards; always exists if the coin is `KMD` | -| kmd\_rewards.amount | string (numeric, optional) | the amount of accrued rewards | -| kmd\_rewards.claimed\_by\_me | bool (optional) | whether the rewards been claimed by me | - -### โš  Error types - -#### NotSufficientBalance - -The `available` balance is not sufficient to transfer the specified amount. - -| Structure | Type | Description | -| --------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -| coin | string | the name of the coin which balance is not sufficient. This coin name may differ from the requested coin. For example, ERC20 fees are paid by ETH (gas) | -| available | string (numeric) | the balance available for transfer | -| required | string (numeric) | the amount required to transfer the specified amount. This amount is necessary but may not be sufficient | - -#### ZeroBalanceToWithdrawMax - -The available balance is zero. - -| Structure | Type | Description | -| --------- | ---- | ----------- | -| (none) | | | - -#### AmountTooLow - -The specified amount is too low. Required at least `threshold`. - -| Structure | Type | Description | -| --------- | ---------------- | ---------------------------------------------------- | -| amount | string (numeric) | the amount the user was willing to transfer | -| threshold | string (numeric) | the `amount` has not to be less than the `threshold` | - -#### InvalidAddress - -The specified `to` address is not valid. - -| Structure | Type | Description | -| --------- | ------ | --------------------- | -| (none) | string | the error description | - -#### InvalidFeePolicy - -The specified `fee` is not valid. - -| Structure | Type | Description | -| --------- | ------ | --------------------- | -| (none) | string | the error description | - -#### NoSuchCoin - -The specified coin was not found or is not activated yet. - -| Structure | Type | Description | -| --------- | ------ | --------------------------------------------- | -| coin | string | the not found `coin` specified in the Request | - -#### Transport - -The request was failed due to a network error. - -| Structure | Type | Description | -| --------- | ------ | ------------------------------- | -| (none) | string | the transport error description | + -#### InternalError + + #### Response (success) -The request was failed due to an AtomicDEX API internal error. + ```json + { + "mmrpc": "2.0", + "result": { + "tx_hex": "f86d820b2884d09dc30082d6d894bab36286672fbdc7b250804bf6d14be0df69fa29888ac7230489e80000801ca0ef0167b0e53ed50d87b6fd630925f2bce6ee72e9b5fdb51c6499a7caaecaed96a062e5cb954e503ff83f2d6ce082649fdcdf8a77c8d37c7d26d46d3f736b228d10", + "tx_hash": "a26c4dcacf63c04e385dd973ca7e7ca1465a3b904a0893bcadb7e37681d38c95", + "from": ["0xbAB36286672fbdc7B250804bf6D14Be0dF69fa29"], + "to": ["0xbAB36286672fbdc7B250804bf6D14Be0dF69fa29"], + "total_amount": "10", + "spent_by_me": "10.0001925", + "received_by_me": "10", + "my_balance_change": "-0.0001925", + "block_height": 0, + "timestamp": 1566474670, + "fee_details": { + "type": "Eth", + "coin": "ETH", + "gas": 55000, + "gas_price": "0.0000000035", + "total_fee": "0.0001925" + }, + "coin": "ETH", + "internal_id": "" + }, + "id": 0 + } + ``` -| Structure | Type | Description | -| --------- | ------ | ------------------------------ | -| (none) | string | the internal error description | + #### Response (InvalidFeePolicy error - attempt to use UtxoFixed or UtxoPerKbyte for ETH coin) -### ๐Ÿ“Œ Examples + ```json + { + "mmrpc": "2.0", + "error": "Invalid fee policy: Expected 'EthGas' fee type, found UtxoFixed", + "error_path": "eth", + "error_trace": "eth:535]", + "error_type": "InvalidFeePolicy", + "error_data": "Expected 'EthGas' fee type, found UtxoFixed", + "id": 0 + } + ``` + -#### Withdraw BTC, KMD, and other BTC-based forks +#### Withdraw maximum ```json { - "userpass": "testpsw", "mmrpc": "2.0", + "userpass": "testpsw", "method": "withdraw", "params": { - "coin": "KMD", - "to": "RJTYiYeJ8eVvJ53n2YbrVmxWNNMVZjDGLh", - "amount": "10" + "coin": "ETH", + "to": "0xbab36286672fbdc7b250804bf6d14be0df69fa28", + "max": true }, "id": 0 } @@ -43002,55 +44006,86 @@ The request was failed due to an AtomicDEX API internal error. - #### Response (KMD success) + ##### Response (success) ```json { "mmrpc": "2.0", "result": { "block_height": 0, - "coin": "KMD", + "coin": "ETH", "fee_details": { - "type": "Utxo", - "amount": "0.00001" + "type": "Eth", + "coin": "ETH", + "gas": 21000, + "gas_price": "0.000000001", + "total_fee": "0.000021" }, - "from": ["R9o9xTocqr6CeEDGDH6mEYpwLoMz6jNjMW"], - "my_balance_change": "-10.00001", - "received_by_me": "0.34417325", - "spent_by_me": "10.34418325", - "to": ["RJTYiYeJ8eVvJ53n2YbrVmxWNNMVZjDGLh"], - "total_amount": "10.34418325", - "tx_hash": "3a1c382c50a7d12e4675d12ed7e723ce9f0167693dd75fd772bae8524810e605", - "tx_hex": "0400008085202f890207a8e96978acfb8f0d002c3e4390142810dc6568b48f8cd6d8c71866ad8743c5010000006a47304402201960a7089f2d93480fff68ce0b7ca7bb7a32a52915753ac7ae780abd6162cb1d02202c9b11d442e5f72a532f44ceb10122898d486b1474a10eb981c60c5538b9c82d012102031d4256c4bc9f99ac88bf3dba21773132281f65f9bf23a59928bce08961e2f3ffffffff97f56bf3b0f815bb737b7867e71ddb8198bba3574bb75737ba9c389a4d08edc6000000006a473044022055199d80bd7e2d1b932e54f097c6a15fc4b148d21299dc50067c1da18045f0ed02201d26d85333df65e6daab40a07a0e8a671af9d9b9d92fdf7d7ef97bd868ca545a012102031d4256c4bc9f99ac88bf3dba21773132281f65f9bf23a59928bce08961e2f3ffffffff0200ca9a3b000000001976a91464ae8510aac9546d5e7704e31ce177451386455588acad2a0d02000000001976a91405aab5342166f8594baf17a7d9bef5d56744332788ac00000000000000000000000000000000000000", - "kmd_rewards": { - "amount": "0.0791809", - "claimed_by_my": true - } + "from": ["0xbab36286672fbdc7b250804bf6d14be0df69fa29"], + "my_balance_change": "-10.000021", + "received_by_me": "0", + "spent_by_me": "10.000021", + "to": ["0xbab36286672fbdc7b250804bf6d14be0df69fa28"], + "total_amount": "10.000021", + "tx_hash": "8fbc5538679e4c4b78f8b9db0faf9bf78d02410006e8823faadba8e8ae721d60", + "tx_hex": "f86d820a59843b9aca0082520894bab36286672fbdc7b250804bf6d14be0df69fa28888ac7230489e80000801ba0fee87414a3b40d58043a1ae143f7a75d7f47a24e872b638281c448891fd69452a05b0efcaed9dee1b6d182e3215d91af317d53a627404b0efc5102cfe714c93a28" + }, + "id": 0 + } + ``` + + +##### Withdraw QRC20 coins + + + ```json + { + "mmrpc": "2.0", + "userpass": "testpsw", + "method": "withdraw", + "params": { + "coin": "QRC20", + "to": "qHmJ3KA6ZAjR9wGjpFASn4gtUSeFAqdZgs", + "amount": 10 }, "id": 0 } ``` + - #### Response (NotSufficientBalance error) + + ##### Response (success) ```json { "mmrpc": "2.0", - "error": "Not enough DOC to withdraw: available 69.75066225, required at least 1000.00001", - "error_path": "utxo_common", - "error_trace": "utxo_common:1379] utxo_common:449]", - "error_type": "NotSufficientBalance", - "error_data": { - "coin": "DOC", - "available": "69.75066225", - "required": "1000.00001" + "result": { + "block_height": 0, + "coin": "QRC20", + "timestamp": 1608725061, + "fee_details": { + "type": "Qrc20", + "coin": "tQTUM", + "miner_fee": "0.00000447", + "gas_limit": 100000, + "gas_price": 40, + "total_gas_fee": "0.04" + }, + "from": ["qXxsj5RtciAby9T7m98AgAATL4zTi4UwDG"], + "my_balance_change": "-10", + "received_by_me": "0", + "spent_by_me": "10", + "to": ["qHmJ3KA6ZAjR9wGjpFASn4gtUSeFAqdZgs"], + "total_amount": "10", + "tx_hash": "8fbc5538679e4c4b78f8b9db0faf9bf78d02410006e8823faadba8e8ae721d60", + "tx_hex": "f86d820a59843b9aca0082520894bab36286672fbdc7b250804bf6d14be0df69fa28888ac7230489e80000801ba0fee87414a3b40d58043a1ae143f7a75d7f47a24e872b638281c448891fd69452a05b0efcaed9dee1b6d182e3215d91af317d53a627404b0efc5102cfe714c93a28" }, "id": 0 } ``` -#### Withdraw BTC, KMD, and other BTC-based forks, fixed fee +##### Withdraw QRC20 coins with gas limit ```json @@ -43059,12 +44094,13 @@ The request was failed due to an AtomicDEX API internal error. "userpass": "testpsw", "method": "withdraw", "params": { - "coin": "DOC", - "to": "R9o9xTocqr6CeEDGDH6mEYpwLoMz6jNjMW", - "amount": "1.0", + "coin": "QRC20", + "to": "qHmJ3KA6ZAjR9wGjpFASn4gtUSeFAqdZgs", + "amount": 10, "fee": { - "type": "UtxoFixed", - "amount": "0.1" + "type": "Qrc20Gas", + "gas_limit": 250000, + "gas_price": 40 } }, "id": 0 @@ -43073,35 +44109,36 @@ The request was failed due to an AtomicDEX API internal error. - #### Response (success) - ```json { "mmrpc": "2.0", "result": { - "tx_hex": "0400008085202f8901ef25b1b7417fe7693097918ff90e90bba1351fff1f3a24cb51a9b45c5636e57e010000006b483045022100b05c870fcd149513d07b156e150a22e3e47fab4bb4776b5c2c1b9fc034a80b8f022038b1bf5b6dad923e4fb1c96e2c7345765ff09984de12bbb40b999b88b628c0f9012102031d4256c4bc9f99ac88bf3dba21773132281f65f9bf23a59928bce08961e2f3ffffffff0200e1f505000000001976a91405aab5342166f8594baf17a7d9bef5d56744332788ac8cbaae5f010000001976a91405aab5342166f8594baf17a7d9bef5d56744332788ace87a5e5d000000000000000000000000000000", - "tx_hash": "1ab3bc9308695960bc728fa427ac00d1812c4ae89aaa714c7618cb96d111be58", - "from": ["R9o9xTocqr6CeEDGDH6mEYpwLoMz6jNjMW"], - "to": ["R9o9xTocqr6CeEDGDH6mEYpwLoMz6jNjMW"], - "total_amount": "60.10253836", - "spent_by_me": "60.10253836", - "received_by_me": "60.00253836", - "my_balance_change": "-0.1", "block_height": 0, - "timestamp": 1566472936, + "coin": "QRC20", + "timestamp": 1608725061, "fee_details": { - "type": "Utxo", - "amount": "0.1" + "type": "Qrc20", + "coin": "tQTUM", + "miner_fee": "0.00000447", + "gas_limit": 250000, + "gas_price": 40, + "total_gas_fee": "0.1" }, - "coin": "DOC", - "internal_id": "" + "from": ["qXxsj5RtciAby9T7m98AgAATL4zTi4UwDG"], + "my_balance_change": "-10", + "received_by_me": "0", + "spent_by_me": "10", + "to": ["qHmJ3KA6ZAjR9wGjpFASn4gtUSeFAqdZgs"], + "total_amount": "10", + "tx_hash": "8fbc5538679e4c4b78f8b9db0faf9bf78d02410006e8823faadba8e8ae721d60", + "tx_hex": "f86d820a59843b9aca0082520894bab36286672fbdc7b250804bf6d14be0df69fa28888ac7230489e80000801ba0fee87414a3b40d58043a1ae143f7a75d7f47a24e872b638281c448891fd69452a05b0efcaed9dee1b6d182e3215d91af317d53a627404b0efc5102cfe714c93a28" }, "id": 0 } ``` -#### Withdraw BTC, KMD, and other BTC-based forks, 1 coin per Kbyte fee +##### Withdraw Tendermint coins with a memo and custom gas fee ```json @@ -43110,12 +44147,14 @@ The request was failed due to an AtomicDEX API internal error. "userpass": "testpsw", "method": "withdraw", "params": { - "coin": "DOC", - "to": "R9o9xTocqr6CeEDGDH6mEYpwLoMz6jNjMW", - "amount": "1.0", + "coin": "IRIS", + "to": "iaa16drqvl3u8sukfsu4lm3qsk28jr3fahja9vsv6k", + "amount": 13, + "memo": "It was a bright cold day in April, and the clocks were striking thirteen.", "fee": { - "type": "UtxoPerKbyte", - "amount": "1" + "type": "CosmosGas", + "gas_price": 0.05, + "gas_limit": 150000 } }, "id": 0 @@ -43124,48 +44163,116 @@ The request was failed due to an AtomicDEX API internal error. - #### Response (success) - ```json { "mmrpc": "2.0", "result": { - "tx_hex": "0400008085202f890258be11d196cb18764c71aa9ae84a2c81d100ac27a48f72bc6059690893bcb31a000000006b483045022100ef11280e981be280ca5d24c947842ca6a8689d992b73e3a7eb9ff21070b0442b02203e458a2bbb1f2bf8448fc47c51485015904a5271bb17e14be5afa6625d67b1e8012102031d4256c4bc9f99ac88bf3dba21773132281f65f9bf23a59928bce08961e2f3ffffffff58be11d196cb18764c71aa9ae84a2c81d100ac27a48f72bc6059690893bcb31a010000006b483045022100daaa10b09e7abf9d4f596fc5ac1f2542b8ecfab9bb9f2b02201644944ddc0280022067aa1b91ec821aa48f1d06d34cd26fb69a9f27d59d5eecdd451006940d9e83db012102031d4256c4bc9f99ac88bf3dba21773132281f65f9bf23a59928bce08961e2f3ffffffff0200e1f505000000001976a91405aab5342166f8594baf17a7d9bef5d56744332788acf31c655d010000001976a91405aab5342166f8594baf17a7d9bef5d56744332788accd7c5e5d000000000000000000000000000000", - "tx_hash": "fd115190feec8c0c14df2696969295c59c674886344e5072d64000379101b78c", - "from": ["R9o9xTocqr6CeEDGDH6mEYpwLoMz6jNjMW"], - "to": ["R9o9xTocqr6CeEDGDH6mEYpwLoMz6jNjMW"], - "total_amount": "60.00253836", - "spent_by_me": "60.00253836", - "received_by_me": "59.61874931", - "my_balance_change": "-0.38378905", + "tx_hex": "0ade010a8b010a1c2f636f736d6f732e62616e6b2e763162657461312e4d736753656e64126b0a2a6961613136647271766c33753873756b667375346c6d3371736b32386a72336661686a6139767376366b122a6961613136647271766c33753873756b667375346c6d3371736b32386a72336661686a6139767376366b1a110a05756972697312083133303030303030124949742077617320612062726967687420636f6c642064617920696e20417072696c2c20616e642074686520636c6f636b73207765726520737472696b696e6720746869727465656e2e188f85b50812680a500a460a1f2f636f736d6f732e63727970746f2e736563703235366b312e5075624b657912230a2103d8064eece4fa5c0f8dc0267f68cee9bdd527f9e88f3594a323428718c391ecc212040a020801181d12140a0e0a0575697269731205333835353310a08d061a40a9ac8c4112d7d7252062e289d222a438258a7c49c6657fdcbf831d62fc5eb2d05af46d6b86881335b3bc7ca98b2bfc3ef02ec5adf6768de9a778b282f9cc868e", + "tx_hash": "E00982A2A8442D7140916A34E29E287A0B1CBB4B38940372D1966BA7ACDE5BD6", + "from": ["iaa16drqvl3u8sukfsu4lm3qsk28jr3fahja9vsv6k"], + "to": ["iaa16drqvl3u8sukfsu4lm3qsk28jr3fahja9vsv6k"], + "total_amount": "13.038553", + "spent_by_me": "13.038553", + "received_by_me": "13", + "my_balance_change": "-0.038553", "block_height": 0, - "timestamp": 1566473421, + "timestamp": 0, "fee_details": { - "type": "Utxo", - "amount": "0.38378905" + "type": "Tendermint", + "coin": "IRIS", + "amount": "0.038553", + "gas_limit": 100000 }, - "coin": "DOC", - "internal_id": "" + "coin": "IRIS", + "internal_id": "e00982a2a8442d7140916a34e29e287a0b1cbb4b38940372d1966ba7acde5bd6", + "transaction_type": "StandardTransfer", + "memo": "It was a bright cold day in April, and the clocks were striking thirteen." }, "id": 0 } ``` + + You can see the memo is included on the [block explorer](https://irishub.iobscan.io/#/txs/E00982A2A8442D7140916A34E29E287A0B1CBB4B38940372D1966BA7ACDE5BD6) -#### Withdraw ETH, ERC20, and other ETH-based forks +### Error Responses - +#### InvalidRequest: Unknown fee type + +```json +{ + "mmrpc": "2.0", + "error": "Error parsing request: unknown variant `Tendermint`, expected one of `UtxoFixed`, `UtxoPerKbyte`, `EthGas`, `Qrc20Gas`, `CosmosGas`", + "error_path": "dispatcher", + "error_trace": "dispatcher:109]", + "error_type": "InvalidRequest", + "error_data": "unknown variant `Tendermint`, expected one of `UtxoFixed`, `UtxoPerKbyte`, `EthGas`, `Qrc20Gas`, `CosmosGas`", + "id": 0 +} +``` + +#### InvalidRequest: wrong parameter type + +```json +{ + "mmrpc": "2.0", + "error": "Error parsing request: invalid type: string \"0.1\", expected f64", + "error_path": "dispatcher", + "error_trace": "dispatcher:109]", + "error_type": "InvalidRequest", + "error_data": "invalid type: string \"0.1\", expected f64", + "id": 0 +} +``` + +#### InvalidFeePolicy: attempt to use EthGas for UTXO coin + +```json +{ + "mmrpc": "2.0", + "error": "Invalid fee policy: Expected 'UtxoFixed' or 'UtxoPerKbyte' fee types, found EthGas", + "error_path": "utxo_common", + "error_trace": "utxo_common:1371]", + "error_type": "InvalidFeePolicy", + "error_data": "Expected 'UtxoFixed' or 'UtxoPerKbyte' fee types, found EthGas", + "id": 0 +} +``` +export const title = "AtomicDEX Method: Get Current MTP"; +export const description = "The get_current_mtp method returns the Median Time Past (MTP) from electrum servers for UTXO coins."; + +# get\_current\_mtp + +The `get_current_mtp` method returns the Median Time Past (MTP) from electrum servers for UTXO coins. This information is useful for debugging, specifically in cases where an electrum server has been misconfigured. + +## Arguments + +| Parameter | Type | Description | +| --------- | ------- | --------------------------------------------------------------------------------------- | +| coin | string | A compatible (UTXO) coin's ticker | +| id | integer | Optional. Identifies a request to allow matching it with a response. Defaults to `null` | + +#### Response + +| Parameter | Type | Description | +| --------- | ------- | ------------------------------------------------------------------------------------------------------------- | +| mtp | integer | Unix timestamp | +| id | integer | Identifies a response to allow matching it with a request. Defaults to `null` if `id` not provided in request | + +#### ๐Ÿ“Œ Examples + +#### Command + + ```json { - "mmrpc": "2.0", + "method": "get_current_mtp", "userpass": "testpsw", - "method": "withdraw", + "mmrpc": "2.0", + "id": 42, "params": { - "coin": "ETH", - "to": "0xbab36286672fbdc7b250804bf6d14be0df69fa28", - "amount": 10 - }, - "id": 0 + "coin": "DOC" + } } ``` @@ -43177,48 +44284,49 @@ The request was failed due to an AtomicDEX API internal error. { "mmrpc": "2.0", "result": { - "block_height": 0, - "coin": "ETH", - "fee_details": { - "type": "Eth", - "coin": "ETH", - "gas": 21000, - "gas_price": "0.000000001", - "total_fee": "0.000021" - }, - "from": ["0xbab36286672fbdc7b250804bf6d14be0df69fa29"], - "my_balance_change": "-10.000021", - "received_by_me": "0", - "spent_by_me": "10.000021", - "to": ["0xbab36286672fbdc7b250804bf6d14be0df69fa28"], - "total_amount": "10.000021", - "tx_hash": "8fbc5538679e4c4b78f8b9db0faf9bf78d02410006e8823faadba8e8ae721d60", - "tx_hex": "f86d820a59843b9aca0082520894bab36286672fbdc7b250804bf6d14be0df69fa28888ac7230489e80000801ba0fee87414a3b40d58043a1ae143f7a75d7f47a24e872b638281c448891fd69452a05b0efcaed9dee1b6d182e3215d91af317d53a627404b0efc5102cfe714c93a28" + "mtp": 1658746383 }, - "id": 0 + "id": 42 } ``` +export const title = "AtomicDEX Method: Get Locked Amount"; +export const description = "The get_locked_amount method returns the amount of a coin which is currently locked by a swap which is in progress."; + +# get\_locked\_amount + +The `get_locked_amount` method returns the amount of a coin which is currently locked by a swap which is in progress. If the coin is not activated, a `NoSuchCoin` error will be returned. + +## Arguments + +| Parameter | Type | Description | +| --------- | ------ | ----------------------------------------- | +| coin | string | The ticker of the coin you want to query. | + +#### Response + +| Parameter | Type | Description | +| ----------------------- | --------------- | --------------------------------------------------------------------------------------------- | +| coin | string | The ticker of the coin you queried. | +| locked\_amount | object | An object cointaining the locked amount in decimal, fraction and rational formats. | +| locked\_amount.decimal | numeric string | The locked amount in [decimal format](https://www.mathsisfun.com/definitions/decimal.html). | +| locked\_amount.rational | rational object | The locked amount in [rational format](/atomicdex/api/legacy/rational_number_note/). | +| locked\_amount.fraction | fraction object | The locked amount in [fraction format](https://www.mathsisfun.com/definitions/fraction.html). | -#### ETH/ERC20 and other ETH-based forks, with gas fee +#### ๐Ÿ“Œ Examples - +#### Command + + ```json { - "mmrpc": "2.0", "userpass": "testpsw", - "method": "withdraw", + "mmrpc": "2.0", + "method": "get_locked_amount", "params": { - "coin": "COIN_NAME", - "to": "RECIPIENT_ADDRESS", - "amount": "AMOUNT", - "fee": { - "type": "EthGas", - "gas_price": "3.5", - "gas": 55000 - } + "coin": "DOC" }, - "id": 0 + "id": 42 } ``` @@ -43230,858 +44338,985 @@ The request was failed due to an AtomicDEX API internal error. { "mmrpc": "2.0", "result": { - "tx_hex": "f86d820b2884d09dc30082d6d894bab36286672fbdc7b250804bf6d14be0df69fa29888ac7230489e80000801ca0ef0167b0e53ed50d87b6fd630925f2bce6ee72e9b5fdb51c6499a7caaecaed96a062e5cb954e503ff83f2d6ce082649fdcdf8a77c8d37c7d26d46d3f736b228d10", - "tx_hash": "a26c4dcacf63c04e385dd973ca7e7ca1465a3b904a0893bcadb7e37681d38c95", - "from": ["0xbAB36286672fbdc7B250804bf6D14Be0dF69fa29"], - "to": ["0xbAB36286672fbdc7B250804bf6D14Be0dF69fa29"], - "total_amount": "10", - "spent_by_me": "10.0001925", - "received_by_me": "10", - "my_balance_change": "-0.0001925", - "block_height": 0, - "timestamp": 1566474670, - "fee_details": { - "type": "Eth", - "coin": "ETH", - "gas": 55000, - "gas_price": "0.0000000035", - "total_fee": "0.0001925" - }, - "coin": "ETH", - "internal_id": "" + "coin": "DOC", + "locked_amount": { + "decimal": "0.77803", + "rational": [ + [1, [77803]], + [1, [100000]] + ], + "fraction": { + "numer": "77803", + "denom": "100000" + } + } }, - "id": 0 + "id": 42 } ``` - #### Response (InvalidFeePolicy error - attempt to use UtxoFixed or UtxoPerKbyte for ETH coin) + #### Response (error) ```json { "mmrpc": "2.0", - "error": "Invalid fee policy: Expected 'EthGas' fee type, found UtxoFixed", - "error_path": "eth", - "error_trace": "eth:535]", - "error_type": "InvalidFeePolicy", - "error_data": "Expected 'EthGas' fee type, found UtxoFixed", - "id": 0 + "error": "No such coin: TIME", + "error_path": "lp_swap.lp_coins", + "error_trace": "lp_swap:486] lp_coins:2894]", + "error_type": "NoSuchCoin", + "error_data": { + "coin": "TIME" + }, + "id": 42 } ``` +export const title = "AtomicDEX: HD Address Management"; +export const description = "The methods in this document allow generation of HD addresses on AtomicDEX."; -#### Withdraw maximum +# Heirarchical Deterministic Address Management - +A hierarchical-deterministic (HD) wallet generates a new key pair from a master key pair, allowing for multiple addresses to be generated from the same seed so that change from transactions go to a previously unused address, enhancing privacy and security. The hierarchical structure resembles that of a tree, with the master key โ€œdeterminingโ€ the key pairs that follow it in the hierarchy. If you have activated a coin with the [task::enable\_utxo::init](/atomicdex/api/v20-dev/task_enable_utxo/#init) or [task::enable\_qtum::init](/atomicdex/api/v20-dev/task_enable_qtum/#init) and used the `"priv_key_policy": "Trezor"` parameter, you can use the methods below to generate new addresses. + +## can\_get\_new\_address + +To avoid generating too many addresses at once, we can use a `gap_limit` constraint so that no more than a specific amount of unused addresses can be generated before more addresses can be generated. + +#### Arguments + +| Parameter | Type | Description | +| ----------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| coin | string | The ticker of the coin you want to get a new address for | +| account\_id | integer | Generally this will be `0` unless you have multiple accounts registered on your Trezor | +| chain | string | `Internal`, or `External`. External is used for addresses that are meant to be visible outside of the wallet (e.g. for receiving payments). Internal is used for addresses which are not meant to be visible outside of the wallet and is used for return transaction change. | +| gap\_limit | integer | The maximum number of empty addresses in a row. | + +#### Response + +| Parameter | Type | Description | +| ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------ | +| result | string | Returns with value `success` when successful, otherwise returns the error values below | +| result.allowed | boolean | Whether or not you can get a new address. | +| result.reason | string | The reason you cant get a new address (if allowed is `false`). | +| result.details | object | Contains extra contextual information about the reason why allowed is `false` | +| result.details.address | boolean | If reason is `LastAddressNotUsed`, this is the address that should be used before you can get a new address. | + +Other reasons you might not be able to get a new address are: + +* `EmptyAddressesLimitReached` - Last gap\_limit addresses are still unused. +* `AddressLimitReached` - Addresses limit reached. Currently, the limit is [2^31](https://www.wolframalpha.com/input?i=2%5E%2832%29) + +#### ๐Ÿ“Œ Examples + +#### Command + + ```json { - "mmrpc": "2.0", "userpass": "testpsw", - "method": "withdraw", + "mmrpc": "2.0", + "method": "can_get_new_address", "params": { - "coin": "ETH", - "to": "0xbab36286672fbdc7b250804bf6d14be0df69fa28", - "max": true - }, - "id": 0 + "coin": "DOC", + "account_id": 0, + "chain": "External", + "gap_limit": 20 + } } ``` - ##### Response (success) + #### Response (success, allowed) ```json { "mmrpc": "2.0", "result": { - "block_height": 0, - "coin": "ETH", - "fee_details": { - "type": "Eth", - "coin": "ETH", - "gas": 21000, - "gas_price": "0.000000001", - "total_fee": "0.000021" - }, - "from": ["0xbab36286672fbdc7b250804bf6d14be0df69fa29"], - "my_balance_change": "-10.000021", - "received_by_me": "0", - "spent_by_me": "10.000021", - "to": ["0xbab36286672fbdc7b250804bf6d14be0df69fa28"], - "total_amount": "10.000021", - "tx_hash": "8fbc5538679e4c4b78f8b9db0faf9bf78d02410006e8823faadba8e8ae721d60", - "tx_hex": "f86d820a59843b9aca0082520894bab36286672fbdc7b250804bf6d14be0df69fa28888ac7230489e80000801ba0fee87414a3b40d58043a1ae143f7a75d7f47a24e872b638281c448891fd69452a05b0efcaed9dee1b6d182e3215d91af317d53a627404b0efc5102cfe714c93a28" - }, - "id": 0 - } - ``` - - -##### Withdraw QRC20 coins - - - ```json - { - "mmrpc": "2.0", - "userpass": "testpsw", - "method": "withdraw", - "params": { - "coin": "QRC20", - "to": "qHmJ3KA6ZAjR9wGjpFASn4gtUSeFAqdZgs", - "amount": 10 + "allowed": true }, - "id": 0 + "id": null } ``` - - - ##### Response (success) + #### Response (success, not allowed) ```json { "mmrpc": "2.0", "result": { - "block_height": 0, - "coin": "QRC20", - "timestamp": 1608725061, - "fee_details": { - "type": "Qrc20", - "coin": "tQTUM", - "miner_fee": "0.00000447", - "gas_limit": 100000, - "gas_price": 40, - "total_gas_fee": "0.04" - }, - "from": ["qXxsj5RtciAby9T7m98AgAATL4zTi4UwDG"], - "my_balance_change": "-10", - "received_by_me": "0", - "spent_by_me": "10", - "to": ["qHmJ3KA6ZAjR9wGjpFASn4gtUSeFAqdZgs"], - "total_amount": "10", - "tx_hash": "8fbc5538679e4c4b78f8b9db0faf9bf78d02410006e8823faadba8e8ae721d60", - "tx_hex": "f86d820a59843b9aca0082520894bab36286672fbdc7b250804bf6d14be0df69fa28888ac7230489e80000801ba0fee87414a3b40d58043a1ae143f7a75d7f47a24e872b638281c448891fd69452a05b0efcaed9dee1b6d182e3215d91af317d53a627404b0efc5102cfe714c93a28" + "allowed": false, + "reason": "LastAddressNotUsed", + "details": { + "address": "RMHFCEWacWP7dYw1DWxH3TF5YW8q8hM5z7" + } }, - "id": 0 + "id": null } ``` -##### Withdraw QRC20 coins with gas limit +## get\_new\_address - +If we don't already have too many unused addresses, we can use the `get_new_address` method to generate a new address. The generated address will be shown in account\_balance and init\_account\_balance RPCs and on the next coin activation. + +#### Arguments + +| Parameter | Type | Description | +| ----------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| coin | string | The ticker of the coin you want to get a new address for | +| account\_id | integer | Generally this will be `0` unless you have multiple accounts registered on your Trezor | +| chain | string | `Internal`, or `External`. External is used for addresses that are meant to be visible outside of the wallet (e.g. for receiving payments). Internal is used for addresses which are not meant to be visible outside of the wallet and is used for return transaction change. | +| gap\_limit | integer | The maximum number of empty addresses in a row. | + +#### Response + +| Parameter | Type | Description | +| ---------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| result | string | Returns with value `success` when successful, otherwise returns the error values below | +| result.new\_address | object | Contains details about your new address. | +| result.address | string | The new address that was generated. | +| result.details | object | Contains extra contextual information about the reason why allowed is `false` | +| result.details.address | boolean | If reason is `LastAddressNotUsed`, this is the address that should be used before you can get a new address. | +| result.details.derivation\_path | string | The [BIP44 derivation path](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki) of the address. | +| result.details.chain | string | `External` or `Internal` External is used for addresses that are meant to be visible outside of the wallet (e.g. for receiving payments). Internal is used for addresses which are not meant to be visible outside of the wallet and is used for return transaction change. | +| result.details.balance | object | Contains the spendable and unspendable balance for this address | +| result.details.balance.spendable | string(numeric) | Spendable balance for this address | +| result.details.balance.unspendable | string(numeric) | Unspendable balance for this address (e.g. from unconfirmed incoming transactions) | + +Other reasons you might not be able to get a new address are: + +* `EmptyAddressesLimitReached` - Last gap\_limit addresses are still unused. +* `AddressLimitReached` - Addresses limit reached. Currently, the limit is [2^31](https://www.wolframalpha.com/input?i=2%5E%2832%29) + +#### ๐Ÿ“Œ Examples + +#### Command + + ```json { - "mmrpc": "2.0", "userpass": "testpsw", - "method": "withdraw", + "mmrpc": "2.0", + "method": "get_new_address", "params": { - "coin": "QRC20", - "to": "qHmJ3KA6ZAjR9wGjpFASn4gtUSeFAqdZgs", - "amount": 10, - "fee": { - "type": "Qrc20Gas", - "gas_limit": 250000, - "gas_price": 40 - } - }, - "id": 0 + "coin": "DOC", + "account_id": 0, + "chain": "External", + "gap_limit": 20 + } } ``` + #### Response (success) + ```json { "mmrpc": "2.0", "result": { - "block_height": 0, - "coin": "QRC20", - "timestamp": 1608725061, - "fee_details": { - "type": "Qrc20", - "coin": "tQTUM", - "miner_fee": "0.00000447", - "gas_limit": 250000, - "gas_price": 40, - "total_gas_fee": "0.1" - }, - "from": ["qXxsj5RtciAby9T7m98AgAATL4zTi4UwDG"], - "my_balance_change": "-10", - "received_by_me": "0", - "spent_by_me": "10", - "to": ["qHmJ3KA6ZAjR9wGjpFASn4gtUSeFAqdZgs"], - "total_amount": "10", - "tx_hash": "8fbc5538679e4c4b78f8b9db0faf9bf78d02410006e8823faadba8e8ae721d60", - "tx_hex": "f86d820a59843b9aca0082520894bab36286672fbdc7b250804bf6d14be0df69fa28888ac7230489e80000801ba0fee87414a3b40d58043a1ae143f7a75d7f47a24e872b638281c448891fd69452a05b0efcaed9dee1b6d182e3215d91af317d53a627404b0efc5102cfe714c93a28" + "allowed": true }, - "id": 0 + "id": null } ``` - -##### Withdraw Tendermint coins with a memo and custom gas fee + #### Response (success, not allowed) - ```json { "mmrpc": "2.0", - "userpass": "testpsw", - "method": "withdraw", - "params": { - "coin": "IRIS", - "to": "iaa16drqvl3u8sukfsu4lm3qsk28jr3fahja9vsv6k", - "amount": 13, - "memo": "It was a bright cold day in April, and the clocks were striking thirteen.", - "fee": { - "type": "CosmosGas", - "gas_price": 0.05, - "gas_limit": 150000 + "result": { + "new_address": { + "address": "RRqF4cYniMwYs66S4QDUUZ4GJQFQF69rBE", + "derivation_path": "m/44'/141'/0'/0/3", + "chain": "External", + "balance": { + "spendable": "0", + "unspendable": "0" + } } }, - "id": 0 + "id": null } ``` - + +export const title = "AtomicDEX: HD Wallets Overview"; +export const description = + "This document describes all the methods available to activate coins, generate addresses etc., in Hardware Wallet mode."; - - ```json - { - "mmrpc": "2.0", - "result": { - "tx_hex": "0ade010a8b010a1c2f636f736d6f732e62616e6b2e763162657461312e4d736753656e64126b0a2a6961613136647271766c33753873756b667375346c6d3371736b32386a72336661686a6139767376366b122a6961613136647271766c33753873756b667375346c6d3371736b32386a72336661686a6139767376366b1a110a05756972697312083133303030303030124949742077617320612062726967687420636f6c642064617920696e20417072696c2c20616e642074686520636c6f636b73207765726520737472696b696e6720746869727465656e2e188f85b50812680a500a460a1f2f636f736d6f732e63727970746f2e736563703235366b312e5075624b657912230a2103d8064eece4fa5c0f8dc0267f68cee9bdd527f9e88f3594a323428718c391ecc212040a020801181d12140a0e0a0575697269731205333835353310a08d061a40a9ac8c4112d7d7252062e289d222a438258a7c49c6657fdcbf831d62fc5eb2d05af46d6b86881335b3bc7ca98b2bfc3ef02ec5adf6768de9a778b282f9cc868e", - "tx_hash": "E00982A2A8442D7140916A34E29E287A0B1CBB4B38940372D1966BA7ACDE5BD6", - "from": ["iaa16drqvl3u8sukfsu4lm3qsk28jr3fahja9vsv6k"], - "to": ["iaa16drqvl3u8sukfsu4lm3qsk28jr3fahja9vsv6k"], - "total_amount": "13.038553", - "spent_by_me": "13.038553", - "received_by_me": "13", - "my_balance_change": "-0.038553", - "block_height": 0, - "timestamp": 0, - "fee_details": { - "type": "Tendermint", - "coin": "IRIS", - "amount": "0.038553", - "gas_limit": 100000 - }, - "coin": "IRIS", - "internal_id": "e00982a2a8442d7140916a34e29e287a0b1cbb4b38940372d1966ba7acde5bd6", - "transaction_type": "StandardTransfer", - "memo": "It was a bright cold day in April, and the clocks were striking thirteen." - }, - "id": 0 - } - ``` +# HD Wallets Overview - You can see the memo is included on the [block explorer](https://irishub.iobscan.io/#/txs/E00982A2A8442D7140916A34E29E287A0B1CBB4B38940372D1966BA7ACDE5BD6) - +The AtomicDEX API now is able to activate coins in Iguana and HW modes simultaneously! -### Error Responses +For example, you can activate DOC with seed phrase or private key in Iguana mode and also activate MARTY with a Hardware wallet or using a HD account at the same time. -#### InvalidRequest: Unknown fee type +To get started, [configure and launch the AtomicDEX API](/atomicdex/setup/), then plug in your Trezor hardware wallet device. + +## Initialisation and authentication: + +* Initialise connection with your Trezor with [task::init\_trezor::init](/atomicdex/api/v20-dev/task_init_trezor/#init) +* Check the status of the connecton with [task::init\_trezor::status](/atomicdex/api/v20-dev/task_init_trezor/#status) +* Cancel authentication process with [task::init\_trezor::cancel](/atomicdex/api/v20-dev/task_init_trezor/#cancel) +* Authenticate using PIN or phrase with [task::init\_trezor::user\_action](/atomicdex/api/v20-dev/task_init_trezor/#user-action) + +## UTXO Coin Activation in Hardware Mode: + +* Use [task::enable\_utxo::init](/atomicdex/api/v20-dev/task_enable_utxo/#init) for UTXO coins like KMD, BTC and DOGE. +* Check the activation status with [task::enable\_utxo::status](/atomicdex/api/v20-dev/task_enable_utxo/#status) +* Authenticate the activation with [task::enable\_utxo::user\_action](/atomicdex/api/v20-dev/task_enable_utxo/#user-action) + +## QTUM Coin Activation in Hardware Mode: + +* Use [task::enable\_qtum::init](/atomicdex/api/v20-dev/task_enable_qtum/#init) for QTUM Ecosystem coins. +* Check the activation status with [task::enable\_qtum::status](/atomicdex/api/v20-dev/task_enable_qtum/#status) +* Authenticate the activation with [task::enable\_qtum::user\_action](/atomicdex/api/v20-dev/task_enable_qtum/#user-action) + +## Withdrawing your Funds: + +* Prepare a transaction with [task::withdraw::init](/atomicdex/api/v20-dev/task_withdraw/#init) +* Check the status of the transaction preparation with [task::withdraw::status](/atomicdex/api/v20-dev/task_withdraw/#status) +* Cancel the transaction preparation with [task::withdraw::cancel](/atomicdex/api/v20-dev/task_withdraw/#cancel) + +## Viewing Hardware Wallet Coin Balances: + +* Initialise the balance request with [task::account\_balance::init](/atomicdex/api/v20-dev/task_account_balance/#init) +* Check the status of the balance request with [task::account\_balance::status](/atomicdex/api/v20-dev/task_account_balance/#status) + +## Creating New Addresses: + +* Use [can\_get\_new\_address](/atomicdex/api/v20-dev/hd_address_management/#can-get-new-address) to determine if your current address has been used, or should be updated. +* Use [get\_new\_address](/atomicdex/api/v20-dev/hd_address_management/#get-new-address) to generate a new address + + + These methods (and others with a `task::` prefix) will be linked to a numeric + `task_id` value which is used to query the status or outcome of the task. + + +## Details for HwError error type + +When requesting the status of a task, if an `error_type` of `HwError` is returned, the GUI / User should check the details in `error_data` field to know which action is required (as detailed below). + +### FoundUnexpectedDevice + +The connected Trezor device has a different pubkey value than what was specified in the `device_pubkey` parameter ```json { - "mmrpc": "2.0", - "error": "Error parsing request: unknown variant `Tendermint`, expected one of `UtxoFixed`, `UtxoPerKbyte`, `EthGas`, `Qrc20Gas`, `CosmosGas`", - "error_path": "dispatcher", - "error_trace": "dispatcher:109]", - "error_type": "InvalidRequest", - "error_data": "unknown variant `Tendermint`, expected one of `UtxoFixed`, `UtxoPerKbyte`, `EthGas`, `Qrc20Gas`, `CosmosGas`", - "id": 0 + "mmrpc": "2.0", + "result": { + "status": "Error", + "details": { + "error": "Found unexpected device. Please re-initialize Hardware wallet", + "error_path": "lib.common_impl.coin_balance.utxo_common.hd_pubkey.hw_ctx", + "error_trace": "lib:93] common_impl:46] coin_balance:304] utxo_common:163] hd_pubkey:176] hw_ctx:149]", + "error_type": "HwError", + "error_data": "FoundUnexpectedDevice" + } + }, + "id": null +} +``` + +### FoundMultipleDevices + +Multiple Trezor devices are plugged in. Remove the additional devices, and keep the one you want to use plugged in. + +```json +{ + "mmrpc": "2.0", + "result": { + "status": "Error", + "details": { + "error": "Found multiple devices. Please unplug unused devices", + "error_path": "init_hw.crypto_ctx.hw_client", + "error_trace": "init_hw:151] crypto_ctx:248] crypto_ctx:354] hw_client:152] hw_client:126]", + "error_type": "HwError", + "error_data": "FoundMultipleDevices" + } + }, + "id": null +} +``` + +### NoTrezorDeviceAvailable + +No Trezor device detected by the AtomicDEX API. Make sure it is plugged in, or try a different USB cable / port. + +```json +{ + "mmrpc": "2.0", + "result": { + "status": "Error", + "details": { + "error": "No Trezor device available", + "error_path": "init_hw.crypto_ctx.hw_ctx.response.usb.libusb", + "error_trace": "init_hw:151] crypto_ctx:248] crypto_ctx:354] hw_ctx:120] response:136] usb:46] libusb:195]", + "error_type": "HwError", + "error_data": "NoTrezorDeviceAvailable" + } + }, + "id": null } ``` +export const title = "AtomicDEX API RPC Protocol v2.0 (Dev)"; +export const description = "AtomicDEX API now supports mmrpc 2.0 protocol format, providing a standardized format for requests, successful responses, and error responses."; + +# AtomicDEX API RPC Protocol v2.0 (Dev) + +Starting with version [beta-2.1.3434](https://github.com/KomodoPlatform/komodo-defi-framework/releases/tag/beta-2.1.3434), the AtomicDEX API supports the standardized protocol format called `mmrpc 2.0`. + +It includes a uniform request, successful and error response formats. At the moment, only a few RPC methods support the `mmrpc 2.0` protocol. + +## Request + +| Structure | Type | Description | +| --------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| mmrpc | string | the string specifying the version of the AtomicDEX API RPC protocol. Must be exactly "2.0" | +| userpass | string (optional) | your password for protected RPC methods. Skip this field if the specified `method` is public | +| method | string | the name of the method to be invoked | +| params | object (optional) | a structured value that holds the parameter values to be used during the invocation of the method. This field may be omitted if the method doesn't take arguments | +| id | number (optional) | the identifier is established by the client. AtomicDEX API will reply with the same value in the Response object if the `id` field is included and not `NULL` | + +### Response (Success) + +| Structure | Type | Description | +| --------- | ----------------- | ------------------------------------------------------------------------------------------- | +| mmrpc | string | the string specifying the version of the AtomicDEX API RPC protocol | +| result | object | the value of this field is determined by the method invoked on AtomicDEX API | +| id | number (optional) | the identifier established by the client. The same value as in the Request if it was passed | + +### Response (Error) + +| Structure | Type | Description | +| ------------ | ----------------- | ------------------------------------------------------------------------------------------- | +| mmrpc | string | the string specifying the version of the AtomicDEX API RPC protocol | +| error | string | the common error description | +| error\_path | string | the error path consisting of file names separated by a dot similar to JSON path notation | +| error\_trace | string | the error path consisting of file and line number pairs separated by ']' | +| error\_type | string | the string error identifier used to determine the cause of the error | +| error\_data | object | an object containing the error data of the corresponding `error_type` | +| id | number (optional) | the identifier established by the client. The same value as in the Request if it was passed | + +### ๐Ÿ“Œ Examples + +#### Command + + + ```json + { + "mmrpc": "2.0", + "userpass": "testpsw", + "method": "withdraw", + "params": { + "coin": "KMD", + "to": "RJTYiYeJ8eVvJ53n2YbrVmxWNNMVZjDGLh", + "amount": "10" + }, + "id": 0 + } + ``` + -#### InvalidRequest: wrong parameter type +#### Response (success) ```json { - "mmrpc": "2.0", - "error": "Error parsing request: invalid type: string \"0.1\", expected f64", - "error_path": "dispatcher", - "error_trace": "dispatcher:109]", - "error_type": "InvalidRequest", - "error_data": "invalid type: string \"0.1\", expected f64", - "id": 0 + "mmrpc": "2.0", + "result": { + "tx_hex": "0400008085202f8901ef25b1b7417fe7693097918ff90e90bba1351fff1f3a24cb51a9b45c5636e57e010000006b483045022100b05c870fcd149513d07b156e150a22e3e47fab4bb4776b5c2c1b9fc034a80b8f022038b1bf5b6dad923e4fb1c96e2c7345765ff09984de12bbb40b999b88b628c0f9012102031d4256c4bc9f99ac88bf3dba21773132281f65f9bf23a59928bce08961e2f3ffffffff0200e1f505000000001976a91405aab5342166f8594baf17a7d9bef5d56744332788ac8cbaae5f010000001976a91405aab5342166f8594baf17a7d9bef5d56744332788ace87a5e5d000000000000000000000000000000", + "tx_hash": "1ab3bc9308695960bc728fa427ac00d1812c4ae89aaa714c7618cb96d111be58", + "from": ["R9o9xTocqr6CeEDGDH6mEYpwLoMz6jNjMW"], + "to": ["R9o9xTocqr6CeEDGDH6mEYpwLoMz6jNjMW"], + "total_amount": "60.10253836", + "spent_by_me": "60.10253836", + "received_by_me": "60.00253836", + "my_balance_change": "-0.1", + "block_height": 0, + "timestamp": 1566472936, + "fee_details": { + "type": "Utxo", + "amount": "0.1" + }, + "coin": "DOC", + "internal_id": "" + }, + "id": 0 } ``` -#### InvalidFeePolicy: attempt to use EthGas for UTXO coin +#### Response (error) ```json { "mmrpc": "2.0", - "error": "Invalid fee policy: Expected 'UtxoFixed' or 'UtxoPerKbyte' fee types, found EthGas", + "error": "The amount 0.000005 is too small", "error_path": "utxo_common", - "error_trace": "utxo_common:1371]", - "error_type": "InvalidFeePolicy", - "error_data": "Expected 'UtxoFixed' or 'UtxoPerKbyte' fee types, found EthGas", + "error_trace": "utxo_common:1379] utxo_common:301]", + "error_type": "AmountIsTooSmall", + "error_data": { + "amount": "0.000005" + }, "id": 0 } ``` -export const title = "AtomicDEX Method: Get Current MTP"; -export const description = "The get_current_mtp method returns the Median Time Past (MTP) from electrum servers for UTXO coins."; +export const title = "AtomicDEX: Lightning Network Initialization Tasks"; +export const description = "The methods in this document allow initialization of Lightning Network on AtomicDEX-API."; -# get\_current\_mtp +# Lightning Network Initialization Tasks -The `get_current_mtp` method returns the Median Time Past (MTP) from electrum servers for UTXO coins. This information is useful for debugging, specifically in cases where an electrum server has been misconfigured. + + Lightning methods are currently only available using the native AtomicDEX-API. WASM support should be available in late 2023. + -## Arguments +## Initialize Lightning {{label : 'task::enable_lightning::init', tag : 'API-v2'}} -| Parameter | Type | Description | -| --------- | ------- | --------------------------------------------------------------------------------------- | -| coin | string | A compatible (UTXO) coin's ticker | -| id | integer | Optional. Identifies a request to allow matching it with a response. Defaults to `null` | +The `task::enable_lightning::init` request a task to run a lightning node. Use the returned `task_id` as an input to check the status of the lightning node (i.e, running or still initiating). An error will be returned if a lightning node was already running for the requested ticker. -#### Response + + Any methods with a `task::` prefix will be linked to a numeric `task_id` value which is used to query the status or outcome of the task. + -| Parameter | Type | Description | -| --------- | ------- | ------------------------------------------------------------------------------------------------------------- | -| mtp | integer | Unix timestamp | -| id | integer | Identifies a response to allow matching it with a request. Defaults to `null` if `id` not provided in request | +### Request Parameters -#### ๐Ÿ“Œ Examples +| Parameter | Type | Description | +| ------------------ | ------ | ----------------------------------------------------------------------------------------------------------------------- | +| ticker | string | Ticker of coin to activate | +| activation\_params | object | A standard [LightningActivationParams](/atomicdex/api/common_structures/lightning/#lightning-activation-params) object. | -#### Command +#### ๐Ÿ“Œ Example - + ```json { - "method": "get_current_mtp", + "method": "task::enable_lightning::init", "userpass": "testpsw", "mmrpc": "2.0", - "id": 42, "params": { - "coin": "DOC" - } + "ticker": "tBTC-lightning", + "activation_params": { + "name": "AtomicDEX-Docs-Node-1", + "listening_port": 9735, + "color": "000000", + "payment_retries": 5 + } + }, + "id": 2 } ``` - #### Response (success) + ### Response Parameters + + | Parameter | Type | Description | + | --------- | ------- | --------------------------------------------------------- | + | task\_id | integer | An identifying number which is used to query task status. | + + #### Response ```json { - "mmrpc": "2.0", - "result": { - "mtp": 1658746383 - }, - "id": 42 + "mmrpc": "2.0", + "result": { + "task_id": 1 + }, + "id": null } ``` -export const title = "AtomicDEX Method: Get Locked Amount"; -export const description = "The get_locked_amount method returns the amount of a coin which is currently locked by a swap which is in progress."; - -# get\_locked\_amount - -The `get_locked_amount` method returns the amount of a coin which is currently locked by a swap which is in progress. If the coin is not activated, a `NoSuchCoin` error will be returned. - -## Arguments - -| Parameter | Type | Description | -| --------- | ------ | ----------------------------------------- | -| coin | string | The ticker of the coin you want to query. | - -#### Response - -| Parameter | Type | Description | -| ----------------------- | --------------- | --------------------------------------------------------------------------------------------- | -| coin | string | The ticker of the coin you queried. | -| locked\_amount | object | An object cointaining the locked amount in decimal, fraction and rational formats. | -| locked\_amount.decimal | numeric string | The locked amount in [decimal format](https://www.mathsisfun.com/definitions/decimal.html). | -| locked\_amount.rational | rational object | The locked amount in [rational format](/atomicdex/api/legacy/rational_number_note/). | -| locked\_amount.fraction | fraction object | The locked amount in [fraction format](https://www.mathsisfun.com/definitions/fraction.html). | -#### ๐Ÿ“Œ Examples + + #### L2ConfigIsNotFound Error -#### Command + Coin is not in `coins` file. Refer to the [coins file configuration for lightning](/atomicdex/api/v20-dev/lightning/#lightning-coin-config-parameters) for more information. - ```json { - "userpass": "testpsw", - "mmrpc": "2.0", - "method": "get_locked_amount", - "params": { - "coin": "DOC" - }, - "id": 42 + "mmrpc": "2.0", + "error": "Layer 2 tBTC-lightning config is not found", + "error_path": "init_l2.prelude", + "error_trace": "init_l2:82] prelude:82]", + "error_type": "L2ConfigIsNotFound", + "error_data": "tBTC-lightning", + "id": 2 } ``` - - - - #### Response (success) - ```json - { - "mmrpc": "2.0", - "result": { - "coin": "DOC", - "locked_amount": { - "decimal": "0.77803", - "rational": [ - [1, [77803]], - [1, [100000]] - ], - "fraction": { - "numer": "77803", - "denom": "100000" - } - } - }, - "id": 42 - } - ``` + #### InvalidRequest Error - #### Response (error) + A parameter is incorrect. ```json { - "mmrpc": "2.0", - "error": "No such coin: TIME", - "error_path": "lp_swap.lp_coins", - "error_trace": "lp_swap:486] lp_coins:2894]", - "error_type": "NoSuchCoin", - "error_data": { - "coin": "TIME" - }, - "id": 42 + "mmrpc": "2.0", + "error": "Error parsing request: invalid type: string "9735", expected u16", + "error_path": "dispatcher", + "error_trace": "dispatcher:110]", + "error_type": "InvalidRequest", + "error_data": "invalid type: string "9735", expected u16", + "id": 762 } ``` - -export const title = "AtomicDEX: HD Address Management"; -export const description = "The methods in this document allow generation of HD addresses on AtomicDEX."; - -# Heirarchical Deterministic Address Management - -A hierarchical-deterministic (HD) wallet generates a new key pair from a master key pair, allowing for multiple addresses to be generated from the same seed so that change from transactions go to a previously unused address, enhancing privacy and security. The hierarchical structure resembles that of a tree, with the master key โ€œdeterminingโ€ the key pairs that follow it in the hierarchy. If you have activated a coin with the [task::enable\_utxo::init](/atomicdex/api/v20-dev/task_enable_utxo/#init) or [task::enable\_qtum::init](/atomicdex/api/v20-dev/task_enable_qtum/#init) and used the `"priv_key_policy": "Trezor"` parameter, you can use the methods below to generate new addresses. - -## can\_get\_new\_address - -To avoid generating too many addresses at once, we can use a `gap_limit` constraint so that no more than a specific amount of unused addresses can be generated before more addresses can be generated. - -#### Arguments - -| Parameter | Type | Description | -| ----------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| coin | string | The ticker of the coin you want to get a new address for | -| account\_id | integer | Generally this will be `0` unless you have multiple accounts registered on your Trezor | -| chain | string | `Internal`, or `External`. External is used for addresses that are meant to be visible outside of the wallet (e.g. for receiving payments). Internal is used for addresses which are not meant to be visible outside of the wallet and is used for return transaction change. | -| gap\_limit | integer | The maximum number of empty addresses in a row. | - -#### Response - -| Parameter | Type | Description | -| ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------ | -| result | string | Returns with value `success` when successful, otherwise returns the error values below | -| result.allowed | boolean | Whether or not you can get a new address. | -| result.reason | string | The reason you cant get a new address (if allowed is `false`). | -| result.details | object | Contains extra contextual information about the reason why allowed is `false` | -| result.details.address | boolean | If reason is `LastAddressNotUsed`, this is the address that should be used before you can get a new address. | - -Other reasons you might not be able to get a new address are: - -* `EmptyAddressesLimitReached` - Last gap\_limit addresses are still unused. -* `AddressLimitReached` - Addresses limit reached. Currently, the limit is [2^31](https://www.wolframalpha.com/input?i=2%5E%2832%29) -#### ๐Ÿ“Œ Examples + #### UnexpectedL2Protocol Error -#### Command + Coin is wrong protocol type. - ```json { - "userpass": "testpsw", - "mmrpc": "2.0", - "method": "can_get_new_address", - "params": { - "coin": "DOC", - "account_id": 0, - "chain": "External", - "gap_limit": 20 - } + "mmrpc": "2.0", + "error": "Unexpected layer 2 protocol UTXO for tBTC-segwit", + "error_path": "init_l2.prelude.lightning_activation", + "error_trace": "init_l2:82] prelude:93] lightning_activation:92]", + "error_type": "UnexpectedL2Protocol", + "error_data": { + "ticker": "tBTC-segwit", + "protocol": { + "type": "UTXO" + } + }, + "id": 2 } ``` - - - #### Response (success, allowed) + #### Internal Error + + Address already in use. ```json { - "mmrpc": "2.0", - "result": { - "allowed": true - }, - "id": null + "mmrpc": "2.0", + "result": { + "status": "Error", + "details": { + "error": "I/O error Address already in use (os error 48)", + "error_path": "lib.lightning_activation.ln_p2p", + "error_trace": "lib:103] lightning_activation:280] ln_p2p:196]", + "error_type": "Internal", + "error_data": "I/O error Address already in use (os error 48)" + } + }, + "id": null } ``` - #### Response (success, not allowed) + #### PlatformCoinIsNotActivated Error + + The selected coin is not activated. It needs to be activated before the lightning node can be initialized. ```json { - "mmrpc": "2.0", - "result": { - "allowed": false, - "reason": "LastAddressNotUsed", - "details": { - "address": "RMHFCEWacWP7dYw1DWxH3TF5YW8q8hM5z7" - } - }, - "id": null + "mmrpc": "2.0", + "error": "Platform coin tBTC-lightning is not activated", + "error_path": "init_l2.lp_coins", + "error_trace": "init_l2:87] lp_coins:3087]", + "error_type": "PlatformCoinIsNotActivated", + "error_data": "tBTC-lightning", + "id": 2 } ``` - - -## get\_new\_address -If we don't already have too many unused addresses, we can use the `get_new_address` method to generate a new address. The generated address will be shown in account\_balance and init\_account\_balance RPCs and on the next coin activation. + + [https://github.com/KomodoPlatform/komodo-docs-mdx/pull/31#discussion\\\_r1197550229](https://github.com/KomodoPlatform/komodo-docs-mdx/pull/31#discussion\\_r1197550229) + Another bug found, will fix it in an upcoming PR. Platform coin should be tBTC-segwit. You can leave as it is in docs until I fix it. + -#### Arguments + #### InvalidPlatformConfiguration Error -| Parameter | Type | Description | -| ----------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| coin | string | The ticker of the coin you want to get a new address for | -| account\_id | integer | Generally this will be `0` unless you have multiple accounts registered on your Trezor | -| chain | string | `Internal`, or `External`. External is used for addresses that are meant to be visible outside of the wallet (e.g. for receiving payments). Internal is used for addresses which are not meant to be visible outside of the wallet and is used for return transaction change. | -| gap\_limit | integer | The maximum number of empty addresses in a row. | + Coin's configuration is missing a required parameter. Refer to the [coins file configuration for lightning](/atomicdex/api/v20-dev/lightning/#lightning-network-coins-file-configuration) for more information. -#### Response + ```json + { + "mmrpc": "2.0", + "error": "Invalid config for platform coin: tBTC-segwit, error: 'avg_blocktime' field is not found in platform coin config", + "error_path": "init_l2.lightning_activation", + "error_trace": "init_l2:95] lightning_activation:254]", + "error_type": "InvalidPlatformConfiguration", + "error_data": { + "platform_coin_ticker": "tBTC-segwit", + "err": "'avg_blocktime' field is not found in platform coin config" + }, + "id": 2 + } + ``` + -| Parameter | Type | Description | -| ---------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| result | string | Returns with value `success` when successful, otherwise returns the error values below | -| result.new\_address | object | Contains details about your new address. | -| result.address | string | The new address that was generated. | -| result.details | object | Contains extra contextual information about the reason why allowed is `false` | -| result.details.address | boolean | If reason is `LastAddressNotUsed`, this is the address that should be used before you can get a new address. | -| result.details.derivation\_path | string | The [BIP44 derivation path](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki) of the address. | -| result.details.chain | string | `External` or `Internal` External is used for addresses that are meant to be visible outside of the wallet (e.g. for receiving payments). Internal is used for addresses which are not meant to be visible outside of the wallet and is used for return transaction change. | -| result.details.balance | object | Contains the spendable and unspendable balance for this address | -| result.details.balance.spendable | string(numeric) | Spendable balance for this address | -| result.details.balance.unspendable | string(numeric) | Unspendable balance for this address (e.g. from unconfirmed incoming transactions) | +## Initialization Status {{label : 'task::enable_lightning::status', tag : 'API-v2'}} -Other reasons you might not be able to get a new address are: +The `task::enable_lightning::status` request checks the status of lightning node initialization. -* `EmptyAddressesLimitReached` - Last gap\_limit addresses are still unused. -* `AddressLimitReached` - Addresses limit reached. Currently, the limit is [2^31](https://www.wolframalpha.com/input?i=2%5E%2832%29) +### Request Parameters -#### ๐Ÿ“Œ Examples +| Parameter | Type | Description | +| -------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------- | +| task\_id | integer | The task id returned from `task::enable_lightning::init` | +| forget\_if\_finished | boolean | Optional, defaults to `true`. If `false`, the status of the `task_id` will still be available after the task has completed. | -#### Command +#### ๐Ÿ“Œ Example - + ```json { "userpass": "testpsw", "mmrpc": "2.0", - "method": "get_new_address", + "method": "task::enable_lightning::status", "params": { - "coin": "DOC", - "account_id": 0, - "chain": "External", - "gap_limit": 20 - } + "task_id": 1, + "forget_if_finished": false + }, + "id": 2 } ``` - #### Response (success) + ### Response Parameters + + | Parameter | Type | Description | + | -------------- | ------ | ---------------------------------------------------------------------------------- | + | platform\_coin | string | The coin ticker for which the lightning node is being intitialized. | + | address | string | This node's address for the activated coin. | + | balance | object | A standard [balanceInfos](/atomicdex/api/common_structures/#balance-infos) object. | + + + The unspendable balance for lightning is different to a layer-1 unspendable balance. The channel reserve is part of the unspendable balance in lightning - the user will get this part of the balance on chain when closing the channel, but it can't be spent on layer 2 (lightning) because it's part of the security mechanism to prevent channel breaches and ensure that both parties fulfill their obligations within the channel. + + + #### Response (ready, success) ```json { - "mmrpc": "2.0", - "result": { - "allowed": true - }, - "id": null + "mmrpc": "2.0", + "result": { + "status": "Ok", + "details": { + "platform_coin": "BTC-segwit", + "address": "0321937a095229510bd2b02a930d7b7eb273147e348ef1086b22e8790e3c609804", + "balance": { + "spendable": "0", + "unspendable": "0" + } + } + }, + "id": null } ``` - #### Response (success, not allowed) + + In the above response spendable will always be 0 since the balance is unspendable until connections with lightning channels counterparties are established. + Using the [my\_balance](/atomicdex/api/legacy/my_balance/) method after the coin is activated will get the spendable balance depending on how many channel counterparties are online. + For exact channels balances and which channels are usable, use [lightning::channels::list\_open\_channels\_by\_filter](/atomicdex/api/v20-dev/lightning/channels/#list-open-channels-by-filter). + + + #### Response (in progress state) ```json { - "mmrpc": "2.0", - "result": { - "new_address": { - "address": "RRqF4cYniMwYs66S4QDUUZ4GJQFQF69rBE", - "derivation_path": "m/44'/141'/0'/0/3", - "chain": "External", - "balance": { - "spendable": "0", - "unspendable": "0" - } - } - }, - "id": null + "mmrpc": "2.0", + "result": { + "status": "InProgress", + "details": "ReadingNetworkGraphFromFile" + }, + "id": null } ``` - -export const title = "AtomicDEX: HD Wallets Overview"; -export const description = - "This document describes all the methods available to activate coins, generate addresses etc., in Hardware Wallet mode."; - -# HD Wallets Overview - -The AtomicDEX API now is able to activate coins in Iguana and HW modes simultaneously! -For example, you can activate DOC with seed phrase or private key in Iguana mode and also activate MARTY with a Hardware wallet or using a HD account at the same time. + Possible in progress statuses: -To get started, [configure and launch the AtomicDEX API](/atomicdex/setup/), then plug in your Trezor hardware wallet device. + * ActivatingCoin + * GettingFeesFromRPC + * ReadingNetworkGraphFromFile + * InitializingChannelManager + * InitializingPeerManager + * ReadingScorerFromFile + * InitializingBackgroundProcessor + * ReadingChannelsAddressesFromFile + -## Initialisation and authentication: +## Cancel Initialization {{label : 'task::enable_lightning::cancel', tag : 'API-v2'}} -* Initialise connection with your Trezor with [task::init\_trezor::init](/atomicdex/api/v20-dev/task_init_trezor/#init) -* Check the status of the connecton with [task::init\_trezor::status](/atomicdex/api/v20-dev/task_init_trezor/#status) -* Cancel authentication process with [task::init\_trezor::cancel](/atomicdex/api/v20-dev/task_init_trezor/#cancel) -* Authenticate using PIN or phrase with [task::init\_trezor::user\_action](/atomicdex/api/v20-dev/task_init_trezor/#user-action) +The `task::enable_lightning::cancel` request cancels lightning node initialization. -## UTXO Coin Activation in Hardware Mode: +### Request Parameters -* Use [task::enable\_utxo::init](/atomicdex/api/v20-dev/task_enable_utxo/#init) for UTXO coins like KMD, BTC and DOGE. -* Check the activation status with [task::enable\_utxo::status](/atomicdex/api/v20-dev/task_enable_utxo/#status) -* Authenticate the activation with [task::enable\_utxo::user\_action](/atomicdex/api/v20-dev/task_enable_utxo/#user-action) +| Parameter | Type | Description | +| --------- | ------- | -------------------------------------------------------- | +| task\_id | integer | The task id returned from `task::enable_lightning::init` | -## QTUM Coin Activation in Hardware Mode: +#### ๐Ÿ“Œ Example -* Use [task::enable\_qtum::init](/atomicdex/api/v20-dev/task_enable_qtum/#init) for QTUM Ecosystem coins. -* Check the activation status with [task::enable\_qtum::status](/atomicdex/api/v20-dev/task_enable_qtum/#status) -* Authenticate the activation with [task::enable\_qtum::user\_action](/atomicdex/api/v20-dev/task_enable_qtum/#user-action) + + ```json + { + "userpass": "testpsw", + "mmrpc": "2.0", + "method": "task::enable_lightning::cancel", + "params": { + "task_id": 1 + }, + "id": 1 + } + ``` + -## Withdrawing your Funds: + + #### Response -* Prepare a transaction with [task::withdraw::init](/atomicdex/api/v20-dev/task_withdraw/#init) -* Check the status of the transaction preparation with [task::withdraw::status](/atomicdex/api/v20-dev/task_withdraw/#status) -* Cancel the transaction preparation with [task::withdraw::cancel](/atomicdex/api/v20-dev/task_withdraw/#cancel) + ```json + { + "mmrpc": "2.0", + "result": "success", + "id": null + } + ``` + -## Viewing Hardware Wallet Coin Balances: + + #### TaskFinished Error -* Initialise the balance request with [task::account\_balance::init](/atomicdex/api/v20-dev/task_account_balance/#init) -* Check the status of the balance request with [task::account\_balance::status](/atomicdex/api/v20-dev/task_account_balance/#status) + Task has already been completed. -## Creating New Addresses: + ```json + { + "mmrpc": "2.0", + "error": "Task is finished already", + "error_path": "init_l2.manager", + "error_trace": "init_l2:157] manager:104]", + "error_type": "TaskFinished", + "error_data": 3, + "id": null + } + ``` + +export const title = "AtomicDEX: Lightning Network Channels"; +export const description = "The methods in this document allow management of Lightning Network Channels on AtomicDEX-API."; -* Use [can\_get\_new\_address](/atomicdex/api/v20-dev/hd_address_management/#can-get-new-address) to determine if your current address has been used, or should be updated. -* Use [get\_new\_address](/atomicdex/api/v20-dev/hd_address_management/#get-new-address) to generate a new address +# Lightning Network Channels - These methods (and others with a `task::` prefix) will be linked to a numeric - `task_id` value which is used to query the status or outcome of the task. + Lightning methods are currently only available using the native AtomicDEX-API. WASM support should be available in late 2023. -## Details for HwError error type - -When requesting the status of a task, if an `error_type` of `HwError` is returned, the GUI / User should check the details in `error_data` field to know which action is required (as detailed below). - -### FoundUnexpectedDevice - -The connected Trezor device has a different pubkey value than what was specified in the `device_pubkey` parameter - -```json -{ - "mmrpc": "2.0", - "result": { - "status": "Error", - "details": { - "error": "Found unexpected device. Please re-initialize Hardware wallet", - "error_path": "lib.common_impl.coin_balance.utxo_common.hd_pubkey.hw_ctx", - "error_trace": "lib:93] common_impl:46] coin_balance:304] utxo_common:163] hd_pubkey:176] hw_ctx:149]", - "error_type": "HwError", - "error_data": "FoundUnexpectedDevice" - } - }, - "id": null -} -``` +## Open Channel {{label : 'lightning::channels::open_channel', tag : 'API-v2'}} -### FoundMultipleDevices +The `lightning::channels::open_channel` method opens a new channel with a remote node. -Multiple Trezor devices are plugged in. Remove the additional devices, and keep the one you want to use plugged in. +### Request Parameters -```json -{ - "mmrpc": "2.0", - "result": { - "status": "Error", - "details": { - "error": "Found multiple devices. Please unplug unused devices", - "error_path": "init_hw.crypto_ctx.hw_client", - "error_trace": "init_hw:151] crypto_ctx:248] crypto_ctx:354] hw_client:152] hw_client:126]", - "error_type": "HwError", - "error_data": "FoundMultipleDevices" - } - }, - "id": null -} -``` +| Parameter | Type | Description | +| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| coin | string | The ticker of the coin you would like to open a channel for. | +| node\_address | string | Lightning node addresses always have a format of `node_pubkey`@`ip_address`:`port`. | +| amount | object | A standard [LightningChannelAmount](/atomicdex/api/common_structures/lightning/#lightning-channel-amount) object. | +| push\_msat | integer | Optional. The amount in millisatoshi to push to the counterparty while openning, to create inbound liquidity for the channel. Using the `push_msat` parameter avoids having to send funds in a separate request later. Please note that the funds given using push\_msat is given unconditionally, meaning that there is no proof of payment in a preimage as with paying an invoice. | +| channel\_options | object | Optional. A standard [LightningChannelOptions](/atomicdex/api/common_structures/lightning/#lightning-channel-options) object. | +| channel\_configs | object | Optional. A standard [LightningChannelConfig](/atomicdex/api/common_structures/lightning/#lightning-channel-config) object. | -### NoTrezorDeviceAvailable +#### ๐Ÿ“Œ Example using an exact amount -No Trezor device detected by the AtomicDEX API. Make sure it is plugged in, or try a different USB cable / port. + + ```json + { + "userpass": "testpsw", + "mmrpc": "2.0", + "method": "lightning::channels::open_channel", + "params": { + "coin": "tBTC-lightning", + "node_address": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9@203.132.94.196:9735", + "amount": { + "type": "Exact", + "value": 0.004 + } + }, + "id": 22 + } + ``` + -```json -{ - "mmrpc": "2.0", - "result": { - "status": "Error", - "details": { - "error": "No Trezor device available", - "error_path": "init_hw.crypto_ctx.hw_ctx.response.usb.libusb", - "error_trace": "init_hw:151] crypto_ctx:248] crypto_ctx:354] hw_ctx:120] response:136] usb:46] libusb:195]", - "error_type": "HwError", - "error_data": "NoTrezorDeviceAvailable" - } - }, - "id": null -} -``` -export const title = "AtomicDEX API RPC Protocol v2.0 (Dev)"; -export const description = "AtomicDEX API now supports mmrpc 2.0 protocol format, providing a standardized format for requests, successful responses, and error responses."; + + #### Response -# AtomicDEX API RPC Protocol v2.0 (Dev) + ```json + { + "mmrpc": "2.0", + "result": { + "uuid": "434681f8-95e5-484f-af49-fa80d8ae857b", + "node_address": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9@233.112.95.142:9735" + }, + "id": 22 + } + ``` + -Starting with version [beta-2.1.3434](https://github.com/KomodoPlatform/komodo-defi-framework/releases/tag/beta-2.1.3434), the AtomicDEX API supports the standardized protocol format called `mmrpc 2.0`. +#### ๐Ÿ“Œ Example using max available with channel options and configs -It includes a uniform request, successful and error response formats. At the moment, only a few RPC methods support the `mmrpc 2.0` protocol. + + ```json + { + "userpass": "testpsw", + "mmrpc": "2.0", + "method": "lightning::channels::open_channel", + "params": { + "coin": "tBTC-lightning", + "node_address": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9@203.132.94.196:9735", + "amount": { + "type": "Max" + }, + "push_msat": 0, + "channel_options": { + "proportional_fee_in_millionths_sats": 0, + "base_fee_msat": 1000, + "cltv_expiry_delta": 72, + "max_dust_htlc_exposure_msat": 5000000, + "force_close_avoidance_max_fee_satoshis": 1000 + }, + "channel_configs": { + "counterparty_locktime": 144, + "our_htlc_minimum_msat": 1, + "negotiate_scid_privacy": false, + "max_inbound_in_flight_htlc_percent": 10, + "commit_upfront_shutdown_pubkey": true, + "inbound_channels_confirmations": 3, + "their_channel_reserve_sats": 10000 + } + }, + "id": null + } + ``` + -## Request + + #### Response -| Structure | Type | Description | -| --------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| mmrpc | string | the string specifying the version of the AtomicDEX API RPC protocol. Must be exactly "2.0" | -| userpass | string (optional) | your password for protected RPC methods. Skip this field if the specified `method` is public | -| method | string | the name of the method to be invoked | -| params | object (optional) | a structured value that holds the parameter values to be used during the invocation of the method. This field may be omitted if the method doesn't take arguments | -| id | number (optional) | the identifier is established by the client. AtomicDEX API will reply with the same value in the Response object if the `id` field is included and not `NULL` | + ```json + { + "mmrpc": "2.0", + "result": { + "uuid": "2b50e274-c173-4fa1-95f3-97f9f82ace92", + "node_address": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9@203.132.94.196:9735" + }, + "id": null + } + ``` + -### Response (Success) +## Close Channel {{label : 'lightning::channels::close_channel', tag : 'API-v2'}} -| Structure | Type | Description | -| --------- | ----------------- | ------------------------------------------------------------------------------------------- | -| mmrpc | string | the string specifying the version of the AtomicDEX API RPC protocol | -| result | object | the value of this field is determined by the method invoked on AtomicDEX API | -| id | number (optional) | the identifier established by the client. The same value as in the Request if it was passed | +The `lightning::channels::close_channel` method closes a channel with a remote node. -### Response (Error) +### Request Parameters -| Structure | Type | Description | -| ------------ | ----------------- | ------------------------------------------------------------------------------------------- | -| mmrpc | string | the string specifying the version of the AtomicDEX API RPC protocol | -| error | string | the common error description | -| error\_path | string | the error path consisting of file names separated by a dot similar to JSON path notation | -| error\_trace | string | the error path consisting of file and line number pairs separated by ']' | -| error\_type | string | the string error identifier used to determine the cause of the error | -| error\_data | object | an object containing the error data of the corresponding `error_type` | -| id | number (optional) | the identifier established by the client. The same value as in the Request if it was passed | +| Parameter | Type | Description | +| ------------ | ------- | ---------------------------------------------------------------------------- | +| coin | string | The ticker of the coin you would like to close a channel for. | +| uuid | string | Unique channel identifier. | +| force\_close | boolean | Optional, defaults to `false`. If `true`, will force closure of the channel. | -### ๐Ÿ“Œ Examples + + It is not recommended to force close a channel unless the counterparty is offline or unreachable for a long time. + Force closure of a channel will makeresult in the party who initiates the force closure to wait for a number of blocks (equal to the `force_close_spend_delay` value returned by [lightning::channels::get\_channel\_details](/atomicdex/api/v20-dev/lightning/channels/#get-channel-details)) before they can get their funds on chain. + -#### Command +#### ๐Ÿ“Œ Example to force closing a channel - + ```json { - "mmrpc": "2.0", "userpass": "testpsw", - "method": "withdraw", + "mmrpc": "2.0", + "method": "lightning::channels::close_channel", "params": { - "coin": "KMD", - "to": "RJTYiYeJ8eVvJ53n2YbrVmxWNNMVZjDGLh", - "amount": "10" + "coin": "tBTC-lightning", + "uuid": "2b50e274-c173-4fa1-95f3-97f9f82ace92", + "force_close": true }, - "id": 0 + "id": 8 } ``` -#### Response (success) + + #### Response -```json -{ - "mmrpc": "2.0", - "result": { - "tx_hex": "0400008085202f8901ef25b1b7417fe7693097918ff90e90bba1351fff1f3a24cb51a9b45c5636e57e010000006b483045022100b05c870fcd149513d07b156e150a22e3e47fab4bb4776b5c2c1b9fc034a80b8f022038b1bf5b6dad923e4fb1c96e2c7345765ff09984de12bbb40b999b88b628c0f9012102031d4256c4bc9f99ac88bf3dba21773132281f65f9bf23a59928bce08961e2f3ffffffff0200e1f505000000001976a91405aab5342166f8594baf17a7d9bef5d56744332788ac8cbaae5f010000001976a91405aab5342166f8594baf17a7d9bef5d56744332788ace87a5e5d000000000000000000000000000000", - "tx_hash": "1ab3bc9308695960bc728fa427ac00d1812c4ae89aaa714c7618cb96d111be58", - "from": ["R9o9xTocqr6CeEDGDH6mEYpwLoMz6jNjMW"], - "to": ["R9o9xTocqr6CeEDGDH6mEYpwLoMz6jNjMW"], - "total_amount": "60.10253836", - "spent_by_me": "60.10253836", - "received_by_me": "60.00253836", - "my_balance_change": "-0.1", - "block_height": 0, - "timestamp": 1566472936, - "fee_details": { - "type": "Utxo", - "amount": "0.1" - }, - "coin": "DOC", - "internal_id": "" - }, - "id": 0 -} -``` + ```json + { + "mmrpc": "2.0", + "result": "Initiated closing of channel with uuid: 2b50e274-c173-4fa1-95f3-97f9f82ace92", + "id": 8 + } + ``` -#### Response (error) + + To see if the channel is closed or not, use the [lightning::channels::get\_channel\_details](/atomicdex/api/v20-dev/lightning/channels/#get-channel-details) method. + -```json -{ - "mmrpc": "2.0", - "error": "The amount 0.000005 is too small", - "error_path": "utxo_common", - "error_trace": "utxo_common:1379] utxo_common:301]", - "error_type": "AmountIsTooSmall", - "error_data": { - "amount": "0.000005" - }, - "id": 0 -} -``` -export const title = "AtomicDEX: Lightning Network Initialization Tasks"; -export const description = "The methods in this document allow initialization of Lightning Network on AtomicDEX-API."; + + Already added this message to the response in this upcoming PR KomodoPlatform/atomicDEX-API#1814, also added force\_close\_spend\_delay to the close channel response. No need to change the docs now until this PR is merged KomodoPlatform/atomicDEX-API#1814, I will write a comment about all the changes when opening the PR for review. + [https://github.com/KomodoPlatform/komodo-docs-mdx/pull/31#discussion\\\_r1202462310](https://github.com/KomodoPlatform/komodo-docs-mdx/pull/31#discussion\\_r1202462310) + + -# Lightning Network Initialization Tasks + + #### InvalidRequest Error - - Lightning methods are currently only available using the native AtomicDEX-API. WASM support should be available in late 2023. - + ```json + { + "mmrpc": "2.0", + "error": "Error parsing request: missing field `uuid`", + "error_path": "dispatcher", + "error_trace": "dispatcher:109]", + "error_type": "InvalidRequest", + "error_data": "missing field `uuid`", + "id": 8 + } + ``` -## Initialize Lightning {{label : 'task::enable_lightning::init', tag : 'API-v2'}} + #### NoSuchChannel Error -The `task::enable_lightning::init` request a task to run a lightning node. Use the returned `task_id` as an input to check the status of the lightning node (i.e, running or still initiating). An error will be returned if a lightning node was already running for the requested ticker. + ```json + { + "mmrpc": "2.0", + "error": "No such channel with uuid 2b50e274-c173-4fa1-95f3-97f9f82ace92", + "error_path": "close_channel", + "error_trace": "close_channel:55]", + "error_type": "NoSuchChannel", + "error_data": "2b50e274-c173-4fa1-95f3-97f9f82ace92", + "id": 8 + } + ``` + - - Any methods with a `task::` prefix will be linked to a numeric `task_id` value which is used to query the status or outcome of the task. - +## Update Channel {{label : 'lightning::channels::update_channel', tag : 'API-v2'}} + +The `lightning::channels::update_channel` method updates channel options. ### Request Parameters -| Parameter | Type | Description | -| ------------------ | ------ | ----------------------------------------------------------------------------------------------------------------------- | -| ticker | string | Ticker of coin to activate | -| activation\_params | object | A standard [LightningActivationParams](/atomicdex/api/common_structures/lightning/#lightning-activation-params) object. | +| Parameter | Type | Description | +| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------- | +| coin | string | The ticker of the coin you would like to update channel configuration options for. | +| uuid | string | Unique channel identifier. | +| channel\_options | object | A standard [LightningChannelOptions](/atomicdex/api/common_structures/lightning/#lightning-channel-options) object. | -#### ๐Ÿ“Œ Example +#### ๐Ÿ“Œ Example to update all available channel options - + ```json { - "method": "task::enable_lightning::init", "userpass": "testpsw", "mmrpc": "2.0", + "method": "lightning::channels::update_channel", "params": { - "ticker": "tBTC-lightning", - "activation_params": { - "name": "AtomicDEX-Docs-Node-1", - "listening_port": 9735, - "color": "000000", - "payment_retries": 5 + "coin": "tBTC-lightning", + "uuid": "434681f8-95e5-484f-af49-fa80d8ae857b", + "channel_options": { + "proportional_fee_in_millionths_sats": 1, + "base_fee_msat": 1100, + "cltv_expiry_delta": 72, + "max_dust_htlc_exposure_msat": 5000000, + "force_close_avoidance_max_fee_satoshis": 1000 } }, "id": 2 @@ -44090,255 +45325,246 @@ The `task::enable_lightning::init` request a task to run a lightning node. Use t - ### Response Parameters - - | Parameter | Type | Description | - | --------- | ------- | --------------------------------------------------------- | - | task\_id | integer | An identifying number which is used to query task status. | - #### Response ```json { - "mmrpc": "2.0", - "result": { - "task_id": 1 - }, - "id": null + "mmrpc": "2.0", + "result": { + "channel_options": { + "proportional_fee_in_millionths_sats": 1, + "base_fee_msat": 1100, + "cltv_expiry_delta": 72, + "max_dust_htlc_exposure_msat": 5000000, + "force_close_avoidance_max_fee_sats": null + } + }, + "id": 2 } ``` - #### L2ConfigIsNotFound Error + #### NoSuchChannel Error - Coin is not in `coins` file. Refer to the [coins file configuration for lightning](/atomicdex/api/v20-dev/lightning/#lightning-coin-config-parameters) for more information. + Channel with the given uuid is not foun on the lightning network. ```json { "mmrpc": "2.0", - "error": "Layer 2 tBTC-lightning config is not found", - "error_path": "init_l2.prelude", - "error_trace": "init_l2:82] prelude:82]", - "error_type": "L2ConfigIsNotFound", - "error_data": "tBTC-lightning", + "error": "No such channel with uuid dc33b998-8589-44fd-a246-256a582e8942", + "error_path": "update_channel", + "error_trace": "update_channel:61]", + "error_type": "NoSuchChannel", + "error_data": "dc33b998-8589-44fd-a246-256a582e8942", "id": 2 } ``` + - #### InvalidRequest Error +## Get Channel Details {{label : 'lightning::channels::get_channel_details', tag : 'API-v2'}} - A parameter is incorrect. +The `lightning::channels::get_channel_details` method returns details about a channel. - ```json - { - "mmrpc": "2.0", - "error": "Error parsing request: invalid type: string "9735", expected u16", - "error_path": "dispatcher", - "error_trace": "dispatcher:110]", - "error_type": "InvalidRequest", - "error_data": "invalid type: string "9735", expected u16", - "id": 762 - } - ``` +### Request Parameters - #### UnexpectedL2Protocol Error +| Parameter | Type | Description | +| --------- | ------ | ------------------------------------------------------------------ | +| coin | string | The ticker of the coin you would like to view channel details for. | +| uuid | string | Unique channel identifier. | - Coin is wrong protocol type. +#### ๐Ÿ“Œ Example to update all available channel options + ```json { - "mmrpc": "2.0", - "error": "Unexpected layer 2 protocol UTXO for tBTC-segwit", - "error_path": "init_l2.prelude.lightning_activation", - "error_trace": "init_l2:82] prelude:93] lightning_activation:92]", - "error_type": "UnexpectedL2Protocol", - "error_data": { - "ticker": "tBTC-segwit", - "protocol": { - "type": "UTXO" - } - }, - "id": 2 + "userpass": "testpsw", + "mmrpc": "2.0", + "method": "lightning::channels::get_channel_details", + "params": { + "coin": "tBTC-lightning", + "uuid": "2b50e274-c173-4fa1-95f3-97f9f82ace92" + }, + "id": 54 } ``` + - #### Internal Error + + + The response will vary depending on whether the channel status is `open` or `closed`. + - Address already in use. + #### Response (opened channel) ```json { - "mmrpc": "2.0", - "result": { - "status": "Error", - "details": { - "error": "I/O error Address already in use (os error 48)", - "error_path": "lib.lightning_activation.ln_p2p", - "error_trace": "lib:103] lightning_activation:280] ln_p2p:196]", - "error_type": "Internal", - "error_data": "I/O error Address already in use (os error 48)" - } - }, - "id": null + "mmrpc": "2.0", + "result": { + "status": "Open", + "details": { + "uuid": "2b50e274-c173-4fa1-95f3-97f9f82ace92", + "channel_id": "4a869115dfd260d0925a1266f544a6ab36666448d4bbc0e2a028d8426b2b6d4e", + "counterparty_node_id": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9", + "funding_tx": "4e6d2b6b42d828a0e2c0bbd448646636aba644f566125a92d060d2df1591864a", + "funding_tx_output_index": 0, + "funding_tx_value_sats": 959722, + "is_outbound": true, + "balance_msat": 959722000, + "outbound_capacity_msat": 950125000, + "inbound_capacity_msat": 0, + "current_confirmations": 0, + "required_confirmations": 3, + "is_ready": false, + "is_usable": false, + "is_public": false + } + }, + "id": 54 } ``` - #### PlatformCoinIsNotActivated Error + + `force_close_spend_delay` is not currently available in get\_channel\_details response, but should be added soon. + It's configured by the other side using counterparty\_locktime where we are the counterparty to the other side, the other side gets to set it since it's part of their security considerations since they have to be online at least once during this period if we tried to steal funds by broadcasting an old commitment transaction. We set our own too in our configs where it shows in the channel details of the other side as force\_close\_spend\_delay. The other side can't set counterparty\_locktime to any value when opening the channel though, since they can set it to a very long time and our funds will be locked for a very long time if we force closed the channel, this is where counterparty\_channel\_config\_limits::our\_locktime\_limit comes in as the other side can't make counterparty\_locktime larger than this limit otherwise the channel gets rejected and is never opened in the first place. + [https://github.com/KomodoPlatform/komodo-docs-mdx/pull/31#discussion\\\_r1206109172](https://github.com/KomodoPlatform/komodo-docs-mdx/pull/31#discussion\\_r1206109172) + - The selected coin is not activated. It needs to be activated before the lightning node can be initialized. + #### Response (closed channel) ```json { "mmrpc": "2.0", - "error": "Platform coin tBTC-lightning is not activated", - "error_path": "init_l2.lp_coins", - "error_trace": "init_l2:87] lp_coins:3087]", - "error_type": "PlatformCoinIsNotActivated", - "error_data": "tBTC-lightning", - "id": 2 + "result": { + "status": "Open", + "details": { + "uuid": "2b50e274-c173-4fa1-95f3-97f9f82ace92", + "channel_id": "4a869115dfd260d0925a1266f544a6ab36666448d4bbc0e2a028d8426b2b6d4e", + "counterparty_node_id": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9", + "funding_tx": "4e6d2b6b42d828a0e2c0bbd448646636aba644f566125a92d060d2df1591864a", + "funding_value": "98982", + "closing_tx": "f1591864ad0e2c0bad060425a94b8288646e6d24f56b6d2db42d4636aba64612", + "closure_reason": "null", + "claiming_tx": "null", + "claimed_balance": "null", + "funding_generated_in_block": "null", + "is_outbound": false, + "is_public": true, + "is_closed": true, + "created_at": 167273496966, + "closed_at": 171069595935 + } + }, + "id": 54 } ``` - [https://github.com/KomodoPlatform/komodo-docs-mdx/pull/31#discussion\\\_r1197550229](https://github.com/KomodoPlatform/komodo-docs-mdx/pull/31#discussion\\_r1197550229) - Another bug found, will fix it in an upcoming PR. Platform coin should be tBTC-segwit. You can leave as it is in docs until I fix it. - - - #### InvalidPlatformConfiguration Error + The closed response above was spoofed, so the values are not accurate. Once code is finalised we should generate a real one. + [https://github.com/KomodoPlatform/komodo-docs-mdx/pull/31#discussion\\\_r1206150595](https://github.com/KomodoPlatform/komodo-docs-mdx/pull/31#discussion\\_r1206150595) + + - Coin's configuration is missing a required parameter. Refer to the [coins file configuration for lightning](/atomicdex/api/v20-dev/lightning/#lightning-network-coins-file-configuration) for more information. + + #### InvalidRequest Error ```json { "mmrpc": "2.0", - "error": "Invalid config for platform coin: tBTC-segwit, error: 'avg_blocktime' field is not found in platform coin config", - "error_path": "init_l2.lightning_activation", - "error_trace": "init_l2:95] lightning_activation:254]", - "error_type": "InvalidPlatformConfiguration", - "error_data": { - "platform_coin_ticker": "tBTC-segwit", - "err": "'avg_blocktime' field is not found in platform coin config" - }, - "id": 2 + "error": "Error parsing request: missing field `coin`", + "error_path": "dispatcher", + "error_trace": "dispatcher:109]", + "error_type": "InvalidRequest", + "error_data": "missing field `coin`", + "id": 54 } ``` -## Initialization Status {{label : 'task::enable_lightning::status', tag : 'API-v2'}} +## Get Claimable Balances {{label : 'lightning::channels::get_claimable_balances', tag : 'API-v2'}} -The `task::enable_lightning::status` request checks the status of lightning node initialization. +The `lightning::channels::get_claimable_balances` method returns a list of claimable balances for a coin. ### Request Parameters -| Parameter | Type | Description | -| -------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------- | -| task\_id | integer | The task id returned from `task::enable_lightning::init` | -| forget\_if\_finished | boolean | Optional, defaults to `true`. If `false`, the status of the `task_id` will still be available after the task has completed. | +| Parameter | Type | Description | +| --------------------------------- | ------- | ------------------------------------------------------------------------------- | +| coin | string | The ticker of the coin you would like to view claimable balances for. | +| include\_open\_channels\_balances | integer | Optional, defaults to `false`. If `true`, includes balances from open channels. | -#### ๐Ÿ“Œ Example +#### ๐Ÿ“Œ Example to update all available channel options - + ```json { "userpass": "testpsw", "mmrpc": "2.0", - "method": "task::enable_lightning::status", + "method": "lightning::channels::get_claimable_balances", "params": { - "task_id": 1, - "forget_if_finished": false + "coin": "tBTC-lightning", + "include_open_channels_balances": true }, - "id": 2 + "id": 762 } ``` - ### Response Parameters - - | Parameter | Type | Description | - | -------------- | ------ | ---------------------------------------------------------------------------------- | - | platform\_coin | string | The coin ticker for which the lightning node is being intitialized. | - | address | string | This node's address for the activated coin. | - | balance | object | A standard [balanceInfos](/atomicdex/api/common_structures/#balance-infos) object. | - - - The unspendable balance for lightning is different to a layer-1 unspendable balance. The channel reserve is part of the unspendable balance in lightning - the user will get this part of the balance on chain when closing the channel, but it can't be spent on layer 2 (lightning) because it's part of the security mechanism to prevent channel breaches and ensure that both parties fulfill their obligations within the channel. - - - #### Response (ready, success) - - ```json - { - "mmrpc": "2.0", - "result": { - "status": "Ok", - "details": { - "platform_coin": "BTC-segwit", - "address": "0321937a095229510bd2b02a930d7b7eb273147e348ef1086b22e8790e3c609804", - "balance": { - "spendable": "0", - "unspendable": "0" - } - } - }, - "id": null - } - ``` - - - In the above response spendable will always be 0 since the balance is unspendable until connections with lightning channels counterparties are established. - Using the [my\_balance](/atomicdex/api/legacy/my_balance/) method after the coin is activated will get the spendable balance depending on how many channel counterparties are online. - For exact channels balances and which channels are usable, use [lightning::channels::list\_open\_channels\_by\_filter](/atomicdex/api/v20-dev/lightning/channels/#list-open-channels-by-filter). - - - #### Response (in progress state) + #### Response ```json { - "mmrpc": "2.0", - "result": { - "status": "InProgress", - "details": "ReadingNetworkGraphFromFile" - }, - "id": null + "mmrpc": "2.0", + "result": [{ + "ClaimableOnChannelClose": { + "claimable_amount_satoshis": 0 + } + }, { + "ClaimableOnChannelClose": { + "claimable_amount_satoshis": 38815 + } + }, { + "ClaimableOnChannelClose": { + "claimable_amount_satoshis": 959539 + } + }], + "id": 762 } ``` - Possible in progress statuses: - - * ActivatingCoin - * GettingFeesFromRPC - * ReadingNetworkGraphFromFile - * InitializingChannelManager - * InitializingPeerManager - * ReadingScorerFromFile - * InitializingBackgroundProcessor - * ReadingChannelsAddressesFromFile + + This response may include additional information in future. + [https://github.com/KomodoPlatform/komodo-docs-mdx/pull/31#discussion\\\_r1206152132](https://github.com/KomodoPlatform/komodo-docs-mdx/pull/31#discussion\\_r1206152132) + -## Cancel Initialization {{label : 'task::enable_lightning::cancel', tag : 'API-v2'}} +## List Open Channels by Filter {{label : 'lightning::channels::list_open_channels_by_filter', tag : 'API-v2'}} -The `task::enable_lightning::cancel` request cancels lightning node initialization. +The `lightning::channels::list_open_channels_by_filter` method returns a list of open channels filtered by the provided filter object. ### Request Parameters -| Parameter | Type | Description | -| --------- | ------- | -------------------------------------------------------- | -| task\_id | integer | The task id returned from `task::enable_lightning::init` | +| Parameter | Type | Description | +| --------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- | +| coin | string | The ticker of the coin you would like to view open channels for. | +| filter | object | A standard [LightningOpenChannelsFilter](/atomicdex/api/common_structures/lightning/#lightning-open-channels-filter) object. | +| paging\_options | object | Optional. A standard [Pagination](/atomicdex/api/common_structures/#pagination) object. | +| limit | integer | Optional, defaults to `10`. Maximum number of results to return. | -#### ๐Ÿ“Œ Example +#### ๐Ÿ“Œ Example without using `filter` parameter - +#### Command + + ```json { "userpass": "testpsw", "mmrpc": "2.0", - "method": "task::enable_lightning::cancel", + "method": "lightning::channels::list_open_channels_by_filter", "params": { - "task_id": 1 + "coin": "tBTC-lightning" }, - "id": 1 + "id": 55 } ``` @@ -44348,71 +45574,113 @@ The `task::enable_lightning::cancel` request cancels lightning node initializati ```json { - "mmrpc": "2.0", - "result": "success", - "id": null + "mmrpc": "2.0", + "result": { + "open_channels": [{ + "uuid": "434681f8-95e5-484f-af49-fa80d8ae857b", + "channel_id": "ebfbf19193ee26f25c6e236e863786e59818c11e136ce9c50dba63ec44b0c89a", + "counterparty_node_id": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9", + "funding_tx": null, + "funding_tx_output_index": null, + "funding_tx_value_sats": 4000, + "is_outbound": true, + "balance_msat": 4000000, + "outbound_capacity_msat": 4000000, + "inbound_capacity_msat": 0, + "current_confirmations": 0, + "required_confirmations": null, + "is_ready": false, + "is_usable": false, + "is_public": false + }], + "limit": 10, + "skipped": 0, + "total": 1, + "total_pages": 1, + "paging_options": { + "PageNumber": 1 + } + }, + "id": 55 } ``` - - #### TaskFinished Error +#### ๐Ÿ“Œ Example with `filter` for inbound channels only - Task has already been completed. +#### Command + ```json { - "mmrpc": "2.0", - "error": "Task is finished already", - "error_path": "init_l2.manager", - "error_trace": "init_l2:157] manager:104]", - "error_type": "TaskFinished", - "error_data": 3, - "id": null + "userpass": "testpsw", + "mmrpc": "2.0", + "method": "lightning::channels::list_open_channels_by_filter", + "params": { + "coin": "tBTC-lightning", + "filter": { + "is_outbound": false + } + }, + "id": 55 } ``` - -export const title = "AtomicDEX: Lightning Network Channels"; -export const description = "The methods in this document allow management of Lightning Network Channels on AtomicDEX-API."; - -# Lightning Network Channels - - - Lightning methods are currently only available using the native AtomicDEX-API. WASM support should be available in late 2023. - - -## Open Channel {{label : 'lightning::channels::open_channel', tag : 'API-v2'}} + -The `lightning::channels::open_channel` method opens a new channel with a remote node. + + #### Response -### Request Parameters + ```json + { + "mmrpc": "2.0", + "result": { + "open_channels": [{ + "uuid": "f86dbfae-898a-4f49-8149-58d9dfa095a5", + "channel_id": "143cd1fa265c4bed860ce81f369d5c4ee8ef80c5c91872176f524348c2c1fff4", + "counterparty_node_id": "03cf982b1c16f7d3561d8bb17f7cf30057389d228756bce517c0f3cc111b38ecd0", + "funding_tx": "f4ffc1c24843526f177218c9c580efe84e5c9d361fe80c86ed4b5c26fad13c14", + "funding_tx_output_index": 0, + "funding_tx_value_sats": 40000, + "is_outbound": false, + "balance_msat": 5211, + "outbound_capacity_msat": 0, + "inbound_capacity_msat": 38994789, + "current_confirmations": 215, + "required_confirmations": 3, + "is_ready": true, + "is_usable": false, + "is_public": false + }], + "limit": 10, + "skipped": 0, + "total": 1, + "total_pages": 1, + "paging_options": { + "PageNumber": 1 + } + }, + "id": 55 + } + ``` + -| Parameter | Type | Description | -| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| coin | string | The ticker of the coin you would like to open a channel for. | -| node\_address | string | Lightning node addresses always have a format of `node_pubkey`@`ip_address`:`port`. | -| amount | object | A standard [LightningChannelAmount](/atomicdex/api/common_structures/lightning/#lightning-channel-amount) object. | -| push\_msat | integer | Optional. The amount in millisatoshi to push to the counterparty while openning, to create inbound liquidity for the channel. Using the `push_msat` parameter avoids having to send funds in a separate request later. Please note that the funds given using push\_msat is given unconditionally, meaning that there is no proof of payment in a preimage as with paying an invoice. | -| channel\_options | object | Optional. A standard [LightningChannelOptions](/atomicdex/api/common_structures/lightning/#lightning-channel-options) object. | -| channel\_configs | object | Optional. A standard [LightningChannelConfig](/atomicdex/api/common_structures/lightning/#lightning-channel-config) object. | +#### ๐Ÿ“Œ Example with `filter` for a specific `node_id` -#### ๐Ÿ“Œ Example using an exact amount +#### Command - + ```json { "userpass": "testpsw", "mmrpc": "2.0", - "method": "lightning::channels::open_channel", + "method": "lightning::channels::list_open_channels_by_filter", "params": { "coin": "tBTC-lightning", - "node_address": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9@203.132.94.196:9735", - "amount": { - "type": "Exact", - "value": 0.004 + "filter": { + "counterparty_node_id": "02eb0b178576857b6990ba57d56aa08f651a05a8098496004f42df5e7440b0a9c1" } }, - "id": 22 + "id": 55 } ``` @@ -44424,47 +45692,54 @@ The `lightning::channels::open_channel` method opens a new channel with a remote { "mmrpc": "2.0", "result": { - "uuid": "434681f8-95e5-484f-af49-fa80d8ae857b", - "node_address": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9@233.112.95.142:9735" + "open_channels": [{ + "uuid": "adde8899-ba11-435a-9433-d180e2f5af6b", + "channel_id": "4cde288dd1ec1691b51cac8890a867a58fcfc98670e32ed7a112402b819a01f1", + "counterparty_node_id": "02312627fdf07fbdd7e5ddb136611bdde9b00d26821d14d94891395452f67af248", + "funding_tx": "f1019a812b4012a1d72ee37086c9cf8fa567a89088ac1cb59116ecd18d28de4c", + "funding_tx_output_index": 0, + "funding_tx_value_sats": 40000, + "is_outbound": true, + "balance_msat": 38998197, + "outbound_capacity_msat": 38598197, + "inbound_capacity_msat": 1803, + "current_confirmations": 215, + "required_confirmations": 3, + "is_ready": true, + "is_usable": true, + "is_public": false + }], + "limit": 10, + "skipped": 0, + "total": 1, + "total_pages": 1, + "paging_options": { + "PageNumber": 1 + } }, - "id": 22 + "id": 55 } ``` -#### ๐Ÿ“Œ Example using max available with channel options and configs +#### ๐Ÿ“Œ Example with `filter` for a node with between 100000 and 500000 satoshi funding value - +#### Command + + ```json { "userpass": "testpsw", "mmrpc": "2.0", - "method": "lightning::channels::open_channel", + "method": "lightning::channels::list_open_channels_by_filter", "params": { "coin": "tBTC-lightning", - "node_address": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9@203.132.94.196:9735", - "amount": { - "type": "Max" - }, - "push_msat": 0, - "channel_options": { - "proportional_fee_in_millionths_sats": 0, - "base_fee_msat": 1000, - "cltv_expiry_delta": 72, - "max_dust_htlc_exposure_msat": 5000000, - "force_close_avoidance_max_fee_satoshis": 1000 - }, - "channel_configs": { - "counterparty_locktime": 144, - "our_htlc_minimum_msat": 1, - "negotiate_scid_privacy": false, - "max_inbound_in_flight_htlc_percent": 10, - "commit_upfront_shutdown_pubkey": true, - "inbound_channels_confirmations": 3, - "their_channel_reserve_sats": 10000 + "filter": { + "from_funding_value_sats": 1000, + "to_funding_value_sats": 500000 } }, - "id": null + "id": 55 } ``` @@ -44476,45 +45751,79 @@ The `lightning::channels::open_channel` method opens a new channel with a remote { "mmrpc": "2.0", "result": { - "uuid": "2b50e274-c173-4fa1-95f3-97f9f82ace92", - "node_address": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9@203.132.94.196:9735" + "open_channels": [{ + "uuid": "adde8899-ba11-435a-9433-d180e2f5af6b", + "channel_id": "4cde288dd1ec1691b51cac8890a867a58fcfc98670e32ed7a112402b819a01f1", + "counterparty_node_id": "02312627fdf07fbdd7e5ddb136611bdde9b00d26821d14d94891395452f67af248", + "funding_tx": "f1019a812b4012a1d72ee37086c9cf8fa567a89088ac1cb59116ecd18d28de4c", + "funding_tx_output_index": 0, + "funding_tx_value_sats": 40000, + "is_outbound": true, + "balance_msat": 38998197, + "outbound_capacity_msat": 38598197, + "inbound_capacity_msat": 1803, + "current_confirmations": 218, + "required_confirmations": 3, + "is_ready": true, + "is_usable": true, + "is_public": false + }, { + "uuid": "f86dbfae-898a-4f49-8149-58d9dfa095a5", + "channel_id": "143cd1fa265c4bed860ce81f369d5c4ee8ef80c5c91872176f524348c2c1fff4", + "counterparty_node_id": "03cf982b1c16f7d3561d8bb17f7cf30057389d228756bce517c0f3cc111b38ecd0", + "funding_tx": "f4ffc1c24843526f177218c9c580efe84e5c9d361fe80c86ed4b5c26fad13c14", + "funding_tx_output_index": 0, + "funding_tx_value_sats": 40000, + "is_outbound": false, + "balance_msat": 5211, + "outbound_capacity_msat": 0, + "inbound_capacity_msat": 38994789, + "current_confirmations": 218, + "required_confirmations": 3, + "is_ready": true, + "is_usable": false, + "is_public": false + }], + "limit": 10, + "skipped": 0, + "total": 2, + "total_pages": 1, + "paging_options": { + "PageNumber": 1 + } }, - "id": null + "id": 55 } ``` -## Close Channel {{label : 'lightning::channels::close_channel', tag : 'API-v2'}} +## List Closed Channels by Filter {{label : 'lightning::channels::list_closed_channels_by_filter', tag : 'API-v2'}} -The `lightning::channels::close_channel` method closes a channel with a remote node. +The `lightning::channels::list_closed_channels_by_filter` method returns a list of closed channels filtered by the provided filter object. ### Request Parameters -| Parameter | Type | Description | -| ------------ | ------- | ---------------------------------------------------------------------------- | -| coin | string | The ticker of the coin you would like to close a channel for. | -| uuid | string | Unique channel identifier. | -| force\_close | boolean | Optional, defaults to `false`. If `true`, will force closure of the channel. | +| Parameter | Type | Description | +| --------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- | +| coin | string | The ticker of the coin you would like to view closed channels for. | +| filter | object | A standard [LightningClosedChannelsFilter](/atomicdex/api/common_structures/lightning/#lightning-closed-channels-filter) object. | +| paging\_options | object | Optional. A standard [Pagination](/atomicdex/api/common_structures/#pagination) object. | +| limit | integer | Optional, defaults to `10`. Maximum number of results to return. | - - It is not recommended to force close a channel unless the counterparty is offline or unreachable for a long time. - Force closure of a channel will makeresult in the party who initiates the force closure to wait for a number of blocks (equal to the `force_close_spend_delay` value returned by [lightning::channels::get\_channel\_details](/atomicdex/api/v20-dev/lightning/channels/#get-channel-details)) before they can get their funds on chain. - +#### ๐Ÿ“Œ Example without using `filter` parameter -#### ๐Ÿ“Œ Example to force closing a channel +#### Command - + ```json { "userpass": "testpsw", "mmrpc": "2.0", - "method": "lightning::channels::close_channel", + "method": "lightning::channels::list_closed_channels_by_filter", "params": { - "coin": "tBTC-lightning", - "uuid": "2b50e274-c173-4fa1-95f3-97f9f82ace92", - "force_close": true + "coin": "tBTC-lightning" }, - "id": 8 + "id": 55 } ``` @@ -44522,86 +45831,163 @@ The `lightning::channels::close_channel` method closes a channel with a remote n #### Response + ```json + {"mmrpc": "2.0", + "result": { + "closed_channels": [{ + "uuid": "434681f8-95e5-484f-af49-fa80d8ae857b", + "channel_id": "ebfbf19193ee26f25c6e236e863786e59818c11e136ce9c50dba63ec44b0c89a", + "counterparty_node_id": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9", + "closure_reason": "Channel closed because counterparty force-closed with message chan size of 0.00004 BTC is below min chan size of 0.0002 BTC", + "is_outbound": true, + "is_public": false, + "is_closed": true, + "created_at": 1683864431, + "closed_at": 1683864432 + }, + { + "uuid": "de006b65-bd30-41e1-9b44-5e04518a3d98", + "channel_id": "928a041767f23c461fe3b41a387bd3f91a10b284cd7f90fb04544eda4f38f967", + "counterparty_node_id": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9", + "closure_reason": "Channel closed because of an exception: We consider the minimum depth to be unreasonably large. Expected minimum: (1). Actual: (3)", + "is_outbound": true, + "is_public": false, + "is_closed": true, + "created_at": 1683866505, + "closed_at": 1683866505 + }], + "limit": 10, + "skipped": 0, + "total": 1, + "total_pages": 1, + "paging_options": { + "PageNumber": 1 + } + }, "id": 55 + } + ``` + + +#### ๐Ÿ“Œ Example with `filter` for inbound channels only + +#### Command + + ```json { - "mmrpc": "2.0", - "result": "Initiated closing of channel with uuid: 2b50e274-c173-4fa1-95f3-97f9f82ace92", - "id": 8 + "userpass": "testpsw", + "mmrpc": "2.0", + "method": "lightning::channels::list_closed_channels_by_filter", + "params": { + "coin": "tBTC-lightning", + "filter": { + "channel_type": "Inbound" + } + }, + "id": 55 } ``` + - - To see if the channel is closed or not, use the [lightning::channels::get\_channel\_details](/atomicdex/api/v20-dev/lightning/channels/#get-channel-details) method. - + + #### Response - - Already added this message to the response in this upcoming PR KomodoPlatform/atomicDEX-API#1814, also added force\_close\_spend\_delay to the close channel response. No need to change the docs now until this PR is merged KomodoPlatform/atomicDEX-API#1814, I will write a comment about all the changes when opening the PR for review. - [https://github.com/KomodoPlatform/komodo-docs-mdx/pull/31#discussion\\\_r1202462310](https://github.com/KomodoPlatform/komodo-docs-mdx/pull/31#discussion\\_r1202462310) - + ```json + + {"mmrpc": "2.0", + "result": { + "closed_channels": [{ + "uuid": "de006b65-bd30-41e1-9b44-5e04518a3d98", + "channel_id": "928a041767f23c461fe3b41a387bd3f91a10b284cd7f90fb04544eda4f38f967", + "counterparty_node_id": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9", + "closure_reason": "Channel closed because of an exception: We consider the minimum depth to be unreasonably large. Expected minimum: (1). Actual: (3)", + "is_outbound": false, + "is_public": false, + "is_closed": true, + "created_at": 1683866505, + "closed_at": 1683866505 + }], + "limit": 10, + "skipped": 0, + "total": 1, + "total_pages": 1, + "paging_options": { + "PageNumber": 1 + } + }, "id": 55 + } + ``` - - #### InvalidRequest Error +#### ๐Ÿ“Œ Example with `filter` for a specific `node_id` +#### Command + + ```json { - "mmrpc": "2.0", - "error": "Error parsing request: missing field `uuid`", - "error_path": "dispatcher", - "error_trace": "dispatcher:109]", - "error_type": "InvalidRequest", - "error_data": "missing field `uuid`", - "id": 8 + "userpass": "testpsw", + "mmrpc": "2.0", + "method": "lightning::channels::list_closed_channels_by_filter", + "params": { + "coin": "tBTC-lightning", + "filter": { + "counterparty_node_id": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9" + } + }, + "id": 55 } ``` + - #### NoSuchChannel Error + + #### Response ```json - { - "mmrpc": "2.0", - "error": "No such channel with uuid 2b50e274-c173-4fa1-95f3-97f9f82ace92", - "error_path": "close_channel", - "error_trace": "close_channel:55]", - "error_type": "NoSuchChannel", - "error_data": "2b50e274-c173-4fa1-95f3-97f9f82ace92", - "id": 8 + + {"mmrpc": "2.0", + "result": { + "closed_channels": [{ + "uuid": "434681f8-95e5-484f-af49-fa80d8ae857b", + "channel_id": "ebfbf19193ee26f25c6e236e863786e59818c11e136ce9c50dba63ec44b0c89a", + "counterparty_node_id": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9", + "closure_reason": "Channel closed because counterparty force-closed with message chan size of 0.00004 BTC is below min chan size of 0.0002 BTC", + "is_outbound": true, + "is_public": false, + "is_closed": true, + "created_at": 1683864431, + "closed_at": 1683864432 + }], + "limit": 10, + "skipped": 0, + "total": 1, + "total_pages": 1, + "paging_options": { + "PageNumber": 1 + } + }, "id": 55 } ``` -## Update Channel {{label : 'lightning::channels::update_channel', tag : 'API-v2'}} - -The `lightning::channels::update_channel` method updates channel options. - -### Request Parameters - -| Parameter | Type | Description | -| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------- | -| coin | string | The ticker of the coin you would like to update channel configuration options for. | -| uuid | string | Unique channel identifier. | -| channel\_options | object | A standard [LightningChannelOptions](/atomicdex/api/common_structures/lightning/#lightning-channel-options) object. | +#### ๐Ÿ“Œ Example with `filter` for a node with between 100000 and 500000 satoshi funding value -#### ๐Ÿ“Œ Example to update all available channel options +#### Command - + ```json { "userpass": "testpsw", "mmrpc": "2.0", - "method": "lightning::channels::update_channel", + "method": "lightning::channels::list_closed_channels_by_filter", "params": { "coin": "tBTC-lightning", - "uuid": "434681f8-95e5-484f-af49-fa80d8ae857b", - "channel_options": { - "proportional_fee_in_millionths_sats": 1, - "base_fee_msat": 1100, - "cltv_expiry_delta": 72, - "max_dust_htlc_exposure_msat": 5000000, - "force_close_avoidance_max_fee_satoshis": 1000 + "filter": { + "from_funding_value_sats": 100000, + "to_funding_value_sats": 500000 } }, - "id": 2 + "id": 55 } ``` @@ -44613,298 +45999,313 @@ The `lightning::channels::update_channel` method updates channel options. { "mmrpc": "2.0", "result": { - "channel_options": { - "proportional_fee_in_millionths_sats": 1, - "base_fee_msat": 1100, - "cltv_expiry_delta": 72, - "max_dust_htlc_exposure_msat": 5000000, - "force_close_avoidance_max_fee_sats": null + "closed_channels": [{ + "uuid": "f901b604-54f7-4094-80f7-86aa9e362343", + "channel_id": "20aae008973fad5a59559ac0650143ec5b53aba1c6584d3d92177491a8284d00", + "counterparty_node_id": "02312627fdf07fbdd7e5ddb136611bdde9b00d26821d14d94891395452f67af248", + "funding_tx": "3807d9353557d15ad46e90a68dab8e4cd3a68a4af6b61bc7414bf81e29bc0517", + "funding_value": 40000, + "closing_tx": "61575237132b78aa5d1b4d62137da316bc67d09804b0bee53ab50f5d7cd0337c", + "closure_reason": "Channel closed because the channel was cooperatively closed", + "funding_generated_in_block": 2433122, + "is_outbound": true, + "is_public": false, + "is_closed": true, + "created_at": 1684083341, + "closed_at": 1684146940 + }], + "limit": 10, + "skipped": 0, + "total": 1, + "total_pages": 1, + "paging_options": { + "PageNumber": 1 } }, - "id": 2 + "id": 762 } ``` +export const title = "AtomicDEX: Lightning Network Methods"; +export const description = + "This document describes all the available methods for the Lightning Network on AtomicDEX-API."; - - #### NoSuchChannel Error +import lightningflowchart from "@/public/images/api-images/lightning-methods.png"; - Channel with the given uuid is not foun on the lightning network. +# Lightning Network Methods + + + Lightning methods are currently only available using the native AtomicDEX-API. + WASM support should be available in late 2023. + + +## Lightning Network Initialization Tasks + +* Initialise your lightning node with [task::enable\_lightning::init](/atomicdex/api/v20-dev/lightning/activation/#initialize-lightning) +* Check the initialization status of the lightning node with [task::enable\_lightning::status](/atomicdex/api/v20-dev/lightning/activation/#initialization-status) +* Cancel initialization process of the lightning node with [task::enable\_lightning::cancel](/atomicdex/api/v20-dev/lightning/activation/#cancel-initialization) + + + Any methods with a `task::` prefix will be linked to a numeric `task_id` value + which is used to query the status or outcome of the task. + + +## Lightning Network Nodes Methods + +* Connect to a lightning node with [lightning::nodes::connect\_to\_node](/atomicdex/api/v20-dev/lightning/nodes/#connect-to-node) +* Add a trusted node with [lightning::nodes::add\_trusted\_node](/atomicdex/api/v20-dev/lightning/nodes/#add-trusted-node) +* Remove a trusted node with [lightning::nodes::remove\_trusted\_node](/atomicdex/api/v20-dev/lightning/nodes/#remove-trusted-node) +* List your trusted lightning nodes with [lightning::nodes::list\_trusted\_nodes](/atomicdex/api/v20-dev/lightning/nodes/#list-trusted-nodes) + +## Lightning Network Channels Methods + +* Open a lightning channel [lightning::channels::open\_channel](/atomicdex/api/v20-dev/lightning/channels/#open-channel) +* Close a lightning channel [lightning::channels::close\_channel](/atomicdex/api/v20-dev/lightning/channels/#close-channel) +* Update a lightning channel [lightning::channels::update\_channel](/atomicdex/api/v20-dev/lightning/channels/#update-channel) +* Get details about a lightning channel [lightning::channels::get\_channel\_details](/atomicdex/api/v20-dev/lightning/channels/#get-channel-details) +* Get claimable balances from lightning channels [lightning::channels::get\_claimable\_balances](/atomicdex/api/v20-dev/lightning/channels/#get-claimable-balances) +* List open lightning channels matching a filter [lightning::channels::list\_open\_channels\_by\_filter](/atomicdex/api/v20-dev/lightning/channels/#list-open-channels-by-filter) +* List closed lightning channels matching a filter [lightning::channels::list\_closed\_channels\_by\_filter](/atomicdex/api/v20-dev/lightning/channels/#list-closed-channels-by-filter) + +## Lightning Network Payments Methods + +* Generate lightning invoices with [lightning::payments::generate\_invoice](/atomicdex/api/v20-dev/lightning/payments/#generate-invoice) +* Send lightning payments with [lightning::payments::send\_payment](/atomicdex/api/v20-dev/lightning/payments/#send-payment) +* Get details about a lightning payment with [lightning::payments::get\_payment\_details](/atomicdex/api/v20-dev/lightning/payments/#get-payment-details) +* Get a filtered list of lightning payments with [lightning::payments::list\_payments\_by\_filter](/atomicdex/api/v20-dev/lightning/payments/#list-payments-by-filter) + +## Lightning Network Flowchart + +Once you: + +* Enable lightning with [task::enable\_lightning::init](/atomicdex/api/v20-dev/lightning/activation/#initialize-lightning) +* Connect to a lightning node with [lightning::nodes::connect\_to\_node](/atomicdex/api/v20-dev/lightning/nodes/#connect-to-node) +* Open a lightning channel [lightning::channels::open\_channel](/atomicdex/api/v20-dev/lightning/channels/#open-channel) + +You can get an invoice for a coffee from [https://starblocks.acinq.co](https://starblocks.acinq.co)! + +Then you can: + +* Pay the invoice with [lightning::payments::send\_payment](/atomicdex/api/v20-dev/lightning/payments/#send-payment) +* View details about the payment with [lightning::payments::get\_payment\_details](/atomicdex/api/v20-dev/lightning/payments/#get-payment-details) +* List your payments with [lightning::payments::list\_payments\_by\_filter](/atomicdex/api/v20-dev/lightning/payments/#list-payments-by-filter) + +Follow the flowchart below to visualize the process: + + + +## Lightning Network Coins File Configuration + + + Some configurations are set per coin, and some are set per channel. The + [counterparty\_channel\_config\_limits](/atomicdex/api/common_structures/lightning/#counterparty-channel-config) + param must be set in the `coins` configuration file, and aplies to all + channels opened by counterparty nodes. The + [our\_channels\_config](/atomicdex/api/common_structures/lightning/#lightning-channel-config) and + [channel\_options](/atomicdex/api/common_structures/lightning/#lightning-channel-options) parameters + are set per channel. These can be defined in the `coins` configuration file to + act as the default for all opened channels, and optionally overwritten or + updated using the + [open\_channel](/atomicdex/api/v20-dev/lightning/channels/#open-channel) or + [update\_channel](/atomicdex/api/v20-dev/lightning/channels/#update-channel) + methods. + + +### Lightning Coin Config Parameters + +| Parameter | Type | Description | +| ------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| coin | object | The ticker of the coin you will use lightning network with, suffixed with `-lightning` | +| mm2 | integer | Defaults to `0`. A value of `1`, indicates the coin is atomic swap compatible. | +| decimals | integer | The decimal precision of the coin you will use the lightning network with. | +| protocol | object | A standard [CoinProtocol](/atomicdex/api/common_structures/activation/#coin-protocol) object. | +| accept\_inbound\_channels | boolean | Optional, defaults to `true`. If this is set to false, we do not accept inbound requests to open a new channel. | +| accept\_forwards\_to\_priv\_channels | boolean | Optional, defaults to `false`. When set to `false`, any HTLCs which were to be forwarded over private channels will be rejected. This prevents us from taking on HTLC-forwarding risk when we intend to run as a node which is not online reliably (e.g. GUI wallet apps). Generally, private channels are used for non-routing purposes only. | +| counterparty\_channel\_config\_limits | object | Optional. A standard [CounterpartyChannelConfig](/atomicdex/api/common_structures/lightning/#counterparty-channel-config) object. | +| channel\_options | object | Optional. A standard [LightningChannelOptions](/atomicdex/api/common_structures/lightning/#lightning-channel-options) object. | +| our\_channels\_config | object | Optional. A standard [LightningChannelConfig](/atomicdex/api/common_structures/lightning/#lightning-channel-config) object. | + + + For GUIs and wallet apps, it is recommended to set + `accept_forwards_to_priv_channels` to `false`. This prevents users from taking + on HTLC-forwarding risk when a node is expected to not be reliably online. + [our\_channels\_config::announced\_channel](/atomicdex/api/common_structures/lightning/#lightning-channel-options) + should also be set to `false` for GUIs and wallet apps. + + ```json - { - "mmrpc": "2.0", - "error": "No such channel with uuid dc33b998-8589-44fd-a246-256a582e8942", - "error_path": "update_channel", - "error_trace": "update_channel:61]", - "error_type": "NoSuchChannel", - "error_data": "dc33b998-8589-44fd-a246-256a582e8942", - "id": 2 - } + { + "coin": "BTC-lightning", + "mm2": 1, + "decimals": 11, + "our_channels_config": { + "inbound_channels_confirmations": 3, + "max_inbound_in_flight_htlc_percent": 90 + }, + "counterparty_channel_config_limits": { + "outbound_channels_confirmations": 3, + "force_announced_channel_preference": false + }, + "protocol": { + "type": "LIGHTNING", + "protocol_data":{ + "platform": "BTC-segwit", + "network": "mainnet", + "confirmation_targets": { + "background": 12, + "normal": 6, + "high_priority": 1 + } + } + } + }, + { + "coin": "tBTC-lightning", + "mm2": 1, + "decimals": 11, + "our_channels_configs": { + "inbound_channels_confirmations": 3, + "max_inbound_in_flight_htlc_percent": 90, + "their_channel_reserve_sats": 10000 + }, + "counterparty_channel_config_limits": { + "outbound_channels_confirmations": 3 + }, + "protocol": { + "type": "LIGHTNING", + "protocol_data":{ + "platform": "tBTC-segwit", + "network": "testnet", + "confirmation_targets": { + "background": 12, + "normal": 6, + "high_priority": 1 + } + } + } + }, ``` +export const title = "AtomicDEX: Lightning Network Nodes"; +export const description = "The methods in this document allow management of connections to Lightning Network Nodes on AtomicDEX-API."; -## Get Channel Details {{label : 'lightning::channels::get_channel_details', tag : 'API-v2'}} +# Lightning Network Nodes -The `lightning::channels::get_channel_details` method returns details about a channel. + + Lightning methods are currently only available using the native AtomicDEX-API. WASM support should be available in late 2023. + + +## Connect to Node {{label : 'lightning::nodes::connect_to_node', tag : 'API-v2'}} + +The `lightning::nodes::connect_to_node` method allows you to connect to a lightning node. ### Request Parameters -| Parameter | Type | Description | -| --------- | ------ | ------------------------------------------------------------------ | -| coin | string | The ticker of the coin you would like to view channel details for. | -| uuid | string | Unique channel identifier. | +| Parameter | Type | Description | +| ------------- | ------ | ----------------------------------------------------------------------------------- | +| coin | string | The coin ticker you would like to connect to a node on. | +| node\_address | string | Lightning nodes addresses always have a format of `node_pubkey`@`ip_address`:`port` | -#### ๐Ÿ“Œ Example to update all available channel options +#### ๐Ÿ“Œ Example - + ```json { "userpass": "testpsw", "mmrpc": "2.0", - "method": "lightning::channels::get_channel_details", + "method": "lightning::nodes::connect_to_node", "params": { "coin": "tBTC-lightning", - "uuid": "2b50e274-c173-4fa1-95f3-97f9f82ace92" + "node_address": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9@203.132.94.196:9735" }, - "id": 54 + "id": 1 } ``` - - - The response will vary depending on whether the channel status is `open` or `closed`. - + + The node address in the above request is for the WalletOfSatoshi lightning node, which is one of the most connected lightning nodes. + Other node addresses can be retrieved from any lightning explorer, such as: - #### Response (opened channel) + * [https://1ml.com/](https://1ml.com/) + * [https://mempool.space/lightning/](https://mempool.space/lightning/) + + + + #### Response (success) ```json { - "mmrpc": "2.0", - "result": { - "status": "Open", - "details": { - "uuid": "2b50e274-c173-4fa1-95f3-97f9f82ace92", - "channel_id": "4a869115dfd260d0925a1266f544a6ab36666448d4bbc0e2a028d8426b2b6d4e", - "counterparty_node_id": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9", - "funding_tx": "4e6d2b6b42d828a0e2c0bbd448646636aba644f566125a92d060d2df1591864a", - "funding_tx_output_index": 0, - "funding_tx_value_sats": 959722, - "is_outbound": true, - "balance_msat": 959722000, - "outbound_capacity_msat": 950125000, - "inbound_capacity_msat": 0, - "current_confirmations": 0, - "required_confirmations": 3, - "is_ready": false, - "is_usable": false, - "is_public": false - } - }, - "id": 54 + "mmrpc": "2.0", + "result": "Connected successfully to node : 035e4ff418fc8b5554c5d9eea66396c227bd429a3251c8cbc711002ba215bfc226@170.75.163.209:9735", + "id": null } ``` - - `force_close_spend_delay` is not currently available in get\_channel\_details response, but should be added soon. - It's configured by the other side using counterparty\_locktime where we are the counterparty to the other side, the other side gets to set it since it's part of their security considerations since they have to be online at least once during this period if we tried to steal funds by broadcasting an old commitment transaction. We set our own too in our configs where it shows in the channel details of the other side as force\_close\_spend\_delay. The other side can't set counterparty\_locktime to any value when opening the channel though, since they can set it to a very long time and our funds will be locked for a very long time if we force closed the channel, this is where counterparty\_channel\_config\_limits::our\_locktime\_limit comes in as the other side can't make counterparty\_locktime larger than this limit otherwise the channel gets rejected and is never opened in the first place. - [https://github.com/KomodoPlatform/komodo-docs-mdx/pull/31#discussion\\\_r1206109172](https://github.com/KomodoPlatform/komodo-docs-mdx/pull/31#discussion\\_r1206109172) - - - #### Response (closed channel) + #### Response (already connected) ```json { - "mmrpc": "2.0", - "result": { - "status": "Open", - "details": { - "uuid": "2b50e274-c173-4fa1-95f3-97f9f82ace92", - "channel_id": "4a869115dfd260d0925a1266f544a6ab36666448d4bbc0e2a028d8426b2b6d4e", - "counterparty_node_id": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9", - "funding_tx": "4e6d2b6b42d828a0e2c0bbd448646636aba644f566125a92d060d2df1591864a", - "funding_value": "98982", - "closing_tx": "f1591864ad0e2c0bad060425a94b8288646e6d24f56b6d2db42d4636aba64612", - "closure_reason": "null", - "claiming_tx": "null", - "claimed_balance": "null", - "funding_generated_in_block": "null", - "is_outbound": false, - "is_public": true, - "is_closed": true, - "created_at": 167273496966, - "closed_at": 171069595935 - } - }, - "id": 54 + "mmrpc": "2.0", + "result": "Already connected to node : 035e4ff418fc8b5554c5d9eea66396c227bd429a3251c8cbc711002ba215bfc226@170.75.163.209:9735", + "id": null } ``` - - - The closed response above was spoofed, so the values are not accurate. Once code is finalised we should generate a real one. - [https://github.com/KomodoPlatform/komodo-docs-mdx/pull/31#discussion\\\_r1206150595](https://github.com/KomodoPlatform/komodo-docs-mdx/pull/31#discussion\\_r1206150595) - - #### InvalidRequest Error + #### InvalidRequest Error (Invalid node\_address) ```json { "mmrpc": "2.0", - "error": "Error parsing request: missing field `coin`", + "error": "Error parsing request: Could not parse node address from str rgjhk3", "error_path": "dispatcher", "error_trace": "dispatcher:109]", "error_type": "InvalidRequest", - "error_data": "missing field `coin`", - "id": 54 - } - ``` - - -## Get Claimable Balances {{label : 'lightning::channels::get_claimable_balances', tag : 'API-v2'}} - -The `lightning::channels::get_claimable_balances` method returns a list of claimable balances for a coin. - -### Request Parameters - -| Parameter | Type | Description | -| --------------------------------- | ------- | ------------------------------------------------------------------------------- | -| coin | string | The ticker of the coin you would like to view claimable balances for. | -| include\_open\_channels\_balances | integer | Optional, defaults to `false`. If `true`, includes balances from open channels. | - -#### ๐Ÿ“Œ Example to update all available channel options - - - ```json - { - "userpass": "testpsw", - "mmrpc": "2.0", - "method": "lightning::channels::get_claimable_balances", - "params": { - "coin": "tBTC-lightning", - "include_open_channels_balances": true - }, - "id": 762 + "error_data": "Could not parse node address from str rgjhk3", + "id": 762 } ``` - - - #### Response + #### ConnectionError Error (Timed out waiting to connect to node\_address) ```json { - "mmrpc": "2.0", - "result": [{ - "ClaimableOnChannelClose": { - "claimable_amount_satoshis": 0 - } - }, { - "ClaimableOnChannelClose": { - "claimable_amount_satoshis": 38815 - } - }, { - "ClaimableOnChannelClose": { - "claimable_amount_satoshis": 959539 - } - }], - "id": 762 + "mmrpc": "2.0", + "error": "Error connecting to node: Timeout error: Failed to connect to node: 035e4ff418fc8b5554c5d9eea66396c227bd429a3251c8cbc711002ba215bfc226", + "error_path": "connect_to_node", + "error_trace": "connect_to_node:78]", + "error_type": "ConnectionError", + "error_data": "Timeout error: Failed to connect to node: 035e4ff418fc8b5554c5d9eea66396c227bd429a3251c8cbc711002ba215bfc226", + "id": null } ``` - - - This response may include additional information in future. - [https://github.com/KomodoPlatform/komodo-docs-mdx/pull/31#discussion\\\_r1206152132](https://github.com/KomodoPlatform/komodo-docs-mdx/pull/31#discussion\\_r1206152132) - -## List Open Channels by Filter {{label : 'lightning::channels::list_open_channels_by_filter', tag : 'API-v2'}} +## List Trusted Nodes {{label : 'lightning::nodes::list_trusted_nodes', tag : 'API-v2'}} -The `lightning::channels::list_open_channels_by_filter` method returns a list of open channels filtered by the provided filter object. +The `lightning::nodes::list_trusted_nodes` method allows you to list all nodes in your trusted list. ### Request Parameters -| Parameter | Type | Description | -| --------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- | -| coin | string | The ticker of the coin you would like to view open channels for. | -| filter | object | A standard [LightningOpenChannelsFilter](/atomicdex/api/common_structures/lightning/#lightning-open-channels-filter) object. | -| paging\_options | object | Optional. A standard [Pagination](/atomicdex/api/common_structures/#pagination) object. | -| limit | integer | Optional, defaults to `10`. Maximum number of results to return. | - -#### ๐Ÿ“Œ Example without using `filter` parameter - -#### Command - - - ```json - { - "userpass": "testpsw", - "mmrpc": "2.0", - "method": "lightning::channels::list_open_channels_by_filter", - "params": { - "coin": "tBTC-lightning" - }, - "id": 55 - } - ``` - - - - #### Response - - ```json - { - "mmrpc": "2.0", - "result": { - "open_channels": [{ - "uuid": "434681f8-95e5-484f-af49-fa80d8ae857b", - "channel_id": "ebfbf19193ee26f25c6e236e863786e59818c11e136ce9c50dba63ec44b0c89a", - "counterparty_node_id": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9", - "funding_tx": null, - "funding_tx_output_index": null, - "funding_tx_value_sats": 4000, - "is_outbound": true, - "balance_msat": 4000000, - "outbound_capacity_msat": 4000000, - "inbound_capacity_msat": 0, - "current_confirmations": 0, - "required_confirmations": null, - "is_ready": false, - "is_usable": false, - "is_public": false - }], - "limit": 10, - "skipped": 0, - "total": 1, - "total_pages": 1, - "paging_options": { - "PageNumber": 1 - } - }, - "id": 55 - } - ``` - - -#### ๐Ÿ“Œ Example with `filter` for inbound channels only +| Parameter | Type | Description | +| --------- | ------ | ------------------------------------------------------------- | +| coin | string | The coin ticker you would like to view your trusted nodes to. | -#### Command +#### ๐Ÿ“Œ Example - + ```json { "userpass": "testpsw", "mmrpc": "2.0", - "method": "lightning::channels::list_open_channels_by_filter", + "method": "lightning::nodes::list_trusted_nodes", "params": { - "coin": "tBTC-lightning", - "filter": { - "is_outbound": false - } + "coin": "tBTC-lightning" }, - "id": 55 + "id": 1 } ``` @@ -44916,53 +46317,37 @@ The `lightning::channels::list_open_channels_by_filter` method returns a list of { "mmrpc": "2.0", "result": { - "open_channels": [{ - "uuid": "f86dbfae-898a-4f49-8149-58d9dfa095a5", - "channel_id": "143cd1fa265c4bed860ce81f369d5c4ee8ef80c5c91872176f524348c2c1fff4", - "counterparty_node_id": "03cf982b1c16f7d3561d8bb17f7cf30057389d228756bce517c0f3cc111b38ecd0", - "funding_tx": "f4ffc1c24843526f177218c9c580efe84e5c9d361fe80c86ed4b5c26fad13c14", - "funding_tx_output_index": 0, - "funding_tx_value_sats": 40000, - "is_outbound": false, - "balance_msat": 5211, - "outbound_capacity_msat": 0, - "inbound_capacity_msat": 38994789, - "current_confirmations": 215, - "required_confirmations": 3, - "is_ready": true, - "is_usable": false, - "is_public": false - }], - "limit": 10, - "skipped": 0, - "total": 1, - "total_pages": 1, - "paging_options": { - "PageNumber": 1 - } + "trusted_nodes": ["038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9"] }, - "id": 55 + "id": 1 } ``` -#### ๐Ÿ“Œ Example with `filter` for a specific `node_id` +## Add Trusted Node {{label : 'lightning::nodes::add_trusted_node', tag : 'API-v2'}} -#### Command +The `lightning::nodes::add_trusted_node` method allows you to add a node to your trusted list. - +### Request Parameters + +| Parameter | Type | Description | +| --------- | ------ | --------------------------------------------------------- | +| coin | string | The coin ticker you would like to add a trusted node for. | +| node\_id | string | ID of node you would like to add to your trusted list. | + +#### ๐Ÿ“Œ Example + + ```json { "userpass": "testpsw", "mmrpc": "2.0", - "method": "lightning::channels::list_open_channels_by_filter", + "method": "lightning::nodes::add_trusted_node", "params": { "coin": "tBTC-lightning", - "filter": { - "counterparty_node_id": "02eb0b178576857b6990ba57d56aa08f651a05a8098496004f42df5e7440b0a9c1" - } + "node_id": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9" }, - "id": 55 + "id": 1 } ``` @@ -44974,54 +46359,37 @@ The `lightning::channels::list_open_channels_by_filter` method returns a list of { "mmrpc": "2.0", "result": { - "open_channels": [{ - "uuid": "adde8899-ba11-435a-9433-d180e2f5af6b", - "channel_id": "4cde288dd1ec1691b51cac8890a867a58fcfc98670e32ed7a112402b819a01f1", - "counterparty_node_id": "02312627fdf07fbdd7e5ddb136611bdde9b00d26821d14d94891395452f67af248", - "funding_tx": "f1019a812b4012a1d72ee37086c9cf8fa567a89088ac1cb59116ecd18d28de4c", - "funding_tx_output_index": 0, - "funding_tx_value_sats": 40000, - "is_outbound": true, - "balance_msat": 38998197, - "outbound_capacity_msat": 38598197, - "inbound_capacity_msat": 1803, - "current_confirmations": 215, - "required_confirmations": 3, - "is_ready": true, - "is_usable": true, - "is_public": false - }], - "limit": 10, - "skipped": 0, - "total": 1, - "total_pages": 1, - "paging_options": { - "PageNumber": 1 - } + "added_node": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9" }, - "id": 55 + "id": 1 } ``` -#### ๐Ÿ“Œ Example with `filter` for a node with between 100000 and 500000 satoshi funding value +## Remove Trusted Node {{label : 'lightning::nodes::remove_trusted_node', tag : 'API-v2'}} -#### Command +The `lightning::nodes::remove_trusted_node` method allows you to remove a node from your trusted list. - +### Request Parameters + +| Parameter | Type | Description | +| --------- | ------ | ------------------------------------------------------------- | +| coin | string | The coin ticker you would like to remove a trusted node from. | +| node\_id | string | ID of node you would like to remove from your trusted list. | + +#### ๐Ÿ“Œ Example + + ```json { "userpass": "testpsw", "mmrpc": "2.0", - "method": "lightning::channels::list_open_channels_by_filter", + "method": "lightning::nodes::remove_trusted_node", "params": { "coin": "tBTC-lightning", - "filter": { - "from_funding_value_sats": 1000, - "to_funding_value_sats": 500000 - } + "node_id": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9" }, - "id": 55 + "id": 1 } ``` @@ -45033,79 +46401,49 @@ The `lightning::channels::list_open_channels_by_filter` method returns a list of { "mmrpc": "2.0", "result": { - "open_channels": [{ - "uuid": "adde8899-ba11-435a-9433-d180e2f5af6b", - "channel_id": "4cde288dd1ec1691b51cac8890a867a58fcfc98670e32ed7a112402b819a01f1", - "counterparty_node_id": "02312627fdf07fbdd7e5ddb136611bdde9b00d26821d14d94891395452f67af248", - "funding_tx": "f1019a812b4012a1d72ee37086c9cf8fa567a89088ac1cb59116ecd18d28de4c", - "funding_tx_output_index": 0, - "funding_tx_value_sats": 40000, - "is_outbound": true, - "balance_msat": 38998197, - "outbound_capacity_msat": 38598197, - "inbound_capacity_msat": 1803, - "current_confirmations": 218, - "required_confirmations": 3, - "is_ready": true, - "is_usable": true, - "is_public": false - }, { - "uuid": "f86dbfae-898a-4f49-8149-58d9dfa095a5", - "channel_id": "143cd1fa265c4bed860ce81f369d5c4ee8ef80c5c91872176f524348c2c1fff4", - "counterparty_node_id": "03cf982b1c16f7d3561d8bb17f7cf30057389d228756bce517c0f3cc111b38ecd0", - "funding_tx": "f4ffc1c24843526f177218c9c580efe84e5c9d361fe80c86ed4b5c26fad13c14", - "funding_tx_output_index": 0, - "funding_tx_value_sats": 40000, - "is_outbound": false, - "balance_msat": 5211, - "outbound_capacity_msat": 0, - "inbound_capacity_msat": 38994789, - "current_confirmations": 218, - "required_confirmations": 3, - "is_ready": true, - "is_usable": false, - "is_public": false - }], - "limit": 10, - "skipped": 0, - "total": 2, - "total_pages": 1, - "paging_options": { - "PageNumber": 1 - } + "removed_node": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9" }, - "id": 55 + "id": 1 } ``` +export const title = "AtomicDEX: Lightning Network Payments"; +export const description = "The methods in this document allow management of Lightning Network Payments on AtomicDEX-API."; -## List Closed Channels by Filter {{label : 'lightning::channels::list_closed_channels_by_filter', tag : 'API-v2'}} +# Lightning Network Payments -The `lightning::channels::list_closed_channels_by_filter` method returns a list of closed channels filtered by the provided filter object. + + Lightning methods are currently only available using the native AtomicDEX-API. WASM support should be available in late 2023. + -### Request Parameters +## Generate invoice {{label : 'lightning::payments::generate_invoice', tag : 'API-v2'}} -| Parameter | Type | Description | -| --------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- | -| coin | string | The ticker of the coin you would like to view closed channels for. | -| filter | object | A standard [LightningClosedChannelsFilter](/atomicdex/api/common_structures/lightning/#lightning-closed-channels-filter) object. | -| paging\_options | object | Optional. A standard [Pagination](/atomicdex/api/common_structures/#pagination) object. | -| limit | integer | Optional, defaults to `10`. Maximum number of results to return. | +The `lightning::payments::generate_invoice` method generates an invoice to be paid by another node. -#### ๐Ÿ“Œ Example without using `filter` parameter +### Request Parameters -#### Command +| Parameter | Type | Description | +| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| coin | string | Ticker of coin to generate invoice for. | +| description | string | A note to indicate the purpose of the invoice. | +| amount\_in\_msat | integer | Amount to be paid, in [millisatoshis](https://bitcoindata.science/bitcoin-units-converter) (A thousandth of a satoshi; the same as 0.00000000001 bitcoin.) | +| expiry | integer | Optional, defaults to `3600`. Seconds until the invoice expires. | - +#### ๐Ÿ“Œ Example + + ```json { + "method": "lightning::payments::generate_invoice", "userpass": "testpsw", "mmrpc": "2.0", - "method": "lightning::channels::list_closed_channels_by_filter", "params": { - "coin": "tBTC-lightning" + "coin": "tBTC-lightning", + "description": "For the burger on Tuesday", + "amount_in_msat": 10000, + "expiry": 600 }, - "id": 55 + "id": 1 } ``` @@ -45114,59 +46452,62 @@ The `lightning::channels::list_closed_channels_by_filter` method returns a list #### Response ```json - {"mmrpc": "2.0", + { + "mmrpc": "2.0", "result": { - "closed_channels": [{ - "uuid": "434681f8-95e5-484f-af49-fa80d8ae857b", - "channel_id": "ebfbf19193ee26f25c6e236e863786e59818c11e136ce9c50dba63ec44b0c89a", - "counterparty_node_id": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9", - "closure_reason": "Channel closed because counterparty force-closed with message chan size of 0.00004 BTC is below min chan size of 0.0002 BTC", - "is_outbound": true, - "is_public": false, - "is_closed": true, - "created_at": 1683864431, - "closed_at": 1683864432 - }, - { - "uuid": "de006b65-bd30-41e1-9b44-5e04518a3d98", - "channel_id": "928a041767f23c461fe3b41a387bd3f91a10b284cd7f90fb04544eda4f38f967", - "counterparty_node_id": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9", - "closure_reason": "Channel closed because of an exception: We consider the minimum depth to be unreasonably large. Expected minimum: (1). Actual: (3)", - "is_outbound": true, - "is_public": false, - "is_closed": true, - "created_at": 1683866505, - "closed_at": 1683866505 - }], - "limit": 10, - "skipped": 0, - "total": 1, - "total_pages": 1, - "paging_options": { - "PageNumber": 1 - } - }, "id": 55 + "payment_hash": "3ff39605f214a4b4159f9c4f44c94de3a273f300042ca18b7cb3d62f270a9ebc", + "invoice": "lntb100n1pj9aq73dpggehhygr5dpjjqcn4wfnk2u3qdahzq4r4v4ekgctenp4qf3dqylh55jd8m5x5hh0g5q82h9p86yghwhl2s0t826nlyp8zdgjzpp58leevp0jzjjtg9vln385fj2duw388ucqqsk2rzmuk0tz7fc2n67qsp5k33rvvq46xtuppl22ggcq5q7qqywyekcemhzazt4m6vulwsarcrq9qyysgqcqpcxqzjcrzjqwyx8nu2hygyvgc02cwdtvuxe0lcxz06qt3lpsldzcdr46my5epmjfgaasqqqvqqqqqqqqlgqqqqqqgq9qpwesnhre7xmdg6tajvp939vl72vxm8csecy6hfcah9fzgazd5eyzjskgtt7u9xshj7gq2vkejjcquem08tqfrc2pj78xa95teazzf0qq7pnyqj" + }, + "id": 1 + } + ``` + + + + ### InvalidRequest (invalid paramater value) + + ```json + { + "mmrpc": "2.0", + "error": "Error parsing request: invalid type: string '56', expected u64", + "error_path": "dispatcher", + "error_trace": "dispatcher:109]", + "error_type": "InvalidRequest", + "error_data": "invalid type: string '56', expected u64", + "id": 762 } ``` -#### ๐Ÿ“Œ Example with `filter` for inbound channels only +## Send Payment {{label : 'lightning::payments::send_payment', tag : 'API-v2'}} + +The `lightning::payments::send_payment` method sends a payment to another node. + +Used to pay an invoice or send a payment via pubkey/address. + +### Request Parameters + +| Parameter | Type | Description | +| --------- | ------ | ---------------------------------------------------------------------------------------------------- | +| type | string | Ticker of the coin to query. | +| payment | object | A standard [LightningPayment](/atomicdex/api/common_structures/lightning/#lightning-payment) object. | -#### Command +#### ๐Ÿ“Œ Example using `invoice` - + ```json { "userpass": "testpsw", "mmrpc": "2.0", - "method": "lightning::channels::list_closed_channels_by_filter", + "method": "lightning::payments::send_payment", "params": { "coin": "tBTC-lightning", - "filter": { - "channel_type": "Inbound" + "payment": { + "type": "invoice", + "invoice": "lntb20u1p32wwxapp5p8gjy2e79jku5tshhq2nkdauv0malqqhzefnqmx9pjwa8h83cmwqdp8xys9xcmpd3sjqsmgd9czq3njv9c8qatrvd5kumcxqrrsscqp79qy9qsqsp5m473qknpecv6ajmwwtjw7keggrwxerymehx6723avhdrlnxmuvhs54zmyrumkasvjp0fvvk2np30cx5xpjs329alvm60rwy3payrnkmsd3n8ahnky3kuxaraa3u4k453yf3age7cszdxhjxjkennpt75erqpsfmy4y" } }, - "id": 55 + "id": 6 } ``` @@ -45175,49 +46516,34 @@ The `lightning::channels::list_closed_channels_by_filter` method returns a list #### Response ```json - - {"mmrpc": "2.0", + { + "mmrpc": "2.0", "result": { - "closed_channels": [{ - "uuid": "de006b65-bd30-41e1-9b44-5e04518a3d98", - "channel_id": "928a041767f23c461fe3b41a387bd3f91a10b284cd7f90fb04544eda4f38f967", - "counterparty_node_id": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9", - "closure_reason": "Channel closed because of an exception: We consider the minimum depth to be unreasonably large. Expected minimum: (1). Actual: (3)", - "is_outbound": false, - "is_public": false, - "is_closed": true, - "created_at": 1683866505, - "closed_at": 1683866505 - }], - "limit": 10, - "skipped": 0, - "total": 1, - "total_pages": 1, - "paging_options": { - "PageNumber": 1 - } - }, "id": 55 + "payment_hash": "c4e25cc10d77e3cd5f3d2af7b14ad72f123b2a5021bd6705c0b8ee8386bdeceb" + }, + "id": 762 } ``` -#### ๐Ÿ“Œ Example with `filter` for a specific `node_id` - -#### Command +#### ๐Ÿ“Œ Example using `keysend` - + ```json { "userpass": "testpsw", "mmrpc": "2.0", - "method": "lightning::channels::list_closed_channels_by_filter", + "method": "lightning::payments::send_payment", "params": { "coin": "tBTC-lightning", - "filter": { - "counterparty_node_id": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9" + "payment": { + "type": "keysend", + "destination": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9", + "amount_in_msat": 1000, + "expiry": 24 } }, - "id": 55 + "id": 6 } ``` @@ -45226,366 +46552,353 @@ The `lightning::channels::list_closed_channels_by_filter` method returns a list #### Response ```json - - {"mmrpc": "2.0", + { + "mmrpc": "2.0", "result": { - "closed_channels": [{ - "uuid": "434681f8-95e5-484f-af49-fa80d8ae857b", - "channel_id": "ebfbf19193ee26f25c6e236e863786e59818c11e136ce9c50dba63ec44b0c89a", - "counterparty_node_id": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9", - "closure_reason": "Channel closed because counterparty force-closed with message chan size of 0.00004 BTC is below min chan size of 0.0002 BTC", - "is_outbound": true, - "is_public": false, - "is_closed": true, - "created_at": 1683864431, - "closed_at": 1683864432 - }], - "limit": 10, - "skipped": 0, - "total": 1, - "total_pages": 1, - "paging_options": { - "PageNumber": 1 - } - }, "id": 55 + "payment_hash": "2620d47033fd366bff40cfe0879c47f683ef66c3882d0fab88a9bc72b5499655" + }, + "id": 762 } ``` -#### ๐Ÿ“Œ Example with `filter` for a node with between 100000 and 500000 satoshi funding value - -#### Command + + ### PaymentError (attempt to pay self) - ```json { - "userpass": "testpsw", - "mmrpc": "2.0", - "method": "lightning::channels::list_closed_channels_by_filter", - "params": { - "coin": "tBTC-lightning", - "filter": { - "from_funding_value_sats": 100000, - "to_funding_value_sats": 500000 - } - }, - "id": 55 + "mmrpc": "2.0", + "error": "Payment error: Error paying invoice: Routing(LightningError { err: "Cannot generate a route to ourselves", action: IgnoreError })", + "error_path": "send_payment.lightning", + "error_trace": "send_payment:102] lightning:231]", + "error_type": "PaymentError", + "error_data": "Error paying invoice: Routing(LightningError { err: "Cannot generate a route to ourselves", action: IgnoreError })", + "id": 6 } ``` - - - #### Response + ### PaymentError (no outbound routes) ```json { "mmrpc": "2.0", - "result": { - "closed_channels": [{ - "uuid": "f901b604-54f7-4094-80f7-86aa9e362343", - "channel_id": "20aae008973fad5a59559ac0650143ec5b53aba1c6584d3d92177491a8284d00", - "counterparty_node_id": "02312627fdf07fbdd7e5ddb136611bdde9b00d26821d14d94891395452f67af248", - "funding_tx": "3807d9353557d15ad46e90a68dab8e4cd3a68a4af6b61bc7414bf81e29bc0517", - "funding_value": 40000, - "closing_tx": "61575237132b78aa5d1b4d62137da316bc67d09804b0bee53ab50f5d7cd0337c", - "closure_reason": "Channel closed because the channel was cooperatively closed", - "funding_generated_in_block": 2433122, - "is_outbound": true, - "is_public": false, - "is_closed": true, - "created_at": 1684083341, - "closed_at": 1684146940 - }], - "limit": 10, - "skipped": 0, - "total": 1, - "total_pages": 1, - "paging_options": { - "PageNumber": 1 - } - }, + "error": "Payment error: Error paying invoice: Routing(LightningError { err: 'Cannot route when there are no outbound routes away from us ', action: IgnoreError })", + "error_path": "send_payment.lightning", + "error_trace": "send_payment:102] lightning:232]", + "error_type": "PaymentError", + "error_data": "Error paying invoice: Routing(LightningError { err: 'Cannot route when there are no outbound routes away from us ', action: IgnoreError })", "id": 762 } ``` - -export const title = "AtomicDEX: Lightning Network Methods"; -export const description = - "This document describes all the available methods for the Lightning Network on AtomicDEX-API."; - -import lightningflowchart from "@/public/images/api-images/lightning-methods.png"; - -# Lightning Network Methods - - - Lightning methods are currently only available using the native AtomicDEX-API. - WASM support should be available in late 2023. - - -## Lightning Network Initialization Tasks - -* Initialise your lightning node with [task::enable\_lightning::init](/atomicdex/api/v20-dev/lightning/activation/#initialize-lightning) -* Check the initialization status of the lightning node with [task::enable\_lightning::status](/atomicdex/api/v20-dev/lightning/activation/#initialization-status) -* Cancel initialization process of the lightning node with [task::enable\_lightning::cancel](/atomicdex/api/v20-dev/lightning/activation/#cancel-initialization) - - - Any methods with a `task::` prefix will be linked to a numeric `task_id` value - which is used to query the status or outcome of the task. - - -## Lightning Network Nodes Methods - -* Connect to a lightning node with [lightning::nodes::connect\_to\_node](/atomicdex/api/v20-dev/lightning/nodes/#connect-to-node) -* Add a trusted node with [lightning::nodes::add\_trusted\_node](/atomicdex/api/v20-dev/lightning/nodes/#add-trusted-node) -* Remove a trusted node with [lightning::nodes::remove\_trusted\_node](/atomicdex/api/v20-dev/lightning/nodes/#remove-trusted-node) -* List your trusted lightning nodes with [lightning::nodes::list\_trusted\_nodes](/atomicdex/api/v20-dev/lightning/nodes/#list-trusted-nodes) - -## Lightning Network Channels Methods - -* Open a lightning channel [lightning::channels::open\_channel](/atomicdex/api/v20-dev/lightning/channels/#open-channel) -* Close a lightning channel [lightning::channels::close\_channel](/atomicdex/api/v20-dev/lightning/channels/#close-channel) -* Update a lightning channel [lightning::channels::update\_channel](/atomicdex/api/v20-dev/lightning/channels/#update-channel) -* Get details about a lightning channel [lightning::channels::get\_channel\_details](/atomicdex/api/v20-dev/lightning/channels/#get-channel-details) -* Get claimable balances from lightning channels [lightning::channels::get\_claimable\_balances](/atomicdex/api/v20-dev/lightning/channels/#get-claimable-balances) -* List open lightning channels matching a filter [lightning::channels::list\_open\_channels\_by\_filter](/atomicdex/api/v20-dev/lightning/channels/#list-open-channels-by-filter) -* List closed lightning channels matching a filter [lightning::channels::list\_closed\_channels\_by\_filter](/atomicdex/api/v20-dev/lightning/channels/#list-closed-channels-by-filter) - -## Lightning Network Payments Methods - -* Generate lightning invoices with [lightning::payments::generate\_invoice](/atomicdex/api/v20-dev/lightning/payments/#generate-invoice) -* Send lightning payments with [lightning::payments::send\_payment](/atomicdex/api/v20-dev/lightning/payments/#send-payment) -* Get details about a lightning payment with [lightning::payments::get\_payment\_details](/atomicdex/api/v20-dev/lightning/payments/#get-payment-details) -* Get a filtered list of lightning payments with [lightning::payments::list\_payments\_by\_filter](/atomicdex/api/v20-dev/lightning/payments/#list-payments-by-filter) - -## Lightning Network Flowchart - -Once you: - -* Enable lightning with [task::enable\_lightning::init](/atomicdex/api/v20-dev/lightning/activation/#initialize-lightning) -* Connect to a lightning node with [lightning::nodes::connect\_to\_node](/atomicdex/api/v20-dev/lightning/nodes/#connect-to-node) -* Open a lightning channel [lightning::channels::open\_channel](/atomicdex/api/v20-dev/lightning/channels/#open-channel) - -You can get an invoice for a coffee from [https://starblocks.acinq.co](https://starblocks.acinq.co)! - -Then you can: - -* Pay the invoice with [lightning::payments::send\_payment](/atomicdex/api/v20-dev/lightning/payments/#send-payment) -* View details about the payment with [lightning::payments::get\_payment\_details](/atomicdex/api/v20-dev/lightning/payments/#get-payment-details) -* List your payments with [lightning::payments::list\_payments\_by\_filter](/atomicdex/api/v20-dev/lightning/payments/#list-payments-by-filter) - -Follow the flowchart below to visualize the process: - - -## Lightning Network Coins File Configuration + ### PaymentError (keysend - no path to destination) - - Some configurations are set per coin, and some are set per channel. The - [counterparty\_channel\_config\_limits](/atomicdex/api/common_structures/lightning/#counterparty-channel-config) - param must be set in the `coins` configuration file, and aplies to all - channels opened by counterparty nodes. The - [our\_channels\_config](/atomicdex/api/common_structures/lightning/#lightning-channel-config) and - [channel\_options](/atomicdex/api/common_structures/lightning/#lightning-channel-options) parameters - are set per channel. These can be defined in the `coins` configuration file to - act as the default for all opened channels, and optionally overwritten or - updated using the - [open\_channel](/atomicdex/api/v20-dev/lightning/channels/#open-channel) or - [update\_channel](/atomicdex/api/v20-dev/lightning/channels/#update-channel) - methods. - + ```json + { + "mmrpc": "2.0", + "error": "Payment error: Keysend error: Routing(LightningError { err: "Failed to find a path to the given destination", action: IgnoreError })", + "error_path": "send_payment.lightning", + "error_trace": "send_payment:107] lightning:256]", + "error_type": "PaymentError", + "error_data": "Keysend error: Routing(LightningError { err: "Failed to find a path to the given destination", action: IgnoreError })", + "id": 762 + } + ``` -### Lightning Coin Config Parameters + ### PaymentError (invoice - no path to destination) -| Parameter | Type | Description | -| ------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| coin | object | The ticker of the coin you will use lightning network with, suffixed with `-lightning` | -| mm2 | integer | Defaults to `0`. A value of `1`, indicates the coin is atomic swap compatible. | -| decimals | integer | The decimal precision of the coin you will use the lightning network with. | -| protocol | object | A standard [CoinProtocol](/atomicdex/api/common_structures/activation/#coin-protocol) object. | -| accept\_inbound\_channels | boolean | Optional, defaults to `true`. If this is set to false, we do not accept inbound requests to open a new channel. | -| accept\_forwards\_to\_priv\_channels | boolean | Optional, defaults to `false`. When set to `false`, any HTLCs which were to be forwarded over private channels will be rejected. This prevents us from taking on HTLC-forwarding risk when we intend to run as a node which is not online reliably (e.g. GUI wallet apps). Generally, private channels are used for non-routing purposes only. | -| counterparty\_channel\_config\_limits | object | Optional. A standard [CounterpartyChannelConfig](/atomicdex/api/common_structures/lightning/#counterparty-channel-config) object. | -| channel\_options | object | Optional. A standard [LightningChannelOptions](/atomicdex/api/common_structures/lightning/#lightning-channel-options) object. | -| our\_channels\_config | object | Optional. A standard [LightningChannelConfig](/atomicdex/api/common_structures/lightning/#lightning-channel-config) object. | + ```json + { + "mmrpc": "2.0", + "error": "Payment error: Error paying invoice: Routing(LightningError { err: 'Failed to find a path to the given destination', action: IgnoreError })", + "error_path": "send_payment.lightning", + "error_trace": "send_payment:102] lightning:232]", + "error_type": "PaymentError", + "error_data": "Error paying invoice: Routing(LightningError { err: 'Failed to find a path to the given destination', action: IgnoreError })", + "id": 762 + } + ``` - - For GUIs and wallet apps, it is recommended to set - `accept_forwards_to_priv_channels` to `false`. This prevents users from taking - on HTLC-forwarding risk when a node is expected to not be reliably online. - [our\_channels\_config::announced\_channel](/atomicdex/api/common_structures/lightning/#lightning-channel-options) - should also be set to `false` for GUIs and wallet apps. - + ### InvalidRequest (request is missing a required field) - ```json - { - "coin": "BTC-lightning", - "mm2": 1, - "decimals": 11, - "our_channels_config": { - "inbound_channels_confirmations": 3, - "max_inbound_in_flight_htlc_percent": 90 - }, - "counterparty_channel_config_limits": { - "outbound_channels_confirmations": 3, - "force_announced_channel_preference": false - }, - "protocol": { - "type": "LIGHTNING", - "protocol_data":{ - "platform": "BTC-segwit", - "network": "mainnet", - "confirmation_targets": { - "background": 12, - "normal": 6, - "high_priority": 1 - } - } - } - }, - { - "coin": "tBTC-lightning", - "mm2": 1, - "decimals": 11, - "our_channels_configs": { - "inbound_channels_confirmations": 3, - "max_inbound_in_flight_htlc_percent": 90, - "their_channel_reserve_sats": 10000 - }, - "counterparty_channel_config_limits": { - "outbound_channels_confirmations": 3 - }, - "protocol": { - "type": "LIGHTNING", - "protocol_data":{ - "platform": "tBTC-segwit", - "network": "testnet", - "confirmation_targets": { - "background": 12, - "normal": 6, - "high_priority": 1 - } - } - } - }, + { + "mmrpc": "2.0", + "error": "Error parsing request: missing field `payment`", + "error_path": "dispatcher", + "error_trace": "dispatcher:109]", + "error_type": "InvalidRequest", + "error_data": "missing field `payment`", + "id": 762 + } ``` - -export const title = "AtomicDEX: Lightning Network Nodes"; -export const description = "The methods in this document allow management of connections to Lightning Network Nodes on AtomicDEX-API."; -# Lightning Network Nodes + ### InvalidRequest (A required field is invalid) - - Lightning methods are currently only available using the native AtomicDEX-API. WASM support should be available in late 2023. - + ```json + { + "mmrpc": "2.0", + "error": "Error parsing request: ParseError(Bech32Error(MissingSeparator))", + "error_path": "dispatcher", + "error_trace": "dispatcher:109]", + "error_type": "InvalidRequest", + "error_data": "ParseError(Bech32Error(MissingSeparator))", + "id": 762 + } + ``` + -## Connect to Node {{label : 'lightning::nodes::connect_to_node', tag : 'API-v2'}} +## Get Payment Details {{label : 'lightning::payments::get_payment_details', tag : 'API-v2'}} -The `lightning::nodes::connect_to_node` method allows you to connect to a lightning node. +The `lightning::payments::get_payment_details` method returns details about a lightning payment from a given `payment_hash`. ### Request Parameters -| Parameter | Type | Description | -| ------------- | ------ | ----------------------------------------------------------------------------------- | -| coin | string | The coin ticker you would like to connect to a node on. | -| node\_address | string | Lightning nodes addresses always have a format of `node_pubkey`@`ip_address`:`port` | +| Parameter | Type | Description | +| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| coin | string | Ticker of the coin to query. | +| payment\_hash | string | The hexidecimal string which identifies a invoice. The payment\_hash is returned from a `lightning::payments::send_payment` request if the payment was sent by us, or from a `lightning::payments::generate_invoice` request if the payment is received (or will be received) by us. | #### ๐Ÿ“Œ Example - + ```json { + "method": "lightning::payments::get_payment_details", "userpass": "testpsw", "mmrpc": "2.0", - "method": "lightning::nodes::connect_to_node", "params": { "coin": "tBTC-lightning", - "node_address": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9@203.132.94.196:9735" + "payment_hash": "414f9b3524fc4e48c99f2723952732d8bc2eba1b35ce3bf2a70f5144b40f599e" }, "id": 1 } ``` - - The node address in the above request is for the WalletOfSatoshi lightning node, which is one of the most connected lightning nodes. - Other node addresses can be retrieved from any lightning explorer, such as: + + ```json + { + "mmrpc": "2.0", + "result": { + "payment_details": { + "payment_hash": "c4e25cc10d77e3cd5f3d2af7b14ad72f123b2a5021bd6705c0b8ee8386bdeceb", + "payment_type": { + "type": "Outbound Payment", + "destination": "0348cc1a9479697cd52db445ea74149ad40bb01bb2045a3e8acba21b70f94ab7cf" + }, + "description": "1 Blokaccino", + "amount_in_msat": 1000000, + "fee_paid_msat": 1803, + "status": "succeeded", + "created_at": 1684081413, + "last_updated": 1684081419 + } + }, + "id": 762 + } + ``` + - * [https://1ml.com/](https://1ml.com/) - * [https://mempool.space/lightning/](https://mempool.space/lightning/) - + + ### NoSuchPayment (payment hash not found) - - #### Response (success) + ```json + { + "mmrpc": "2.0", + "error": "Payment with hash: 414f9b3524fc4e48c99f2723952732d8bc2eba1b35ce3bf2a70f5144b40f599e is not found", + "error_path": "get_payment_details", + "error_trace": "get_payment_details:75]", + "error_type": "NoSuchPayment", + "error_data": "414f9b3524fc4e48c99f2723952732d8bc2eba1b35ce3bf2a70f5144b40f599e", + "id": 762 + } + ``` + + ### InvalidRequest (payment\_hash not a hash string) ```json { - "mmrpc": "2.0", - "result": "Connected successfully to node : 035e4ff418fc8b5554c5d9eea66396c227bd429a3251c8cbc711002ba215bfc226@170.75.163.209:9735", - "id": null + "mmrpc": "2.0", + "error": "Error parsing request: invalid value: string '', expected a hash string", + "error_path": "dispatcher", + "error_trace": "dispatcher:109]", + "error_type": "InvalidRequest", + "error_data": "invalid value: string '', expected a hash string", + "id": 762 } ``` + - #### Response (already connected) +## List Payments by Filter {{label : 'lightning::payments::list_payments_by_filter', tag : 'API-v2'}} + +The `lightning::payments::list_payments_by_filter` method returns a list of payments (sent and/or received) for a coin which match the given filter. + +### Request Parameters + +| Parameter | Type | Description | +| --------------- | ------- | --------------------------------------------------------------------------------------------------------------------------- | +| coin | string | Ticker of the coin to query. | +| filter | object | Optional. A standard [LightningPaymentFilter](/atomicdex/api/common_structures/lightning/#lightning-payment-filter) object. | +| paging\_options | object | Optional. A standard [Pagination](/atomicdex/api/common_structures/#pagination) object. | +| limit | integer | Optional, defaults to `10`. Maximum number of results to return. | +#### ๐Ÿ“Œ Example without filter + + ```json { - "mmrpc": "2.0", - "result": "Already connected to node : 035e4ff418fc8b5554c5d9eea66396c227bd429a3251c8cbc711002ba215bfc226@170.75.163.209:9735", - "id": null + "method": "lightning::payments::list_payments_by_filter", + "userpass": "testpsw", + "mmrpc": "2.0", + "params": { + "coin": "tBTC-lightning" + }, + "id": 1 + } + ``` + + + + #### Response + + ```json + { + "mmrpc": "2.0", + "result": { + "payments": [{ + "payment_hash": "59175643db24fc79c77da073994d596444b6909fb2d452bde662ae386115c758", + "payment_type": { + "type": "Inbound Payment" + }, + "description": "For the burger on Tuesday", + "amount_in_msat": 10000, + "status": "pending", + "created_at": 1683917593, + "last_updated": 1683917593 + }, { + "payment_hash": "3ff39605f214a4b4159f9c4f44c94de3a273f300042ca18b7cb3d62f270a9ebc", + "payment_type": { + "type": "Outbound Payment" + }, + "description": "A 1:24 scale model of a 1981 DeLorean DMC-12", + "amount_in_msat": 88000, + "status": "succeeded", + "created_at": 1683815625, + "last_updated": 1683815721 + }, { + "payment_hash": "c4f44c94214a4b4159f9273f30de3a3ff39605f18b7c27b3d62f0a9ebc", + "payment_type": { + "type": "Outbound Payment" + }, + "description": "Grays Sports Almanac, 1950-2000", + "amount_in_msat": 1000000000, + "status": "succeeded", + "created_at": 1683714225, + "last_updated": 1683805721 + }, { + "payment_hash": "c4f44c94214a4b4159f9273f30de3a3ff39605f18b7c27b3d62f0a9ebc", + "payment_type": { + "type": "Outbound Payment" + }, + "description": "ACME shrink ray", + "amount_in_msat": 4000012, + "status": "succeeded", + "created_at": 1683814625, + "last_updated": 1683815321 + }], + "limit": 10, + "skipped": 0, + "total": 6, + "total_pages": 1, + "paging_options": { + "PageNumber": 1 + } + }, + "id": 1 } ``` - - #### InvalidRequest Error (Invalid node\_address) +#### ๐Ÿ“Œ Example for Inbound Payment `payment_type`, `limit` and `pagination` + ```json { - "mmrpc": "2.0", - "error": "Error parsing request: Could not parse node address from str rgjhk3", - "error_path": "dispatcher", - "error_trace": "dispatcher:109]", - "error_type": "InvalidRequest", - "error_data": "Could not parse node address from str rgjhk3", - "id": 762 + "method": "lightning::payments::list_payments_by_filter", + "userpass": "testpsw", + "mmrpc": "2.0", + "params": { + "coin": "tBTC-lightning", + "filter": { + "payment_type": { + "type": "Inbound Payment" + } + }, + "limit": 2, + "paging_options": { + "PageNumber": 2 + } + }, + "id": 1 } ``` + - #### ConnectionError Error (Timed out waiting to connect to node\_address) - + ```json { - "mmrpc": "2.0", - "error": "Error connecting to node: Timeout error: Failed to connect to node: 035e4ff418fc8b5554c5d9eea66396c227bd429a3251c8cbc711002ba215bfc226", - "error_path": "connect_to_node", - "error_trace": "connect_to_node:78]", - "error_type": "ConnectionError", - "error_data": "Timeout error: Failed to connect to node: 035e4ff418fc8b5554c5d9eea66396c227bd429a3251c8cbc711002ba215bfc226", - "id": null + "mmrpc": "2.0", + "result": { + "payments": [{ + "payment_hash": "e51f1526d3322ddc0aaa0e893e5875418ddd12f206b7e1545c8e4375c97d0e31", + "payment_type": { + "type": "Inbound Payment" + }, + "description": "For the burger on Tuesday", + "amount_in_msat": 10000, + "status": "pending", + "created_at": 1683916900, + "last_updated": 1683916900 + }, { + "payment_hash": "605f214a4b4b159f9c4f44c94de3a273f3ff39300042ca18b7cbb4159f3d62f2", + "payment_type": { + "type": "Inbound Payment" + }, + "description": "14 pallets of frozen spinach", + "amount_in_msat": 56005000, + "status": "succeeded", + "created_at": 1683815625, + "last_updated": 1683815721 + }], + "limit": 2, + "skipped": 2, + "total": 7, + "total_pages": 4, + "paging_options": { + "PageNumber": 2 + } + }, + "id": 1 } ``` -## List Trusted Nodes {{label : 'lightning::nodes::list_trusted_nodes', tag : 'API-v2'}} - -The `lightning::nodes::list_trusted_nodes` method allows you to list all nodes in your trusted list. - -### Request Parameters - -| Parameter | Type | Description | -| --------- | ------ | ------------------------------------------------------------- | -| coin | string | The coin ticker you would like to view your trusted nodes to. | - -#### ๐Ÿ“Œ Example +#### ๐Ÿ“Œ Example for `pending` payments between 10000 and 40000 millisatoshis - + ```json { + "method": "lightning::payments::list_payments_by_filter", "userpass": "testpsw", "mmrpc": "2.0", - "method": "lightning::nodes::list_trusted_nodes", "params": { - "coin": "tBTC-lightning" + "coin": "tBTC-lightning", + "filter": { + "status": "pending", + "from_amount_msat": 10000, + "to_amount_msat": 40000 + } }, "id": 1 } @@ -45599,35 +46912,45 @@ The `lightning::nodes::list_trusted_nodes` method allows you to list all nodes i { "mmrpc": "2.0", "result": { - "trusted_nodes": ["038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9"] + "payments": [{ + "payment_hash": "e51f1526d3322ddc0aaa0e893e5875418ddd12f206b7e1545c8e4375c97d0e31", + "payment_type": { + "type": "Inbound Payment" + }, + "description": "For the burger on Tuesday", + "amount_in_msat": 10000, + "status": "pending", + "created_at": 1683916900, + "last_updated": 1683916900 + }], + "limit": 10, + "skipped": 6, + "total": 1, + "total_pages": 1, + "paging_options": { + "PageNumber": 1 + } }, "id": 1 } ``` -## Add Trusted Node {{label : 'lightning::nodes::add_trusted_node', tag : 'API-v2'}} - -The `lightning::nodes::add_trusted_node` method allows you to add a node to your trusted list. - -### Request Parameters - -| Parameter | Type | Description | -| --------- | ------ | --------------------------------------------------------- | -| coin | string | The coin ticker you would like to add a trusted node for. | -| node\_id | string | ID of node you would like to add to your trusted list. | - -#### ๐Ÿ“Œ Example +#### ๐Ÿ“Œ Example for successful payments on the 20th of April 2023 - + ```json { + "method": "lightning::payments::list_payments_by_filter", "userpass": "testpsw", "mmrpc": "2.0", - "method": "lightning::nodes::add_trusted_node", "params": { "coin": "tBTC-lightning", - "node_id": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9" + "filter": { + "status": "succeeded", + "from_timestamp": 1681948800, + "to_timestamp": 1682035199 + } }, "id": 1 } @@ -45641,319 +46964,539 @@ The `lightning::nodes::add_trusted_node` method allows you to add a node to your { "mmrpc": "2.0", "result": { - "added_node": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9" + "payments": [{ + "payment_hash": "c4f44c94214a4b4159f9273f30de3a3ff39605f18b7c27b3d62f0a9ebc", + "payment_type": { + "type": "Outbound Payment" + }, + "description": "Grays Sports Almanac, 1950-2000", + "amount_in_msat": 1000000000, + "status": "succeeded", + "created_at": 1681998480, + "last_updated": 1682008491 + }], + "limit": 10, + "skipped": 6, + "total": 1, + "total_pages": 1, + "paging_options": { + "PageNumber": 1 + } }, "id": 1 } ``` +export const title = "AtomicDEX Method: Max Maker Vol"; +export const description = + "The max_maker_vol method returns the maximum volume of a coin which can be used to create a maker order."; -## Remove Trusted Node {{label : 'lightning::nodes::remove_trusted_node', tag : 'API-v2'}} +# max\_maker\_vol -The `lightning::nodes::remove_trusted_node` method allows you to remove a node from your trusted list. +The `max_maker_vol` method returns the maximum volume of a coin which can be used to create a maker order (taking into account estimated fees). If the coin is not activated, a `NoSuchCoin` error will be returned. -### Request Parameters +#### Arguments -| Parameter | Type | Description | -| --------- | ------ | ------------------------------------------------------------- | -| coin | string | The coin ticker you would like to remove a trusted node from. | -| node\_id | string | ID of node you would like to remove from your trusted list. | +| Parameter | Type | Description | +| --------- | ------ | ----------------------------------------- | +| coin | string | The ticker of the coin you want to query. | -#### ๐Ÿ“Œ Example +#### Response - +| Parameter | Type | Description | +| ----------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| coin | string | The ticker of the coin you queried. | +| volume | object | A standard [NumericFormatsValue](/atomicdex/api/common_structures/#numeric-formats-value) object representing the tradable maker volume. | +| balance | object | A standard [NumericFormatsValue](/atomicdex/api/common_structures/#numeric-formats-value) object representing the tradable taker balance. | +| locked\_by\_swaps | object | A standard [NumericFormatsValue](/atomicdex/api/common_structures/#numeric-formats-value) object representing the volume of a coin's balance which is locked by swaps in progress. | + +#### ๐Ÿ“Œ Examples + +#### Command + + ```json { "userpass": "testpsw", "mmrpc": "2.0", - "method": "lightning::nodes::remove_trusted_node", + "method": "max_maker_vol", "params": { - "coin": "tBTC-lightning", - "node_id": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9" - }, - "id": 1 + "coin": "DOC" + } } ``` - #### Response + #### Response (success) ```json { - "mmrpc": "2.0", - "result": { - "removed_node": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9" - }, - "id": 1 - } - ``` - -export const title = "AtomicDEX: Lightning Network Payments"; -export const description = "The methods in this document allow management of Lightning Network Payments on AtomicDEX-API."; - -# Lightning Network Payments - - - Lightning methods are currently only available using the native AtomicDEX-API. WASM support should be available in late 2023. - - -## Generate invoice {{label : 'lightning::payments::generate_invoice', tag : 'API-v2'}} - -The `lightning::payments::generate_invoice` method generates an invoice to be paid by another node. - -### Request Parameters - -| Parameter | Type | Description | -| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -| coin | string | Ticker of coin to generate invoice for. | -| description | string | A note to indicate the purpose of the invoice. | -| amount\_in\_msat | integer | Amount to be paid, in [millisatoshis](https://bitcoindata.science/bitcoin-units-converter) (A thousandth of a satoshi; the same as 0.00000000001 bitcoin.) | -| expiry | integer | Optional, defaults to `3600`. Seconds until the invoice expires. | + "mmrpc": "2.0", + "result": { + "coin": "MARTY", + "volume": { + "decimal": "4.489763268712998712998712998712998712998712998712998712998712998712998712998712998712998712998712999", + "rational": [ + [1, [962255003, 81]], + [1, [390588672, 18]] + ], + "fraction": { + "numer": "348854605979", + "denom": "77700000000" + } + }, + "balance": { + "decimal": "5.49110027", + "rational": [ + [1, [549110027]], + [1, [100000000]] + ], + "fraction": { + "numer": "549110027", + "denom": "100000000" + } + }, + "locked_by_swaps": { + "decimal": "1.001317001287001287001287001287001287001287001287001287001287001287001287001287001287001287001287001", + "rational": [ + [1, [77802331]], + [1, [77700000]] + ], + "fraction": { + "numer": "77802331", + "denom": "77700000" + } + } + }, + "id": null + } + ``` -#### ๐Ÿ“Œ Example + #### Response (error) - ```json { - "method": "lightning::payments::generate_invoice", - "userpass": "testpsw", "mmrpc": "2.0", - "params": { - "coin": "tBTC-lightning", - "description": "For the burger on Tuesday", - "amount_in_msat": 10000, - "expiry": 600 + "error": "No such coin TIME", + "error_path": "max_maker_vol_rpc.lp_coins", + "error_trace": "max_maker_vol_rpc:140] lp_coins:2894]", + "error_type": "NoSuchCoin", + "error_data": { + "coin": "TIME" }, - "id": 1 + "id": null } ``` - - - #### Response + #### Response (balance too low) ```json { - "mmrpc": "2.0", - "result": { - "payment_hash": "3ff39605f214a4b4159f9c4f44c94de3a273f300042ca18b7cb3d62f270a9ebc", - "invoice": "lntb100n1pj9aq73dpggehhygr5dpjjqcn4wfnk2u3qdahzq4r4v4ekgctenp4qf3dqylh55jd8m5x5hh0g5q82h9p86yghwhl2s0t826nlyp8zdgjzpp58leevp0jzjjtg9vln385fj2duw388ucqqsk2rzmuk0tz7fc2n67qsp5k33rvvq46xtuppl22ggcq5q7qqywyekcemhzazt4m6vulwsarcrq9qyysgqcqpcxqzjcrzjqwyx8nu2hygyvgc02cwdtvuxe0lcxz06qt3lpsldzcdr46my5epmjfgaasqqqvqqqqqqqqlgqqqqqqgq9qpwesnhre7xmdg6tajvp939vl72vxm8csecy6hfcah9fzgazd5eyzjskgtt7u9xshj7gq2vkejjcquem08tqfrc2pj78xa95teazzf0qq7pnyqj" - }, - "id": 1 + "mmrpc": "2.0", + "error": "Not enough QTUM for swap: available 0, required at least 0.000728, locked by swaps None", + "error_path": "max_maker_vol_rpc.maker_swap.utxo_common", + "error_trace": "max_maker_vol_rpc:148] maker_swap:2203] utxo_common:3327] utxo_common:892]", + "error_type": "NotSufficientBalance", + "error_data": { + "coin": "QTUM", + "available": "0", + "required": "0.000728" + }, + "id": null } ``` - - - ### InvalidRequest (invalid paramater value) + #### Response (Transport error) ```json { - "mmrpc": "2.0", - "error": "Error parsing request: invalid type: string '56', expected u64", - "error_path": "dispatcher", - "error_trace": "dispatcher:109]", - "error_type": "InvalidRequest", - "error_data": "invalid type: string '56', expected u64", - "id": 762 + "mmrpc": "2.0", + "error": "Transport error: JsonRpcError { client_info: 'coin: tBTC', request: JsonRpcRequest { jsonrpc: '2.0', id: '31', method: 'blockchain.estimatefee', params: [Number(1), String('ECONOMICAL')] }, error: Transport('rpc_clients:1237] rpc_clients:1239] ['rpc_clients:2047] common:1385] future timed out']') }", + "error_path": "taker_swap.utxo_common", + "error_trace": "taker_swap:1599] utxo_common:1990] utxo_common:166]", + "error_type": "Transport", + "error_data": "JsonRpcError { client_info: 'coin: tBTC', request: JsonRpcRequest { jsonrpc: '2.0', id: '31', method: 'blockchain.estimatefee', params: [Number(1), String('ECONOMICAL')] }, error: Transport('rpc_clients:1237] rpc_clients:1239] ['rpc_clients:2047] common:1385] future timed out']') }", + "id": 0 } ``` +export const title = "AtomicDEX: Non Fungible Tokens - Get NFT List"; +export const description = + "This document describes all the get_nft_list method AtomicDEX-API provides to get a list of your wallets NFTs"; -## Send Payment {{label : 'lightning::payments::send_payment', tag : 'API-v2'}} +# Get a list of NFTs {{label : 'get_nft_list', tag : 'API-v2'}} -The `lightning::payments::send_payment` method sends a payment to another node. +Returns a list of the NFTs owned by the user, shown in descending order of the `block_number` value (the block height when the amount or owner changed). If the request is for NFTs on more than one chain, this means that the order may not be chronological. In the case of ERC1155 tokens, the `block_number` will update when additional NFTs are received or when all NFTs are withdrawn, but will generally remain the same if only some NFTs are withdrawn. -Used to pay an invoice or send a payment via pubkey/address. + + Before using this method, you must first call the [update\_nft](/atomicdex/api/v20-dev/non_fungible_tokens/update_nft/) + method to populate/refresh the local database. + ### Request Parameters -| Parameter | Type | Description | -| --------- | ------ | ---------------------------------------------------------------------------------------------------- | -| type | string | Ticker of the coin to query. | -| payment | object | A standard [LightningPayment](/atomicdex/api/common_structures/lightning/#lightning-payment) object. | +| Parameter | Type | Description | +| ------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| chains | array | List of networks to scan for NFTs. Options are: `POLYGON`, `FANTOM`, `ETH`, `BSC`, or `AVALANCHE`. | +| max | boolean | Optional, defaults to `false`. If `true`, response will return all NFTs without pagination, and will ignore the `limit` and `page_number` values. | +| limit | integer | Optional, defaults to `10`. The number of NFTs displayed per page in response. | +| page\_number | integer | Optional, defaults to `1`. The page offset for items in response. | +| protect\_from\_spam | boolean | Optional, defaults to `false`. If `true`, any potential spam link found in collection name, token name, symbol will be replaced with `URL redacted for user protection` | +| filters | object | Optional. A standard [TokenFilter](/atomicdex/api/v20/#token-filter) object. | -#### ๐Ÿ“Œ Example using `invoice` +### Response Parameters - +| Parameter | Type | Description | +| --------- | --------------- | -------------------------------------------------------------------------------------- | +| nfts | list of objects | A list of standard [NftInfo](/atomicdex/api/common_structures/nfts/#nft-info) objects. | +| total | string | The total number of NFTs in your wallet matching the request filters. | +| skipped | string | The number of NFTs in your wallet excluded by the request filters. | + +#### ๐Ÿ“Œ Example with no optional params + + ```json { "userpass": "testpsw", + "method": "get_nft_list", "mmrpc": "2.0", - "method": "lightning::payments::send_payment", "params": { - "coin": "tBTC-lightning", - "payment": { - "type": "invoice", - "invoice": "lntb20u1p32wwxapp5p8gjy2e79jku5tshhq2nkdauv0malqqhzefnqmx9pjwa8h83cmwqdp8xys9xcmpd3sjqsmgd9czq3njv9c8qatrvd5kumcxqrrsscqp79qy9qsqsp5m473qknpecv6ajmwwtjw7keggrwxerymehx6723avhdrlnxmuvhs54zmyrumkasvjp0fvvk2np30cx5xpjs329alvm60rwy3payrnkmsd3n8ahnky3kuxaraa3u4k453yf3age7cszdxhjxjkennpt75erqpsfmy4y" - } - }, - "id": 6 + "chains": [ + "BSC", + "POLYGON" + ] + } } ``` - #### Response - ```json { - "mmrpc": "2.0", - "result": { - "payment_hash": "c4e25cc10d77e3cd5f3d2af7b14ad72f123b2a5021bd6705c0b8ee8386bdeceb" - }, - "id": 762 + "mmrpc": "2.0", + "result": { + "nfts": [ + { + "chain": "BSC", + "token_address": "0x5c7d6712dfaf0cb079d48981781c8705e8417ca0", + "token_id": "0", + "amount": "1", + "owner_of": "0xf622a6c52c94b500542e2ae6bcad24c53bc5b6a2", + "token_hash": "b34ddf294013d20a6d70691027625839", + "block_number_minted": 25465916, + "block_number": 25919780, + "contract_type": "ERC1155", + "name": null, + "symbol": null, + "token_uri": "https://tikimetadata.s3.amazonaws.com/tiki_box.json", + "token_domain": "tikimetadata.s3.amazonaws.com", + "metadata": "{\"name\":\"Tiki box\",\"description\":\"Born to usher in Bull markets. Tiki JumpStarters are crazed guardians that worship NGU technology. Tiki guardians attach themselves to their owners to guide and protect them from the evils of the crypto industry. Manifested by the power of community and infused with unlimited creativity, the Unlockable Road Map summons powerful gifts and surprises to all Tiki Holders. Booyaaah!!\",\"external_url\":\"\",\"image\":\"https://tikimetadata.s3.amazonaws.com/tiki_box.png\",\"attributes\":[{\"trait_type\":\"Crypto Logo\",\"value\":\"TIKI NFT CRYPTOLOGO SCAR\"}],\"properties\":{\"category\":\"image\",\"creators\":[]}}", + "last_token_uri_sync": "2023-02-07T17:10:08.402Z", + "last_metadata_sync": "2023-02-07T17:10:16.858Z", + "minter_address": "ERC1155 tokens don't have a single minter", + "possible_spam": false, + "possible_phishing": false, + "uri_meta": { + "image": "https://tikimetadata.s3.amazonaws.com/tiki_box.png", + "image_url": "https://tikimetadata.s3.amazonaws.com/tiki_box.png", + "image_domain": "tikimetadata.s3.amazonaws.com", + "name": "Tiki box", + "description": "Born to usher in Bull markets. Tiki JumpStarters are crazed guardians that worship NGU technology. Tiki guardians attach themselves to their owners to guide and protect them from the evils of the crypto industry. Manifested by the power of community and infused with unlimited creativity, the Unlockable Road Map summons powerful gifts and surprises to all Tiki Holders. Booyaaah!!", + "attributes": [ + { + "trait_type": "Crypto Logo", + "value": "TIKI NFT CRYPTOLOGO SCAR" + } + ], + "animation_url": null, + "animation_domain": null, + "external_url": "", + "external_domain": null, + "image_details": null + } + }, + { + "chain": "POLYGON", + "token_address": "0x48c75fbf0452fa8ff2928ddf46b0fe7629cca2ff", + "token_id": "5", + "amount": "1", + "owner_of": "0xf622a6c52c94b500542e2ae6bcad24c53bc5b6a2", + "token_hash": "28f970585fd743b056859a6e41f50a8e", + "block_number_minted": 36781490, + "block_number": 42491885, + "contract_type": "ERC1155", + "name": null, + "symbol": null, + "token_uri": "https://app.thesmurfssociety.com/metadata/public/metadata/cauldron/5", + "token_domain": "app.thesmurfssociety.com", + "metadata": "{\"name\":\"Forest Mushrooms\",\"description\":\"Sweet and nutty with distinct earthy tones, these forest mushrooms will make a fine addition to all your soups, salads, and potions.\",\"image\":\"https://metadata.thesmurfssociety.com/ingredients/nft/5.Forest_Mushrooms.jpg\",\"animation_url\":null,\"external_url\":\"https://app.thesmurfssociety.com/detail/ingredients/5\",\"attributes\":[{\"trait_type\":\"Type\",\"value\":\"Ingredient\"},{\"trait_type\":\"Category\",\"value\":\"COMMON\"}]}", + "last_token_uri_sync": "2022-12-13T13:12:50.840Z", + "last_metadata_sync": "2023-05-15T07:30:04.882Z", + "minter_address": "ERC1155 tokens don't have a single minter", + "possible_spam": false, + "possible_phishing": false, + "uri_meta": { + "image": "https://metadata.thesmurfssociety.com/ingredients/nft/5.Forest_Mushrooms.jpg", + "image_url": "https://metadata.thesmurfssociety.com/ingredients/nft/5.Forest_Mushrooms.jpg", + "image_domain": "metadata.thesmurfssociety.com", + "name": "Forest Mushrooms", + "description": "Sweet and nutty with distinct earthy tones, these forest mushrooms will make a fine addition to all your soups, salads, and potions.", + "attributes": [ + { + "trait_type": "Type", + "value": "Ingredient" + }, + { + "trait_type": "Category", + "value": "COMMON" + } + ], + "animation_url": null, + "animation_domain": null, + "external_url": "https://app.thesmurfssociety.com/detail/ingredients/5", + "external_domain": "app.thesmurfssociety.com", + "image_details": null + } + } + ], + "skipped": 0, + "total": 2 + }, + "id": null } ``` -#### ๐Ÿ“Œ Example using `keysend` +#### ๐Ÿ“Œ Example with optional limit & page\_number params - + ```json { "userpass": "testpsw", + "method": "get_nft_list", "mmrpc": "2.0", - "method": "lightning::payments::send_payment", "params": { - "coin": "tBTC-lightning", - "payment": { - "type": "keysend", - "destination": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9", - "amount_in_msat": 1000, - "expiry": 24 - } - }, - "id": 6 + "chains": [ + "BSC", + "POLYGON" + ], + "limit": 1, + "page_number": 2 + } } ``` - #### Response - ```json { - "mmrpc": "2.0", - "result": { - "payment_hash": "2620d47033fd366bff40cfe0879c47f683ef66c3882d0fab88a9bc72b5499655" - }, - "id": 762 + "mmrpc": "2.0", + "result": { + "nfts": [ + { + "chain": "POLYGON", + "token_address": "0x48c75fbf0452fa8ff2928ddf46b0fe7629cca2ff", + "token_id": "5", + "amount": "1", + "owner_of": "0xf622a6c52c94b500542e2ae6bcad24c53bc5b6a2", + "token_hash": "28f970585fd743b056859a6e41f50a8e", + "block_number_minted": 36781490, + "block_number": 42491885, + "contract_type": "ERC1155", + "name": null, + "symbol": null, + "token_uri": "https://app.thesmurfssociety.com/metadata/public/metadata/cauldron/5", + "token_domain": "app.thesmurfssociety.com", + "metadata": "{\"name\":\"Forest Mushrooms\",\"description\":\"Sweet and nutty with distinct earthy tones, these forest mushrooms will make a fine addition to all your soups, salads, and potions.\",\"image\":\"https://metadata.thesmurfssociety.com/ingredients/nft/5.Forest_Mushrooms.jpg\",\"animation_url\":null,\"external_url\":\"https://app.thesmurfssociety.com/detail/ingredients/5\",\"attributes\":[{\"trait_type\":\"Type\",\"value\":\"Ingredient\"},{\"trait_type\":\"Category\",\"value\":\"COMMON\"}]}", + "last_token_uri_sync": "2022-12-13T13:12:50.840Z", + "last_metadata_sync": "2023-05-15T07:30:04.882Z", + "minter_address": "ERC1155 tokens don't have a single minter", + "possible_spam": false, + "possible_phishing": false, + "uri_meta": { + "image": "https://metadata.thesmurfssociety.com/ingredients/nft/5.Forest_Mushrooms.jpg", + "image_url": "https://metadata.thesmurfssociety.com/ingredients/nft/5.Forest_Mushrooms.jpg", + "image_domain": "metadata.thesmurfssociety.com", + "name": "Forest Mushrooms", + "description": "Sweet and nutty with distinct earthy tones, these forest mushrooms will make a fine addition to all your soups, salads, and potions.", + "attributes": [ + { + "trait_type": "Type", + "value": "Ingredient" + }, + { + "trait_type": "Category", + "value": "COMMON" + } + ], + "animation_url": null, + "animation_domain": null, + "external_url": "https://app.thesmurfssociety.com/detail/ingredients/5", + "external_domain": "app.thesmurfssociety.com", + "image_details": null + } + } + ], + "skipped": 1, + "total": 1 + }, + "id": null } ``` - - ### PaymentError (attempt to pay self) - - ```json - { - "mmrpc": "2.0", - "error": "Payment error: Error paying invoice: Routing(LightningError { err: "Cannot generate a route to ourselves", action: IgnoreError })", - "error_path": "send_payment.lightning", - "error_trace": "send_payment:102] lightning:231]", - "error_type": "PaymentError", - "error_data": "Error paying invoice: Routing(LightningError { err: "Cannot generate a route to ourselves", action: IgnoreError })", - "id": 6 - } - ``` - - ### PaymentError (no outbound routes) - - ```json - { - "mmrpc": "2.0", - "error": "Payment error: Error paying invoice: Routing(LightningError { err: 'Cannot route when there are no outbound routes away from us ', action: IgnoreError })", - "error_path": "send_payment.lightning", - "error_trace": "send_payment:102] lightning:232]", - "error_type": "PaymentError", - "error_data": "Error paying invoice: Routing(LightningError { err: 'Cannot route when there are no outbound routes away from us ', action: IgnoreError })", - "id": 762 - } - ``` - - ### PaymentError (keysend - no path to destination) +#### ๐Ÿ“Œ Example with optional spam protection + ```json { - "mmrpc": "2.0", - "error": "Payment error: Keysend error: Routing(LightningError { err: "Failed to find a path to the given destination", action: IgnoreError })", - "error_path": "send_payment.lightning", - "error_trace": "send_payment:107] lightning:256]", - "error_type": "PaymentError", - "error_data": "Keysend error: Routing(LightningError { err: "Failed to find a path to the given destination", action: IgnoreError })", - "id": 762 + "userpass": "testpsw", + "method": "get_nft_list", + "mmrpc": "2.0", + "params": { + "chains": [ + "BSC", + "POLYGON" + ], + "protect_from_spam": true, + "filters": { + "exclude_spam": true, + "exclude_phishing": true + } + } } ``` + - ### PaymentError (invoice - no path to destination) - + ```json { - "mmrpc": "2.0", - "error": "Payment error: Error paying invoice: Routing(LightningError { err: 'Failed to find a path to the given destination', action: IgnoreError })", - "error_path": "send_payment.lightning", - "error_trace": "send_payment:102] lightning:232]", - "error_type": "PaymentError", - "error_data": "Error paying invoice: Routing(LightningError { err: 'Failed to find a path to the given destination', action: IgnoreError })", - "id": 762 + "mmrpc": "2.0", + "result": { + "nfts": [ + { + "chain": "POLYGON", + "token_address": "0x48c75fbf0452fa8ff2928ddf46b0fe7629cca2ff", + "token_id": "5", + "amount": "1", + "owner_of": "0xf622a6c52c94b500542e2ae6bcad24c53bc5b6a2", + "token_hash": "28f970585fd743b056859a6e41f50a8e", + "block_number_minted": 36781490, + "block_number": 42491885, + "contract_type": "ERC1155", + "name": null, + "symbol": null, + "token_uri": "https://app.thesmurfssociety.com/metadata/public/metadata/cauldron/5", + "token_domain": "app.thesmurfssociety.com", + "metadata": "{\"name\":\"Forest Mushrooms\",\"description\":\"Sweet and nutty with distinct earthy tones, these forest mushrooms will make a fine addition to all your soups, salads, and potions.\",\"image\":\"https://metadata.thesmurfssociety.com/ingredients/nft/5.Forest_Mushrooms.jpg\",\"animation_url\":null,\"external_url\":\"https://app.thesmurfssociety.com/detail/ingredients/5\",\"attributes\":[{\"trait_type\":\"Type\",\"value\":\"Ingredient\"},{\"trait_type\":\"Category\",\"value\":\"COMMON\"}]}", + "last_token_uri_sync": "2022-12-13T13:12:50.840Z", + "last_metadata_sync": "2023-05-15T07:30:04.882Z", + "minter_address": "ERC1155 tokens don't have a single minter", + "possible_spam": false, + "possible_phishing": false, + "uri_meta": { + "image": "https://metadata.thesmurfssociety.com/ingredients/nft/5.Forest_Mushrooms.jpg", + "image_url": "https://metadata.thesmurfssociety.com/ingredients/nft/5.Forest_Mushrooms.jpg", + "image_domain": "metadata.thesmurfssociety.com", + "name": "Forest Mushrooms", + "description": "Sweet and nutty with distinct earthy tones, these forest mushrooms will make a fine addition to all your soups, salads, and potions.", + "attributes": [ + { + "trait_type": "Type", + "value": "Ingredient" + }, + { + "trait_type": "Category", + "value": "COMMON" + } + ], + "animation_url": null, + "animation_domain": null, + "external_url": "https://app.thesmurfssociety.com/detail/ingredients/5", + "external_domain": "app.thesmurfssociety.com", + "image_details": null + } + } + ], + "skipped": 0, + "total": 1 + }, + "id": null } ``` + - ### InvalidRequest (request is missing a required field) - - ```json - { - "mmrpc": "2.0", - "error": "Error parsing request: missing field `payment`", - "error_path": "dispatcher", - "error_trace": "dispatcher:109]", - "error_type": "InvalidRequest", - "error_data": "missing field `payment`", - "id": 762 - } - ``` +### ๐Ÿ“Œ Error responses - ### InvalidRequest (A required field is invalid) +#### Unsupported Chain Type - ```json - { - "mmrpc": "2.0", - "error": "Error parsing request: ParseError(Bech32Error(MissingSeparator))", - "error_path": "dispatcher", - "error_trace": "dispatcher:109]", - "error_type": "InvalidRequest", - "error_data": "ParseError(Bech32Error(MissingSeparator))", - "id": 762 - } - ``` - +The supported chains are -## Get Payment Details {{label : 'lightning::payments::get_payment_details', tag : 'API-v2'}} +``` +{ + "mmrpc":"2.0", + "error":"Error parsing request: UnsupportedChainType", + "error_path":"dispatcher", + "error_trace":"dispatcher:109]", + "error_type":"InvalidRequest", + "error_data":"UnsupportedChainType", + "id":null +} +``` +export const title = "AtomicDEX: Non Fungible Tokens"; +export const description = + "This document describes the get_nft_metadata method AtomicDEX-API provides to get metadata for your NFTs"; -The `lightning::payments::get_payment_details` method returns details about a lightning payment from a given `payment_hash`. +# Get NFT Metadata {{label : 'get_nft_metadata', tag : 'API-v2'}} ### Request Parameters -| Parameter | Type | Description | -| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| coin | string | Ticker of the coin to query. | -| payment\_hash | string | The hexidecimal string which identifies a invoice. The payment\_hash is returned from a `lightning::payments::send_payment` request if the payment was sent by us, or from a `lightning::payments::generate_invoice` request if the payment is received (or will be received) by us. | +| Parameter | Type | Description | +| ------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- | +| chain | string | The token chain. | +| token\_address | string | The token address. | +| token\_id | string | Token ID. | +| protect\_from\_spam | boolean | Optional, defaults to `false`. If `true`, any potentially spam link found in collection name, token name, symbol will be censored | + +### Response Parameters + +| Parameter | Type | Description | +| ---------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| amount | string | The amount of this NFT the user owns (used by `ERC1155`). | +| block\_number\_minted | integer | The block height when the NFT was minted. May be `null`. | +| block\_number | integer | The block height when the amount or owner changed. | +| chain | string | Chain name. One of `AVALANCHE`, `BSC`, `ETH`, `FANTOM`, or `POLYGON`. | +| name | string | May be `null`. An NFT collection name. | +| contract\_type | string | The type of NFT contract standard. One of `ERC721` or `ERC1155`. | +| last\_token\_uri\_sync | string | When the token\_uri was last updated. | +| last\_metadata\_sync | string | When the metadata was last updated. | +| metadata | string | The metadata of the token. May be `null`. | +| minter\_address | string | Minter address. May be `null`. | +| owner\_of | string | The wallet address of the owner of the NFT. | +| possible\_spam | boolean | If `true`, the contract address has [been identified](https://docs.moralis.io/web3-data-api/evm/nft-spam-detection) as associated with spam or suspicious activities. | +| possible\_phishing | boolean | If `true`, the token has been identified as associated with phishing, as at least one of domain fields is found in database with phishing domains. | +| symbol | string | May be `null`. The symbol of the NFT contract. | +| token\_address | string | The address of the NFT contract. | +| token\_id | string | The token ID of the NFT. | +| token\_hash | string | The token hash. May be `null`. | +| token\_uri | string | The URI to the metadata of the token. May be `null`. | +| token\_domain | string | Token domain. May be `null`. | +| uri\_meta | object | A standard [NftMetadata](/atomicdex/api/v20/#token-metadata) object. | #### ๐Ÿ“Œ Example - + ```json { - "method": "lightning::payments::get_payment_details", "userpass": "testpsw", + "method": "get_nft_metadata", "mmrpc": "2.0", "params": { - "coin": "tBTC-lightning", - "payment_hash": "414f9b3524fc4e48c99f2723952732d8bc2eba1b35ce3bf2a70f5144b40f599e" - }, - "id": 1 + "token_address": "0xfd913a305d70a60aac4faac70c739563738e1f81", + "token_id": "214300044414", + "chain": "BSC" + } } ``` @@ -45961,448 +47504,742 @@ The `lightning::payments::get_payment_details` method returns details about a li ```json { - "mmrpc": "2.0", - "result": { - "payment_details": { - "payment_hash": "c4e25cc10d77e3cd5f3d2af7b14ad72f123b2a5021bd6705c0b8ee8386bdeceb", - "payment_type": { - "type": "Outbound Payment", - "destination": "0348cc1a9479697cd52db445ea74149ad40bb01bb2045a3e8acba21b70f94ab7cf" - }, - "description": "1 Blokaccino", - "amount_in_msat": 1000000, - "fee_paid_msat": 1803, - "status": "succeeded", - "created_at": 1684081413, - "last_updated": 1684081419 - } - }, - "id": 762 + "mmrpc": "2.0", + "result": { + "token_address": "0x2953399124f0cbb46d2cbacd8a89cf0599974963", + "amount": "1", + "owner_of": "0xab95d01bc8214e4d993043e8ca1b68db2c946498", + "token_hash": "af811b641bccbdc10c444ba4f3a2ffb5", + "name": "OpenSea Collections", + "symbol": "OPENSTORE", + "token_uri": "https://api.opensea.io/api/v2/metadata/matic/0x2953399124F0cBB46d2CbACD8A89cF0599974963/0xf43db4f488f644b73a9442de4978fb7572b73d85000000000000110000002710", + "token_domain": "api.opensea.io", + "metadata": "{\"image\":\"https://i.seadn.io/gae/nY8wjVVQqDZBl-Bk3h9kwSqR1bXt16x_tESRAQmctEb0SCFCPtvtSsBtp98TFiUzP-LpMGt_kiqHDDOfkgbxOuWxkdH4aBNkmzrjZM0?w=500&auto=format\",\"name\":\"Doge Napoleon\",\"description\":null,\"external_link\":null,\"animation_url\":\"https://openseauserdata.com/files/df71203f48e54d027bb2c47b2840cacb.mp4\",\"traits\":[]}", + "last_token_uri_sync": "2023-09-01T04:04:30.867Z", + "last_metadata_sync": "2023-09-01T04:35:01.128Z", + "minter_address": "ERC1155 tokens don't have a single minter", + "possible_spam": true, + "chain": "POLYGON", + "token_id": "110473361632261669912565539602449606788298723469812631769659886404530570536720", + "block_number_minted": 19645247, + "block_number": 45776404, + "contract_type": "ERC1155", + "possible_phishing": false, + "uri_meta": { + "image": "https://i.seadn.io/gae/nY8wjVVQqDZBl-Bk3h9kwSqR1bXt16x_tESRAQmctEb0SCFCPtvtSsBtp98TFiUzP-LpMGt_kiqHDDOfkgbxOuWxkdH4aBNkmzrjZM0?w=500&auto=format", + "image_url": "https://i.seadn.io/gae/nY8wjVVQqDZBl-Bk3h9kwSqR1bXt16x_tESRAQmctEb0SCFCPtvtSsBtp98TFiUzP-LpMGt_kiqHDDOfkgbxOuWxkdH4aBNkmzrjZM0?w=500&auto=format", + "image_domain": "i.seadn.io", + "name": "Doge Napoleon", + "description": null, + "attributes": null, + "animation_url": "https://openseauserdata.com/files/df71203f48e54d027bb2c47b2840cacb.mp4", + "animation_domain": "openseauserdata.com", + "external_url": null, + "external_domain": null, + "image_details": null + } + }, + "id": null } ``` - - ### NoSuchPayment (payment hash not found) +## Error responses + +``` +{ + "mmrpc": "2.0", + "error": "Token: token_address 0xfd913a305d70a60aac4faac70c739563738e1f81, token_id 214300044414 was not found in wallet", + "error_path": "nft", + "error_trace": "nft:123]", + "error_type": "TokenNotFoundInWallet", + "error_data": { + "token_address": "0xfd913a305d70a60aac4faac70c739563738e1f81", + "token_id": "214300044414" + }, + "id": null +} +``` +export const title = "AtomicDEX: Non Fungible Tokens"; +export const description = + "This document describes the get_nft_transfers method AtomicDEX-API provides to get information about your NFT transactions"; + +# Get a list of NFT transfers {{label : 'get_nft_transfers', tag : 'API-v2'}} + +Returns a list of the NFT transfers involving the user, shown in descending order of the `block_timestamp` value of the NFT's last transfer. + + + To view NFT transactions, you must [activate the coin](/atomicdex/api/legacy/coin_activation/) which holds the NFTs first. + + +### Request Parameters +| Parameter | Type | Description | +| ------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| chains | array | List of chains to scan for NFTs. | +| max | boolean | Optional, defaults to `false`. If `true`, response will return all NFT transfers without pagination, and will ignore the `limit` and `page_number` values. | +| limit | integer | Optional, defaults to `10`. The number of NFT transfers displayed per page in response. | +| page\_number | integer | Optional, defaults to `1`. The page offset for items in response. | +| protect\_from\_spam | boolean | Optional, defaults to `false`. If `true`, any potentially spam link found in `collection_name`, `token_name` will be censored | +| filters | object | Optional. A standard [TokenTransferFilter](/atomicdex/api/v20/#token-transfer-filter) object. | + +### Response Parameters + +| Parameter | Type | Description | +| ----------------- | --------------- | ---------------------------------------------------------------------------------------------- | +| transfer\_history | list of objects | A list of standard [NftTransfer](/atomicdex/api/common_structures/nfts/#nft-transfer) objects. | +| total | string | The total number of NFT transfers in your wallet matching the request filters. | +| skipped | string | The number of NFT transfers in your wallet excluded by the request filters. | + +#### ๐Ÿ“Œ Example with date and `send` filters + + ```json { - "mmrpc": "2.0", - "error": "Payment with hash: 414f9b3524fc4e48c99f2723952732d8bc2eba1b35ce3bf2a70f5144b40f599e is not found", - "error_path": "get_payment_details", - "error_trace": "get_payment_details:75]", - "error_type": "NoSuchPayment", - "error_data": "414f9b3524fc4e48c99f2723952732d8bc2eba1b35ce3bf2a70f5144b40f599e", - "id": 762 + "userpass": "testpsw", + "method": "get_nft_transfers", + "mmrpc": "2.0", + "params": { + "chains": [ + "POLYGON" + ], + "max": true, + "filters": { + "receive": true, + "from_date": 1678233600 + }, + "protect_from_spam": true + } } ``` + - ### InvalidRequest (payment\_hash not a hash string) - + ```json { - "mmrpc": "2.0", - "error": "Error parsing request: invalid value: string '', expected a hash string", - "error_path": "dispatcher", - "error_trace": "dispatcher:109]", - "error_type": "InvalidRequest", - "error_data": "invalid value: string '', expected a hash string", - "id": 762 + "mmrpc": "2.0", + "result": { + "transfer_history": [ + { + "block_hash": "0xfd012e9dc2c7fa652ae3c0923599a9e6196520ac46e55f0f467d3a1ce84b8580", + "transaction_hash": "0x4063c4ae3e56a06b6c8768ad76e0cb1523e671cf06e4325517106497778ede9e", + "transaction_index": 87, + "log_index": 468, + "value": "0", + "transaction_type": "Single", + "token_address": "0x48c75fbf0452fa8ff2928ddf46b0fe7629cca2ff", + "from_address": "0xf622a6c52c94b500542e2ae6bcad24c53bc5b6a2", + "to_address": "0xf622a6c52c94b500542e2ae6bcad24c53bc5b6a2", + "amount": "2", + "verified": 1, + "operator": "0xf622a6c52c94b500542e2ae6bcad24c53bc5b6a2", + "possible_spam": false, + "chain": "POLYGON", + "token_id": "5", + "block_number": 44506464, + "block_timestamp": 1688107346, + "contract_type": "ERC1155", + "token_uri": "https://app.thesmurfssociety.com/metadata/public/metadata/cauldron/5", + "token_domain": "app.thesmurfssociety.com", + "collection_name": null, + "image_url": "https://metadata.thesmurfssociety.com/ingredients/nft/5.Forest_Mushrooms.jpg", + "image_domain": "metadata.thesmurfssociety.com", + "token_name": "Forest Mushrooms", + "status": "Receive", + "possible_phishing": false, + "fee_details": { + "coin": "MATIC", + "gas": 40249, + "gas_price": "0.000000153160317706", + "total_fee": "0.006164549627348794" + }, + "confirmations": 5775855 + } + ], + "skipped": 0, + "total": 1 + }, + "id": null } ``` +export const title = "AtomicDEX: Non Fungible Tokens"; +export const description = + "This document describes all the methods AtomicDEX-API provides to get information and transact with NFTs"; -## List Payments by Filter {{label : 'lightning::payments::list_payments_by_filter', tag : 'API-v2'}} +# Non Fungible Tokens (NFTs) -The `lightning::payments::list_payments_by_filter` method returns a list of payments (sent and/or received) for a coin which match the given filter. +The AtomicDEX API supports [ERC1155](https://www.nftstandards.wtf/Standards/ERC1155+Multi+token) and [ERC721](https://www.nftstandards.wtf/Standards/ERC721+Non+Fungible+Standard) NFTs via the [Moralis API](https://docs.moralis.io/) on the Avalanche (AVAX), BNB Smart Chain (BNB), Ethereum (ETH), Fantom (FTM), Polygon (MATIC) networks. + + + Before using other NFT methods, you should first call the [update\_nft](/atomicdex/api/v20-dev/non_fungible_tokens/update_nft/) + method to populate/refresh the local database. + + +## NFT Information Methods + +* Get a list of your tokens with [get\_nft\_list](/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_list/) +* Get a list of token transfers with [get\_nft\_transfers](/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_transfers/) +* Get token metadata with [get\_nft\_metadata](/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_metadata/) +* Update NFT [update\_nft](/atomicdex/api/v20-dev/non_fungible_tokens/update_nft/) +* Refresh NFT metadata with [refresh\_nft\_metadata](/atomicdex/api/v20-dev/non_fungible_tokens/refresh_nft_metadata/) + +## NFT Transaction Methods + +* Withdraw ERC721 tokens with [withdraw\_nft](/atomicdex/api/v20-dev/non_fungible_tokens/withdraw_nft/#erc-721-withdraw-example) +* Withdraw ERC1155 tokens with [withdraw\_nft](/atomicdex/api/v20-dev/non_fungible_tokens/withdraw_nft/#erc-1155-withdraw-example) + + + View the source code at: [https://github.com/KomodoPlatform/komodo-defi-framework/blob/main/mm2src/coins/nft.rs](https://github.com/KomodoPlatform/komodo-defi-framework/blob/main/mm2src/coins/nft.rs) + +export const title = "AtomicDEX: Non Fungible Tokens - Query NFT database tables"; +export const description = + "This document describes how to query the local NFT database tables."; + +# Query NFT database tables + +After using the [update\_nft](/atomicdex/api/v20-dev/non_fungible_tokens/update_nft/#update-nft) method to initialise your local NFT database, +the following tables are available in `DB/KOMODEFI.db`: + +* AVAX\_nft\_list +* AVAX\_nft\_transfer\_history +* BNB\_nft\_list +* BNB\_nft\_transfer\_history +* ETH\_nft\_list +* ETH\_nft\_transfer\_history +* FTM\_nft\_list +* FTM\_nft\_transfer\_history +* MATIC\_nft\_list +* MATIC\_nft\_transfer\_history +* scanned\_nft\_blocks + +## NFT List tables + +The COIN\_nft\_list tables contain the NFTs that you own +It has the following columns, though not all columns are populated for all NFTs: + +| ID | Name | Type | Description | +| -- | ---------------------- | ------------ | ------------------------------------------------------------------------------ | +| 0 | token\_address | VARCHAR(256) | The address of the token contract. | +| 1 | token\_id | VARCHAR(256) | The id of the token. | +| 2 | chain | TEXT | The coin network which the NFT is on. | +| 3 | amount | VARCHAR(256) | The amount of NFTs transfered in this transaction. | +| 4 | block\_number | INTEGER | The block height of this transaction. | +| 5 | contract\_type | TEXT | The contract type. Either `ERC721` or `ERC1155`. | +| 6 | possible\_spam | INTEGER | `1` indicates the NFT has been identified as spam. `0` indicates it has not. | +| 7 | possible\_phishing | INTEGER | `1` indicates the NFT has been identified as a scam. `0` indicates it has not. | +| 8 | collection\_name | TEXT | The collection name which includes the token. | +| 9 | symbol | TEXT | An arbitrary symbol for the NFT | +| 10 | token\_uri | TEXT | A link to the token's metadata. | +| 11 | token\_domain | TEXT | The domain the token metadata is hosted on. | +| 12 | metadata | TEXT | The token's metadata in JSON format. | +| 13 | last\_token\_uri\_sync | TEXT | Date and time when the token uri was last syncronised. | +| 14 | last\_metadata\_sync | TEXT | Date and time when the token metadata was last syncronised. | +| 15 | raw\_image\_url | TEXT | The raw URL for the token image. | +| 16 | image\_url | TEXT | A link for the token's image (or other media). | +| 17 | image\_domain | TEXT | The domain the token image (or other media) is hosted on. | +| 18 | token\_name | TEXT | The name of the token. | +| 19 | description | TEXT | An arbitrary description of the NFT. | +| 20 | attributes | TEXT | Additional attribute data for the NFT in JSON format. | +| 21 | animation\_url | TEXT | If NFT is animated, the URL of the animation. | +| 22 | animation\_domain | TEXT | If NFT is animated, the domain of the animation. | +| 23 | external\_url | TEXT | Additional URL related to the NFT | +| 24 | external\_domain | TEXT | Domain of the additional URL related to the NFT | +| 25 | image\_details | TEXT | Additional details about the NFT's image. | +| 26 | details\_json | TEXT | Additional information about the transaction in JSON format. | + +### Example COIN\_nft\_list table query + +> SELECT chain, token\_name, token\_address, token\_id, possible\_spam, possible\_phishing FROM MATIC\_nft\_list LIMIT 5; + +| chain | token\_name | token\_address | token\_id | possible\_spam | possible\_phishing | +| ------- | ---------------------- | ------------------------------------------ | --------- | -------------- | ------------------ | +| POLYGON | $2000 USDT Airdrop๐ŸŽ | 0xe7ee9dcf5f4b7f9254b348ba596c9fb9121f77e7 | 1 | 1 | 0 | +| POLYGON | $1000 USDC Voucher๐ŸŽ | 0xb092b5eb5c653e915880dfc1f606be2ffe6fae8c | 1 | 1 | 0 | +| POLYGON | 1000 BLUR Reward | 0xeaa3c52052b809c8d8072187efc134def2dd5b13 | 0 | 1 | 0 | +| POLYGON | SHIB Voucher 66 of 100 | 0xc46e36339ebd8bed48b1bdb6bd815e4b72103949 | 0 | 1 | 0 | +| POLYGON | $1000 Rewards | 0x6e0b84421388ad635f2a1167e39aff2dc742da2a | 0 | 1 | 0 | + +The NFTs listed above are all spam, and will be ignored by the [get\_nft\_list](/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_list/) method. + +## NFT Transfer table + +The COIN\_nft\_transfer\_history tables contain the history of transfers of your NFTs, and have the following columns: + +| ID | Name | Type | Description | +| -- | ------------------ | ------------ | ------------------------------------------------------------------------------ | +| 0 | transaction\_hash | VARCHAR(256) | Hex string, representing the transaction. | +| 1 | log\_index | INTEGER | Simply a table index. | +| 2 | chain | TEXT | The coin network which the NFT is on. | +| 3 | block\_number | INTEGER | The block height of this transaction. | +| 4 | block\_timestamp | INTEGER | The block time of this transaction. | +| 5 | contract\_type | TEXT | The contract type. Either `ERC721` or `ERC1155`. | +| 6 | token\_address | VARCHAR(256) | The address of the token contract. | +| 7 | token\_id | VARCHAR(256) | The id of the token. | +| 8 | status | TEXT | The transaction type: `Recieve` or `Send` | +| 9 | amount | VARCHAR(256) | The amount of NFTs transfered in this transaction. | +| 10 | possible\_spam | INTEGER | `1` indicates the NFT has been identified as spam. `0` indicates it has not. | +| 11 | possible\_phishing | INTEGER | `1` indicates the NFT has been identified as a scam. `0` indicates it has not. | +| 12 | token\_uri | TEXT | A link to the token's metadata. | +| 13 | token\_domain | TEXT | The domain the token metadata is hosted on. | +| 14 | collection\_name | TEXT | The collection name which includes the token. | +| 15 | image\_url | TEXT | A link for the token's image (or other media). | +| 16 | image\_domain | TEXT | The domain the token image (or other media) is hosted on. | +| 17 | token\_name | TEXT | The name of the token. | +| 18 | details\_json | TEXT | Additional information about the transaction in JSON format. | + +### Example scanned\_nft\_blocks table query + +`SELECT transaction\_hash, token\_name, token\_address, token\_id, FROM MATIC_nft_transfer_history WHERE block_timestamp > 1701519320;` + +| transaction\_hash | token\_name | token\_address | token\_id | +| ------------------------------------------------------------------ | -------------------- | ------------------------------------------ | --------- | +| 0x7b57303bcc2c68808b460490e984adcd18567a80660a18b7a151b62015247cda | $2000 USDT Airdrop๐ŸŽ | 0xe7ee9dcf5f4b7f9254b348ba596c9fb9121f77e7 | 1 | + +## NFT Last Scanned Block table + +The scanned\_nft\_blocks table contains the last block that was scanned for each chain. +It has the following columns: + +| ID | Name | Type | Description | +| -- | -------------------- | ------- | ---------------------------------------------------------------------- | +| 2 | chain | TEXT | The coin network which the NFT is on. | +| 1 | last\_scanned\_block | INTEGER | The block height when the last scan for NFTs was performed on a chain. | + +### Example scanned\_nft\_blocks table query + +`SELECT * FROM scanned_nft_blocks;` + +| chain | last\_scanned\_block | +| ----- | -------------------- | +| MATIC | 50651981 | +| FTM | 66512090 | +| ETH | 0 | +| BNB | 0 | +| AVAX | 0 | +export const title = "AtomicDEX: Non Fungible Tokens"; +export const description = + "This document describes all the refresh_nft_metadata method AtomicDEX-API provides to refresh an NFT's metadata"; + +# Refresh NFT Metadata {{label : 'refresh_nft_metadata', tag : 'API-v2'}} + +This method refreshes metadata of one NFT and metadata of related transactions with the same token\_address and token\_id. ### Request Parameters -| Parameter | Type | Description | -| --------------- | ------- | --------------------------------------------------------------------------------------------------------------------------- | -| coin | string | Ticker of the coin to query. | -| filter | object | Optional. A standard [LightningPaymentFilter](/atomicdex/api/common_structures/lightning/#lightning-payment-filter) object. | -| paging\_options | object | Optional. A standard [Pagination](/atomicdex/api/common_structures/#pagination) object. | -| limit | integer | Optional, defaults to `10`. Maximum number of results to return. | +| Parameter | Type | Description | +| -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| chain | string | Chains which holds the NFT you would like to updated metadata for. | +| url | string | URL link to the Moralis API proxy base url ([https://moralis-proxy.komodo.earth](https://moralis-proxy.komodo.earth)) or equivalent. | +| token\_address | string | Token address. | +| token\_id | string | Token ID. | +| url\_antispam | string | URL link to the [Antispam API proxy base url](https://nft.antispam.dragonhound.info) or equivalent. [docs](https://nft.antispam.dragonhound.info/docs). | -#### ๐Ÿ“Œ Example without filter + + If there are no errors, this request will return an empty response. + - +#### ๐Ÿ“Œ Example + + ```json { - "method": "lightning::payments::list_payments_by_filter", "userpass": "testpsw", + "method": "refresh_nft_metadata", "mmrpc": "2.0", "params": { - "coin": "tBTC-lightning" - }, - "id": 1 + "token_address": "0x48c75fbf0452fa8ff2928ddf46b0fe7629cca2ff", + "token_id": "5", + "chain": "POLYGON", + "url": "https://moralis-proxy.komodo.earth", + "url_antispam": "https://nft.antispam.dragonhound.info" + } } ``` - #### Response + + If there are no errors, this request will return an empty response. + ```json { "mmrpc": "2.0", - "result": { - "payments": [{ - "payment_hash": "59175643db24fc79c77da073994d596444b6909fb2d452bde662ae386115c758", - "payment_type": { - "type": "Inbound Payment" - }, - "description": "For the burger on Tuesday", - "amount_in_msat": 10000, - "status": "pending", - "created_at": 1683917593, - "last_updated": 1683917593 - }, { - "payment_hash": "3ff39605f214a4b4159f9c4f44c94de3a273f300042ca18b7cb3d62f270a9ebc", - "payment_type": { - "type": "Outbound Payment" - }, - "description": "A 1:24 scale model of a 1981 DeLorean DMC-12", - "amount_in_msat": 88000, - "status": "succeeded", - "created_at": 1683815625, - "last_updated": 1683815721 - }, { - "payment_hash": "c4f44c94214a4b4159f9273f30de3a3ff39605f18b7c27b3d62f0a9ebc", - "payment_type": { - "type": "Outbound Payment" - }, - "description": "Grays Sports Almanac, 1950-2000", - "amount_in_msat": 1000000000, - "status": "succeeded", - "created_at": 1683714225, - "last_updated": 1683805721 - }, { - "payment_hash": "c4f44c94214a4b4159f9273f30de3a3ff39605f18b7c27b3d62f0a9ebc", - "payment_type": { - "type": "Outbound Payment" - }, - "description": "ACME shrink ray", - "amount_in_msat": 4000012, - "status": "succeeded", - "created_at": 1683814625, - "last_updated": 1683815321 - }], - "limit": 10, - "skipped": 0, - "total": 6, - "total_pages": 1, - "paging_options": { - "PageNumber": 1 - } - }, - "id": 1 + "result": null, + "id": null } ``` -#### ๐Ÿ“Œ Example for Inbound Payment `payment_type`, `limit` and `pagination` + + Need to add some error responses here. + +export const title = "AtomicDEX: Non Fungible Tokens"; +export const description = + "This document describes the update_nft method AtomicDEX-API provides to update NFT information in your local database"; - +# Update NFT {{label : 'update_nft', tag : 'API-v2'}} + +This method will scan selected networks to update NFT information stored in the local database. +To interact with your NFTs, you will first need to activate the coin for the network the NFT is on. + +See below for which coin to activate for each network: + +| Network | Coin | +| --------- | ----- | +| AVALANCHE | AVAX | +| BSC | BNB | +| ETH | ETH | +| FANTOM | FTM | +| POLYGON | MATIC | + +These coins can be activated using the [enable\_eth\_with\_tokens](/atomicdex/api/v20/enable_eth_with_tokens/) or method. + +### Request Parameters + +| Parameter | Type | Description | +| ------------- | ------ | --------------------------------------------------------------------------------------------------- | +| chains | array | List of networks to scan for NFTs. Options are: `POLYGON`, `FANTOM`, `ETH`, `BSC`, or `AVALANCHE`. | +| url | string | URL link to the [Moralis API proxy base url](https://moralis-proxy.komodo.earth) or equivalent. | +| url\_antispam | string | URL link to the [Antispam API proxy base url](https://nft.antispam.dragonhound.info) or equivalent. | + + + If there are no errors, this request will return an empty response. + When updating multiple networks, or wallets with numerous NFTs, this request may take a while to complete. + + +#### ๐Ÿ“Œ Example + + ```json { - "method": "lightning::payments::list_payments_by_filter", "userpass": "testpsw", + "method": "update_nft", "mmrpc": "2.0", "params": { - "coin": "tBTC-lightning", - "filter": { - "payment_type": { - "type": "Inbound Payment" - } - }, - "limit": 2, - "paging_options": { - "PageNumber": 2 - } - }, - "id": 1 + "chains": [ + "BSC", + "POLYGON" + ], + "url": "https://moralis-proxy.komodo.earth", + "url_antispam": "https://nft.antispam.dragonhound.info" + } } - ``` - - - - ```json - { - "mmrpc": "2.0", - "result": { - "payments": [{ - "payment_hash": "e51f1526d3322ddc0aaa0e893e5875418ddd12f206b7e1545c8e4375c97d0e31", - "payment_type": { - "type": "Inbound Payment" - }, - "description": "For the burger on Tuesday", - "amount_in_msat": 10000, - "status": "pending", - "created_at": 1683916900, - "last_updated": 1683916900 - }, { - "payment_hash": "605f214a4b4b159f9c4f44c94de3a273f3ff39300042ca18b7cbb4159f3d62f2", - "payment_type": { - "type": "Inbound Payment" - }, - "description": "14 pallets of frozen spinach", - "amount_in_msat": 56005000, - "status": "succeeded", - "created_at": 1683815625, - "last_updated": 1683815721 - }], - "limit": 2, - "skipped": 2, - "total": 7, - "total_pages": 4, - "paging_options": { - "PageNumber": 2 - } - }, - "id": 1 + ``` + + + + ```json + { + "mmrpc": "2.0", + "result": null, + "id": null } ``` -#### ๐Ÿ“Œ Example for `pending` payments between 10000 and 40000 millisatoshis + + Need to add some error responses here. + +export const title = "AtomicDEX: Non Fungible Tokens"; +export const description = + "This document describes the withdraw_nft method AtomicDEX-API provides to send NFTs to an address"; - +# Withdraw NFTs {{label : 'withdraw_nft', tag : 'API-v2'}} + + + To withdraw NFTs, you must [activate the coin](/atomicdex/api/legacy/coin_activation/) which holds the NFTs first. + The `withdraw_nft` method will return signed raw transaction hex which must be broadcast using the [send\_raw\_transaction](/atomicdex/api/legacy/send_raw_transaction/) method to complete the withdrawal. + + +### Request Parameters + +| Parameter | Type | Description | +| -------------- | ------ | ---------------------------------------------------------------------------------------- | +| type | string | The contract type of the NFT to withdraw. Either `withdraw_erc721` or `withdraw_erc1155` | +| withdraw\_data | object | A standard [WithdrawNftData](/atomicdex/api/v20/#withdraw-nft-data) object. | + +### Response Parameters + +| Parameter | Type | Description | +| ----------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| amount | string | Amount of tokens to withdraw. | +| tx\_hex | string | Raw hex of signed transaction. Use this with the [send\_raw\_transaction](/atomicdex/api/legacy/send_raw_transaction/) RPC to broadcast the transaction. | +| tx\_hash | string | Transaction ID of the withdrawl. | +| from | array | List of source addresses. | +| to | array | List of destination addresses. | +| contract\_type | string | Contract type. `ERC721` or `ERC1155`. | +| token\_address | string | Token address. | +| token\_id | string | Token ID. | +| fee\_details | object | A standard [WithdrawFee](/atomicdex/api/v20/#withdraw-fee) object. | +| coin | string | Coin name. One of `AVALANCHE`, `BSC`, `ETH`, `FANTOM`, or `POLYGON`. | +| block\_height | integer | Block height of the transaction. If the value is `0`, the transaction is unconfirmed. | +| timestamp | integer | Timestamp of the block containing the withdrawl transaction in [unix epoch format](https://www.epochconverter.com/). | +| internal\_id | integer | Used for internal transaction identification, for some coins it may be equal to transaction hash. | +| transaction\_type | string | This will always be `NftTransfer`. | + +#### ๐Ÿ“Œ ERC721 Withdraw Example + + ```json { - "method": "lightning::payments::list_payments_by_filter", "userpass": "testpsw", + "method": "withdraw_nft", "mmrpc": "2.0", "params": { - "coin": "tBTC-lightning", - "filter": { - "status": "pending", - "from_amount_msat": 10000, - "to_amount_msat": 40000 + "type": "withdraw_erc721", + "withdraw_data": { + "chain": "POLYGON", + "to": "0xaB95D01Bc8214E4D993043E8Ca1B68dB2c946498", + "token_address": "0x73a5299824cd955af6377b56f5762dc3ca4cc078", + "token_id": "1" } - }, - "id": 1 + } } ``` - #### Response - ```json { - "mmrpc": "2.0", - "result": { - "payments": [{ - "payment_hash": "e51f1526d3322ddc0aaa0e893e5875418ddd12f206b7e1545c8e4375c97d0e31", - "payment_type": { - "type": "Inbound Payment" - }, - "description": "For the burger on Tuesday", - "amount_in_msat": 10000, - "status": "pending", - "created_at": 1683916900, - "last_updated": 1683916900 - }], - "limit": 10, - "skipped": 6, - "total": 1, - "total_pages": 1, - "paging_options": { - "PageNumber": 1 - } - }, - "id": 1 + "mmrpc": "2.0", + "result": { + "tx_hex": "f8cb2a8509818733db8289929473a5299824cd955af6377b56f5762dc3ca4cc07880b86442842e0e000000000000000000000000ab95d01bc8214e4d993043e8ca1b68db2c946498000000000000000000000000ab95d01bc8214e4d993043e8ca1b68db2c9464980000000000000000000000000000000000000000000000000000000000000001820136a0564b5c9c8309a3f8f6cc007ca957e4c411259026d68c2c34419158aff4d3ebf8a007afaa0590da01a2ce36c7edb5380f41235168f3633ed459b1fc8a750fecd38d", + "tx_hash": "bb030f618702715eb39035dccd218355f78ae5379ff6d0691f0f3c0db3c03789", + "from": [ + "0xaB95D01Bc8214E4D993043E8Ca1B68dB2c946498" + ], + "to": [ + "0xaB95D01Bc8214E4D993043E8Ca1B68dB2c946498" + ], + "contract_type": "ERC721", + "token_address": "0x73a5299824cd955af6377b56f5762dc3ca4cc078", + "token_id": "1", + "amount": "1", + "fee_details": { + "type": "Eth", + "coin": "MATIC", + "gas": 35218, + "gas_price": "0.000000040827827163", + "total_fee": "0.001437874417026534" + }, + "coin": "MATIC", + "block_height": 0, + "timestamp": 1700732198, + "internal_id": 0, + "transaction_type": "NftTransfer" + }, + "id": null } ``` -#### ๐Ÿ“Œ Example for successful payments on the 20th of April 2023 +#### ๐Ÿ“Œ ERC1155 Withdraw Example - +If you are sending 2 or more NFTs, you must use the `withdraw_erc1155` withdraw type. + + ```json { - "method": "lightning::payments::list_payments_by_filter", "userpass": "testpsw", + "method": "withdraw_nft", "mmrpc": "2.0", "params": { - "coin": "tBTC-lightning", - "filter": { - "status": "succeeded", - "from_timestamp": 1681948800, - "to_timestamp": 1682035199 + "type": "withdraw_erc1155", + "withdraw_data": { + "chain": "POLYGON", + "to": "0xaB95D01Bc8214E4D993043E8Ca1B68dB2c946498", + "token_address": "0x73a5299824cd955af6377b56f5762dc3ca4cc078", + "token_id": "1" } - }, - "id": 1 + } } ``` - #### Response - ```json { - "mmrpc": "2.0", - "result": { - "payments": [{ - "payment_hash": "c4f44c94214a4b4159f9273f30de3a3ff39605f18b7c27b3d62f0a9ebc", - "payment_type": { - "type": "Outbound Payment" - }, - "description": "Grays Sports Almanac, 1950-2000", - "amount_in_msat": 1000000000, - "status": "succeeded", - "created_at": 1681998480, - "last_updated": 1682008491 - }], - "limit": 10, - "skipped": 6, - "total": 1, - "total_pages": 1, - "paging_options": { - "PageNumber": 1 - } - }, - "id": 1 + "mmrpc": "2.0", + "result": { + "tx_hex": "f8cb2a8502dffe7b4682f3a09473a5299824cd955af6377b56f5762dc3ca4cc07880b86442842e0e000000000000000000000000ab95d01bc8214e4d993043e8ca1b68db2c94649800000000000000000000000027ad1f808c1ef82626277ae38998afa5395656600000000000000000000000000000000000000000000000000000000000000001820135a0476a4623c9df31cecbd319e0571c62d14a6dcedd5a760ced945ffa2e39fb12c5a03293f3c10d115edcc3795e414670f070c04ad936e2e87001da12f961df5962a7", + "tx_hash": "d6b46e70bf755617366a5c10875eb639d55586bb568010ea82ef42e8d68c6523", + "from": [ + "0xaB95D01Bc8214E4D993043E8Ca1B68dB2c946498" + ], + "to": [ + "0x27Ad1F808c1ef82626277Ae38998AfA539565660" + ], + "contract_type": "ERC721", + "token_address": "0x73a5299824cd955af6377b56f5762dc3ca4cc078", + "token_id": "1", + "amount": "1", + "fee_details": { + "type": "Eth", + "coin": "MATIC", + "gas": 62368, + "gas_price": "0.000000012347931462", + "total_fee": "0.000770115789422016" + }, + "coin": "MATIC", + "block_height": 0, + "timestamp": 1700732805, + "internal_id": 0, + "transaction_type": "NftTransfer" + }, + "id": null } ``` -export const title = "AtomicDEX Method: Max Maker Vol"; -export const description = - "The max_maker_vol method returns the maximum volume of a coin which can be used to create a maker order."; - -# max\_maker\_vol - -The `max_maker_vol` method returns the maximum volume of a coin which can be used to create a maker order (taking into account estimated fees). If the coin is not activated, a `NoSuchCoin` error will be returned. - -#### Arguments - -| Parameter | Type | Description | -| --------- | ------ | ----------------------------------------- | -| coin | string | The ticker of the coin you want to query. | - -#### Response -| Parameter | Type | Description | -| ----------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| coin | string | The ticker of the coin you queried. | -| volume | object | A standard [NumericFormatsValue](/atomicdex/api/common_structures/#numeric-formats-value) object representing the tradable maker volume. | -| balance | object | A standard [NumericFormatsValue](/atomicdex/api/common_structures/#numeric-formats-value) object representing the tradable taker balance. | -| locked\_by\_swaps | object | A standard [NumericFormatsValue](/atomicdex/api/common_structures/#numeric-formats-value) object representing the volume of a coin's balance which is locked by swaps in progress. | - -#### ๐Ÿ“Œ Examples +#### ๐Ÿ“Œ ERC1155 Withdraw Max Example -#### Command +If you would like to withdraw all NFTs from a token\_address, you must use the `withdraw_erc1155` withdraw type and set `max` to `true`. - + ```json { "userpass": "testpsw", + "method": "withdraw_nft", "mmrpc": "2.0", - "method": "max_maker_vol", "params": { - "coin": "DOC" + "type": "withdraw_erc1155", + "withdraw_data": { + "chain": "POLYGON", + "to": "0x27Ad1F808c1ef82626277Ae38998AfA539565660", + "token_address": "0x2953399124f0cbb46d2cbacd8a89cf0599974963", + "token_id": "110473361632261669912565539602449606788298723469812631769659886404530570536720", + "max": true + } } } ``` - #### Response (success) - ```json { - "mmrpc": "2.0", - "result": { - "coin": "MARTY", - "volume": { - "decimal": "4.489763268712998712998712998712998712998712998712998712998712998712998712998712998712998712998712999", - "rational": [ - [1, [962255003, 81]], - [1, [390588672, 18]] - ], - "fraction": { - "numer": "348854605979", - "denom": "77700000000" - } - }, - "balance": { - "decimal": "5.49110027", - "rational": [ - [1, [549110027]], - [1, [100000000]] - ], - "fraction": { - "numer": "549110027", - "denom": "100000000" - } + "mmrpc": "2.0", + "result": { + "tx_hex": "f9014b2a8508d579565282ea3b942953399124f0cbb46d2cbacd8a89cf059997496380b8e4f242432a000000000000000000000000ab95d01bc8214e4d993043e8ca1b68db2c94649800000000000000000000000027ad1f808c1ef82626277ae38998afa539565660f43db4f488f644b73a9442de4978fb7572b73d85000000000000110000002710000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000000023078000000000000000000000000000000000000000000000000000000000000820135a0feb67607bd5e5c58f7533c8d2c88ef0ba3beac7fea29bfe11c3ce9bd10641f2ca02f1045b9f87536e45fe63556805734293e534284efecd9210f614316a3e8dca7", + "tx_hash": "9dce8e555d388532bdafd42dd44cd6a2bdcbf74bdda079e15f71b808c8395bcc", + "from": [ + "0xaB95D01Bc8214E4D993043E8Ca1B68dB2c946498" + ], + "to": [ + "0x27Ad1F808c1ef82626277Ae38998AfA539565660" + ], + "contract_type": "ERC1155", + "token_address": "0x2953399124f0cbb46d2cbacd8a89cf0599974963", + "token_id": "110473361632261669912565539602449606788298723469812631769659886404530570536720", + "amount": "7", + "fee_details": { + "type": "Eth", + "coin": "MATIC", + "gas": 59963, + "gas_price": "0.00000003794123733", + "total_fee": "0.00227507041401879" + }, + "coin": "MATIC", + "block_height": 0, + "timestamp": 1700732937, + "internal_id": 0, + "transaction_type": "NftTransfer" }, - "locked_by_swaps": { - "decimal": "1.001317001287001287001287001287001287001287001287001287001287001287001287001287001287001287001287001", - "rational": [ - [1, [77802331]], - [1, [77700000]] - ], - "fraction": { - "numer": "77802331", - "denom": "77700000" - } - } - }, - "id": null + "id": null } ``` + - #### Response (error) + + ### ๐Ÿ“Œ Withdraw NFTs Error Responses - ```json + #### InvalidRequest (missing field) + + ``` + { + "mmrpc": "2.0", + "error": "Error parsing request: missing field `type`", + "error_path": "dispatcher", + "error_trace": "dispatcher:109]", + "error_type": "InvalidRequest", + "error_data": "missing field `type`", + "id": null + } + ``` + + #### InvalidRequest (wrong withdraw type) + + ``` { - "mmrpc": "2.0", - "error": "No such coin TIME", - "error_path": "max_maker_vol_rpc.lp_coins", - "error_trace": "max_maker_vol_rpc:140] lp_coins:2894]", - "error_type": "NoSuchCoin", - "error_data": { - "coin": "TIME" - }, - "id": null + "mmrpc": "2.0", + "error": "Error parsing request: unknown variant `withdraw_erc420`, expected `withdraw_erc1155` or `withdraw_erc721`", + "error_path": "dispatcher", + "error_trace": "dispatcher:109]", + "error_type": "InvalidRequest", + "error_data": "unknown variant `withdraw_erc420`, expected `withdraw_erc1155` or `withdraw_erc721`", + "id": null } ``` - #### Response (balance too low) + #### TokenNotFoundInWallet (trying to send NFT you dont own) - ```json + ``` { - "mmrpc": "2.0", - "error": "Not enough QTUM for swap: available 0, required at least 0.000728, locked by swaps None", - "error_path": "max_maker_vol_rpc.maker_swap.utxo_common", - "error_trace": "max_maker_vol_rpc:148] maker_swap:2203] utxo_common:3327] utxo_common:892]", - "error_type": "NotSufficientBalance", - "error_data": { - "coin": "QTUM", - "available": "0", - "required": "0.000728" - }, - "id": null + "mmrpc": "2.0", + "error": "Token: token_address 0xfd913a305d70a60aac4faac70c739563738e1f82, token_id 110473361632261669912565539602449606788298723469812631769659886404530570536722 was not found in wallet", + "error_path": "eth.nft", + "error_trace": "eth:883] nft:1177]", + "error_type": "GetNftInfoError", + "error_data": { + "error_type": "TokenNotFoundInWallet", + "error_data": { + "token_address": "0xfd913a305d70a60aac4faac70c739563738e1f82", + "token_id": "110473361632261669912565539602449606788298723469812631769659886404530570536722" + } + }, + "id": null } ``` - #### Response (Transport error) + #### TransportError (unable to estimate gas) - ```json + ``` { - "mmrpc": "2.0", - "error": "Transport error: JsonRpcError { client_info: 'coin: tBTC', request: JsonRpcRequest { jsonrpc: '2.0', id: '31', method: 'blockchain.estimatefee', params: [Number(1), String('ECONOMICAL')] }, error: Transport('rpc_clients:1237] rpc_clients:1239] ['rpc_clients:2047] common:1385] future timed out']') }", - "error_path": "taker_swap.utxo_common", - "error_trace": "taker_swap:1599] utxo_common:1990] utxo_common:166]", - "error_type": "Transport", - "error_data": "JsonRpcError { client_info: 'coin: tBTC', request: JsonRpcRequest { jsonrpc: '2.0', id: '31', method: 'blockchain.estimatefee', params: [Number(1), String('ECONOMICAL')] }, error: Transport('rpc_clients:1237] rpc_clients:1239] ['rpc_clients:2047] common:1385] future timed out']') }", - "id": 0 + "mmrpc": "2.0", + "error": "Transport error: request MethodCall(MethodCall { jsonrpc: Some(V2), method: \"eth_estimateGas\", params: Array([Object({\"from\": String(\"0xab95d01bc8214e4d993043e8ca1b68db2c946498\"), \"to\": String(\"0x2953399124f0cbb46d2cbacd8a89cf0599974963\"), \"gasPrice\": String(\"0x9ddeaaffe\"), \"value\": String(\"0x0\"), \"data\": String(\"0x42842e0e000000000000000000000000ab95d01bc8214e4d993043e8ca1b68db2c946498000000000000000000000000ab95d01bc8214e4d993043e8ca1b68db2c946498f43db4f488f644b73a9442de4978fb7572b73d85000000000000110000002710\")})]), id: Num(64) }) failed: InvalidResponse(\"Server: 'https://polygon-rpc.com/', error: RPC error: Error { code: ServerError(-32000), message: \\\"execution reverted\\\", data: None }\"); InvalidResponse(\"Server: 'https://polygon.blockpi.network/v1/rpc/public', error: RPC error: Error { code: ServerError(-32000), message: \\\"execution reverted\\\", data: None }\"); Transport(\"Server: 'https://node.komodo.earth:8080/polygon', response !200: 502 Bad Gateway, <html>..<head><title>502 Bad Gateway</title></head>..<body>..<center><h1>502 Bad Gateway</h1></center>..<hr><center>nginx/1.18.0 (Ubuntu)</center>..</body>..</html>..\"); InvalidResponse(\"Server: 'https://polygon.llamarpc.com/', error: RPC error: Error { code: ServerError(-32000), message: \\\"execution reverted\\\", data: None }\"); ", + "error_path": "eth", + "error_trace": "eth:1004] eth:5792]", + "error_type": "Transport", + "error_data": "request MethodCall(MethodCall { jsonrpc: Some(V2), method: \"eth_estimateGas\", params: Array([Object({\"from\": String(\"0xab95d01bc8214e4d993043e8ca1b68db2c946498\"), \"to\": String(\"0x2953399124f0cbb46d2cbacd8a89cf0599974963\"), \"gasPrice\": String(\"0x9ddeaaffe\"), \"value\": String(\"0x0\"), \"data\": String(\"0x42842e0e000000000000000000000000ab95d01bc8214e4d993043e8ca1b68db2c946498000000000000000000000000ab95d01bc8214e4d993043e8ca1b68db2c946498f43db4f488f644b73a9442de4978fb7572b73d85000000000000110000002710\")})]), id: Num(64) }) failed: InvalidResponse(\"Server: 'https://polygon-rpc.com/', error: RPC error: Error { code: ServerError(-32000), message: \\\"execution reverted\\\", data: None }\"); InvalidResponse(\"Server: 'https://polygon.blockpi.network/v1/rpc/public', error: RPC error: Error { code: ServerError(-32000), message: \\\"execution reverted\\\", data: None }\"); Transport(\"Server: 'https://node.komodo.earth:8080/polygon', response !200: 502 Bad Gateway, <html>..<head><title>502 Bad Gateway</title></head>..<body>..<center><h1>502 Bad Gateway</h1></center>..<hr><center>nginx/1.18.0 (Ubuntu)</center>..</body>..</html>..\"); InvalidResponse(\"Server: 'https://polygon.llamarpc.com/', error: RPC error: Error { code: ServerError(-32000), message: \\\"execution reverted\\\", data: None }\"); ", + "id": null + } + ``` + + #### NotEnoughNftsAmount (trying to send more NFTs than you have) + + ``` + { + "mmrpc": "2.0", + "error": "Not enough NFTs amount with token_address: 0x2953399124f0cbb46d2cbacd8a89cf0599974963 and token_id 110473361632261669912565539602449606788298723469812631769659886404530570536720. Available 1, required 2", + "error_path": "eth", + "error_trace": "eth:897]", + "error_type": "NotEnoughNftsAmount", + "error_data": { + "token_address": "0x2953399124f0cbb46d2cbacd8a89cf0599974963", + "token_id": "110473361632261669912565539602449606788298723469812631769659886404530570536720", + "available": "1", + "required": "2" + }, + "id": null } ``` + + + View the source code at: [https://github.com/KomodoPlatform/komodo-defi-framework/blob/main/mm2src/coins/nft.rs](https://github.com/KomodoPlatform/komodo-defi-framework/blob/main/mm2src/coins/nft.rs) + export const title = "AtomicDEX: Account Balance Tasks"; export const description = "The methods in this document allow tracking of balances across multiple addresses under a specified account index."; diff --git a/data-for-gpts/komodefi-api/code.rs b/data-for-gpts/komodefi-api/code.rs index 9a7ae14d..4a417024 100644 --- a/data-for-gpts/komodefi-api/code.rs +++ b/data-for-gpts/komodefi-api/code.rs @@ -131756,7 +131756,7 @@ pub struct GetTransactionResponse { #[prost(message, optional, tag="1")] pub transaction: ::core::option::Option, #[prost(message, optional, tag="2")] - pub token_metadata: ::core::option::Option, + pub token_metadata: ::core::option::Option, } /// Get an encoded transaction from a transaction hash. #[derive(Clone, PartialEq, ::prost::Message)] @@ -131898,7 +131898,7 @@ pub struct GetAddressUnspentOutputsResponse { #[prost(message, repeated, tag="1")] pub outputs: ::prost::alloc::vec::Vec, #[prost(message, repeated, tag="2")] - pub token_metadata: ::prost::alloc::vec::Vec, + pub token_metadata: ::prost::alloc::vec::Vec, } #[derive(Clone, PartialEq, ::prost::Message)] pub struct GetUnspentOutputRequest { @@ -131936,7 +131936,7 @@ pub struct GetUnspentOutputResponse { #[prost(message, optional, tag="6")] pub slp_token: ::core::option::Option, #[prost(message, optional, tag="7")] - pub token_metadata: ::core::option::Option, + pub token_metadata: ::core::option::Option, } #[derive(Clone, PartialEq, ::prost::Message)] pub struct GetMerkleProofRequest { @@ -132068,14 +132068,14 @@ pub struct SubscribeBlocksRequest { pub serialize_block: bool, } #[derive(Clone, PartialEq, ::prost::Message)] -pub struct GetSlpTokenMetadataRequest { +pub struct GetSlpNftMetadataRequest { #[prost(bytes="vec", repeated, tag="1")] pub token_ids: ::prost::alloc::vec::Vec<::prost::alloc::vec::Vec>, } #[derive(Clone, PartialEq, ::prost::Message)] -pub struct GetSlpTokenMetadataResponse { +pub struct GetSlpNftMetadataResponse { #[prost(message, repeated, tag="1")] - pub token_metadata: ::prost::alloc::vec::Vec, + pub token_metadata: ::prost::alloc::vec::Vec, } #[derive(Clone, PartialEq, ::prost::Message)] pub struct GetSlpParsedScriptRequest { @@ -132628,9 +132628,9 @@ pub struct SlpV1Nft1ChildSendMetadata { #[prost(bytes="vec", tag="1")] pub group_token_id: ::prost::alloc::vec::Vec, } -/// SlpTokenMetadata is used to marshal metadata about a specific TokenID +/// SlpNftMetadata is used to marshal metadata about a specific TokenID #[derive(Clone, PartialEq, ::prost::Message)] -pub struct SlpTokenMetadata { +pub struct SlpNftMetadata { #[prost(bytes="vec", tag="1")] pub token_id: ::prost::alloc::vec::Vec, #[prost(enumeration="SlpTokenType", tag="2")] @@ -132638,7 +132638,7 @@ pub struct SlpTokenMetadata { #[prost(oneof="slp_token_metadata::TypeMetadata", tags="3, 4, 5")] pub type_metadata: ::core::option::Option, } -/// Nested message and enum types in `SlpTokenMetadata`. +/// Nested message and enum types in `SlpNftMetadata`. pub mod slp_token_metadata { /// V1Fungible is used to marshal metadata specific to Type 1 token IDs #[derive(Clone, PartialEq, ::prost::Message)] diff --git a/data-for-gpts/komodefi-api/v20-api-content.txt b/data-for-gpts/komodefi-api/v20-api-content.txt index b0c6e4e9..1a958791 100644 --- a/data-for-gpts/komodefi-api/v20-api-content.txt +++ b/data-for-gpts/komodefi-api/v20-api-content.txt @@ -2695,6 +2695,650 @@ It includes a uniform request, successful and error response formats. At the mom } ``` + +## Common Komodo DeFi SDK Request / Response Objects + +The folowing objects are used in the request or response of multiple Komodo DeFi SDK methods. + +### ActivationParams + +The `ActivationParams` object defines additional parameters used for activation. These params may vary depending on the coin type. + +| Parameter | Type | Description | +| ---------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| required\_confirmations | integer | Optional. Confirmations to wait for steps in swap. Defaults to value in the coins file if not set. | +| requires\_notarization | boolean | Optional, defaults to `false`. For [dPoW](https://komodoplatform.com/en/blog/dpow-demystified/) protected coins, a `true` value will wait for transactions to be notarised when doing swaps. Overrides value if set in `coins` file. | +| priv\_key\_policy | string | Defaults to `ContextPrivkey`. Set as `Trezor` to activate in Trezor mode. | +| min\_addresses\_number | integer | HD wallets only. How many additional addreesses to generate at a minimum. | +| scan\_policy | string | HD wallets only. Whether or not to scan for new addresses. Select from `do_not_scan`, `scan_if_new_wallet` or `scan`. Note that `scan` will result in multple requests to the Komodo DeFi SDK. | +| gap\_limit | integer | HD wallets only. The max number of empty addresses in a row. If transactions were sent to an address outside the `gap_limit`, they will not be identified when scanning. | +| zcash\_params\_path | string | ZHTLC coins only. Path to folder containing Zcash parameters. Optional, defaults to standard location as defined in [this guide](https://forum.komodoplatform.com/t/installing-zcash-params/603) | +| scan\_blocks\_per\_iteration | integer | ZHTLC coins only. Sets the number of scanned blocks per iteration during `BuildingWalletDb` state. Optional, default value is 1000. | +| scan\_interval\_ms | integer | ZHTLC coins only. Sets the interval in milliseconds between iterations of `BuildingWalletDb` state. Optional, default value is 0. | +| mode | object | QTUM, UTXO & ZHTLC coins only. A standard [ActivationMode](/atomicdex/api/v20/#activation-mode) object. | + + + For ZHTLC coins, older wallets need to set the `sync_params` field to a date before its + first transaction to see all balance and history. This may take a long time on the first + activation, but subsequent activations will be much faster. + Using a smaller `scan_blocks_per_iteration` and larger `scan_interval_ms`, + will reduce the average CPU load during ZHTLC coin activation (at the cost of a + longer activation time). These optional fields are recommended when developing + for iOS, where a high CPU load may kill the activation process. Android & + desktop operating systems do not appear to have any problems with high CPU + load during ZHTLC coin activation. + + +### ActivationMode + +Defines the activation mode for QTUM, BCH, UTXO & ZHTLC coins. + +| Parameter | Type | Description | +| --------- | ------ | ---------------------------------------------------------------------------------------------------------------- | +| rpc | string | `Native` if running a native blockchain node, `Electrum` if using electrum servers or `Light` for ZHTLC coins. | +| rpc\_data | object | `Electrum` or `Light` mode only. A standard [ActivationRpcData](/atomicdex/api/v20/#activation-rpc-data) object. | + +### ActivationRpcData + +Contains information about electrum & lightwallet\_d servers for coins being used in `Electrum` or `Light` mode. + +| Parameter | Type | Description | +| ------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| light\_wallet\_d\_servers | list | ZHTLC only. A list of urls which are hosting lightwallet\_d servers for a coin. | +| electrum\_servers | list of objects | ZHTLC only. A list of standard [ActivationServers](/atomicdex/api/v20/#activation-servers) objects. | +| electrum | list of objects | QTUM, BCH & UTXO coins only. A list of standard [ActivationServers](/atomicdex/api/v20/#activation-servers) objects. | +| sync\_params | integer or string | ZHTLC coins only. Optional, defaults to two days ago. Defines where to start scanning blockchain data upon initial activation. Options: `"earliest"` (the coin's sapling\_activation\_height), `height` (a specific block height) or `date` (a timestamp in [unix epoch format](https://www.epochconverter.com/)). | + +### ActivationServers + +Contains information electrum servers for coins being used in `Electrum` or `Light` mode. + +| Parameter | Type | Description | +| --------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| url | string | The URL and port for an electrum server. | +| ws\_url | string | Optional, for WSS only. The URL and port for an electrum server's WSS port. | +| protocol | string | Optional, defaults to `TCP`. Transport protocol used to connect to the server. Options: `TCP` or `SSL` | +| disable\_cert\_verification | boolean | Optional, defaults to `false`. If `true`, this disables server SSL/TLS certificate verification (e.g. for self-signed certificates). Use at your own risk! | + + + #### ZHTLC Example + + ```json + { + "activation_params": { + "mode": { + "rpc": "Light", + "rpc_data": { + "electrum_servers": [ + { + "url":"zombie.dragonhound.info:10033" + } + ], + "light_wallet_d_servers": [ + "http://zombie.dragonhound.info:443" + ] + }, + "sync_params": { + "height": 2528700 + } + }, + "zcash_params_path": "/home/username/path_to/.zcash-params", + "scan_blocks_per_iteration": 100, + "scan_interval_ms": 200 + } + } + ``` + + #### HD UTXO Activation (v2) + + ```json + { + "activation_params": { + "mode": { + "rpc": "Electrum", + "rpc_data": { + "servers": [ + { + "url": "electrum2.cipig.net:10001" + }, + { + "url": "electrum3.cipig.net:20001", + "ws_url": "electrum3.cipig.net:30001", + "protocol": "SSL" + } + ] + } + }, + "scan_policy": "scan_if_new_wallet", + "priv_key_policy": "Trezor", + "min_addresses_number": 3, + "gap_limit": 20 + } + } + ``` + + +### AddressInfos + +The `addressInfos` object includes the following items for a given address: + +| Parameter | Type | Description | +| ------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------ | +| balances | object | A standard [balanceInfos](/atomicdex/api/v20/#balance-infos) object. Not included in responses where `get_balances` is `false` | +| derivation\_method | object | A standard [DerivationMethod](/atomicdex/api/v20/#derivation-method) object | +| pubkey | string | The public key associated with the seed used to launch AtomicDEX | +| tickers | array | A list of tokens which were successfully activated. Only included in responses where `get_balances` is `false` | + + + #### Example with balances + + ```json + "bitcoincash:qrf5vpn78s7rjexrjhlwyzzeg7gw98k7t5qx64fztj": { + "derivation_method": { + "type": "Iguana" + }, + "pubkey": "036879df230663db4cd083c8eeb0f293f46abc460ad3c299b0089b72e6d472202c", + "balances": { + "spendable": "0.11398301", + "unspendable": "0.00001" + } + } + ``` + + #### Example without balances + + ```json + "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" + } + ``` + + +### EvmNode + +The `EvmNode` object includes the following items for a given coin or token: + +| Parameter | Type | Description | +| --------- | ------- | ------------------------------------------------------------------------------------------------------------------- | +| url | string | URL of an RPC node | +| gui\_auth | boolean | Optional, defaults to `false`. Must be set to `true` to access RPC nodes run officially by the Komodo Platform team | + + + ```json + { + "url": "http://eth1.cipig.net:8555", + "gui_auth": false + } + ``` + + +### CoinProtocol + +| Parameter | Type | Description | +| -------------- | ------- | ----------------------------------------------------------------------------- | +| type | integer | One of the supported \[coin types]\(link TBA) | +| protocol\_data | object | A standard [CoinProtocolData](/atomicdex/api/v20/#coin-protocol-data) object. | + +### CoinProtocolData + +| Parameter | Type | Description | +| --------------------- | ------ | ------------------------------------------------------------------------------------------------ | +| platform | string | Indicates the platform parent coin for EMV-like protocols, or the coin used for lightning nodes. | +| network | string | Either `mainnet` or \`testnet | +| confirmation\_targets | object | A standard [ConfirmationTargets](/atomicdex/api/v20/#confirmation-targets) object. | + +### ConfirmationTargets + +This object represents the number of blocks required for an on-chain lightning-related transaction to be confirmed. +It is used for estimating the transaction fee rate (`feerate`) for different transaction types in the context of permissionless transactions performed by the node. Different target types are `background`, `normal`, and `high_priority`. + +| Parameter | Type | Description | +| -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| background | integer | Used for transactions that can tolerate slower confirmation times when the transaction fee rate decreases. These transactions are not time-sensitive and can afford to wait longer for confirmation. The recommended range is `12` to `144` blocks to ensure a low `feerate`. | +| normal | integer | Used for transactions that we want to confirm promptly, without significant delay (e.g, transactions for opening payment channels). These transactions are important but not critical. Suggested value is `6` blocks to ensure a moderate `feerate`. | +| high\_priority | integer | Used for transactions that require quick confirmation to prevent potential loss of funds (e.g. redeeming a Hashed Time Lock Contract (HTLC) on the blockchain before it times out). These transactions are time-critical and must be confirmed promptly to ensure the security of funds. Recommended value for `high_priority` is 1-2 blocks to ensure a high `feerate`. | + + + Using the recommended values in the above table with a coin that has a block time of 10 minutes, the equivalent time in minutes is: + + * `background`: 120 minutes to 1440 minutes (2 hours to 1 day). + * `normal`: 60 minutes (one hour). + * `high_priority`: 10 to 20 minutes. + + +### CounterpartyChannelConfig + +| Parameter | Type | Description | +| --------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| allow\_outbound\_0conf | boolean | Optional, defaults to `true`. When setting an outbound channel, it can be used straight away [without waiting](https://docs.rs/lightning/latest/lightning/util/config/struct.ChannelHandshakeLimits.html#structfield.trust_own_funding_0conf) for any on-chain confirmations. | +| force\_announced\_channel\_preference | boolean | Optional, defaults to `true`. Set to force an incoming channel to match our announced channel preference in ChannelOptions announced\_channel. | +| outbound\_channels\_confirmations | integer | Optional, defaults to `144`. Confirmations we will wait for before considering an inbound channel locked in. | +| our\_locktime\_limit | boolean | Optional, defaults to `2016`. Set to the amount of blocks we're willing to wait to claim money back to us. | +| min\_funding\_sats | boolean | Optional, defaults to `0`. Minimum allowed satoshis when an inbound channel is funded. | +| max\_funding\_sats | boolean | Optional, defaults to `16777215`. Maximum allowed satoshis when an inbound channel is funded. | +| max\_htlc\_minimum\_msat | boolean | Optional, defaults to `18446744073709551615`. The remote node sets a limit on the minimum size of HTLCs we can send to them. This allows us to limit the maximum minimum-size they can require. | +| min\_max\_htlc\_value\_in\_flight\_msat | boolean | Optional, defaults to `0`. The remote node sets a limit on the maximum value of pending HTLCs to them at any given time to limit their funds exposure to [HTLCs](https://academy.binance.com/en/glossary/hashed-timelock-contract). This allows us to set a minimum such value. | +| max\_channel\_reserve\_sats | boolean | Optional, defaults to `18446744073709551615`. The remote node will require us to keep a certain amount in direct payment to ourselves at all time, ensuring that we are able to be punished if we broadcast an old state. This allows us to limit the amount which we will have to keep to ourselves (and cannot use for [HTLCs](https://academy.binance.com/en/glossary/hashed-timelock-contract)). | +| min\_max\_accepted\_htlcs | boolean | Optional, defaults to `0`. The remote node sets a limit on the maximum number of pending HTLCs to them at any given time. This allows us to set a minimum such value. | + +### FeeInfo + +The `FeeInfo` response object includes the following items for [withdraw (v2)](/atomicdex/api/v20/withdraw/) requests: + +| Parameter | Type | Description | +| ---------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| type | string | Type of transaction fee; possible values: `UtxoFixed`, `UtxoPerKbyte`, `EthGas` | +| 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) | +| gas\_price | string (numeric) | Used only when fee type is EthGas; sets the gas price in `gwei` units | +| gas | number (integer) | Used only when fee type is EthGas; sets the gas limit for transaction | + +### LightningActivationParams + +| Parameter | Type | Description | +| ---------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| name | string | The name of the node that will be used in [lightning explorers](https://mempool.space/testnet/lightning/node/024e2a940e0cbeda84a0d5e00fa8e83b3f4e7f98382eedb488d058e0f5636dd164/r/n) | +| listening port | integer | Optional, defaults to `9735`. The port that this node listens for incoming connections on. | +| color | string | Optional, defaults to `2b6680`. A hexidecimal color string which will be used in network graphs on [lightning explorers](https://mempool.space/testnet/lightning/node/024e2a940e0cbeda84a0d5e00fa8e83b3f4e7f98382eedb488d058e0f5636dd164/r/n) | +| payment\_retries | integer | Optional, defaults to `5`. Number of times a payment will be retried if it fails. | +| backup\_path | string | Optional. The backup path for channel backups, preferably on an external drive. | + +### LightningChannelAmount + +| Parameter | Type | Description | +| --------- | ------ | -------------------------------------------------------------------------------------- | +| type | string | `Exact` for a specific amount or `Max` for whole balance. | +| value | object | Only required if type is `Exact`. The amount in BTC you want to open the channel with. | + +### LightningChannelConfig + + + The values in this object are only used if the channel is being opened by the user. If the channel is being opened by the counterparty, the values in this object are ignored. + If not specified when using the [open\_channel](/atomicdex/api/v20-dev/lightning/channels/#open-channel) or [update\_channel](/atomicdex/api/v20-dev/lightning/channels/#update-channel) methods, the values in this object will default to the values set in the `coins` configuration file. + + +| Parameter | Type | Description | +| --------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| inbound\_channels\_confirmations | string | Optional, defaults to `6`. Should be set in coins file, and applies to all channels. Confirmations we will wait for before considering an inbound channel locked in. | +| max\_inbound\_in\_flight\_htlc\_percent | integer | Optional, defaults to `10`. Should be set in coins file, and applies to all channels. Sets the percentage of the channel value we will cap the total value of outstanding inbound HTLCs to. | +| our\_htlc\_minimum\_msat | integer | Optional, defaults to `1`. The smallest value HTLC we will accept to process. The channel gets closed any time our counterparty misbehaves by sending us an HTLC with a value smaller than this. | +| announced\_channel | boolean | Optional, defaults to `false`. Set to announce the channel publicly and notify all nodes that they can route via this channel. GUIs and wallet apps should be set to `false`. | +| commit\_upfront\_shutdown\_pubkey | boolean | Optional, defaults to `true`. When `true` (and the counterparty agrees), the user must use the same key for cooperative closing. This prevents a user from changing the destination address in a cooperative close, which slightly increases security (however, this option is not required if the counterparty does not support it and a channel can be accepted regardless). **Note that the key for forced closing is always fixed when opening a channel and is different from shutdown\_pubkey.** | +| counterparty\_locktime | integer | Optional, defaults to `144`. The number of blocks we require our counterparty to wait to claim their money on chainif they broadcast a revoked transaction. We have to be online at least once during this time to punish our counterparty for broadcasting a revoked transaction. We have to account also for the time to broadcast and confirm our transaction, possibly with time in between to [RBF (Replace-By-Fee)](https://bitcoinops.org/en/topics/replace-by-fee/) the spending transaction. | +| negotiate\_scid\_privacy | integer | Optional, defaults to `false`. If `true`, we attempt to negotiate the `scid_privacy` (referred to as `scid_alias` in the [BOLTs](https://github.com/lightning/bolts)) option for outbound private channels. This provides better privacy by not including our real on-chain channel UTXO in each invoice and requiring that our counterparty only relay HTLCs to us using the channel's SCID alias. | +| their\_channel\_reserve\_sats | boolean | Optional, defaults to `10000` or 1% of channel value. The minimum balance that the other node has to maintain on their side, at all times. This ensures that if our counterparty broadcasts a revoked state, we can punish them by claiming at least this value on chain. | + + + For GUIs and wallet apps, it is recommended to set `announced_channel` to + `false` (the default value), as the node is not expected to be reliably + online. + + +### LightningChannelOptions + +| Parameter | Type | Description | +| --------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| proportional\_fee\_in\_millionths\_sats | integer | Optional, defaults to `0`. Amount (in milli-satoshi) charged for payments forwarded outbound over the channel, in excess of proportional\_fee\_in\_millionths\_sats. | +| base\_fee\_msat | integer | Optional, defaults to `1000`. Amount (in milli-satoshi) charged for payments forwarded outbound over the channel, in excess of proportional\_fee\_in\_millionths\_sats. | +| cltv\_expiry\_delta | integer | Optional, defaults to `72`. Blocks until [CheckLockTimeVerify (CLTV)](https://academy.bit2me.com/en/que-es-cltv-bitcoin/) expiry. | +| max\_dust\_htlc\_exposure\_msat | integer | Optional, defaults to `5000000`. Limit our total exposure to in-flight [HTLCs](https://academy.binance.com/en/glossary/hashed-timelock-contract) which are burned to fees as they are too small to claim on-chain. | +| force\_close\_avoidance\_max\_fee\_sats | integer | Optional, defaults to `1000`. The additional fee we're willing to pay to avoid waiting for the counterparty's locktime to reclaim funds. | + +### LightningClosedChannelsFilter + +| Parameter | Type | Description | +| ---------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| channel\_id | string | Optional. Unique string identifying a channel by its ID. | +| counterparty\_node\_id | string | Optional. A hexidecimal string identifying a counterparty node. | +| funding\_tx | string | Optional. A transaction ID which added funds. | +| from\_funding\_value | integer | Optional. The minimum value of channel funding in satoshis. | +| to\_funding\_value | integer | Optional. The maximum value of channel funding in satoshis. | +| channel\_type | string | Optional. `Inbound` or `Outbound`. | +| closing\_tx | integer | Optional. A transaction ID which closed the channel. | +| closure\_reason | integer | Optional. The reason a channel was closed. | +| claiming\_tx | integer | Optional. The ID of the transaction that returned the remaining outbound funds when the channel was closed to our on-chain address. | +| from\_claimed\_balance | integer | Optional. The minimum balance of channel funds claimed in satoshis. | +| to\_claimed\_balance | integer | Optional. The maximum balance of channel funds claimed in satoshis. | +| channel\_visibility | integer | Optional. `Public` or `Private`. | + + + Response may change to be more consistent in future. + [https://github.com/KomodoPlatform/komodo-docs-mdx/pull/31#discussion\\\_r1206446309](https://github.com/KomodoPlatform/komodo-docs-mdx/pull/31#discussion\\_r1206446309) + + +### LightningOpenChannelsFilter + +| Parameter | Type | Description | +| ------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| channel\_id | string | Optional. Unique string identifying a channel by its ID. | +| counterparty\_node\_id | string | Optional. A hexidecimal string identifying a counterparty node. | +| funding\_tx | string | Optional. A transaction ID which added funds. | +| from\_funding\_value\_sats | integer | Optional. The minimum value of channel funding in satoshis. | +| to\_funding\_value\_sats | integer | Optional. The maximum value of channel funding in satoshis. | +| is\_outbound | boolean | Optional. If `true`, limits the response to outbound channels only. | +| from\_balance\_msat | integer | Optional. The minimum channel balance in millisatoshis. | +| to\_balance\_msat | integer | Optional. The maximum channel balance in millisatoshis. | +| from\_outbound\_capacity\_msat | integer | Optional. The minimum outbound capacity of the channel balance in millisatoshis. | +| to\_outbound\_capacity\_msat | integer | Optional. The maximum outbound capacity of the channel balance in millisatoshis. | +| from\_inbound\_capacity\_msat | integer | Optional. The minimum inbound capacity of the channel balance in millisatoshis. | +| to\_inbound\_capacity\_msat | integer | Optional. The maximum inbound capacity of the channel balance in millisatoshis. | +| confirmed | boolean | Optional. If `true`, only channels with channel opening transactions that passed the number of confirmations required for the channel to be usable will be returned. | +| is\_usable | boolean | Optional. If `true`, only channels that are confirmed and the counterparty is online, meaning that these channels can be used for payments will be returned. | +| is\_public | boolean | Optional. If `true`, only channels that our node announces to the lightning network, these channels are visible on lightning explorers will be returned. | + +### LightningPayment + +| Parameter | Type | Description | +| ---------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| type | string | The payment type. Accepted values are `invoice` or [`keysend`](https://cdecker-lightning.readthedocs.io/lightning-keysend.7.html). | +| invoice | string | Only used if `type` is `invoice`. An identifying string which represents the invoice. | +| destination | string | Only used if `type` is `keysend`. A `node_pubkey` (which is also the node address in lightning context). Not to be confused with an onchain address. | +| amount\_in\_msat | string | Only used if `type` is `keysend`. Amount to be paid, in [millisatoshis](https://bitcoindata.science/bitcoin-units-converter) (A thousandth of a satoshi; the same as 0.00000000001 bitcoin). | +| expiry | string | Only used if `type` is `keysend`. Optional, defaults to `3600`. Seconds until the payment expires. | + +### LightningPaymentFilter + +| Parameter | Type | Description | +| --------------------- | ------- | ----------------------------------------------------------------------------------------------------------------- | +| payment\_type | object | A standard `LightningPaymentType` object. | +| description | string | Optional. A note to indicate the purpose of the invoice. | +| status | string | Optional. Accepted values: `pending`, `succeeded`, `failed`. | +| from\_amount\_msat | integer | Optional. Minimum amount sent in [millisatoshis](https://bitcoindata.science/bitcoin-units-converter) | +| to\_amount\_msat | integer | Optional. Maximum amount sent in [millisatoshis](https://bitcoindata.science/bitcoin-units-converter) | +| from\_fee\_paid\_msat | integer | Optional. Minimum transaction fee paid in [millisatoshis](https://bitcoindata.science/bitcoin-units-converter) | +| to\_fee\_paid\_msat | integer | Optional. Maximum transaction fee paid in [millisatoshis](https://bitcoindata.science/bitcoin-units-converter) | +| from\_timestamp | string | Optional. Minimum timestamp in [unix epoch format](https://www.epochconverter.com/) of payment results to return. | +| to\_timestamp | string | Optional. Maximum timestamp in [unix epoch format](https://www.epochconverter.com/) of payment results to return. | + +### LightningPaymentType + +| Parameter | Type | Description | +| ----------- | ------ | ----------------------------------------------------------------------------------- | +| type | object | Accepted values are `Outbound Payment` or `Inbound Payment`. | +| destination | string | Only used if `type` is `Outbound Payment`. A pubkey which will receive the payment. | + + + Response may change in future. See + [https://github.com/KomodoPlatform/komodo-docs-mdx/pull/31#discussion\\\_r1206176530](https://github.com/KomodoPlatform/komodo-docs-mdx/pull/31#discussion\\_r1206176530) + + +### 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 + + ```json + { + "PageNumber": 1 + } + ``` + + ```json + { + "FromId": 4 + } + ``` + + +### TokenFilter + +The `TokenFilter` object includes the following items for a given coin or token: + +| Parameter | Type | Description | +| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ | +| exclude\_spam | boolean | Optional, defaults to `false`. If `true`, only tokens which have param `possible_spam:false` are included in the response. | +| exclude\_phishing | boolean | Optional, defaults to `false`. If `true`, only tokens which have param `possible_phishing:false` are included in the response. | + +### TokenTransferFilter + +The `TokenTransferFilter` object includes the following items for a transfer of given coin or token: + +| Parameter | Type | Description | +| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| receive | boolean | Optional, defaults to `false`. If `true`, only transfers where user received NFTs are included in the response. | +| send | boolean | Optional, defaults to `false`. If `true`, only transfers where user sent NFTs are included in the response. | +| from\_date | integer | Optional. A timestamp in [unix epoch format](https://www.epochconverter.com/). If `true`, filter includes transfers from this date onwards (inclusive). | +| to\_date | integer | Optional. A timestamp in [unix epoch format](https://www.epochconverter.com/). If `true`, filter includes transfers up to this date (inclusive). | +| exclude\_spam | boolean | Optional, defaults to `false`. If `true`, only transfers which have param `possible_spam:false` are included in the response. | +| exclude\_phishing | boolean | Optional, defaults to `false`. If `true`, only transfers which have param `possible_phishing:false` are included in the response. | + + + ```json + { + "ticker": "MINDS-ERC20", + "required_confirmations": 4 + } + ``` + + +### NftMetadata + +The `NftMetadata` object includes the following items for a given coin or token: + +| Parameter | Type | Description | +| ----------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| image | string | Optional. Direct URL to the NFT's image. | +| image\_url | string | Optional. Optional. Url to the NFT's image. Derived from the `image` or `image_url` fields to prioritize the non-null value. Can be null if neither is provided. | +| image\_domain | string | Optional. Extracted domain from the 'image\_url', if valid. | +| name | string | Optional. Name of the token. | +| description | string | Optional. Description of the token. | +| attributes | object or array of objects | Optional. The values within this parameter will vary, and are set by the creator. Often used to store traits. | +| animation\_url | string | Optional. Url to an animation to be displayed instead of a static image. | +| animation\_domain | string | Optional. Extracted domain from the `animation_url`, if valid. | +| external\_url | string | Optional. URL to the external source related to the token. | +| external\_domain | string | Optional. Extracted domain from the `external_url`, if valid. | +| image\_details | object | Optional. JSON containing additional details or attributes of the image. | + + + ```json + [ + { + "trait_type": "Specialization", + "value": "Thief" + }, + { + "trait_type": "Skin Tone", + "value": "#0013b0" + }, + { + "trait_type": "Weapon", + "value": "Crossbow" + }, + { + "trait_type": "Species", + "value": "Dark Elf" + }, + { + "trait_type": "Gender", + "value": "Female" + }, + { + "trait_type": "Strength", + "value": "8" + }, + { + "trait_type": "Dexterity", + "value": "12" + }, + { + "trait_type": "Intelligence", + "value": "10" + }, + { + "trait_type": "Perks", + "value": ["Steath", "Eagle Eye", "Lockpicking", "Pickpocketing", "Fire resistance"] + }, + { + "trait_type": "Weakness", + "value": ["Slow healing", "Elfbark Addict", "Lockpicking", "Fear of cats", "Unconvincing liar"] + }, + { + "trait_type": "Personality", + "value": "Aggressive" + } + ] + ``` + + +### TokensRequest + +The `TokensRequest` object includes the following items for a given coin or token: + +| Parameter | Type | Description | +| ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ | +| ticker | string | Ticker of the token to be enabled | +| required\_confirmations | integer | How many confirmations to wait during the transaction steps of an atomic swap. Overwrites value in coins file; defaults to `3` | + + + ```json + { + "ticker": "MINDS-ERC20", + "required_confirmations": 4 + } + ``` + + +### 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 + + ```json + { + "type": "Eth", + "coin": "BNB", + "gas": 109739, + "gas_price": "0.000000003", + "total_fee": "0.000329217" + } + ``` + + #### Example of Qrc20 type + + ```json + { + "type": "Qrc20", + "coin": "tQTUM", + "miner_fee": "0.00000447", + "gas_limit": 100000, + "gas_price": 40, + "total_gas_fee": "0.04" + } + ``` + + #### Example of Tendermint type + + ```json + { + "type": "Tendermint", + "coin": "IRIS", + "amount": "0.038553", + "gas_limit": 100000 + } + ``` + + #### Example of Utxo type + + ```json + { + "type": "Utxo", + "amount": "0.00001" + } + ``` + + +### WithdrawNftData + +The `WithdrawNftData` object is used for withdrawals of NFTs on ERC721 and ERC1155 contracts. It includes the following items for a given coin or token: + +| Parameter | Type | Description | +| -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| chain | string | The token chain. Chain must be [activated](/atomicdex/api/legacy/coin_activation/) first. | +| to | string | Destination address to withdraw the token to. | +| token\_address | string | Token address. | +| token\_id | string | Token ID. | +| fee | object | A standard [WithdrawFee](/atomicdex/api/v20/#withdraw-fee) object. May be missing for older transfers. | +| amount | string | Optional, ERC1155 only. Defaults to `1`. Amount of NFTs to withdraw. Ignored if `max` is true. | +| max | boolean | Optional, ERC1155 only. Defaults to `false`. If `true`, amount parameter will be ignored and all NFTs with this `token_id` will be sent. | + + + When the `type` parameter in a [withdraw\_nft](/atomicdex/api/v20-dev/non_fungible_tokens/withdraw_nft/) request is `withdraw_erc721`, it means the NFT is absolutely unique, + and it has only 1 owner and the owner can own only 1 NFT with this `token_id` + in its `token_address` (also referred to as contract address). + When the `type` parameter in a [withdraw\_nft](/atomicdex/api/v20-dev/non_fungible_tokens/withdraw_nft/) request is `withdraw_erc1155`, it means that it is possible for more + than 1 user to own one or more of the same NFT (with an identical `token_id`). + Due to this difference, the `amount` and `max` fields are only used the when + the `type` value is `withdraw_erc1155`. + export const title = "AtomicDEX: Signing and Verifying Messages"; export const description = "The methods in this document allow you to sign and verify messages for all coins supported by AtomicDEX."; diff --git a/data-for-gpts/komodefi-api/v20-dev-api-content.txt b/data-for-gpts/komodefi-api/v20-dev-api-content.txt index 6568f263..bc337b60 100644 --- a/data-for-gpts/komodefi-api/v20-dev-api-content.txt +++ b/data-for-gpts/komodefi-api/v20-dev-api-content.txt @@ -2881,6 +2881,1125 @@ The `max_maker_vol` method returns the maximum volume of a coin which can be use } ``` +export const title = "AtomicDEX: Non Fungible Tokens - Get NFT List"; +export const description = + "This document describes all the get_nft_list method AtomicDEX-API provides to get a list of your wallets NFTs"; + +# Get a list of NFTs {{label : 'get_nft_list', tag : 'API-v2'}} + +Returns a list of the NFTs owned by the user, shown in descending order of the `block_number` value (the block height when the amount or owner changed). If the request is for NFTs on more than one chain, this means that the order may not be chronological. In the case of ERC1155 tokens, the `block_number` will update when additional NFTs are received or when all NFTs are withdrawn, but will generally remain the same if only some NFTs are withdrawn. + + + Before using this method, you must first call the [update\_nft](/atomicdex/api/v20-dev/non_fungible_tokens/update_nft/) + method to populate/refresh the local database. + + +### Request Parameters + +| Parameter | Type | Description | +| ------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| chains | array | List of networks to scan for NFTs. Options are: `POLYGON`, `FANTOM`, `ETH`, `BSC`, or `AVALANCHE`. | +| max | boolean | Optional, defaults to `false`. If `true`, response will return all NFTs without pagination, and will ignore the `limit` and `page_number` values. | +| limit | integer | Optional, defaults to `10`. The number of NFTs displayed per page in response. | +| page\_number | integer | Optional, defaults to `1`. The page offset for items in response. | +| protect\_from\_spam | boolean | Optional, defaults to `false`. If `true`, any potential spam link found in collection name, token name, symbol will be replaced with `URL redacted for user protection` | +| filters | object | Optional. A standard [TokenFilter](/atomicdex/api/v20/#token-filter) object. | + +### Response Parameters + +| Parameter | Type | Description | +| --------- | --------------- | -------------------------------------------------------------------------------------- | +| nfts | list of objects | A list of standard [NftInfo](/atomicdex/api/common_structures/nfts/#nft-info) objects. | +| total | string | The total number of NFTs in your wallet matching the request filters. | +| skipped | string | The number of NFTs in your wallet excluded by the request filters. | + +#### ๐Ÿ“Œ Example with no optional params + + + ```json + { + "userpass": "testpsw", + "method": "get_nft_list", + "mmrpc": "2.0", + "params": { + "chains": [ + "BSC", + "POLYGON" + ] + } + } + ``` + + + + ```json + { + "mmrpc": "2.0", + "result": { + "nfts": [ + { + "chain": "BSC", + "token_address": "0x5c7d6712dfaf0cb079d48981781c8705e8417ca0", + "token_id": "0", + "amount": "1", + "owner_of": "0xf622a6c52c94b500542e2ae6bcad24c53bc5b6a2", + "token_hash": "b34ddf294013d20a6d70691027625839", + "block_number_minted": 25465916, + "block_number": 25919780, + "contract_type": "ERC1155", + "name": null, + "symbol": null, + "token_uri": "https://tikimetadata.s3.amazonaws.com/tiki_box.json", + "token_domain": "tikimetadata.s3.amazonaws.com", + "metadata": "{\"name\":\"Tiki box\",\"description\":\"Born to usher in Bull markets. Tiki JumpStarters are crazed guardians that worship NGU technology. Tiki guardians attach themselves to their owners to guide and protect them from the evils of the crypto industry. Manifested by the power of community and infused with unlimited creativity, the Unlockable Road Map summons powerful gifts and surprises to all Tiki Holders. Booyaaah!!\",\"external_url\":\"\",\"image\":\"https://tikimetadata.s3.amazonaws.com/tiki_box.png\",\"attributes\":[{\"trait_type\":\"Crypto Logo\",\"value\":\"TIKI NFT CRYPTOLOGO SCAR\"}],\"properties\":{\"category\":\"image\",\"creators\":[]}}", + "last_token_uri_sync": "2023-02-07T17:10:08.402Z", + "last_metadata_sync": "2023-02-07T17:10:16.858Z", + "minter_address": "ERC1155 tokens don't have a single minter", + "possible_spam": false, + "possible_phishing": false, + "uri_meta": { + "image": "https://tikimetadata.s3.amazonaws.com/tiki_box.png", + "image_url": "https://tikimetadata.s3.amazonaws.com/tiki_box.png", + "image_domain": "tikimetadata.s3.amazonaws.com", + "name": "Tiki box", + "description": "Born to usher in Bull markets. Tiki JumpStarters are crazed guardians that worship NGU technology. Tiki guardians attach themselves to their owners to guide and protect them from the evils of the crypto industry. Manifested by the power of community and infused with unlimited creativity, the Unlockable Road Map summons powerful gifts and surprises to all Tiki Holders. Booyaaah!!", + "attributes": [ + { + "trait_type": "Crypto Logo", + "value": "TIKI NFT CRYPTOLOGO SCAR" + } + ], + "animation_url": null, + "animation_domain": null, + "external_url": "", + "external_domain": null, + "image_details": null + } + }, + { + "chain": "POLYGON", + "token_address": "0x48c75fbf0452fa8ff2928ddf46b0fe7629cca2ff", + "token_id": "5", + "amount": "1", + "owner_of": "0xf622a6c52c94b500542e2ae6bcad24c53bc5b6a2", + "token_hash": "28f970585fd743b056859a6e41f50a8e", + "block_number_minted": 36781490, + "block_number": 42491885, + "contract_type": "ERC1155", + "name": null, + "symbol": null, + "token_uri": "https://app.thesmurfssociety.com/metadata/public/metadata/cauldron/5", + "token_domain": "app.thesmurfssociety.com", + "metadata": "{\"name\":\"Forest Mushrooms\",\"description\":\"Sweet and nutty with distinct earthy tones, these forest mushrooms will make a fine addition to all your soups, salads, and potions.\",\"image\":\"https://metadata.thesmurfssociety.com/ingredients/nft/5.Forest_Mushrooms.jpg\",\"animation_url\":null,\"external_url\":\"https://app.thesmurfssociety.com/detail/ingredients/5\",\"attributes\":[{\"trait_type\":\"Type\",\"value\":\"Ingredient\"},{\"trait_type\":\"Category\",\"value\":\"COMMON\"}]}", + "last_token_uri_sync": "2022-12-13T13:12:50.840Z", + "last_metadata_sync": "2023-05-15T07:30:04.882Z", + "minter_address": "ERC1155 tokens don't have a single minter", + "possible_spam": false, + "possible_phishing": false, + "uri_meta": { + "image": "https://metadata.thesmurfssociety.com/ingredients/nft/5.Forest_Mushrooms.jpg", + "image_url": "https://metadata.thesmurfssociety.com/ingredients/nft/5.Forest_Mushrooms.jpg", + "image_domain": "metadata.thesmurfssociety.com", + "name": "Forest Mushrooms", + "description": "Sweet and nutty with distinct earthy tones, these forest mushrooms will make a fine addition to all your soups, salads, and potions.", + "attributes": [ + { + "trait_type": "Type", + "value": "Ingredient" + }, + { + "trait_type": "Category", + "value": "COMMON" + } + ], + "animation_url": null, + "animation_domain": null, + "external_url": "https://app.thesmurfssociety.com/detail/ingredients/5", + "external_domain": "app.thesmurfssociety.com", + "image_details": null + } + } + ], + "skipped": 0, + "total": 2 + }, + "id": null + } + ``` + + +#### ๐Ÿ“Œ Example with optional limit & page\_number params + + + ```json + { + "userpass": "testpsw", + "method": "get_nft_list", + "mmrpc": "2.0", + "params": { + "chains": [ + "BSC", + "POLYGON" + ], + "limit": 1, + "page_number": 2 + } + } + ``` + + + + ```json + { + "mmrpc": "2.0", + "result": { + "nfts": [ + { + "chain": "POLYGON", + "token_address": "0x48c75fbf0452fa8ff2928ddf46b0fe7629cca2ff", + "token_id": "5", + "amount": "1", + "owner_of": "0xf622a6c52c94b500542e2ae6bcad24c53bc5b6a2", + "token_hash": "28f970585fd743b056859a6e41f50a8e", + "block_number_minted": 36781490, + "block_number": 42491885, + "contract_type": "ERC1155", + "name": null, + "symbol": null, + "token_uri": "https://app.thesmurfssociety.com/metadata/public/metadata/cauldron/5", + "token_domain": "app.thesmurfssociety.com", + "metadata": "{\"name\":\"Forest Mushrooms\",\"description\":\"Sweet and nutty with distinct earthy tones, these forest mushrooms will make a fine addition to all your soups, salads, and potions.\",\"image\":\"https://metadata.thesmurfssociety.com/ingredients/nft/5.Forest_Mushrooms.jpg\",\"animation_url\":null,\"external_url\":\"https://app.thesmurfssociety.com/detail/ingredients/5\",\"attributes\":[{\"trait_type\":\"Type\",\"value\":\"Ingredient\"},{\"trait_type\":\"Category\",\"value\":\"COMMON\"}]}", + "last_token_uri_sync": "2022-12-13T13:12:50.840Z", + "last_metadata_sync": "2023-05-15T07:30:04.882Z", + "minter_address": "ERC1155 tokens don't have a single minter", + "possible_spam": false, + "possible_phishing": false, + "uri_meta": { + "image": "https://metadata.thesmurfssociety.com/ingredients/nft/5.Forest_Mushrooms.jpg", + "image_url": "https://metadata.thesmurfssociety.com/ingredients/nft/5.Forest_Mushrooms.jpg", + "image_domain": "metadata.thesmurfssociety.com", + "name": "Forest Mushrooms", + "description": "Sweet and nutty with distinct earthy tones, these forest mushrooms will make a fine addition to all your soups, salads, and potions.", + "attributes": [ + { + "trait_type": "Type", + "value": "Ingredient" + }, + { + "trait_type": "Category", + "value": "COMMON" + } + ], + "animation_url": null, + "animation_domain": null, + "external_url": "https://app.thesmurfssociety.com/detail/ingredients/5", + "external_domain": "app.thesmurfssociety.com", + "image_details": null + } + } + ], + "skipped": 1, + "total": 1 + }, + "id": null + } + ``` + + +#### ๐Ÿ“Œ Example with optional spam protection + + + ```json + { + "userpass": "testpsw", + "method": "get_nft_list", + "mmrpc": "2.0", + "params": { + "chains": [ + "BSC", + "POLYGON" + ], + "protect_from_spam": true, + "filters": { + "exclude_spam": true, + "exclude_phishing": true + } + } + } + ``` + + + + ```json + { + "mmrpc": "2.0", + "result": { + "nfts": [ + { + "chain": "POLYGON", + "token_address": "0x48c75fbf0452fa8ff2928ddf46b0fe7629cca2ff", + "token_id": "5", + "amount": "1", + "owner_of": "0xf622a6c52c94b500542e2ae6bcad24c53bc5b6a2", + "token_hash": "28f970585fd743b056859a6e41f50a8e", + "block_number_minted": 36781490, + "block_number": 42491885, + "contract_type": "ERC1155", + "name": null, + "symbol": null, + "token_uri": "https://app.thesmurfssociety.com/metadata/public/metadata/cauldron/5", + "token_domain": "app.thesmurfssociety.com", + "metadata": "{\"name\":\"Forest Mushrooms\",\"description\":\"Sweet and nutty with distinct earthy tones, these forest mushrooms will make a fine addition to all your soups, salads, and potions.\",\"image\":\"https://metadata.thesmurfssociety.com/ingredients/nft/5.Forest_Mushrooms.jpg\",\"animation_url\":null,\"external_url\":\"https://app.thesmurfssociety.com/detail/ingredients/5\",\"attributes\":[{\"trait_type\":\"Type\",\"value\":\"Ingredient\"},{\"trait_type\":\"Category\",\"value\":\"COMMON\"}]}", + "last_token_uri_sync": "2022-12-13T13:12:50.840Z", + "last_metadata_sync": "2023-05-15T07:30:04.882Z", + "minter_address": "ERC1155 tokens don't have a single minter", + "possible_spam": false, + "possible_phishing": false, + "uri_meta": { + "image": "https://metadata.thesmurfssociety.com/ingredients/nft/5.Forest_Mushrooms.jpg", + "image_url": "https://metadata.thesmurfssociety.com/ingredients/nft/5.Forest_Mushrooms.jpg", + "image_domain": "metadata.thesmurfssociety.com", + "name": "Forest Mushrooms", + "description": "Sweet and nutty with distinct earthy tones, these forest mushrooms will make a fine addition to all your soups, salads, and potions.", + "attributes": [ + { + "trait_type": "Type", + "value": "Ingredient" + }, + { + "trait_type": "Category", + "value": "COMMON" + } + ], + "animation_url": null, + "animation_domain": null, + "external_url": "https://app.thesmurfssociety.com/detail/ingredients/5", + "external_domain": "app.thesmurfssociety.com", + "image_details": null + } + } + ], + "skipped": 0, + "total": 1 + }, + "id": null + } + ``` + + +### ๐Ÿ“Œ Error responses + +#### Unsupported Chain Type + +The supported chains are + +``` +{ + "mmrpc":"2.0", + "error":"Error parsing request: UnsupportedChainType", + "error_path":"dispatcher", + "error_trace":"dispatcher:109]", + "error_type":"InvalidRequest", + "error_data":"UnsupportedChainType", + "id":null +} +``` +export const title = "AtomicDEX: Non Fungible Tokens"; +export const description = + "This document describes the get_nft_metadata method AtomicDEX-API provides to get metadata for your NFTs"; + +# Get NFT Metadata {{label : 'get_nft_metadata', tag : 'API-v2'}} + +### Request Parameters + +| Parameter | Type | Description | +| ------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- | +| chain | string | The token chain. | +| token\_address | string | The token address. | +| token\_id | string | Token ID. | +| protect\_from\_spam | boolean | Optional, defaults to `false`. If `true`, any potentially spam link found in collection name, token name, symbol will be censored | + +### Response Parameters + +| Parameter | Type | Description | +| ---------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| amount | string | The amount of this NFT the user owns (used by `ERC1155`). | +| block\_number\_minted | integer | The block height when the NFT was minted. May be `null`. | +| block\_number | integer | The block height when the amount or owner changed. | +| chain | string | Chain name. One of `AVALANCHE`, `BSC`, `ETH`, `FANTOM`, or `POLYGON`. | +| name | string | May be `null`. An NFT collection name. | +| contract\_type | string | The type of NFT contract standard. One of `ERC721` or `ERC1155`. | +| last\_token\_uri\_sync | string | When the token\_uri was last updated. | +| last\_metadata\_sync | string | When the metadata was last updated. | +| metadata | string | The metadata of the token. May be `null`. | +| minter\_address | string | Minter address. May be `null`. | +| owner\_of | string | The wallet address of the owner of the NFT. | +| possible\_spam | boolean | If `true`, the contract address has [been identified](https://docs.moralis.io/web3-data-api/evm/nft-spam-detection) as associated with spam or suspicious activities. | +| possible\_phishing | boolean | If `true`, the token has been identified as associated with phishing, as at least one of domain fields is found in database with phishing domains. | +| symbol | string | May be `null`. The symbol of the NFT contract. | +| token\_address | string | The address of the NFT contract. | +| token\_id | string | The token ID of the NFT. | +| token\_hash | string | The token hash. May be `null`. | +| token\_uri | string | The URI to the metadata of the token. May be `null`. | +| token\_domain | string | Token domain. May be `null`. | +| uri\_meta | object | A standard [NftMetadata](/atomicdex/api/v20/#token-metadata) object. | + +#### ๐Ÿ“Œ Example + + + ```json + { + "userpass": "testpsw", + "method": "get_nft_metadata", + "mmrpc": "2.0", + "params": { + "token_address": "0xfd913a305d70a60aac4faac70c739563738e1f81", + "token_id": "214300044414", + "chain": "BSC" + } + } + ``` + + + + ```json + { + "mmrpc": "2.0", + "result": { + "token_address": "0x2953399124f0cbb46d2cbacd8a89cf0599974963", + "amount": "1", + "owner_of": "0xab95d01bc8214e4d993043e8ca1b68db2c946498", + "token_hash": "af811b641bccbdc10c444ba4f3a2ffb5", + "name": "OpenSea Collections", + "symbol": "OPENSTORE", + "token_uri": "https://api.opensea.io/api/v2/metadata/matic/0x2953399124F0cBB46d2CbACD8A89cF0599974963/0xf43db4f488f644b73a9442de4978fb7572b73d85000000000000110000002710", + "token_domain": "api.opensea.io", + "metadata": "{\"image\":\"https://i.seadn.io/gae/nY8wjVVQqDZBl-Bk3h9kwSqR1bXt16x_tESRAQmctEb0SCFCPtvtSsBtp98TFiUzP-LpMGt_kiqHDDOfkgbxOuWxkdH4aBNkmzrjZM0?w=500&auto=format\",\"name\":\"Doge Napoleon\",\"description\":null,\"external_link\":null,\"animation_url\":\"https://openseauserdata.com/files/df71203f48e54d027bb2c47b2840cacb.mp4\",\"traits\":[]}", + "last_token_uri_sync": "2023-09-01T04:04:30.867Z", + "last_metadata_sync": "2023-09-01T04:35:01.128Z", + "minter_address": "ERC1155 tokens don't have a single minter", + "possible_spam": true, + "chain": "POLYGON", + "token_id": "110473361632261669912565539602449606788298723469812631769659886404530570536720", + "block_number_minted": 19645247, + "block_number": 45776404, + "contract_type": "ERC1155", + "possible_phishing": false, + "uri_meta": { + "image": "https://i.seadn.io/gae/nY8wjVVQqDZBl-Bk3h9kwSqR1bXt16x_tESRAQmctEb0SCFCPtvtSsBtp98TFiUzP-LpMGt_kiqHDDOfkgbxOuWxkdH4aBNkmzrjZM0?w=500&auto=format", + "image_url": "https://i.seadn.io/gae/nY8wjVVQqDZBl-Bk3h9kwSqR1bXt16x_tESRAQmctEb0SCFCPtvtSsBtp98TFiUzP-LpMGt_kiqHDDOfkgbxOuWxkdH4aBNkmzrjZM0?w=500&auto=format", + "image_domain": "i.seadn.io", + "name": "Doge Napoleon", + "description": null, + "attributes": null, + "animation_url": "https://openseauserdata.com/files/df71203f48e54d027bb2c47b2840cacb.mp4", + "animation_domain": "openseauserdata.com", + "external_url": null, + "external_domain": null, + "image_details": null + } + }, + "id": null + } + ``` + + +## Error responses + +``` +{ + "mmrpc": "2.0", + "error": "Token: token_address 0xfd913a305d70a60aac4faac70c739563738e1f81, token_id 214300044414 was not found in wallet", + "error_path": "nft", + "error_trace": "nft:123]", + "error_type": "TokenNotFoundInWallet", + "error_data": { + "token_address": "0xfd913a305d70a60aac4faac70c739563738e1f81", + "token_id": "214300044414" + }, + "id": null +} +``` +export const title = "AtomicDEX: Non Fungible Tokens"; +export const description = + "This document describes the get_nft_transfers method AtomicDEX-API provides to get information about your NFT transactions"; + +# Get a list of NFT transfers {{label : 'get_nft_transfers', tag : 'API-v2'}} + +Returns a list of the NFT transfers involving the user, shown in descending order of the `block_timestamp` value of the NFT's last transfer. + + + To view NFT transactions, you must [activate the coin](/atomicdex/api/legacy/coin_activation/) which holds the NFTs first. + + +### Request Parameters + +| Parameter | Type | Description | +| ------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| chains | array | List of chains to scan for NFTs. | +| max | boolean | Optional, defaults to `false`. If `true`, response will return all NFT transfers without pagination, and will ignore the `limit` and `page_number` values. | +| limit | integer | Optional, defaults to `10`. The number of NFT transfers displayed per page in response. | +| page\_number | integer | Optional, defaults to `1`. The page offset for items in response. | +| protect\_from\_spam | boolean | Optional, defaults to `false`. If `true`, any potentially spam link found in `collection_name`, `token_name` will be censored | +| filters | object | Optional. A standard [TokenTransferFilter](/atomicdex/api/v20/#token-transfer-filter) object. | + +### Response Parameters + +| Parameter | Type | Description | +| ----------------- | --------------- | ---------------------------------------------------------------------------------------------- | +| transfer\_history | list of objects | A list of standard [NftTransfer](/atomicdex/api/common_structures/nfts/#nft-transfer) objects. | +| total | string | The total number of NFT transfers in your wallet matching the request filters. | +| skipped | string | The number of NFT transfers in your wallet excluded by the request filters. | + +#### ๐Ÿ“Œ Example with date and `send` filters + + + ```json + { + "userpass": "testpsw", + "method": "get_nft_transfers", + "mmrpc": "2.0", + "params": { + "chains": [ + "POLYGON" + ], + "max": true, + "filters": { + "receive": true, + "from_date": 1678233600 + }, + "protect_from_spam": true + } + } + ``` + + + + ```json + { + "mmrpc": "2.0", + "result": { + "transfer_history": [ + { + "block_hash": "0xfd012e9dc2c7fa652ae3c0923599a9e6196520ac46e55f0f467d3a1ce84b8580", + "transaction_hash": "0x4063c4ae3e56a06b6c8768ad76e0cb1523e671cf06e4325517106497778ede9e", + "transaction_index": 87, + "log_index": 468, + "value": "0", + "transaction_type": "Single", + "token_address": "0x48c75fbf0452fa8ff2928ddf46b0fe7629cca2ff", + "from_address": "0xf622a6c52c94b500542e2ae6bcad24c53bc5b6a2", + "to_address": "0xf622a6c52c94b500542e2ae6bcad24c53bc5b6a2", + "amount": "2", + "verified": 1, + "operator": "0xf622a6c52c94b500542e2ae6bcad24c53bc5b6a2", + "possible_spam": false, + "chain": "POLYGON", + "token_id": "5", + "block_number": 44506464, + "block_timestamp": 1688107346, + "contract_type": "ERC1155", + "token_uri": "https://app.thesmurfssociety.com/metadata/public/metadata/cauldron/5", + "token_domain": "app.thesmurfssociety.com", + "collection_name": null, + "image_url": "https://metadata.thesmurfssociety.com/ingredients/nft/5.Forest_Mushrooms.jpg", + "image_domain": "metadata.thesmurfssociety.com", + "token_name": "Forest Mushrooms", + "status": "Receive", + "possible_phishing": false, + "fee_details": { + "coin": "MATIC", + "gas": 40249, + "gas_price": "0.000000153160317706", + "total_fee": "0.006164549627348794" + }, + "confirmations": 5775855 + } + ], + "skipped": 0, + "total": 1 + }, + "id": null + } + ``` + +export const title = "AtomicDEX: Non Fungible Tokens"; +export const description = + "This document describes all the methods AtomicDEX-API provides to get information and transact with NFTs"; + +# Non Fungible Tokens (NFTs) + +The AtomicDEX API supports [ERC1155](https://www.nftstandards.wtf/Standards/ERC1155+Multi+token) and [ERC721](https://www.nftstandards.wtf/Standards/ERC721+Non+Fungible+Standard) NFTs via the [Moralis API](https://docs.moralis.io/) on the Avalanche (AVAX), BNB Smart Chain (BNB), Ethereum (ETH), Fantom (FTM), Polygon (MATIC) networks. + + + Before using other NFT methods, you should first call the [update\_nft](/atomicdex/api/v20-dev/non_fungible_tokens/update_nft/) + method to populate/refresh the local database. + + +## NFT Information Methods + +* Get a list of your tokens with [get\_nft\_list](/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_list/) +* Get a list of token transfers with [get\_nft\_transfers](/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_transfers/) +* Get token metadata with [get\_nft\_metadata](/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_metadata/) +* Update NFT [update\_nft](/atomicdex/api/v20-dev/non_fungible_tokens/update_nft/) +* Refresh NFT metadata with [refresh\_nft\_metadata](/atomicdex/api/v20-dev/non_fungible_tokens/refresh_nft_metadata/) + +## NFT Transaction Methods + +* Withdraw ERC721 tokens with [withdraw\_nft](/atomicdex/api/v20-dev/non_fungible_tokens/withdraw_nft/#erc-721-withdraw-example) +* Withdraw ERC1155 tokens with [withdraw\_nft](/atomicdex/api/v20-dev/non_fungible_tokens/withdraw_nft/#erc-1155-withdraw-example) + + + View the source code at: [https://github.com/KomodoPlatform/komodo-defi-framework/blob/main/mm2src/coins/nft.rs](https://github.com/KomodoPlatform/komodo-defi-framework/blob/main/mm2src/coins/nft.rs) + +export const title = "AtomicDEX: Non Fungible Tokens - Query NFT database tables"; +export const description = + "This document describes how to query the local NFT database tables."; + +# Query NFT database tables + +After using the [update\_nft](/atomicdex/api/v20-dev/non_fungible_tokens/update_nft/#update-nft) method to initialise your local NFT database, +the following tables are available in `DB/KOMODEFI.db`: + +* AVAX\_nft\_list +* AVAX\_nft\_transfer\_history +* BNB\_nft\_list +* BNB\_nft\_transfer\_history +* ETH\_nft\_list +* ETH\_nft\_transfer\_history +* FTM\_nft\_list +* FTM\_nft\_transfer\_history +* MATIC\_nft\_list +* MATIC\_nft\_transfer\_history +* scanned\_nft\_blocks + +## NFT List tables + +The COIN\_nft\_list tables contain the NFTs that you own +It has the following columns, though not all columns are populated for all NFTs: + +| ID | Name | Type | Description | +| -- | ---------------------- | ------------ | ------------------------------------------------------------------------------ | +| 0 | token\_address | VARCHAR(256) | The address of the token contract. | +| 1 | token\_id | VARCHAR(256) | The id of the token. | +| 2 | chain | TEXT | The coin network which the NFT is on. | +| 3 | amount | VARCHAR(256) | The amount of NFTs transfered in this transaction. | +| 4 | block\_number | INTEGER | The block height of this transaction. | +| 5 | contract\_type | TEXT | The contract type. Either `ERC721` or `ERC1155`. | +| 6 | possible\_spam | INTEGER | `1` indicates the NFT has been identified as spam. `0` indicates it has not. | +| 7 | possible\_phishing | INTEGER | `1` indicates the NFT has been identified as a scam. `0` indicates it has not. | +| 8 | collection\_name | TEXT | The collection name which includes the token. | +| 9 | symbol | TEXT | An arbitrary symbol for the NFT | +| 10 | token\_uri | TEXT | A link to the token's metadata. | +| 11 | token\_domain | TEXT | The domain the token metadata is hosted on. | +| 12 | metadata | TEXT | The token's metadata in JSON format. | +| 13 | last\_token\_uri\_sync | TEXT | Date and time when the token uri was last syncronised. | +| 14 | last\_metadata\_sync | TEXT | Date and time when the token metadata was last syncronised. | +| 15 | raw\_image\_url | TEXT | The raw URL for the token image. | +| 16 | image\_url | TEXT | A link for the token's image (or other media). | +| 17 | image\_domain | TEXT | The domain the token image (or other media) is hosted on. | +| 18 | token\_name | TEXT | The name of the token. | +| 19 | description | TEXT | An arbitrary description of the NFT. | +| 20 | attributes | TEXT | Additional attribute data for the NFT in JSON format. | +| 21 | animation\_url | TEXT | If NFT is animated, the URL of the animation. | +| 22 | animation\_domain | TEXT | If NFT is animated, the domain of the animation. | +| 23 | external\_url | TEXT | Additional URL related to the NFT | +| 24 | external\_domain | TEXT | Domain of the additional URL related to the NFT | +| 25 | image\_details | TEXT | Additional details about the NFT's image. | +| 26 | details\_json | TEXT | Additional information about the transaction in JSON format. | + +### Example COIN\_nft\_list table query + +> SELECT chain, token\_name, token\_address, token\_id, possible\_spam, possible\_phishing FROM MATIC\_nft\_list LIMIT 5; + +| chain | token\_name | token\_address | token\_id | possible\_spam | possible\_phishing | +| ------- | ---------------------- | ------------------------------------------ | --------- | -------------- | ------------------ | +| POLYGON | $2000 USDT Airdrop๐ŸŽ | 0xe7ee9dcf5f4b7f9254b348ba596c9fb9121f77e7 | 1 | 1 | 0 | +| POLYGON | $1000 USDC Voucher๐ŸŽ | 0xb092b5eb5c653e915880dfc1f606be2ffe6fae8c | 1 | 1 | 0 | +| POLYGON | 1000 BLUR Reward | 0xeaa3c52052b809c8d8072187efc134def2dd5b13 | 0 | 1 | 0 | +| POLYGON | SHIB Voucher 66 of 100 | 0xc46e36339ebd8bed48b1bdb6bd815e4b72103949 | 0 | 1 | 0 | +| POLYGON | $1000 Rewards | 0x6e0b84421388ad635f2a1167e39aff2dc742da2a | 0 | 1 | 0 | + +The NFTs listed above are all spam, and will be ignored by the [get\_nft\_list](/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_list/) method. + +## NFT Transfer table + +The COIN\_nft\_transfer\_history tables contain the history of transfers of your NFTs, and have the following columns: + +| ID | Name | Type | Description | +| -- | ------------------ | ------------ | ------------------------------------------------------------------------------ | +| 0 | transaction\_hash | VARCHAR(256) | Hex string, representing the transaction. | +| 1 | log\_index | INTEGER | Simply a table index. | +| 2 | chain | TEXT | The coin network which the NFT is on. | +| 3 | block\_number | INTEGER | The block height of this transaction. | +| 4 | block\_timestamp | INTEGER | The block time of this transaction. | +| 5 | contract\_type | TEXT | The contract type. Either `ERC721` or `ERC1155`. | +| 6 | token\_address | VARCHAR(256) | The address of the token contract. | +| 7 | token\_id | VARCHAR(256) | The id of the token. | +| 8 | status | TEXT | The transaction type: `Recieve` or `Send` | +| 9 | amount | VARCHAR(256) | The amount of NFTs transfered in this transaction. | +| 10 | possible\_spam | INTEGER | `1` indicates the NFT has been identified as spam. `0` indicates it has not. | +| 11 | possible\_phishing | INTEGER | `1` indicates the NFT has been identified as a scam. `0` indicates it has not. | +| 12 | token\_uri | TEXT | A link to the token's metadata. | +| 13 | token\_domain | TEXT | The domain the token metadata is hosted on. | +| 14 | collection\_name | TEXT | The collection name which includes the token. | +| 15 | image\_url | TEXT | A link for the token's image (or other media). | +| 16 | image\_domain | TEXT | The domain the token image (or other media) is hosted on. | +| 17 | token\_name | TEXT | The name of the token. | +| 18 | details\_json | TEXT | Additional information about the transaction in JSON format. | + +### Example scanned\_nft\_blocks table query + +`SELECT transaction\_hash, token\_name, token\_address, token\_id, FROM MATIC_nft_transfer_history WHERE block_timestamp > 1701519320;` + +| transaction\_hash | token\_name | token\_address | token\_id | +| ------------------------------------------------------------------ | -------------------- | ------------------------------------------ | --------- | +| 0x7b57303bcc2c68808b460490e984adcd18567a80660a18b7a151b62015247cda | $2000 USDT Airdrop๐ŸŽ | 0xe7ee9dcf5f4b7f9254b348ba596c9fb9121f77e7 | 1 | + +## NFT Last Scanned Block table + +The scanned\_nft\_blocks table contains the last block that was scanned for each chain. +It has the following columns: + +| ID | Name | Type | Description | +| -- | -------------------- | ------- | ---------------------------------------------------------------------- | +| 2 | chain | TEXT | The coin network which the NFT is on. | +| 1 | last\_scanned\_block | INTEGER | The block height when the last scan for NFTs was performed on a chain. | + +### Example scanned\_nft\_blocks table query + +`SELECT * FROM scanned_nft_blocks;` + +| chain | last\_scanned\_block | +| ----- | -------------------- | +| MATIC | 50651981 | +| FTM | 66512090 | +| ETH | 0 | +| BNB | 0 | +| AVAX | 0 | +export const title = "AtomicDEX: Non Fungible Tokens"; +export const description = + "This document describes all the refresh_nft_metadata method AtomicDEX-API provides to refresh an NFT's metadata"; + +# Refresh NFT Metadata {{label : 'refresh_nft_metadata', tag : 'API-v2'}} + +This method refreshes metadata of one NFT and metadata of related transactions with the same token\_address and token\_id. + +### Request Parameters + +| Parameter | Type | Description | +| -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| chain | string | Chains which holds the NFT you would like to updated metadata for. | +| url | string | URL link to the Moralis API proxy base url ([https://moralis-proxy.komodo.earth](https://moralis-proxy.komodo.earth)) or equivalent. | +| token\_address | string | Token address. | +| token\_id | string | Token ID. | +| url\_antispam | string | URL link to the [Antispam API proxy base url](https://nft.antispam.dragonhound.info) or equivalent. [docs](https://nft.antispam.dragonhound.info/docs). | + + + If there are no errors, this request will return an empty response. + + +#### ๐Ÿ“Œ Example + + + ```json + { + "userpass": "testpsw", + "method": "refresh_nft_metadata", + "mmrpc": "2.0", + "params": { + "token_address": "0x48c75fbf0452fa8ff2928ddf46b0fe7629cca2ff", + "token_id": "5", + "chain": "POLYGON", + "url": "https://moralis-proxy.komodo.earth", + "url_antispam": "https://nft.antispam.dragonhound.info" + } + } + ``` + + + + + If there are no errors, this request will return an empty response. + + + ```json + { + "mmrpc": "2.0", + "result": null, + "id": null + } + ``` + + + + Need to add some error responses here. + +export const title = "AtomicDEX: Non Fungible Tokens"; +export const description = + "This document describes the update_nft method AtomicDEX-API provides to update NFT information in your local database"; + +# Update NFT {{label : 'update_nft', tag : 'API-v2'}} + +This method will scan selected networks to update NFT information stored in the local database. +To interact with your NFTs, you will first need to activate the coin for the network the NFT is on. + +See below for which coin to activate for each network: + +| Network | Coin | +| --------- | ----- | +| AVALANCHE | AVAX | +| BSC | BNB | +| ETH | ETH | +| FANTOM | FTM | +| POLYGON | MATIC | + +These coins can be activated using the [enable\_eth\_with\_tokens](/atomicdex/api/v20/enable_eth_with_tokens/) or method. + +### Request Parameters + +| Parameter | Type | Description | +| ------------- | ------ | --------------------------------------------------------------------------------------------------- | +| chains | array | List of networks to scan for NFTs. Options are: `POLYGON`, `FANTOM`, `ETH`, `BSC`, or `AVALANCHE`. | +| url | string | URL link to the [Moralis API proxy base url](https://moralis-proxy.komodo.earth) or equivalent. | +| url\_antispam | string | URL link to the [Antispam API proxy base url](https://nft.antispam.dragonhound.info) or equivalent. | + + + If there are no errors, this request will return an empty response. + When updating multiple networks, or wallets with numerous NFTs, this request may take a while to complete. + + +#### ๐Ÿ“Œ Example + + + ```json + { + "userpass": "testpsw", + "method": "update_nft", + "mmrpc": "2.0", + "params": { + "chains": [ + "BSC", + "POLYGON" + ], + "url": "https://moralis-proxy.komodo.earth", + "url_antispam": "https://nft.antispam.dragonhound.info" + } + } + ``` + + + + ```json + { + "mmrpc": "2.0", + "result": null, + "id": null + } + ``` + + + + Need to add some error responses here. + +export const title = "AtomicDEX: Non Fungible Tokens"; +export const description = + "This document describes the withdraw_nft method AtomicDEX-API provides to send NFTs to an address"; + +# Withdraw NFTs {{label : 'withdraw_nft', tag : 'API-v2'}} + + + To withdraw NFTs, you must [activate the coin](/atomicdex/api/legacy/coin_activation/) which holds the NFTs first. + The `withdraw_nft` method will return signed raw transaction hex which must be broadcast using the [send\_raw\_transaction](/atomicdex/api/legacy/send_raw_transaction/) method to complete the withdrawal. + + +### Request Parameters + +| Parameter | Type | Description | +| -------------- | ------ | ---------------------------------------------------------------------------------------- | +| type | string | The contract type of the NFT to withdraw. Either `withdraw_erc721` or `withdraw_erc1155` | +| withdraw\_data | object | A standard [WithdrawNftData](/atomicdex/api/v20/#withdraw-nft-data) object. | + +### Response Parameters + +| Parameter | Type | Description | +| ----------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| amount | string | Amount of tokens to withdraw. | +| tx\_hex | string | Raw hex of signed transaction. Use this with the [send\_raw\_transaction](/atomicdex/api/legacy/send_raw_transaction/) RPC to broadcast the transaction. | +| tx\_hash | string | Transaction ID of the withdrawl. | +| from | array | List of source addresses. | +| to | array | List of destination addresses. | +| contract\_type | string | Contract type. `ERC721` or `ERC1155`. | +| token\_address | string | Token address. | +| token\_id | string | Token ID. | +| fee\_details | object | A standard [WithdrawFee](/atomicdex/api/v20/#withdraw-fee) object. | +| coin | string | Coin name. One of `AVALANCHE`, `BSC`, `ETH`, `FANTOM`, or `POLYGON`. | +| block\_height | integer | Block height of the transaction. If the value is `0`, the transaction is unconfirmed. | +| timestamp | integer | Timestamp of the block containing the withdrawl transaction in [unix epoch format](https://www.epochconverter.com/). | +| internal\_id | integer | Used for internal transaction identification, for some coins it may be equal to transaction hash. | +| transaction\_type | string | This will always be `NftTransfer`. | + +#### ๐Ÿ“Œ ERC721 Withdraw Example + + + ```json + { + "userpass": "testpsw", + "method": "withdraw_nft", + "mmrpc": "2.0", + "params": { + "type": "withdraw_erc721", + "withdraw_data": { + "chain": "POLYGON", + "to": "0xaB95D01Bc8214E4D993043E8Ca1B68dB2c946498", + "token_address": "0x73a5299824cd955af6377b56f5762dc3ca4cc078", + "token_id": "1" + } + } + } + ``` + + + + ```json + { + "mmrpc": "2.0", + "result": { + "tx_hex": "f8cb2a8509818733db8289929473a5299824cd955af6377b56f5762dc3ca4cc07880b86442842e0e000000000000000000000000ab95d01bc8214e4d993043e8ca1b68db2c946498000000000000000000000000ab95d01bc8214e4d993043e8ca1b68db2c9464980000000000000000000000000000000000000000000000000000000000000001820136a0564b5c9c8309a3f8f6cc007ca957e4c411259026d68c2c34419158aff4d3ebf8a007afaa0590da01a2ce36c7edb5380f41235168f3633ed459b1fc8a750fecd38d", + "tx_hash": "bb030f618702715eb39035dccd218355f78ae5379ff6d0691f0f3c0db3c03789", + "from": [ + "0xaB95D01Bc8214E4D993043E8Ca1B68dB2c946498" + ], + "to": [ + "0xaB95D01Bc8214E4D993043E8Ca1B68dB2c946498" + ], + "contract_type": "ERC721", + "token_address": "0x73a5299824cd955af6377b56f5762dc3ca4cc078", + "token_id": "1", + "amount": "1", + "fee_details": { + "type": "Eth", + "coin": "MATIC", + "gas": 35218, + "gas_price": "0.000000040827827163", + "total_fee": "0.001437874417026534" + }, + "coin": "MATIC", + "block_height": 0, + "timestamp": 1700732198, + "internal_id": 0, + "transaction_type": "NftTransfer" + }, + "id": null + } + ``` + + +#### ๐Ÿ“Œ ERC1155 Withdraw Example + +If you are sending 2 or more NFTs, you must use the `withdraw_erc1155` withdraw type. + + + ```json + { + "userpass": "testpsw", + "method": "withdraw_nft", + "mmrpc": "2.0", + "params": { + "type": "withdraw_erc1155", + "withdraw_data": { + "chain": "POLYGON", + "to": "0xaB95D01Bc8214E4D993043E8Ca1B68dB2c946498", + "token_address": "0x73a5299824cd955af6377b56f5762dc3ca4cc078", + "token_id": "1" + } + } + } + ``` + + + + ```json + { + "mmrpc": "2.0", + "result": { + "tx_hex": "f8cb2a8502dffe7b4682f3a09473a5299824cd955af6377b56f5762dc3ca4cc07880b86442842e0e000000000000000000000000ab95d01bc8214e4d993043e8ca1b68db2c94649800000000000000000000000027ad1f808c1ef82626277ae38998afa5395656600000000000000000000000000000000000000000000000000000000000000001820135a0476a4623c9df31cecbd319e0571c62d14a6dcedd5a760ced945ffa2e39fb12c5a03293f3c10d115edcc3795e414670f070c04ad936e2e87001da12f961df5962a7", + "tx_hash": "d6b46e70bf755617366a5c10875eb639d55586bb568010ea82ef42e8d68c6523", + "from": [ + "0xaB95D01Bc8214E4D993043E8Ca1B68dB2c946498" + ], + "to": [ + "0x27Ad1F808c1ef82626277Ae38998AfA539565660" + ], + "contract_type": "ERC721", + "token_address": "0x73a5299824cd955af6377b56f5762dc3ca4cc078", + "token_id": "1", + "amount": "1", + "fee_details": { + "type": "Eth", + "coin": "MATIC", + "gas": 62368, + "gas_price": "0.000000012347931462", + "total_fee": "0.000770115789422016" + }, + "coin": "MATIC", + "block_height": 0, + "timestamp": 1700732805, + "internal_id": 0, + "transaction_type": "NftTransfer" + }, + "id": null + } + ``` + + +#### ๐Ÿ“Œ ERC1155 Withdraw Max Example + +If you would like to withdraw all NFTs from a token\_address, you must use the `withdraw_erc1155` withdraw type and set `max` to `true`. + + + ```json + { + "userpass": "testpsw", + "method": "withdraw_nft", + "mmrpc": "2.0", + "params": { + "type": "withdraw_erc1155", + "withdraw_data": { + "chain": "POLYGON", + "to": "0x27Ad1F808c1ef82626277Ae38998AfA539565660", + "token_address": "0x2953399124f0cbb46d2cbacd8a89cf0599974963", + "token_id": "110473361632261669912565539602449606788298723469812631769659886404530570536720", + "max": true + } + } + } + ``` + + + + ```json + { + "mmrpc": "2.0", + "result": { + "tx_hex": "f9014b2a8508d579565282ea3b942953399124f0cbb46d2cbacd8a89cf059997496380b8e4f242432a000000000000000000000000ab95d01bc8214e4d993043e8ca1b68db2c94649800000000000000000000000027ad1f808c1ef82626277ae38998afa539565660f43db4f488f644b73a9442de4978fb7572b73d85000000000000110000002710000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000000023078000000000000000000000000000000000000000000000000000000000000820135a0feb67607bd5e5c58f7533c8d2c88ef0ba3beac7fea29bfe11c3ce9bd10641f2ca02f1045b9f87536e45fe63556805734293e534284efecd9210f614316a3e8dca7", + "tx_hash": "9dce8e555d388532bdafd42dd44cd6a2bdcbf74bdda079e15f71b808c8395bcc", + "from": [ + "0xaB95D01Bc8214E4D993043E8Ca1B68dB2c946498" + ], + "to": [ + "0x27Ad1F808c1ef82626277Ae38998AfA539565660" + ], + "contract_type": "ERC1155", + "token_address": "0x2953399124f0cbb46d2cbacd8a89cf0599974963", + "token_id": "110473361632261669912565539602449606788298723469812631769659886404530570536720", + "amount": "7", + "fee_details": { + "type": "Eth", + "coin": "MATIC", + "gas": 59963, + "gas_price": "0.00000003794123733", + "total_fee": "0.00227507041401879" + }, + "coin": "MATIC", + "block_height": 0, + "timestamp": 1700732937, + "internal_id": 0, + "transaction_type": "NftTransfer" + }, + "id": null + } + ``` + + + + ### ๐Ÿ“Œ Withdraw NFTs Error Responses + + #### InvalidRequest (missing field) + + ``` + { + "mmrpc": "2.0", + "error": "Error parsing request: missing field `type`", + "error_path": "dispatcher", + "error_trace": "dispatcher:109]", + "error_type": "InvalidRequest", + "error_data": "missing field `type`", + "id": null + } + ``` + + #### InvalidRequest (wrong withdraw type) + + ``` + { + "mmrpc": "2.0", + "error": "Error parsing request: unknown variant `withdraw_erc420`, expected `withdraw_erc1155` or `withdraw_erc721`", + "error_path": "dispatcher", + "error_trace": "dispatcher:109]", + "error_type": "InvalidRequest", + "error_data": "unknown variant `withdraw_erc420`, expected `withdraw_erc1155` or `withdraw_erc721`", + "id": null + } + ``` + + #### TokenNotFoundInWallet (trying to send NFT you dont own) + + ``` + { + "mmrpc": "2.0", + "error": "Token: token_address 0xfd913a305d70a60aac4faac70c739563738e1f82, token_id 110473361632261669912565539602449606788298723469812631769659886404530570536722 was not found in wallet", + "error_path": "eth.nft", + "error_trace": "eth:883] nft:1177]", + "error_type": "GetNftInfoError", + "error_data": { + "error_type": "TokenNotFoundInWallet", + "error_data": { + "token_address": "0xfd913a305d70a60aac4faac70c739563738e1f82", + "token_id": "110473361632261669912565539602449606788298723469812631769659886404530570536722" + } + }, + "id": null + } + ``` + + #### TransportError (unable to estimate gas) + + ``` + { + "mmrpc": "2.0", + "error": "Transport error: request MethodCall(MethodCall { jsonrpc: Some(V2), method: \"eth_estimateGas\", params: Array([Object({\"from\": String(\"0xab95d01bc8214e4d993043e8ca1b68db2c946498\"), \"to\": String(\"0x2953399124f0cbb46d2cbacd8a89cf0599974963\"), \"gasPrice\": String(\"0x9ddeaaffe\"), \"value\": String(\"0x0\"), \"data\": String(\"0x42842e0e000000000000000000000000ab95d01bc8214e4d993043e8ca1b68db2c946498000000000000000000000000ab95d01bc8214e4d993043e8ca1b68db2c946498f43db4f488f644b73a9442de4978fb7572b73d85000000000000110000002710\")})]), id: Num(64) }) failed: InvalidResponse(\"Server: 'https://polygon-rpc.com/', error: RPC error: Error { code: ServerError(-32000), message: \\\"execution reverted\\\", data: None }\"); InvalidResponse(\"Server: 'https://polygon.blockpi.network/v1/rpc/public', error: RPC error: Error { code: ServerError(-32000), message: \\\"execution reverted\\\", data: None }\"); Transport(\"Server: 'https://node.komodo.earth:8080/polygon', response !200: 502 Bad Gateway, <html>..<head><title>502 Bad Gateway</title></head>..<body>..<center><h1>502 Bad Gateway</h1></center>..<hr><center>nginx/1.18.0 (Ubuntu)</center>..</body>..</html>..\"); InvalidResponse(\"Server: 'https://polygon.llamarpc.com/', error: RPC error: Error { code: ServerError(-32000), message: \\\"execution reverted\\\", data: None }\"); ", + "error_path": "eth", + "error_trace": "eth:1004] eth:5792]", + "error_type": "Transport", + "error_data": "request MethodCall(MethodCall { jsonrpc: Some(V2), method: \"eth_estimateGas\", params: Array([Object({\"from\": String(\"0xab95d01bc8214e4d993043e8ca1b68db2c946498\"), \"to\": String(\"0x2953399124f0cbb46d2cbacd8a89cf0599974963\"), \"gasPrice\": String(\"0x9ddeaaffe\"), \"value\": String(\"0x0\"), \"data\": String(\"0x42842e0e000000000000000000000000ab95d01bc8214e4d993043e8ca1b68db2c946498000000000000000000000000ab95d01bc8214e4d993043e8ca1b68db2c946498f43db4f488f644b73a9442de4978fb7572b73d85000000000000110000002710\")})]), id: Num(64) }) failed: InvalidResponse(\"Server: 'https://polygon-rpc.com/', error: RPC error: Error { code: ServerError(-32000), message: \\\"execution reverted\\\", data: None }\"); InvalidResponse(\"Server: 'https://polygon.blockpi.network/v1/rpc/public', error: RPC error: Error { code: ServerError(-32000), message: \\\"execution reverted\\\", data: None }\"); Transport(\"Server: 'https://node.komodo.earth:8080/polygon', response !200: 502 Bad Gateway, <html>..<head><title>502 Bad Gateway</title></head>..<body>..<center><h1>502 Bad Gateway</h1></center>..<hr><center>nginx/1.18.0 (Ubuntu)</center>..</body>..</html>..\"); InvalidResponse(\"Server: 'https://polygon.llamarpc.com/', error: RPC error: Error { code: ServerError(-32000), message: \\\"execution reverted\\\", data: None }\"); ", + "id": null + } + ``` + + #### NotEnoughNftsAmount (trying to send more NFTs than you have) + + ``` + { + "mmrpc": "2.0", + "error": "Not enough NFTs amount with token_address: 0x2953399124f0cbb46d2cbacd8a89cf0599974963 and token_id 110473361632261669912565539602449606788298723469812631769659886404530570536720. Available 1, required 2", + "error_path": "eth", + "error_trace": "eth:897]", + "error_type": "NotEnoughNftsAmount", + "error_data": { + "token_address": "0x2953399124f0cbb46d2cbacd8a89cf0599974963", + "token_id": "110473361632261669912565539602449606788298723469812631769659886404530570536720", + "available": "1", + "required": "2" + }, + "id": null + } + ``` + + + + View the source code at: [https://github.com/KomodoPlatform/komodo-defi-framework/blob/main/mm2src/coins/nft.rs](https://github.com/KomodoPlatform/komodo-defi-framework/blob/main/mm2src/coins/nft.rs) + export const title = "AtomicDEX: Account Balance Tasks"; export const description = "The methods in this document allow tracking of balances across multiple addresses under a specified account index."; diff --git a/filepathSlugs.json b/filepathSlugs.json index c0e1b815..536699d2 100644 --- a/filepathSlugs.json +++ b/filepathSlugs.json @@ -1592,6 +1592,7 @@ "coin-protocol", "coin-protocol-data", "evm-node", + "tokens-request", "utxo-merge-params" ], "src/pages/atomicdex/api/common_structures/index.mdx": [ @@ -1614,7 +1615,12 @@ "rational-value", "sync-status", "sync-status-extended", - "example-3" + "example-3", + "withdraw-fee", + "example-of-eth-type", + "example-of-qrc20-type", + "example-of-tendermint-type", + "example-of-utxo-type" ], "src/pages/atomicdex/api/common_structures/lightning/index.mdx": [ "lightning-network-structures", @@ -1632,7 +1638,12 @@ ], "src/pages/atomicdex/api/common_structures/nfts/index.mdx": [ "non-fungible-token-structures", - "tokens-request" + "nft-info", + "nft-filter", + "nft-transfer", + "nft-transfer-filter", + "nft-metadata", + "withdraw-nft-data" ], "src/pages/atomicdex/api/common_structures/orders/index.mdx": [ "order-structures", @@ -2417,7 +2428,8 @@ "response-error", "examples", "response-success-2", - "response-error-2" + "response-error-2", + "common-komodo-de-fi-sdk-request-response-objects" ], "src/pages/atomicdex/api/v20/message_signing/index.mdx": [ "signing-and-verifying-messages", @@ -2808,6 +2820,75 @@ "response-balance-too-low", "response-transport-error" ], + "src/pages/atomicdex/api/v20-dev/non_fungible_tokens/clear_nft_db/index.mdx": [ + "clear-nft-database", + "request-parameters", + "example-to-clear-binance-smart-chain-and-polygon-nft-data", + "example-to-clear-all-nft-data", + "error-responses", + "unsupported-chain-type" + ], + "src/pages/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_list/index.mdx": [ + "get-a-list-of-nfts", + "request-parameters", + "response-parameters", + "example-with-no-optional-params", + "example-with-optional-limit-and-page-number-params", + "example-with-optional-spam-protection", + "error-responses", + "unsupported-chain-type" + ], + "src/pages/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_metadata/index.mdx": [ + "get-nft-metadata", + "request-parameters", + "response-parameters", + "example", + "error-responses" + ], + "src/pages/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_transfers/index.mdx": [ + "get-a-list-of-nft-transfers", + "request-parameters", + "response-parameters", + "example-with-date-and-send-filters" + ], + "src/pages/atomicdex/api/v20-dev/non_fungible_tokens/index.mdx": [ + "non-fungible-tokens-nfts", + "nft-information-methods", + "nft-transaction-methods" + ], + "src/pages/atomicdex/api/v20-dev/non_fungible_tokens/query_nft_database_tables/index.mdx": [ + "query-nft-database-tables", + "nft-list-tables", + "example-coin-nft-list-table-query", + "nft-transfer-table", + "example-coin-nft-transfer-history-table-query", + "nft-last-scanned-block-table", + "example-scanned-nft-blocks-table-query" + ], + "src/pages/atomicdex/api/v20-dev/non_fungible_tokens/refresh_nft_metadata/index.mdx": [ + "refresh-nft-metadata", + "request-parameters", + "example" + ], + "src/pages/atomicdex/api/v20-dev/non_fungible_tokens/update_nft/index.mdx": [ + "update-nft", + "request-parameters", + "example" + ], + "src/pages/atomicdex/api/v20-dev/non_fungible_tokens/withdraw_nft/index.mdx": [ + "withdraw-nfts", + "request-parameters", + "response-parameters", + "erc-721-withdraw-example", + "erc-1155-withdraw-example", + "erc-1155-withdraw-max-example", + "withdraw-nfts-error-responses", + "invalid-request-missing-field", + "invalid-request-wrong-withdraw-type", + "token-not-found-in-wallet-trying-to-send-nft-you-dont-own", + "transport-error-unable-to-estimate-gas", + "not-enough-nfts-amount-trying-to-send-more-nfts-than-you-have" + ], "src/pages/atomicdex/api/v20-dev/task_account_balance/index.mdx": [ "account-balance-tasks", "init", @@ -3965,8 +4046,6 @@ ], "src/pages/smart-chains/api/control/index.mdx": [ "control", - "getnotarysendmany", - "getiguanajson", "getinfo", "arguments", "response", @@ -4085,10 +4164,7 @@ "activate-mining-with-4-threads", "check-the-setting", "turn-off-generation", - "turning-the-setting-on-via-json-rpc", - "arguments-4", - "response-4", - "examples-4" + "turning-the-setting-on-via-json-rpc" ], "src/pages/smart-chains/api/index.mdx": [ "smart-chain-api" @@ -4454,133 +4530,125 @@ "arguments-30", "response-30", "examples-30", - "opreturn-burn", + "resendwallettransactions", "arguments-31", "response-31", "examples-31", - "command", - "response-32", - "command-2", - "response-33", - "resendwallettransactions", + "sendfrom", "arguments-32", - "response-34", + "response-32", "examples-32", - "sendfrom", + "sendmany", "arguments-33", - "response-35", + "response-33", "examples-33", - "sendmany", + "sendtoaddress", "arguments-34", - "response-36", + "response-34", "examples-34", - "sendtoaddress", + "setaccount", "arguments-35", - "response-37", "examples-35", - "setaccount", + "setpubkey", "arguments-36", + "response-35", "examples-36", - "setpubkey", + "settxfee", "arguments-37", - "response-38", + "response-36", "examples-37", - "settxfee", + "signmessage", "arguments-38", - "response-39", + "response-37", "examples-38", - "signmessage", + "walletlock", "arguments-39", - "response-40", + "response-38", "examples-39", - "walletlock", + "walletpassphrase", "arguments-40", - "response-41", + "response-39", "examples-40", - "walletpassphrase", + "walletpassphrasechange", "arguments-41", - "response-42", + "response-40", "examples-41", - "walletpassphrasechange", + "z-exportkey", "arguments-42", - "response-43", + "response-41", "examples-42", - "z-exportkey", + "z-exportviewingkey", "arguments-43", - "response-44", + "response-42", "examples-43", - "z-exportviewingkey", + "z-exportwallet", "arguments-44", - "response-45", + "response-43", "examples-44", - "z-exportwallet", + "z-getbalance", "arguments-45", - "response-46", + "response-44", "examples-45", - "z-getbalance", + "z-getnewaddress", "arguments-46", - "response-47", + "response-45", "examples-46", - "z-getnewaddress", + "z-getoperationresult", "arguments-47", - "response-48", + "response-46", "examples-47", - "z-getoperationresult", + "z-getoperationstatus", "arguments-48", - "response-49", + "response-47", "examples-48", - "z-getoperationstatus", + "z-gettotalbalance", "arguments-49", - "response-50", + "response-48", "examples-49", - "z-gettotalbalance", + "z-importkey", "arguments-50", - "response-51", + "response-49", "examples-50", - "z-importkey", + "z-importviewingkey", "arguments-51", - "response-52", + "response-50", "examples-51", - "z-importviewingkey", + "z-importwallet", "arguments-52", - "response-53", + "response-51", "examples-52", - "z-importwallet", + "z-listaddresses", "arguments-53", - "response-54", + "response-52", "examples-53", - "z-listaddresses", + "z-listoperationids", "arguments-54", - "response-55", + "response-53", "examples-54", - "z-listoperationids", - "arguments-55", - "response-56", - "examples-55", "z-listreceivedbyaddress", - "arguments-56", + "arguments-55", "result", - "examples-56", + "examples-55", "z-listunspent", - "arguments-57", + "arguments-56", "results", - "examples-57", + "examples-56", "z-mergetoaddress", "the-fromaddresses-array", + "arguments-57", + "response-54", + "examples-57", + "z-sendmany", "arguments-58", - "response-57", + "response-55", "examples-58", - "z-sendmany", + "z-shieldcoinbase", "arguments-59", - "response-58", + "response-56", "examples-59", - "z-shieldcoinbase", - "arguments-60", - "response-59", - "examples-60", "zcbenchmark", - "arguments-61", - "response-60", + "arguments-60", + "response-57", "zcrawjoinsplit", "zcrawkeygen", "zcrawreceive-zcsecretkey-encryptednote", @@ -5571,7 +5639,6 @@ "step-12-experiment-with-the-tokens-antara-module", "step-13-read-the-introduction-to-atomic-dex", "step-14-experiment-with-atomic-swaps", - "step-15-begin-the-advanced-development-tutorial", - "step-16-inspect-komodo-community-bounties" + "step-15-begin-the-advanced-development-tutorial" ] } \ No newline at end of file diff --git a/postman/collections/komodo_defi.postman_collection.json b/postman/collections/komodo_defi.postman_collection.json index 37fdf8c4..de27968c 100644 --- a/postman/collections/komodo_defi.postman_collection.json +++ b/postman/collections/komodo_defi.postman_collection.json @@ -3260,7 +3260,346 @@ "response": [] } ] - }, + }, + { + "name": "Non Fungible Tokens", + "item": [ + { + "name": "get_nft_list", + "event": [ + { + "listen": "prerequest", + "script": { + "exec": [ + "pm.collectionVariables.set(\"userpass\", pm.environment.get(\"userpass\"));", + "" + ], + "type": "text/javascript" + } + } + ], + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"userpass\": \"{{userpass}}\",\n \"method\": \"get_nft_list\",\n \"mmrpc\": \"2.0\",\n \"params\": {\n \"chains\": [\n \"POLYGON\"\n ]\n }\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "{{address}}", + "host": [ + "{{address}}" + ] + }, + "description": "[https://nft-methods.komodo-docs-revamp-2023.pages.dev/en/docs/atomicdex/api/v20-dev/non_fungible_tokens/#get-a-list-of-nfts](https://nft-methods.komodo-docs-revamp-2023.pages.dev/en/docs/atomicdex/api/v20-dev/non_fungible_tokens/#get-a-list-of-nfts)" + }, + "response": [ + { + "name": "Example with optional limit & page_number params", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": " {\n \"userpass\": \"{{userpass}}\",\n \"method\": \"get_nft_list\",\n \"mmrpc\": \"2.0\",\n \"params\": {\n \"chains\": [\n \"BSC\",\n \"POLYGON\"\n ],\n \"limit\": 1,\n \"page_number\": 2\n }\n }", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "{{address}}", + "host": [ + "{{address}}" + ] + }, + "description": "[https://nft-methods.komodo-docs-revamp-2023.pages.dev/en/docs/atomicdex/api/v20-dev/non_fungible_tokens/#get-a-list-of-nfts](https://nft-methods.komodo-docs-revamp-2023.pages.dev/en/docs/atomicdex/api/v20-dev/non_fungible_tokens/#get-a-list-of-nfts)" + }, + "_postman_previewlanguage": "JSON", + "header": null, + "cookie": [], + "body": null + }, + { + "name": "Example with spam protection", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"userpass\": \"{{userpass}}\",\n \"method\": \"get_nft_list\",\n \"mmrpc\": \"2.0\",\n \"params\": {\n \"chains\": [\n \"BSC\",\n \"POLYGON\"\n ],\n \"protect_from_spam\": true,\n \"filters\": {\n \"exclude_spam\": true,\n \"exclude_phishing\": true\n }\n }\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "{{address}}", + "host": [ + "{{address}}" + ] + }, + "description": "[https://nft-methods.komodo-docs-revamp-2023.pages.dev/en/docs/atomicdex/api/v20-dev/non_fungible_tokens/#get-a-list-of-nfts](https://nft-methods.komodo-docs-revamp-2023.pages.dev/en/docs/atomicdex/api/v20-dev/non_fungible_tokens/#get-a-list-of-nfts)" + }, + "_postman_previewlanguage": "JSON", + "header": null, + "cookie": [], + "body": null + } + ] + }, + { + "name": "get_nft_transfers", + "event": [ + { + "listen": "prerequest", + "script": { + "exec": [ + "pm.collectionVariables.set(\"userpass\", pm.environment.get(\"userpass\"));", + "" + ], + "type": "text/javascript" + } + } + ], + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"userpass\": \"{{userpass}}\",\n \"method\": \"get_nft_transfers\",\n \"mmrpc\": \"2.0\",\n \"params\": {\n \"chains\": [\n \"POLYGON\"\n ],\n \"max\": true,\n \"filters\": {\n \"send\": true,\n \"from_date\": 1690890685\n }\n }\n}\n", + "options": { + "raw": { + "language": "text" + } + } + }, + "url": { + "raw": "{{address}}", + "host": [ + "{{address}}" + ] + }, + "description": "[https://nft-methods.komodo-docs-revamp-2023.pages.dev/en/docs/atomicdex/api/v20-dev/non_fungible_tokens/#get-a-list-of-nft-transfers](https://nft-methods.komodo-docs-revamp-2023.pages.dev/en/docs/atomicdex/api/v20-dev/non_fungible_tokens/#get-a-list-of-nft-transfers)" + }, + "response": [] + }, + { + "name": "get_nft_metadata", + "event": [ + { + "listen": "prerequest", + "script": { + "exec": [ + "pm.collectionVariables.set(\"userpass\", pm.environment.get(\"userpass\"));", + "" + ], + "type": "text/javascript" + } + } + ], + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"userpass\": \"{{userpass}}\",\n \"method\": \"get_nft_metadata\",\n \"mmrpc\": \"2.0\",\n \"params\": {\n \"token_address\": \"0x2953399124f0cbb46d2cbacd8a89cf0599974963\",\n \"token_id\": \"110473361632261669912565539602449606788298723469812631769659886404530570536720\",\n \"chain\": \"POLYGON\"\n }\n}", + "options": { + "raw": { + "language": "text" + } + } + }, + "url": { + "raw": "{{address}}", + "host": [ + "{{address}}" + ] + }, + "description": "[https://nft-methods.komodo-docs-revamp-2023.pages.dev/en/docs/atomicdex/api/v20-dev/non_fungible_tokens/#get-nft-metadata](https://nft-methods.komodo-docs-revamp-2023.pages.dev/en/docs/atomicdex/api/v20-dev/non_fungible_tokens/#get-nft-metadata)" + }, + "response": [] + }, + { + "name": "refresh_nft_metadata", + "event": [ + { + "listen": "prerequest", + "script": { + "exec": [ + "pm.collectionVariables.set(\"userpass\", pm.environment.get(\"userpass\"));", + "" + ], + "type": "text/javascript" + } + } + ], + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"userpass\": \"{{userpass}}\",\n \"method\": \"refresh_nft_metadata\",\n \"mmrpc\": \"2.0\",\n \"params\": {\n \"token_address\": \"0x48c75fbf0452fa8ff2928ddf46b0fe7629cca2ff\",\n \"token_id\": \"5\",\n \"chain\": \"POLYGON\",\n \"url\": \"https://moralis-proxy.komodo.earth\",\n \"url_antispam\": \"https://nft.antispam.dragonhound.info\"\n }\n}\n\n", + "options": { + "raw": { + "language": "text" + } + } + }, + "url": { + "raw": "{{address}}", + "host": [ + "{{address}}" + ] + }, + "description": "[https://nft-methods.komodo-docs-revamp-2023.pages.dev/en/docs/atomicdex/api/v20-dev/non_fungible_tokens/#refresh-nft-metadata](https://nft-methods.komodo-docs-revamp-2023.pages.dev/en/docs/atomicdex/api/v20-dev/non_fungible_tokens/#refresh-nft-metadata)" + }, + "response": [] + }, + { + "name": "update_nft", + "event": [ + { + "listen": "prerequest", + "script": { + "exec": [ + "pm.collectionVariables.set(\"userpass\", pm.environment.get(\"userpass\"));", + "" + ], + "type": "text/javascript" + } + } + ], + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"userpass\": \"{{userpass}}\",\n \"method\": \"update_nft\",\n \"mmrpc\": \"2.0\",\n \"params\": {\n \"chains\": [\n \"BSC\",\n \"POLYGON\"\n ],\n \"url\": \"https://moralis-proxy.komodo.earth\",\n \"url_antispam\": \"https://nft.antispam.dragonhound.info\"\n }\n}\n", + "options": { + "raw": { + "language": "text" + } + } + }, + "url": { + "raw": "{{address}}", + "host": [ + "{{address}}" + ] + }, + "description": "[https://nft-methods.komodo-docs-revamp-2023.pages.dev/en/docs/atomicdex/api/v20-dev/non_fungible_tokens/#update-nft](https://nft-methods.komodo-docs-revamp-2023.pages.dev/en/docs/atomicdex/api/v20-dev/non_fungible_tokens/#update-nft)" + }, + "response": [] + }, + { + "name": "withdraw_nft", + "event": [ + { + "listen": "prerequest", + "script": { + "exec": [ + "pm.collectionVariables.set(\"userpass\", pm.environment.get(\"userpass\"));", + "" + ], + "type": "text/javascript" + } + } + ], + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"userpass\": \"{{userpass}}\",\n \"method\": \"withdraw_nft\",\n \"mmrpc\": \"2.0\",\n \"params\": {\n \"type\": \"withdraw_erc721\",\n \"withdraw_data\": {\n \"chain\": \"POLYGON\",\n \"to\": \"0x27Ad1F808c1ef82626277Ae38998AfA539565660\",\n \"token_address\": \"0x73a5299824cd955af6377b56f5762dc3ca4cc078\",\n \"token_id\": \"1\"\n }\n }\n}\n", + "options": { + "raw": { + "language": "text" + } + } + }, + "url": { + "raw": "{{address}}", + "host": [ + "{{address}}" + ] + }, + "description": "[https://nft-methods.komodo-docs-revamp-2023.pages.dev/en/docs/atomicdex/api/v20-dev/non_fungible_tokens/#withdraw-nfts](https://nft-methods.komodo-docs-revamp-2023.pages.dev/en/docs/atomicdex/api/v20-dev/non_fungible_tokens/#withdraw-nfts)" + }, + "response": [] + }, + { + "name": "withdraw_nft (erc1155)", + "event": [ + { + "listen": "prerequest", + "script": { + "exec": [ + "pm.collectionVariables.set(\"userpass\", pm.environment.get(\"userpass\"));", + "" + ], + "type": "text/javascript" + } + } + ], + "request": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"userpass\": \"{{userpass}}\",\n \"method\": \"withdraw_nft\",\n \"mmrpc\": \"2.0\",\n \"params\": {\n \"type\": \"withdraw_erc1155\",\n \"withdraw_data\": {\n \"chain\": \"POLYGON\",\n \"to\": \"0x27Ad1F808c1ef82626277Ae38998AfA539565660\",\n \"token_address\": \"0x2953399124f0cbb46d2cbacd8a89cf0599974963\",\n \"token_id\": \"110473361632261669912565539602449606788298723469812631769659886404530570536720\",\n \"amount\": \"1\"\n }\n }\n}", + "options": { + "raw": { + "language": "text" + } + } + }, + "url": { + "raw": "{{address}}", + "host": [ + "{{address}}" + ] + }, + "description": "[https://nft-methods.komodo-docs-revamp-2023.pages.dev/en/docs/atomicdex/api/v20-dev/non_fungible_tokens/#erc-1155-withdraw-example](https://nft-methods.komodo-docs-revamp-2023.pages.dev/en/docs/atomicdex/api/v20-dev/non_fungible_tokens/#erc-1155-withdraw-example)" + }, + "response": [ + { + "name": "erc1155", + "originalRequest": { + "method": "POST", + "header": [], + "body": { + "mode": "raw", + "raw": "{\n \"userpass\": \"{{userpass}}\",\n \"method\": \"withdraw_nft\",\n \"mmrpc\": \"2.0\",\n \"params\": {\n \"withdraw_type\": {\n \"type\": \"withdraw_erc721\",\n \"withdraw_data\": {\n \"chain\": \"BSC\",\n \"to\": \"0x6FAD0eC6bb76914b2a2a800686acc22970645820\",\n \"token_address\": \"0xfd913a305d70a60aac4faac70c739563738e1f81\",\n \"token_id\": \"214300044414\"\n }\n }\n }\n}\n", + "options": { + "raw": { + "language": "text" + } + } + }, + "url": { + "raw": "{{address}}", + "host": [ + "{{address}}" + ] + } + }, + "_postman_previewlanguage": null, + "header": null, + "cookie": [], + "body": null + } + ] + } + ] + }, { "name": "Wallet", "item": [ diff --git a/src/data/sidebar.json b/src/data/sidebar.json index ab87bb99..13a9912d 100644 --- a/src/data/sidebar.json +++ b/src/data/sidebar.json @@ -409,6 +409,47 @@ } ] }, + { + "title": "Non-Fungible Tokens", + "links": [ + { + "title": "Overview", + "href": "/atomicdex/api/v20-dev/non_fungible_tokens/" + }, + { + "title": "Clear NFT Database Tables", + "href": "/atomicdex/api/v20-dev/non_fungible_tokens/clear_nft_db/" + }, + { + "title": "Query NFT Database Tables", + "href": "/atomicdex/api/v20-dev/non_fungible_tokens/query_nft_database_tables/" + }, + { + "title": "Get NFT List", + "href": "/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_list/" + }, + { + "title": "Get NFT Transactions", + "href": "/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_transfers/" + }, + { + "title": "Get NFT Metadata", + "href": "/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_metadata/" + }, + { + "title": "Refresh NFT Metadata", + "href": "/atomicdex/api/v20-dev/non_fungible_tokens/refresh_nft_metadata/" + }, + { + "title": "Update NFT", + "href": "/atomicdex/api/v20-dev/non_fungible_tokens/update_nft/" + }, + { + "title": "Withdraw NFT", + "href": "/atomicdex/api/v20-dev/non_fungible_tokens/withdraw_nft/" + } + ] + }, { "title": "Lightning Network", "links": [ diff --git a/src/pages/atomicdex/api/common_structures/activation/index.mdx b/src/pages/atomicdex/api/common_structures/activation/index.mdx index 7173e9f7..f6d305cb 100644 --- a/src/pages/atomicdex/api/common_structures/activation/index.mdx +++ b/src/pages/atomicdex/api/common_structures/activation/index.mdx @@ -7,10 +7,6 @@ export const description = "The Komodo DeFi SDK uses a variety of activation met The `ActivationParams` object defines additional parameters used for activation. These params may vary depending on the coin type. -The following methods use this structure: - -* TBA - | Parameter | Type | Description | | ---------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | required\_confirmations | integer | Optional. Confirmations to wait for steps in swap. Defaults to value in the coins file if not set. | @@ -40,10 +36,6 @@ The following methods use this structure: Defines the activation mode for QTUM, BCH, UTXO & ZHTLC coins. -The following methods use this structure: - -* TBA - | Parameter | Type | Description | | --------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | rpc | string | `Native` if running a native blockchain node, `Electrum` if using electrum servers or `Light` for ZHTLC coins. | @@ -66,10 +58,6 @@ Contains information about electrum & lightwallet\_d servers for coins being use ### ActivationServers -The following methods use this structure: - -* TBA - Contains information electrum servers for coins being used in `Electrum` or `Light` mode. | Parameter | Type | Description | @@ -141,7 +129,7 @@ Contains information electrum servers for coins being used in `Electrum` or `Lig | Parameter | Type | Description | | -------------- | ------- | ------------------------------------------------------------------------------------------------------ | -| type | integer | One of the supported \[coin types]\(link TBA) | +| type | integer | One of the Coin Types supported by the Komodo DeFi Framework | | protocol\_data | object | A standard [CoinProtocolData](/atomicdex/api/common_structures/activation/#coin-protocol-data) object. | ### CoinProtocolData @@ -170,6 +158,24 @@ The `EvmNode` object includes the following items for a given coin or token: ``` +### TokensRequest + +The `TokensRequest` object includes the following items for a given coin or token: + +| Parameter | Type | Description | +| ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ | +| ticker | string | Ticker of the token to be enabled | +| required\_confirmations | integer | How many confirmations to wait during the transaction steps of an atomic swap. Overwrites value in coins file; defaults to `3` | + + + ```json + { + "ticker": "MINDS-ERC20", + "required_confirmations": 4 + } + ``` + + ### UtxoMergeParams The `UtxoMergeParams` object defines how often and at which thresholds to merge UTXOs. This is useful for wallets which have been used for a long time, and have many small UTXOs from mining activity. diff --git a/src/pages/atomicdex/api/common_structures/index.mdx b/src/pages/atomicdex/api/common_structures/index.mdx index 214ae99c..f80a2e2d 100644 --- a/src/pages/atomicdex/api/common_structures/index.mdx +++ b/src/pages/atomicdex/api/common_structures/index.mdx @@ -331,3 +331,66 @@ The `numerator` and `denominator` are BigInteger numbers represented as a sign a } ``` + +### 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 + + ```json + { + "type": "Eth", + "coin": "BNB", + "gas": 109739, + "gas_price": "0.000000003", + "total_fee": "0.000329217" + } + ``` + + #### Example of Qrc20 type + + ```json + { + "type": "Qrc20", + "coin": "tQTUM", + "miner_fee": "0.00000447", + "gas_limit": 100000, + "gas_price": 40, + "total_gas_fee": "0.04" + } + ``` + + #### Example of Tendermint type + + ```json + { + "type": "Tendermint", + "coin": "IRIS", + "amount": "0.038553", + "gas_limit": 100000 + } + ``` + + #### Example of Utxo type + + ```json + { + "type": "Utxo", + "amount": "0.00001" + } + ``` + diff --git a/src/pages/atomicdex/api/common_structures/lightning/index.mdx b/src/pages/atomicdex/api/common_structures/lightning/index.mdx index a9d598c6..b108d8bd 100644 --- a/src/pages/atomicdex/api/common_structures/lightning/index.mdx +++ b/src/pages/atomicdex/api/common_structures/lightning/index.mdx @@ -140,17 +140,17 @@ It is used for estimating the transaction fee rate (`feerate`) for different tra ### LightningPaymentFilter -| Parameter | Type | Description | -| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------- | -| payment\_type | object | A standard `LightningPaymentType` object. | -| description | string | Optional. A note to indicate the purpose of the invoice. | -| status | string | Optional. Accepted values: `pending`, `succeeded`, `failed`. | -| from\_amount\_msat | integer | Optional. Minimum amount sent in [millisatoshis](https://bitcoindata.science/bitcoin-units-converter) | -| to\_amount\_msat | integer | Optional. Maximum amount sent in [millisatoshis](https://bitcoindata.science/bitcoin-units-converter) | -| from\_fee\_paid\_msat | integer | Optional. Minimum transaction fee paid in [millisatoshis](https://bitcoindata.science/bitcoin-units-converter) | -| to\_fee\_paid\_msat | integer | Optional. Maximum transaction fee paid in [millisatoshis](https://bitcoindata.science/bitcoin-units-converter) | -| from\_timestamp | string | Optional. Minimum timestamp (in milliseconds) of payment results to return. | -| to\_timestamp | string | Optional. Maximum timestamp (in milliseconds) of payment results to return. | +| Parameter | Type | Description | +| --------------------- | ------- | ----------------------------------------------------------------------------------------------------------------- | +| payment\_type | object | A standard `LightningPaymentType` object. | +| description | string | Optional. A note to indicate the purpose of the invoice. | +| status | string | Optional. Accepted values: `pending`, `succeeded`, `failed`. | +| from\_amount\_msat | integer | Optional. Minimum amount sent in [millisatoshis](https://bitcoindata.science/bitcoin-units-converter) | +| to\_amount\_msat | integer | Optional. Maximum amount sent in [millisatoshis](https://bitcoindata.science/bitcoin-units-converter) | +| from\_fee\_paid\_msat | integer | Optional. Minimum transaction fee paid in [millisatoshis](https://bitcoindata.science/bitcoin-units-converter) | +| to\_fee\_paid\_msat | integer | Optional. Maximum transaction fee paid in [millisatoshis](https://bitcoindata.science/bitcoin-units-converter) | +| from\_timestamp | string | Optional. Minimum timestamp in [unix epoch format](https://www.epochconverter.com/) of payment results to return. | +| to\_timestamp | string | Optional. Maximum timestamp in [unix epoch format](https://www.epochconverter.com/) of payment results to return. | ### LightningPaymentType diff --git a/src/pages/atomicdex/api/common_structures/nfts/index.mdx b/src/pages/atomicdex/api/common_structures/nfts/index.mdx index 2cdde778..b3c21f0c 100644 --- a/src/pages/atomicdex/api/common_structures/nfts/index.mdx +++ b/src/pages/atomicdex/api/common_structures/nfts/index.mdx @@ -3,14 +3,98 @@ export const description = "Starting with version beta-2.1.3434, the Komodo DeFi # Non-Fungible Token Structures -### TokensRequest +The following structures are used in the Komodo DeFi SDK for non-fungible tokens (NFTs). -The `TokensRequest` object includes the following items for a given coin or token: +### NftInfo -| Parameter | Type | Description | -| ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ | -| ticker | string | Ticker of the token to be enabled | -| required\_confirmations | integer | How many confirmations to wait during the transaction steps of an atomic swap. Overwrites value in coins file; defaults to `3` | +The `NftInfo` object includes the following items for a given token: + +| Parameter | Type | Description | +| ---------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| amount | string | The amount of this NFT the user owns (used by `ERC1155`). | +| block\_number\_minted | integer | The block height when the NFT was minted. May be `null`. | +| block\_number | integer | The block height when the amount or owner changed. | +| chain | string | Chain name. One of `AVALANCHE`, `BSC`, `ETH`, `FANTOM`, or `POLYGON`. | +| name | string | May be `null`. An NFT collection name. | +| contract\_type | string | The type of NFT contract standard. One of `ERC721` or `ERC1155`. | +| last\_token\_uri\_sync | string | When the token\_uri was last updated. | +| last\_metadata\_sync | string | When the metadata was last updated. | +| metadata | string | The metadata of the token. May be `null`. | +| minter\_address | string | Minter address. May be `null`. | +| owner\_of | string | The wallet address of the owner of the NFT. | +| possible\_spam | boolean | If `true`, the contract address has [been identified](https://docs.moralis.io/web3-data-api/evm/nft-spam-detection) as associated with spam or suspicious activities. | +| possible\_phishing | boolean | If `true`, the token has been identified as associated with phishing, as at least one of domain fields is found in database with phishing domains. | +| symbol | string | May be `null`. The symbol of the NFT contract. | +| token\_address | string | The address of the NFT contract. | +| token\_id | string | The token ID of the NFT. | +| token\_hash | string | The token hash. May be `null`. | +| token\_uri | string | The URI to the metadata of the token. May be `null`. | +| token\_domain | string | Token domain. May be `null`. | +| uri\_meta | object | A standard [NftMetadata](/atomicdex/api/common_structures/nfts/#nft-metadata) object. | + +### NftFilter + +The `NftFilter` object includes the following items for a given coin or token: + +| Parameter | Type | Description | +| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ | +| exclude\_spam | boolean | Optional, defaults to `false`. If `true`, only tokens which have param `possible_spam:false` are included in the response. | +| exclude\_phishing | boolean | Optional, defaults to `false`. If `true`, only tokens which have param `possible_phishing:false` are included in the response. | + +### NftTransfer + +The `NftTransfer` object includes the following items for each token transaction: + +| Parameter | Type | Description | +| ------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| amount | string | Amount of tokens transferred. | +| block\_hash | string | May be `null`. Hash of block in which transfer occurred. | +| block\_number | integer | Height of block in which transfer occurred. | +| block\_timestamp | integer | Block time in [unix epoch format](https://www.epochconverter.com/). | +| chain | string | Chain name. One of `AVALANCHE`, `BSC`, `ETH`, `FANTOM`, or `POLYGON`. | +| token\_uri | string | May be `null`. The URI to the metadata of the token. | +| token\_domain | string | May be `null`. Extracted domain from the `token_uri`, if valid. | +| collection\_name | string | May be `null`. Name of collection which token belongs to. | +| image\_url | string | May be `null`. The URI to the token image. | +| image\_domain | string | May be `null`. Extracted domain from the `image_url`, if valid. | +| token\_name | string | May be `null`. Name of the token. | +| contract\_type | string | Contract type. `ERC721` or `ERC1155`. | +| token\_address | string | Address of token transferred. | +| token\_id | string | Token ID. | +| possible\_spam | boolean | If `true`, the contract address has [been identified](https://docs.moralis.io/web3-data-api/evm/nft-spam-detection) as associated with spam or suspicious activities. | +| possible\_phishing | boolean | If `true`, the token has been identified as associated with phishing, as at least one of domain fields is found in database with phishing domains. | +| transaction\_hash | string | Transaction ID of the transfer. | +| transaction\_index | string | May be `null`. Transaction index of the transfer. | +| log\_index | string | Log index of the transfer. | +| value | string | May be `null`. Tranfer value. | +| transaction\_type | string | May be `null`. Transaction type. Possible values are `Single`. | +| from\_address | string | Address of previous owner which sent the token(s). | +| to\_address | string | Address of new owner which received the token(s). | +| status | string | Transfer status. Will be either `Send` or `Receive`. When the `from_address` and `to_address` are the same (i.e. sending to yourself), this value will be `Receive`. | +| verified | integer | May be `null`. A deprecated field which will be removed in future. | +| operator | string | May be `null`. | +| fee\_details | object | Optional. A standard [FeeInfo](/atomicdex/api/common_structures//#fee-info) object. | +| confirmations | integer | The count of blocks produced since this transaction was confirmed. | + + + `verified` has no description. Related to [https://cointelegraph.com/news/nft-whale-pranksy-pranked-by-fake-banksy-for-97-7-eth](https://cointelegraph.com/news/nft-whale-pranksy-pranked-by-fake-banksy-for-97-7-eth)? Who verifies it? I can see there are ways to verify on opensea etc, I assume Moralis incormoprates this. + What are the other possible values for `transaction_type`? + What is `operator`? + What does `verified` mean? + + +### NftTransferFilter + +The `NftTransferFilter` object includes the following items for a transfer of given coin or token: + +| Parameter | Type | Description | +| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| receive | boolean | Optional, defaults to `false`. If `true`, only transfers where user received NFTs are included in the response. | +| send | boolean | Optional, defaults to `false`. If `true`, only transfers where user sent NFTs are included in the response. | +| from\_date | integer | Optional. A timestamp in [unix epoch format](https://www.epochconverter.com/). If `true`, filter includes transfers from this date onwards (inclusive). | +| to\_date | integer | Optional. A timestamp in [unix epoch format](https://www.epochconverter.com/). If `true`, filter includes transfers up to this date (inclusive). | +| exclude\_spam | boolean | Optional, defaults to `false`. If `true`, only transfers which have param `possible_spam:false` are included in the response. | +| exclude\_phishing | boolean | Optional, defaults to `false`. If `true`, only transfers which have param `possible_phishing:false` are included in the response. | ```json @@ -20,3 +104,96 @@ The `TokensRequest` object includes the following items for a given coin or toke } ``` + +### NftMetadata + +The `NftMetadata` object includes the following items for a given coin or token: + +| Parameter | Type | Description | +| ----------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| image | string | Optional. Direct URL to the NFT's image. | +| image\_url | string | Optional. Optional. Url to the NFT's image. Derived from the `image` or `image_url` fields to prioritize the non-null value. Can be null if neither is provided. | +| image\_domain | string | Optional. Extracted domain from the 'image\_url', if valid. | +| name | string | Optional. Name of the token. | +| description | string | Optional. Description of the token. | +| attributes | object or array of objects | Optional. The values within this parameter will vary, and are set by the creator. Often used to store traits. | +| animation\_url | string | Optional. Url to an animation to be displayed instead of a static image. | +| animation\_domain | string | Optional. Extracted domain from the `animation_url`, if valid. | +| external\_url | string | Optional. URL to the external source related to the token. | +| external\_domain | string | Optional. Extracted domain from the `external_url`, if valid. | +| image\_details | object | Optional. JSON containing additional details or attributes of the image. | + + + ```json + [ + { + "trait_type": "Specialization", + "value": "Thief" + }, + { + "trait_type": "Skin Tone", + "value": "#0013b0" + }, + { + "trait_type": "Weapon", + "value": "Crossbow" + }, + { + "trait_type": "Species", + "value": "Dark Elf" + }, + { + "trait_type": "Gender", + "value": "Female" + }, + { + "trait_type": "Strength", + "value": "8" + }, + { + "trait_type": "Dexterity", + "value": "12" + }, + { + "trait_type": "Intelligence", + "value": "10" + }, + { + "trait_type": "Perks", + "value": ["Steath", "Eagle Eye", "Lockpicking", "Pickpocketing", "Fire resistance"] + }, + { + "trait_type": "Weakness", + "value": ["Slow healing", "Elfbark Addict", "Lockpicking", "Fear of cats", "Unconvincing liar"] + }, + { + "trait_type": "Personality", + "value": "Aggressive" + } + ] + ``` + + +### WithdrawNftData + +The `WithdrawNftData` object is used for withdrawals of NFTs on ERC721 and ERC1155 contracts. It includes the following items for a given coin or token: + +| Parameter | Type | Description | +| -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| chain | string | The token chain. Chain must be [activated](/atomicdex/api/legacy/coin_activation/) first. | +| to | string | Destination address to withdraw the token to. | +| token\_address | string | Token address. | +| token\_id | string | Token ID. | +| fee | object | A standard [WithdrawFee](/atomicdex/api/common_structures/#withdraw-fee) object. May be missing for older transfers. | +| amount | string | Optional, ERC1155 only. Defaults to `1`. Amount of NFTs to withdraw. Ignored if `max` is true. | +| max | boolean | Optional, ERC1155 only. Defaults to `false`. If `true`, amount parameter will be ignored and all NFTs with this `token_id` will be sent. | + + + When the `type` parameter in a [withdraw\_nft](/atomicdex/api/v20-dev/non_fungible_tokens/withdraw_nft/) request is `withdraw_erc721`, it means the NFT is absolutely unique, + and it has only 1 owner and the owner can own only 1 NFT with this `token_id` + in its `token_address` (also referred to as contract address). + When the `type` parameter in a [withdraw\_nft](/atomicdex/api/v20-dev/non_fungible_tokens/withdraw_nft/) request is `withdraw_erc1155`, it means that it is possible for more + than 1 user to own one or more of the same NFT (with an identical `token_id`). + Due to this difference, the `amount` and `max` fields are only used the when + the `type` value is `withdraw_erc1155`. + diff --git a/src/pages/atomicdex/api/index.mdx b/src/pages/atomicdex/api/index.mdx index 25483716..8664fc20 100644 --- a/src/pages/atomicdex/api/index.mdx +++ b/src/pages/atomicdex/api/index.mdx @@ -22,6 +22,7 @@ Below is a table of the currently available legacy, v2.0 and v2.0 (Dev) methods: | | | [can\_get\_new\_address](/atomicdex/api/v20-dev/hd_address_management/#can-get-new-address) | | [cancel\_all\_orders](/atomicdex/api/legacy/cancel_all_orders/#cancel-all-orders) | | | | [cancel\_order](/atomicdex/api/legacy/cancel_order/#cancel-order) | | | +| | | [clear\_nft\_db](/atomicdex/api/v20-dev/non_fungible_tokens/clear_nft_db/#clear-nft-database) | | | | [close\_channel](/atomicdex/api/v20-dev/lightning/channels/#close-channel) | | [coins\_needed\_for\_kick\_start](/atomicdex/api/legacy/coins_needed_for_kick_start/#coins-needed-for-kick-start) | | | | [convert\_utxo\_address](/atomicdex/api/legacy/convert_utxo_address/#convert-utxo-address) | | | @@ -45,6 +46,9 @@ Below is a table of the currently available legacy, v2.0 and v2.0 (Dev) methods: | | | [get\_locked\_amount](/atomicdex/api/v20-dev/get_locked_amount/#get-locked-amount) | | [get\_my\_peer\_id](/atomicdex/api/legacy/get_my_peer_id/#get-my-peer-id) | | | | | | [get\_new\_address](/atomicdex/api/v20-dev/hd_address_management/#get-new-address) | +| | | [get\_nft\_list](/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_list/#get-a-list-of-nfts) | +| | | [get\_nft\_metadata](/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_metadata/#get-nft-metadata) | +| | | [get\_nft\_transfers](/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_transfers/#get-a-list-of-nft-transfers) | | [get\_peers\_info](/atomicdex/api/legacy/get_peers_info/#get-peers-info) | | | | | [get\_public\_key](/atomicdex/api/v20/get_public_key/#get-public-key) | | | | [get\_public\_key\_hash](/atomicdex/api/v20/get_public_key_hash/#get-public-key-hash) | | @@ -81,6 +85,7 @@ Below is a table of the currently available legacy, v2.0 and v2.0 (Dev) methods: | [orders\_history\_by\_filter](/atomicdex/api/legacy/orders_history_by_filter/#orders-history-by-filter) | | | | [recover\_funds\_of\_swap](/atomicdex/api/legacy/recover_funds_of_swap/#recover-funds-of-swap) | | | | | [recreate\_swap\_data](/atomicdex/api/v20/recreate_swap_data/#recreate-swap-data) | | +| | | [refresh\_nft\_metadata](/atomicdex/api/v20-dev/non_fungible_tokens/refresh_nft_metadata/#refresh-nft-metadata) | | | [remove\_delegation](/atomicdex/api/v20/remove_delegation/#remove-delegation) | | | | [remove\_node\_from\_version\_stat](/atomicdex/api/v20/remove_node_from_version_stat/#remove-node-from-version-stat) | | | [sell](/atomicdex/api/legacy/sell/#sell) | | | @@ -120,9 +125,11 @@ Below is a table of the currently available legacy, v2.0 and v2.0 (Dev) methods: | [unban\_pubkeys](/atomicdex/api/legacy/unban_pubkeys/#unban-pubkeys) | | | | | | [update\_channel](/atomicdex/api/v20-dev/lightning/channels/#update-channel) | | [update\_maker\_order](/atomicdex/api/legacy/update_maker_order/#update-maker-order) | | | +| | | [update\_nft](/atomicdex/api/v20-dev/non_fungible_tokens/update_nft/#update-nft) | | | [update\_version\_stat\_collection](/atomicdex/api/v20/update_version_stat_collection/#update-version-stat-collection) | | | [validateaddress](/atomicdex/api/legacy/validateaddress/#validateaddress) | | | | | [verify\_message](/atomicdex/api/v20/message_signing/#verify-message) | | | [version](/atomicdex/api/legacy/version/#version) | | | | [withdraw](/atomicdex/api/legacy/withdraw/#withdraw) | [withdraw](/atomicdex/api/v20/withdraw/#withdraw) | | +| | | [withdraw\_nft](/atomicdex/api/v20-dev/non_fungible_tokens/withdraw_nft/#withdraw-nfts) | | | | [z\_coin\_tx\_history](/atomicdex/api/v20-dev/task_enable_z_coin/#z-coin-transaction-history) | diff --git a/src/pages/atomicdex/api/v20-dev/non_fungible_tokens/clear_nft_db/index.mdx b/src/pages/atomicdex/api/v20-dev/non_fungible_tokens/clear_nft_db/index.mdx new file mode 100644 index 00000000..e22b7d3f --- /dev/null +++ b/src/pages/atomicdex/api/v20-dev/non_fungible_tokens/clear_nft_db/index.mdx @@ -0,0 +1,90 @@ +export const title = "AtomicDEX: Non Fungible Tokens"; +export const description = + "This document describes the clear_nft_db method AtomicDEX-API provides to clear NFT data from your local database"; + +# Clear NFT Database {{label : 'clear_nft_db', tag : 'API-v2'}} + +This method will clear the NFT database data stored in the local database for selected (or all) networks. + +### Request Parameters + +| Parameter | Type | Description | +| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------ | +| clear\_all | boolean | Defaults to `false`. If `true` all NFT data for all networks will be purged. | +| chains | array | Optional. List of networks to remove NFT data for. Options are: `POLYGON`, `FANTOM`, `ETH`, `BSC`, or `AVALANCHE`. | + + + You can confirm the NFT database has been cleared by querying the `KOMODEFI.db` database file. + For more information, refer to the [Query NFT Database Tables](/atomicdex/api/v20-dev/non_fungible_tokens/query_nft_database_tables) documentation. + + +#### ๐Ÿ“Œ Example to clear Binance Smart chain and Polygon NFT data + + + ```json + { + "userpass": "testpsw", + "method": "clear_nft_db", + "mmrpc": "2.0", + "params": { + "chains": [ + "POLYGON", + "BSC" + ] + } + } + ``` + + + + ```json + { + "mmrpc": "2.0", + "result": null, + "id": null + } + ``` + + +#### ๐Ÿ“Œ Example to clear all NFT data + + + ```json + { + "userpass": "testpsw", + "method": "clear_nft_db", + "mmrpc": "2.0", + "params": { + "clear_all": true + } + } + ``` + + + + ```json + { + "mmrpc": "2.0", + "result": null, + "id": null + } + ``` + + +### Error responses + +#### UnsupportedChainType + +Returned when the `chains` parameter contains an unsupported network. + +```json +{ + "mmrpc": "2.0", + "error": "Error parsing request: UnsupportedChainType", + "error_path": "dispatcher", + "error_trace": "dispatcher:110]", + "error_type": "InvalidRequest", + "error_data": "UnsupportedChainType", + "id": null +} +``` diff --git a/src/pages/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_list/index.mdx b/src/pages/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_list/index.mdx new file mode 100644 index 00000000..8c0f521d --- /dev/null +++ b/src/pages/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_list/index.mdx @@ -0,0 +1,323 @@ +export const title = "AtomicDEX: Non Fungible Tokens - Get NFT List"; +export const description = + "This document describes all the get_nft_list method AtomicDEX-API provides to get a list of your wallets NFTs"; + +# Get a list of NFTs {{label : 'get_nft_list', tag : 'API-v2'}} + +Returns a list of the NFTs owned by the user, shown in descending order of the `block_number` value (the block height when the amount or owner changed). If the request is for NFTs on more than one chain, this means that the order may not be chronological. In the case of ERC1155 tokens, the `block_number` will update when additional NFTs are received or when all NFTs are withdrawn, but will generally remain the same if only some NFTs are withdrawn. + + + Before using this method, you must first call the [update\_nft](/atomicdex/api/v20-dev/non_fungible_tokens/update_nft/) + method to populate/refresh the local database. + + +### Request Parameters + +| Parameter | Type | Description | +| ------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| chains | array | List of networks to scan for NFTs. Options are: `POLYGON`, `FANTOM`, `ETH`, `BSC`, or `AVALANCHE`. | +| max | boolean | Optional, defaults to `false`. If `true`, response will return all NFTs without pagination, and will ignore the `limit` and `page_number` values. | +| limit | integer | Optional, defaults to `10`. The number of NFTs displayed per page in response. | +| page\_number | integer | Optional, defaults to `1`. The page offset for items in response. | +| protect\_from\_spam | boolean | Optional, defaults to `false`. If `true`, any potential spam link found in collection name, token name, symbol will be replaced with `URL redacted for user protection` | +| filters | object | Optional. A standard [NftFilter](/atomicdex/api/common_structures/nfts/#nft-filter) object. | + +### Response Parameters + +| Parameter | Type | Description | +| --------- | --------------- | -------------------------------------------------------------------------------------- | +| nfts | list of objects | A list of standard [NftInfo](/atomicdex/api/common_structures/nfts/#nft-info) objects. | +| total | integer | The total number of NFTs in your wallet matching the request filters. | +| skipped | integer | The number of NFTs in your wallet excluded by the request filters. | + +#### ๐Ÿ“Œ Example with no optional params + + + ```json + { + "userpass": "testpsw", + "method": "get_nft_list", + "mmrpc": "2.0", + "params": { + "chains": [ + "BSC", + "POLYGON" + ] + } + } + ``` + + + + ```json + { + "mmrpc": "2.0", + "result": { + "nfts": [ + { + "chain": "BSC", + "token_address": "0x5c7d6712dfaf0cb079d48981781c8705e8417ca0", + "token_id": "0", + "amount": "1", + "owner_of": "0xf622a6c52c94b500542e2ae6bcad24c53bc5b6a2", + "token_hash": "b34ddf294013d20a6d70691027625839", + "block_number_minted": 25465916, + "block_number": 25919780, + "contract_type": "ERC1155", + "name": null, + "symbol": null, + "token_uri": "https://tikimetadata.s3.amazonaws.com/tiki_box.json", + "token_domain": "tikimetadata.s3.amazonaws.com", + "metadata": "{\"name\":\"Tiki box\",\"description\":\"Born to usher in Bull markets. Tiki JumpStarters are crazed guardians that worship NGU technology. Tiki guardians attach themselves to their owners to guide and protect them from the evils of the crypto industry. Manifested by the power of community and infused with unlimited creativity, the Unlockable Road Map summons powerful gifts and surprises to all Tiki Holders. Booyaaah!!\",\"external_url\":\"\",\"image\":\"https://tikimetadata.s3.amazonaws.com/tiki_box.png\",\"attributes\":[{\"trait_type\":\"Crypto Logo\",\"value\":\"TIKI NFT CRYPTOLOGO SCAR\"}],\"properties\":{\"category\":\"image\",\"creators\":[]}}", + "last_token_uri_sync": "2023-02-07T17:10:08.402Z", + "last_metadata_sync": "2023-02-07T17:10:16.858Z", + "minter_address": "ERC1155 tokens don't have a single minter", + "possible_spam": false, + "possible_phishing": false, + "uri_meta": { + "image": "https://tikimetadata.s3.amazonaws.com/tiki_box.png", + "image_url": "https://tikimetadata.s3.amazonaws.com/tiki_box.png", + "image_domain": "tikimetadata.s3.amazonaws.com", + "name": "Tiki box", + "description": "Born to usher in Bull markets. Tiki JumpStarters are crazed guardians that worship NGU technology. Tiki guardians attach themselves to their owners to guide and protect them from the evils of the crypto industry. Manifested by the power of community and infused with unlimited creativity, the Unlockable Road Map summons powerful gifts and surprises to all Tiki Holders. Booyaaah!!", + "attributes": [ + { + "trait_type": "Crypto Logo", + "value": "TIKI NFT CRYPTOLOGO SCAR" + } + ], + "animation_url": null, + "animation_domain": null, + "external_url": "", + "external_domain": null, + "image_details": null + } + }, + { + "chain": "POLYGON", + "token_address": "0x48c75fbf0452fa8ff2928ddf46b0fe7629cca2ff", + "token_id": "5", + "amount": "1", + "owner_of": "0xf622a6c52c94b500542e2ae6bcad24c53bc5b6a2", + "token_hash": "28f970585fd743b056859a6e41f50a8e", + "block_number_minted": 36781490, + "block_number": 42491885, + "contract_type": "ERC1155", + "name": null, + "symbol": null, + "token_uri": "https://app.thesmurfssociety.com/metadata/public/metadata/cauldron/5", + "token_domain": "app.thesmurfssociety.com", + "metadata": "{\"name\":\"Forest Mushrooms\",\"description\":\"Sweet and nutty with distinct earthy tones, these forest mushrooms will make a fine addition to all your soups, salads, and potions.\",\"image\":\"https://metadata.thesmurfssociety.com/ingredients/nft/5.Forest_Mushrooms.jpg\",\"animation_url\":null,\"external_url\":\"https://app.thesmurfssociety.com/detail/ingredients/5\",\"attributes\":[{\"trait_type\":\"Type\",\"value\":\"Ingredient\"},{\"trait_type\":\"Category\",\"value\":\"COMMON\"}]}", + "last_token_uri_sync": "2022-12-13T13:12:50.840Z", + "last_metadata_sync": "2023-05-15T07:30:04.882Z", + "minter_address": "ERC1155 tokens don't have a single minter", + "possible_spam": false, + "possible_phishing": false, + "uri_meta": { + "image": "https://metadata.thesmurfssociety.com/ingredients/nft/5.Forest_Mushrooms.jpg", + "image_url": "https://metadata.thesmurfssociety.com/ingredients/nft/5.Forest_Mushrooms.jpg", + "image_domain": "metadata.thesmurfssociety.com", + "name": "Forest Mushrooms", + "description": "Sweet and nutty with distinct earthy tones, these forest mushrooms will make a fine addition to all your soups, salads, and potions.", + "attributes": [ + { + "trait_type": "Type", + "value": "Ingredient" + }, + { + "trait_type": "Category", + "value": "COMMON" + } + ], + "animation_url": null, + "animation_domain": null, + "external_url": "https://app.thesmurfssociety.com/detail/ingredients/5", + "external_domain": "app.thesmurfssociety.com", + "image_details": null + } + } + ], + "skipped": 0, + "total": 2 + }, + "id": null + } + ``` + + +#### ๐Ÿ“Œ Example with optional limit & page\_number params + + + ```json + { + "userpass": "testpsw", + "method": "get_nft_list", + "mmrpc": "2.0", + "params": { + "chains": [ + "BSC", + "POLYGON" + ], + "limit": 1, + "page_number": 2 + } + } + ``` + + + + ```json + { + "mmrpc": "2.0", + "result": { + "nfts": [ + { + "chain": "POLYGON", + "token_address": "0x48c75fbf0452fa8ff2928ddf46b0fe7629cca2ff", + "token_id": "5", + "amount": "1", + "owner_of": "0xf622a6c52c94b500542e2ae6bcad24c53bc5b6a2", + "token_hash": "28f970585fd743b056859a6e41f50a8e", + "block_number_minted": 36781490, + "block_number": 42491885, + "contract_type": "ERC1155", + "name": null, + "symbol": null, + "token_uri": "https://app.thesmurfssociety.com/metadata/public/metadata/cauldron/5", + "token_domain": "app.thesmurfssociety.com", + "metadata": "{\"name\":\"Forest Mushrooms\",\"description\":\"Sweet and nutty with distinct earthy tones, these forest mushrooms will make a fine addition to all your soups, salads, and potions.\",\"image\":\"https://metadata.thesmurfssociety.com/ingredients/nft/5.Forest_Mushrooms.jpg\",\"animation_url\":null,\"external_url\":\"https://app.thesmurfssociety.com/detail/ingredients/5\",\"attributes\":[{\"trait_type\":\"Type\",\"value\":\"Ingredient\"},{\"trait_type\":\"Category\",\"value\":\"COMMON\"}]}", + "last_token_uri_sync": "2022-12-13T13:12:50.840Z", + "last_metadata_sync": "2023-05-15T07:30:04.882Z", + "minter_address": "ERC1155 tokens don't have a single minter", + "possible_spam": false, + "possible_phishing": false, + "uri_meta": { + "image": "https://metadata.thesmurfssociety.com/ingredients/nft/5.Forest_Mushrooms.jpg", + "image_url": "https://metadata.thesmurfssociety.com/ingredients/nft/5.Forest_Mushrooms.jpg", + "image_domain": "metadata.thesmurfssociety.com", + "name": "Forest Mushrooms", + "description": "Sweet and nutty with distinct earthy tones, these forest mushrooms will make a fine addition to all your soups, salads, and potions.", + "attributes": [ + { + "trait_type": "Type", + "value": "Ingredient" + }, + { + "trait_type": "Category", + "value": "COMMON" + } + ], + "animation_url": null, + "animation_domain": null, + "external_url": "https://app.thesmurfssociety.com/detail/ingredients/5", + "external_domain": "app.thesmurfssociety.com", + "image_details": null + } + } + ], + "skipped": 1, + "total": 1 + }, + "id": null + } + ``` + + +#### ๐Ÿ“Œ Example with optional spam protection + + + ```json + { + "userpass": "testpsw", + "method": "get_nft_list", + "mmrpc": "2.0", + "params": { + "chains": [ + "BSC", + "POLYGON" + ], + "protect_from_spam": true, + "filters": { + "exclude_spam": true, + "exclude_phishing": true + } + } + } + ``` + + + + ```json + { + "mmrpc": "2.0", + "result": { + "nfts": [ + { + "chain": "POLYGON", + "token_address": "0x48c75fbf0452fa8ff2928ddf46b0fe7629cca2ff", + "token_id": "5", + "amount": "1", + "owner_of": "0xf622a6c52c94b500542e2ae6bcad24c53bc5b6a2", + "token_hash": "28f970585fd743b056859a6e41f50a8e", + "block_number_minted": 36781490, + "block_number": 42491885, + "contract_type": "ERC1155", + "name": null, + "symbol": null, + "token_uri": "https://app.thesmurfssociety.com/metadata/public/metadata/cauldron/5", + "token_domain": "app.thesmurfssociety.com", + "metadata": "{\"name\":\"Forest Mushrooms\",\"description\":\"Sweet and nutty with distinct earthy tones, these forest mushrooms will make a fine addition to all your soups, salads, and potions.\",\"image\":\"https://metadata.thesmurfssociety.com/ingredients/nft/5.Forest_Mushrooms.jpg\",\"animation_url\":null,\"external_url\":\"https://app.thesmurfssociety.com/detail/ingredients/5\",\"attributes\":[{\"trait_type\":\"Type\",\"value\":\"Ingredient\"},{\"trait_type\":\"Category\",\"value\":\"COMMON\"}]}", + "last_token_uri_sync": "2022-12-13T13:12:50.840Z", + "last_metadata_sync": "2023-05-15T07:30:04.882Z", + "minter_address": "ERC1155 tokens don't have a single minter", + "possible_spam": false, + "possible_phishing": false, + "uri_meta": { + "image": "https://metadata.thesmurfssociety.com/ingredients/nft/5.Forest_Mushrooms.jpg", + "image_url": "https://metadata.thesmurfssociety.com/ingredients/nft/5.Forest_Mushrooms.jpg", + "image_domain": "metadata.thesmurfssociety.com", + "name": "Forest Mushrooms", + "description": "Sweet and nutty with distinct earthy tones, these forest mushrooms will make a fine addition to all your soups, salads, and potions.", + "attributes": [ + { + "trait_type": "Type", + "value": "Ingredient" + }, + { + "trait_type": "Category", + "value": "COMMON" + } + ], + "animation_url": null, + "animation_domain": null, + "external_url": "https://app.thesmurfssociety.com/detail/ingredients/5", + "external_domain": "app.thesmurfssociety.com", + "image_details": null + } + } + ], + "skipped": 0, + "total": 1 + }, + "id": null + } + ``` + + +### ๐Ÿ“Œ Error responses + +#### Unsupported Chain Type + +The supported chains are + +``` +{ + "mmrpc":"2.0", + "error":"Error parsing request: UnsupportedChainType", + "error_path":"dispatcher", + "error_trace":"dispatcher:109]", + "error_type":"InvalidRequest", + "error_data":"UnsupportedChainType", + "id":null +} +``` diff --git a/src/pages/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_metadata/index.mdx b/src/pages/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_metadata/index.mdx new file mode 100644 index 00000000..ff1ef081 --- /dev/null +++ b/src/pages/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_metadata/index.mdx @@ -0,0 +1,116 @@ +export const title = "AtomicDEX: Non Fungible Tokens"; +export const description = + "This document describes the get_nft_metadata method AtomicDEX-API provides to get metadata for your NFTs"; + +# Get NFT Metadata {{label : 'get_nft_metadata', tag : 'API-v2'}} + +### Request Parameters + +| Parameter | Type | Description | +| ------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| chain | string | The token chain. | +| token\_address | string | The token address. | +| token\_id | string | Token ID. | +| protect\_from\_spam | boolean | Optional, defaults to `false`. If `true`, any potential spam link found in collection name, token name, symbol will be replaced with `URL redacted for user protection` | + +### Response Parameters + +| Parameter | Type | Description | +| ---------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| amount | string | The amount of this NFT the user owns (used by `ERC1155`). | +| block\_number\_minted | integer | The block height when the NFT was minted. May be `null`. | +| block\_number | integer | The block height when the amount or owner changed. | +| chain | string | Chain name. One of `AVALANCHE`, `BSC`, `ETH`, `FANTOM`, or `POLYGON`. | +| name | string | May be `null`. An NFT collection name. | +| contract\_type | string | The type of NFT contract standard. One of `ERC721` or `ERC1155`. | +| last\_token\_uri\_sync | string | When the token\_uri was last updated. | +| last\_metadata\_sync | string | When the metadata was last updated. | +| metadata | string | The metadata of the token. May be `null`. | +| minter\_address | string | Minter address. May be `null`. | +| owner\_of | string | The wallet address of the owner of the NFT. | +| possible\_spam | boolean | If `true`, the contract address has [been identified](https://docs.moralis.io/web3-data-api/evm/nft-spam-detection) as associated with spam or suspicious activities. | +| possible\_phishing | boolean | If `true`, the token has been identified as associated with phishing, as at least one of domain fields is found in database with phishing domains. | +| symbol | string | May be `null`. The symbol of the NFT contract. | +| token\_address | string | The address of the NFT contract. | +| token\_id | string | The token ID of the NFT. | +| token\_hash | string | The token hash. May be `null`. | +| token\_uri | string | The URI to the metadata of the token. May be `null`. | +| token\_domain | string | Token domain. May be `null`. | +| uri\_meta | object | A standard [NftMetadata](/atomicdex/api/common_structures/nfts/#nft-metadata) object. | + +#### ๐Ÿ“Œ Example + + + ```json + { + "userpass": "testpsw", + "method": "get_nft_metadata", + "mmrpc": "2.0", + "params": { + "token_address": "0xfd913a305d70a60aac4faac70c739563738e1f81", + "token_id": "214300044414", + "chain": "BSC" + } + } + ``` + + + + ```json + { + "mmrpc": "2.0", + "result": { + "token_address": "0x2953399124f0cbb46d2cbacd8a89cf0599974963", + "amount": "1", + "owner_of": "0xab95d01bc8214e4d993043e8ca1b68db2c946498", + "token_hash": "af811b641bccbdc10c444ba4f3a2ffb5", + "name": "OpenSea Collections", + "symbol": "OPENSTORE", + "token_uri": "https://api.opensea.io/api/v2/metadata/matic/0x2953399124F0cBB46d2CbACD8A89cF0599974963/0xf43db4f488f644b73a9442de4978fb7572b73d85000000000000110000002710", + "token_domain": "api.opensea.io", + "metadata": "{\"image\":\"https://i.seadn.io/gae/nY8wjVVQqDZBl-Bk3h9kwSqR1bXt16x_tESRAQmctEb0SCFCPtvtSsBtp98TFiUzP-LpMGt_kiqHDDOfkgbxOuWxkdH4aBNkmzrjZM0?w=500&auto=format\",\"name\":\"Doge Napoleon\",\"description\":null,\"external_link\":null,\"animation_url\":\"https://openseauserdata.com/files/df71203f48e54d027bb2c47b2840cacb.mp4\",\"traits\":[]}", + "last_token_uri_sync": "2023-09-01T04:04:30.867Z", + "last_metadata_sync": "2023-09-01T04:35:01.128Z", + "minter_address": "ERC1155 tokens don't have a single minter", + "possible_spam": true, + "chain": "POLYGON", + "token_id": "110473361632261669912565539602449606788298723469812631769659886404530570536720", + "block_number_minted": 19645247, + "block_number": 45776404, + "contract_type": "ERC1155", + "possible_phishing": false, + "uri_meta": { + "image": "https://i.seadn.io/gae/nY8wjVVQqDZBl-Bk3h9kwSqR1bXt16x_tESRAQmctEb0SCFCPtvtSsBtp98TFiUzP-LpMGt_kiqHDDOfkgbxOuWxkdH4aBNkmzrjZM0?w=500&auto=format", + "image_url": "https://i.seadn.io/gae/nY8wjVVQqDZBl-Bk3h9kwSqR1bXt16x_tESRAQmctEb0SCFCPtvtSsBtp98TFiUzP-LpMGt_kiqHDDOfkgbxOuWxkdH4aBNkmzrjZM0?w=500&auto=format", + "image_domain": "i.seadn.io", + "name": "Doge Napoleon", + "description": null, + "attributes": null, + "animation_url": "https://openseauserdata.com/files/df71203f48e54d027bb2c47b2840cacb.mp4", + "animation_domain": "openseauserdata.com", + "external_url": null, + "external_domain": null, + "image_details": null + } + }, + "id": null + } + ``` + + +## Error responses + +``` +{ + "mmrpc": "2.0", + "error": "Token: token_address 0xfd913a305d70a60aac4faac70c739563738e1f81, token_id 214300044414 was not found in wallet", + "error_path": "nft", + "error_trace": "nft:123]", + "error_type": "TokenNotFoundInWallet", + "error_data": { + "token_address": "0xfd913a305d70a60aac4faac70c739563738e1f81", + "token_id": "214300044414" + }, + "id": null +} +``` diff --git a/src/pages/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_transfers/index.mdx b/src/pages/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_transfers/index.mdx new file mode 100644 index 00000000..4abf3a97 --- /dev/null +++ b/src/pages/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_transfers/index.mdx @@ -0,0 +1,103 @@ +export const title = "AtomicDEX: Non Fungible Tokens"; +export const description = + "This document describes the get_nft_transfers method AtomicDEX-API provides to get information about your NFT transactions"; + +# Get a list of NFT transfers {{label : 'get_nft_transfers', tag : 'API-v2'}} + +Returns a list of the NFT transfers involving the user, shown in descending order of the `block_timestamp` value of the NFT's last transfer. + + + To view NFT transactions, you must [activate the coin](/atomicdex/api/legacy/coin_activation/) which holds the NFTs first. + + +### Request Parameters + +| Parameter | Type | Description | +| ------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| chains | array | List of chains to scan for NFTs. | +| max | boolean | Optional, defaults to `false`. If `true`, response will return all NFT transfers without pagination, and will ignore the `limit` and `page_number` values. | +| limit | integer | Optional, defaults to `10`. The number of NFT transfers displayed per page in response. | +| page\_number | integer | Optional, defaults to `1`. The page offset for items in response. | +| protect\_from\_spam | boolean | Optional, defaults to `false`. If `true`, any potential spam link found in collection name, token name, symbol will be replaced with `URL redacted for user protection` | +| filters | object | Optional. A standard [NftTransferFilter](/atomicdex/api/common_structures/nfts/#nft-transfer-filter) object. | + +### Response Parameters + +| Parameter | Type | Description | +| ----------------- | --------------- | ---------------------------------------------------------------------------------------------- | +| transfer\_history | list of objects | A list of standard [NftTransfer](/atomicdex/api/common_structures/nfts/#nft-transfer) objects. | +| total | integer | The total number of NFT transfers in your wallet matching the request filters. | +| skipped | integer | The number of NFT transfers in your wallet excluded by the request filters. | + +#### ๐Ÿ“Œ Example with date and `send` filters + + + ```json + { + "userpass": "testpsw", + "method": "get_nft_transfers", + "mmrpc": "2.0", + "params": { + "chains": [ + "POLYGON" + ], + "max": true, + "filters": { + "receive": true, + "from_date": 1678233600 + }, + "protect_from_spam": true + } + } + ``` + + + + ```json + { + "mmrpc": "2.0", + "result": { + "transfer_history": [ + { + "block_hash": "0xfd012e9dc2c7fa652ae3c0923599a9e6196520ac46e55f0f467d3a1ce84b8580", + "transaction_hash": "0x4063c4ae3e56a06b6c8768ad76e0cb1523e671cf06e4325517106497778ede9e", + "transaction_index": 87, + "log_index": 468, + "value": "0", + "transaction_type": "Single", + "token_address": "0x48c75fbf0452fa8ff2928ddf46b0fe7629cca2ff", + "from_address": "0xf622a6c52c94b500542e2ae6bcad24c53bc5b6a2", + "to_address": "0xf622a6c52c94b500542e2ae6bcad24c53bc5b6a2", + "amount": "2", + "verified": 1, + "operator": "0xf622a6c52c94b500542e2ae6bcad24c53bc5b6a2", + "possible_spam": false, + "chain": "POLYGON", + "token_id": "5", + "block_number": 44506464, + "block_timestamp": 1688107346, + "contract_type": "ERC1155", + "token_uri": "https://app.thesmurfssociety.com/metadata/public/metadata/cauldron/5", + "token_domain": "app.thesmurfssociety.com", + "collection_name": null, + "image_url": "https://metadata.thesmurfssociety.com/ingredients/nft/5.Forest_Mushrooms.jpg", + "image_domain": "metadata.thesmurfssociety.com", + "token_name": "Forest Mushrooms", + "status": "Receive", + "possible_phishing": false, + "fee_details": { + "coin": "MATIC", + "gas": 40249, + "gas_price": "0.000000153160317706", + "total_fee": "0.006164549627348794" + }, + "confirmations": 5775855 + } + ], + "skipped": 0, + "total": 1 + }, + "id": null + } + ``` + diff --git a/src/pages/atomicdex/api/v20-dev/non_fungible_tokens/index.mdx b/src/pages/atomicdex/api/v20-dev/non_fungible_tokens/index.mdx new file mode 100644 index 00000000..374a6312 --- /dev/null +++ b/src/pages/atomicdex/api/v20-dev/non_fungible_tokens/index.mdx @@ -0,0 +1,29 @@ +export const title = "AtomicDEX: Non Fungible Tokens"; +export const description = + "This document describes all the methods AtomicDEX-API provides to get information and transact with NFTs"; + +# Non Fungible Tokens (NFTs) + +The AtomicDEX API supports [ERC1155](https://www.nftstandards.wtf/Standards/ERC1155+Multi+token) and [ERC721](https://www.nftstandards.wtf/Standards/ERC721+Non+Fungible+Standard) NFTs via the [Moralis API](https://docs.moralis.io/) on the Avalanche (AVAX), BNB Smart Chain (BNB), Ethereum (ETH), Fantom (FTM), Polygon (MATIC) networks. + + + Before using other NFT methods, you should first call the [update\_nft](/atomicdex/api/v20-dev/non_fungible_tokens/update_nft/) + method to populate/refresh the local database. + + +## NFT Information Methods + +* Get a list of your tokens with [get\_nft\_list](/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_list/) +* Get a list of token transfers with [get\_nft\_transfers](/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_transfers/) +* Get token metadata with [get\_nft\_metadata](/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_metadata/) +* Update NFT [update\_nft](/atomicdex/api/v20-dev/non_fungible_tokens/update_nft/) +* Refresh NFT metadata with [refresh\_nft\_metadata](/atomicdex/api/v20-dev/non_fungible_tokens/refresh_nft_metadata/) + +## NFT Transaction Methods + +* Withdraw ERC721 tokens with [withdraw\_nft](/atomicdex/api/v20-dev/non_fungible_tokens/withdraw_nft/#erc-721-withdraw-example) +* Withdraw ERC1155 tokens with [withdraw\_nft](/atomicdex/api/v20-dev/non_fungible_tokens/withdraw_nft/#erc-1155-withdraw-example) + + + View the source code at: [https://github.com/KomodoPlatform/komodo-defi-framework/blob/main/mm2src/coins/nft.rs](https://github.com/KomodoPlatform/komodo-defi-framework/blob/main/mm2src/coins/nft.rs) + diff --git a/src/pages/atomicdex/api/v20-dev/non_fungible_tokens/query_nft_database_tables/index.mdx b/src/pages/atomicdex/api/v20-dev/non_fungible_tokens/query_nft_database_tables/index.mdx new file mode 100644 index 00000000..634a8208 --- /dev/null +++ b/src/pages/atomicdex/api/v20-dev/non_fungible_tokens/query_nft_database_tables/index.mdx @@ -0,0 +1,125 @@ +export const title = "AtomicDEX: Non Fungible Tokens - Query NFT database tables"; +export const description = + "This document describes how to query the local NFT database tables."; + +# Query NFT database tables + +After using the [update\_nft](/atomicdex/api/v20-dev/non_fungible_tokens/update_nft/#update-nft) method to initialise your local NFT database, +the following tables are available in `DB/KOMODEFI.db`: + +* AVAX\_nft\_list +* AVAX\_nft\_transfer\_history +* BNB\_nft\_list +* BNB\_nft\_transfer\_history +* ETH\_nft\_list +* ETH\_nft\_transfer\_history +* FTM\_nft\_list +* FTM\_nft\_transfer\_history +* MATIC\_nft\_list +* MATIC\_nft\_transfer\_history +* scanned\_nft\_blocks + +## NFT List tables + +The COIN\_nft\_list tables contain the NFTs that you own +It has the following columns, though not all columns are populated for all NFTs: + +| ID | Name | Type | Description | +| -- | ---------------------- | ------------ | ------------------------------------------------------------------------------ | +| 0 | token\_address | VARCHAR(256) | The address of the token contract. | +| 1 | token\_id | VARCHAR(256) | The id of the token. | +| 2 | chain | TEXT | The coin network which the NFT is on. | +| 3 | amount | VARCHAR(256) | The amount of NFTs transfered in this transaction. | +| 4 | block\_number | INTEGER | The block height of this transaction. | +| 5 | contract\_type | TEXT | The contract type. Either `ERC721` or `ERC1155`. | +| 6 | possible\_spam | INTEGER | `1` indicates the NFT has been identified as spam. `0` indicates it has not. | +| 7 | possible\_phishing | INTEGER | `1` indicates the NFT has been identified as a scam. `0` indicates it has not. | +| 8 | collection\_name | TEXT | The collection name which includes the token. | +| 9 | symbol | TEXT | An arbitrary symbol for the NFT | +| 10 | token\_uri | TEXT | A link to the token's metadata. | +| 11 | token\_domain | TEXT | The domain the token metadata is hosted on. | +| 12 | metadata | TEXT | The token's metadata in JSON format. | +| 13 | last\_token\_uri\_sync | TEXT | Date and time when the token uri was last syncronised. | +| 14 | last\_metadata\_sync | TEXT | Date and time when the token metadata was last syncronised. | +| 15 | raw\_image\_url | TEXT | The raw URL for the token image. | +| 16 | image\_url | TEXT | A link for the token's image (or other media). | +| 17 | image\_domain | TEXT | The domain the token image (or other media) is hosted on. | +| 18 | token\_name | TEXT | The name of the token. | +| 19 | description | TEXT | An arbitrary description of the NFT. | +| 20 | attributes | TEXT | Additional attribute data for the NFT in JSON format. | +| 21 | animation\_url | TEXT | If NFT is animated, the URL of the animation. | +| 22 | animation\_domain | TEXT | If NFT is animated, the domain of the animation. | +| 23 | external\_url | TEXT | Additional URL related to the NFT | +| 24 | external\_domain | TEXT | Domain of the additional URL related to the NFT | +| 25 | image\_details | TEXT | Additional details about the NFT's image. | +| 26 | details\_json | TEXT | Additional information about the transaction in JSON format. | + +### Example COIN\_nft\_list table query + +> SELECT chain, token\_name, token\_address, token\_id, possible\_spam, possible\_phishing FROM MATIC\_nft\_list LIMIT 5; + +| chain | token\_name | token\_address | token\_id | possible\_spam | possible\_phishing | +| ------- | ---------------------- | ------------------------------------------ | --------- | -------------- | ------------------ | +| POLYGON | $2000 USDT Airdrop๐ŸŽ | 0xe7ee9dcf5f4b7f9254b348ba596c9fb9121f77e7 | 1 | 1 | 0 | +| POLYGON | $1000 USDC Voucher๐ŸŽ | 0xb092b5eb5c653e915880dfc1f606be2ffe6fae8c | 1 | 1 | 0 | +| POLYGON | 1000 BLUR Reward | 0xeaa3c52052b809c8d8072187efc134def2dd5b13 | 0 | 1 | 0 | +| POLYGON | SHIB Voucher 66 of 100 | 0xc46e36339ebd8bed48b1bdb6bd815e4b72103949 | 0 | 1 | 0 | +| POLYGON | $1000 Rewards | 0x6e0b84421388ad635f2a1167e39aff2dc742da2a | 0 | 1 | 0 | + +The NFTs listed above are all spam, and will be ignored by the [get\_nft\_list](/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_list/) method. + +## NFT Transfer table + +The COIN\_nft\_transfer\_history tables contain the history of transfers of your NFTs, and have the following columns: + +| ID | Name | Type | Description | +| -- | ------------------ | ------------ | ------------------------------------------------------------------------------ | +| 0 | transaction\_hash | VARCHAR(256) | Hex string, representing the transaction. | +| 1 | log\_index | INTEGER | Simply a table index. | +| 2 | chain | TEXT | The coin network which the NFT is on. | +| 3 | block\_number | INTEGER | The block height of this transaction. | +| 4 | block\_timestamp | INTEGER | The block time of this transaction. | +| 5 | contract\_type | TEXT | The contract type. Either `ERC721` or `ERC1155`. | +| 6 | token\_address | VARCHAR(256) | The address of the token contract. | +| 7 | token\_id | VARCHAR(256) | The id of the token. | +| 8 | status | TEXT | The transaction type: `Recieve` or `Send` | +| 9 | amount | VARCHAR(256) | The amount of NFTs transfered in this transaction. | +| 10 | possible\_spam | INTEGER | `1` indicates the NFT has been identified as spam. `0` indicates it has not. | +| 11 | possible\_phishing | INTEGER | `1` indicates the NFT has been identified as a scam. `0` indicates it has not. | +| 12 | token\_uri | TEXT | A link to the token's metadata. | +| 13 | token\_domain | TEXT | The domain the token metadata is hosted on. | +| 14 | collection\_name | TEXT | The collection name which includes the token. | +| 15 | image\_url | TEXT | A link for the token's image (or other media). | +| 16 | image\_domain | TEXT | The domain the token image (or other media) is hosted on. | +| 17 | token\_name | TEXT | The name of the token. | +| 18 | details\_json | TEXT | Additional information about the transaction in JSON format. | + +### Example COIN\_nft\_transfer\_history table query + +> SELECT transaction\_hash, token\_name, token\_address, token\_id, FROM MATIC\_nft\_transfer\_history WHERE block\_timestamp > 1701519320; + +| transaction\_hash | token\_name | token\_address | token\_id | +| ------------------------------------------------------------------ | -------------------- | ------------------------------------------ | --------- | +| 0x7b57303bcc2c68808b460490e984adcd18567a80660a18b7a151b62015247cda | $2000 USDT Airdrop๐ŸŽ | 0xe7ee9dcf5f4b7f9254b348ba596c9fb9121f77e7 | 1 | + +## NFT Last Scanned Block table + +The scanned\_nft\_blocks table contains the last block that was scanned for each chain. +It has the following columns: + +| ID | Name | Type | Description | +| -- | -------------------- | ------- | ---------------------------------------------------------------------- | +| 2 | chain | TEXT | The coin network which the NFT is on. | +| 1 | last\_scanned\_block | INTEGER | The block height when the last scan for NFTs was performed on a chain. | + +### Example scanned\_nft\_blocks table query + +> SELECT \* FROM scanned\_nft\_blocks; + +| chain | last\_scanned\_block | +| ----- | -------------------- | +| MATIC | 50651981 | +| FTM | 66512090 | +| ETH | 0 | +| BNB | 0 | +| AVAX | 0 | diff --git a/src/pages/atomicdex/api/v20-dev/non_fungible_tokens/refresh_nft_metadata/index.mdx b/src/pages/atomicdex/api/v20-dev/non_fungible_tokens/refresh_nft_metadata/index.mdx new file mode 100644 index 00000000..030a9ca1 --- /dev/null +++ b/src/pages/atomicdex/api/v20-dev/non_fungible_tokens/refresh_nft_metadata/index.mdx @@ -0,0 +1,58 @@ +export const title = "AtomicDEX: Non Fungible Tokens"; +export const description = + "This document describes all the refresh_nft_metadata method AtomicDEX-API provides to refresh an NFT's metadata"; + +# Refresh NFT Metadata {{label : 'refresh_nft_metadata', tag : 'API-v2'}} + +This method refreshes metadata of one NFT and metadata of related transactions with the same token\_address and token\_id. + +### Request Parameters + +| Parameter | Type | Description | +| -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| chain | string | Chains which holds the NFT you would like to updated metadata for. | +| url | string | URL link to the Moralis API proxy base url ([https://moralis-proxy.komodo.earth](https://moralis-proxy.komodo.earth)) or equivalent. | +| token\_address | string | Token address. | +| token\_id | string | Token ID. | +| url\_antispam | string | URL link to the [Antispam API proxy base url](https://nft.antispam.dragonhound.info) or equivalent. [docs](https://nft.antispam.dragonhound.info/docs). | + + + If there are no errors, this request will return an empty response. + + +#### ๐Ÿ“Œ Example + + + ```json + { + "userpass": "testpsw", + "method": "refresh_nft_metadata", + "mmrpc": "2.0", + "params": { + "token_address": "0x48c75fbf0452fa8ff2928ddf46b0fe7629cca2ff", + "token_id": "5", + "chain": "POLYGON", + "url": "https://moralis-proxy.komodo.earth", + "url_antispam": "https://nft.antispam.dragonhound.info" + } + } + ``` + + + + + If there are no errors, this request will return an empty response. + + + ```json + { + "mmrpc": "2.0", + "result": null, + "id": null + } + ``` + + + + Need to add some error responses here. + diff --git a/src/pages/atomicdex/api/v20-dev/non_fungible_tokens/update_nft/index.mdx b/src/pages/atomicdex/api/v20-dev/non_fungible_tokens/update_nft/index.mdx new file mode 100644 index 00000000..ef142e0c --- /dev/null +++ b/src/pages/atomicdex/api/v20-dev/non_fungible_tokens/update_nft/index.mdx @@ -0,0 +1,67 @@ +export const title = "AtomicDEX: Non Fungible Tokens"; +export const description = + "This document describes the update_nft method AtomicDEX-API provides to update NFT information in your local database"; + +# Update NFT {{label : 'update_nft', tag : 'API-v2'}} + +This method will scan selected networks to update NFT information stored in the local database. +To interact with your NFTs, you will first need to activate the coin for the network the NFT is on. + +See below for which coin to activate for each network: + +| Network | Coin | +| --------- | ----- | +| AVALANCHE | AVAX | +| BSC | BNB | +| ETH | ETH | +| FANTOM | FTM | +| POLYGON | MATIC | + +These coins can be activated using the [enable\_eth\_with\_tokens](/atomicdex/api/v20/enable_eth_with_tokens/) or method. + +### Request Parameters + +| Parameter | Type | Description | +| ------------- | ------ | --------------------------------------------------------------------------------------------------- | +| chains | array | List of networks to scan for NFTs. Options are: `POLYGON`, `FANTOM`, `ETH`, `BSC`, or `AVALANCHE`. | +| url | string | URL link to the [Moralis API proxy base url](https://moralis-proxy.komodo.earth) or equivalent. | +| url\_antispam | string | URL link to the [Antispam API proxy base url](https://nft.antispam.dragonhound.info) or equivalent. | + + + If there are no errors, this request will return an empty response. + When updating multiple networks, or wallets with numerous NFTs, this request may take a while to complete. + + +#### ๐Ÿ“Œ Example + + + ```json + { + "userpass": "testpsw", + "method": "update_nft", + "mmrpc": "2.0", + "params": { + "chains": [ + "BSC", + "POLYGON" + ], + "url": "https://moralis-proxy.komodo.earth", + "url_antispam": "https://nft.antispam.dragonhound.info" + } + } + ``` + + + + ```json + { + "mmrpc": "2.0", + "result": null, + "id": null + } + ``` + + + + Need to add some error responses here. + diff --git a/src/pages/atomicdex/api/v20-dev/non_fungible_tokens/withdraw_nft/index.mdx b/src/pages/atomicdex/api/v20-dev/non_fungible_tokens/withdraw_nft/index.mdx new file mode 100644 index 00000000..e9f9df67 --- /dev/null +++ b/src/pages/atomicdex/api/v20-dev/non_fungible_tokens/withdraw_nft/index.mdx @@ -0,0 +1,298 @@ +export const title = "AtomicDEX: Non Fungible Tokens"; +export const description = + "This document describes the withdraw_nft method AtomicDEX-API provides to send NFTs to an address"; + +# Withdraw NFTs {{label : 'withdraw_nft', tag : 'API-v2'}} + + + To withdraw NFTs, you must [activate the coin](/atomicdex/api/legacy/coin_activation/) which holds the NFTs first. + The `withdraw_nft` method will return signed raw transaction hex which must be broadcast using the [send\_raw\_transaction](/atomicdex/api/legacy/send_raw_transaction/) method to complete the withdrawal. + + +### Request Parameters + +| Parameter | Type | Description | +| -------------- | ------ | ---------------------------------------------------------------------------------------------- | +| type | string | The contract type of the NFT to withdraw. Either `withdraw_erc721` or `withdraw_erc1155` | +| withdraw\_data | object | A standard [WithdrawNftData](/atomicdex/api/common_structures/nfts/#withdraw-nft-data) object. | + +### Response Parameters + +| Parameter | Type | Description | +| ----------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| amount | string | Amount of tokens to withdraw. | +| tx\_hex | string | Raw hex of signed transaction. Use this with the [send\_raw\_transaction](/atomicdex/api/legacy/send_raw_transaction/) RPC to broadcast the transaction. | +| tx\_hash | string | Transaction ID of the withdrawl. | +| from | array | List of source addresses. | +| to | array | List of destination addresses. | +| contract\_type | string | Contract type. `ERC721` or `ERC1155`. | +| token\_address | string | Token address. | +| token\_id | string | Token ID. | +| fee\_details | object | A standard [WithdrawFee](/atomicdex/api/common_structures/#withdraw-fee) object. | +| coin | string | Coin name. One of `AVALANCHE`, `BSC`, `ETH`, `FANTOM`, or `POLYGON`. | +| block\_height | integer | Block height of the transaction. If the value is `0`, the transaction is unconfirmed. | +| timestamp | integer | Timestamp of the block containing the withdrawl transaction in [unix epoch format](https://www.epochconverter.com/). | +| internal\_id | integer | Used for internal transaction identification, for some coins it may be equal to transaction hash. | +| transaction\_type | string | This will always be `NftTransfer`. | + +#### ๐Ÿ“Œ ERC721 Withdraw Example + + + ```json + { + "userpass": "testpsw", + "method": "withdraw_nft", + "mmrpc": "2.0", + "params": { + "type": "withdraw_erc721", + "withdraw_data": { + "chain": "POLYGON", + "to": "0xaB95D01Bc8214E4D993043E8Ca1B68dB2c946498", + "token_address": "0x73a5299824cd955af6377b56f5762dc3ca4cc078", + "token_id": "1" + } + } + } + ``` + + + + ```json + { + "mmrpc": "2.0", + "result": { + "tx_hex": "f8cb2a8509818733db8289929473a5299824cd955af6377b56f5762dc3ca4cc07880b86442842e0e000000000000000000000000ab95d01bc8214e4d993043e8ca1b68db2c946498000000000000000000000000ab95d01bc8214e4d993043e8ca1b68db2c9464980000000000000000000000000000000000000000000000000000000000000001820136a0564b5c9c8309a3f8f6cc007ca957e4c411259026d68c2c34419158aff4d3ebf8a007afaa0590da01a2ce36c7edb5380f41235168f3633ed459b1fc8a750fecd38d", + "tx_hash": "bb030f618702715eb39035dccd218355f78ae5379ff6d0691f0f3c0db3c03789", + "from": [ + "0xaB95D01Bc8214E4D993043E8Ca1B68dB2c946498" + ], + "to": [ + "0xaB95D01Bc8214E4D993043E8Ca1B68dB2c946498" + ], + "contract_type": "ERC721", + "token_address": "0x73a5299824cd955af6377b56f5762dc3ca4cc078", + "token_id": "1", + "amount": "1", + "fee_details": { + "type": "Eth", + "coin": "MATIC", + "gas": 35218, + "gas_price": "0.000000040827827163", + "total_fee": "0.001437874417026534" + }, + "coin": "MATIC", + "block_height": 0, + "timestamp": 1700732198, + "internal_id": 0, + "transaction_type": "NftTransfer" + }, + "id": null + } + ``` + + +#### ๐Ÿ“Œ ERC1155 Withdraw Example + +If you are sending 2 or more NFTs, you must use the `withdraw_erc1155` withdraw type. + + + ```json + { + "userpass": "testpsw", + "method": "withdraw_nft", + "mmrpc": "2.0", + "params": { + "type": "withdraw_erc1155", + "withdraw_data": { + "chain": "POLYGON", + "to": "0xaB95D01Bc8214E4D993043E8Ca1B68dB2c946498", + "token_address": "0x73a5299824cd955af6377b56f5762dc3ca4cc078", + "token_id": "1" + } + } + } + ``` + + + + ```json + { + "mmrpc": "2.0", + "result": { + "tx_hex": "f8cb2a8502dffe7b4682f3a09473a5299824cd955af6377b56f5762dc3ca4cc07880b86442842e0e000000000000000000000000ab95d01bc8214e4d993043e8ca1b68db2c94649800000000000000000000000027ad1f808c1ef82626277ae38998afa5395656600000000000000000000000000000000000000000000000000000000000000001820135a0476a4623c9df31cecbd319e0571c62d14a6dcedd5a760ced945ffa2e39fb12c5a03293f3c10d115edcc3795e414670f070c04ad936e2e87001da12f961df5962a7", + "tx_hash": "d6b46e70bf755617366a5c10875eb639d55586bb568010ea82ef42e8d68c6523", + "from": [ + "0xaB95D01Bc8214E4D993043E8Ca1B68dB2c946498" + ], + "to": [ + "0x27Ad1F808c1ef82626277Ae38998AfA539565660" + ], + "contract_type": "ERC721", + "token_address": "0x73a5299824cd955af6377b56f5762dc3ca4cc078", + "token_id": "1", + "amount": "1", + "fee_details": { + "type": "Eth", + "coin": "MATIC", + "gas": 62368, + "gas_price": "0.000000012347931462", + "total_fee": "0.000770115789422016" + }, + "coin": "MATIC", + "block_height": 0, + "timestamp": 1700732805, + "internal_id": 0, + "transaction_type": "NftTransfer" + }, + "id": null + } + ``` + + +#### ๐Ÿ“Œ ERC1155 Withdraw Max Example + +If you would like to withdraw all NFTs from a token\_address, you must use the `withdraw_erc1155` withdraw type and set `max` to `true`. + + + ```json + { + "userpass": "testpsw", + "method": "withdraw_nft", + "mmrpc": "2.0", + "params": { + "type": "withdraw_erc1155", + "withdraw_data": { + "chain": "POLYGON", + "to": "0x27Ad1F808c1ef82626277Ae38998AfA539565660", + "token_address": "0x2953399124f0cbb46d2cbacd8a89cf0599974963", + "token_id": "110473361632261669912565539602449606788298723469812631769659886404530570536720", + "max": true + } + } + } + ``` + + + + ```json + { + "mmrpc": "2.0", + "result": { + "tx_hex": "f9014b2a8508d579565282ea3b942953399124f0cbb46d2cbacd8a89cf059997496380b8e4f242432a000000000000000000000000ab95d01bc8214e4d993043e8ca1b68db2c94649800000000000000000000000027ad1f808c1ef82626277ae38998afa539565660f43db4f488f644b73a9442de4978fb7572b73d85000000000000110000002710000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000000023078000000000000000000000000000000000000000000000000000000000000820135a0feb67607bd5e5c58f7533c8d2c88ef0ba3beac7fea29bfe11c3ce9bd10641f2ca02f1045b9f87536e45fe63556805734293e534284efecd9210f614316a3e8dca7", + "tx_hash": "9dce8e555d388532bdafd42dd44cd6a2bdcbf74bdda079e15f71b808c8395bcc", + "from": [ + "0xaB95D01Bc8214E4D993043E8Ca1B68dB2c946498" + ], + "to": [ + "0x27Ad1F808c1ef82626277Ae38998AfA539565660" + ], + "contract_type": "ERC1155", + "token_address": "0x2953399124f0cbb46d2cbacd8a89cf0599974963", + "token_id": "110473361632261669912565539602449606788298723469812631769659886404530570536720", + "amount": "7", + "fee_details": { + "type": "Eth", + "coin": "MATIC", + "gas": 59963, + "gas_price": "0.00000003794123733", + "total_fee": "0.00227507041401879" + }, + "coin": "MATIC", + "block_height": 0, + "timestamp": 1700732937, + "internal_id": 0, + "transaction_type": "NftTransfer" + }, + "id": null + } + ``` + + + + ### ๐Ÿ“Œ Withdraw NFTs Error Responses + + #### InvalidRequest (missing field) + + ``` + { + "mmrpc": "2.0", + "error": "Error parsing request: missing field `type`", + "error_path": "dispatcher", + "error_trace": "dispatcher:109]", + "error_type": "InvalidRequest", + "error_data": "missing field `type`", + "id": null + } + ``` + + #### InvalidRequest (wrong withdraw type) + + ``` + { + "mmrpc": "2.0", + "error": "Error parsing request: unknown variant `withdraw_erc420`, expected `withdraw_erc1155` or `withdraw_erc721`", + "error_path": "dispatcher", + "error_trace": "dispatcher:109]", + "error_type": "InvalidRequest", + "error_data": "unknown variant `withdraw_erc420`, expected `withdraw_erc1155` or `withdraw_erc721`", + "id": null + } + ``` + + #### TokenNotFoundInWallet (trying to send NFT you dont own) + + ``` + { + "mmrpc": "2.0", + "error": "Token: token_address 0xfd913a305d70a60aac4faac70c739563738e1f82, token_id 110473361632261669912565539602449606788298723469812631769659886404530570536722 was not found in wallet", + "error_path": "eth.nft", + "error_trace": "eth:883] nft:1177]", + "error_type": "GetNftInfoError", + "error_data": { + "error_type": "TokenNotFoundInWallet", + "error_data": { + "token_address": "0xfd913a305d70a60aac4faac70c739563738e1f82", + "token_id": "110473361632261669912565539602449606788298723469812631769659886404530570536722" + } + }, + "id": null + } + ``` + + #### TransportError (unable to estimate gas) + + ``` + { + "mmrpc": "2.0", + "error": "Transport error: request MethodCall(MethodCall { jsonrpc: Some(V2), method: \"eth_estimateGas\", params: Array([Object({\"from\": String(\"0xab95d01bc8214e4d993043e8ca1b68db2c946498\"), \"to\": String(\"0x2953399124f0cbb46d2cbacd8a89cf0599974963\"), \"gasPrice\": String(\"0x9ddeaaffe\"), \"value\": String(\"0x0\"), \"data\": String(\"0x42842e0e000000000000000000000000ab95d01bc8214e4d993043e8ca1b68db2c946498000000000000000000000000ab95d01bc8214e4d993043e8ca1b68db2c946498f43db4f488f644b73a9442de4978fb7572b73d85000000000000110000002710\")})]), id: Num(64) }) failed: InvalidResponse(\"Server: 'https://polygon-rpc.com/', error: RPC error: Error { code: ServerError(-32000), message: \\\"execution reverted\\\", data: None }\"); InvalidResponse(\"Server: 'https://polygon.blockpi.network/v1/rpc/public', error: RPC error: Error { code: ServerError(-32000), message: \\\"execution reverted\\\", data: None }\"); Transport(\"Server: 'https://node.komodo.earth:8080/polygon', response !200: 502 Bad Gateway, <html>..<head><title>502 Bad Gateway</title></head>..<body>..<center><h1>502 Bad Gateway</h1></center>..<hr><center>nginx/1.18.0 (Ubuntu)</center>..</body>..</html>..\"); InvalidResponse(\"Server: 'https://polygon.llamarpc.com/', error: RPC error: Error { code: ServerError(-32000), message: \\\"execution reverted\\\", data: None }\"); ", + "error_path": "eth", + "error_trace": "eth:1004] eth:5792]", + "error_type": "Transport", + "error_data": "request MethodCall(MethodCall { jsonrpc: Some(V2), method: \"eth_estimateGas\", params: Array([Object({\"from\": String(\"0xab95d01bc8214e4d993043e8ca1b68db2c946498\"), \"to\": String(\"0x2953399124f0cbb46d2cbacd8a89cf0599974963\"), \"gasPrice\": String(\"0x9ddeaaffe\"), \"value\": String(\"0x0\"), \"data\": String(\"0x42842e0e000000000000000000000000ab95d01bc8214e4d993043e8ca1b68db2c946498000000000000000000000000ab95d01bc8214e4d993043e8ca1b68db2c946498f43db4f488f644b73a9442de4978fb7572b73d85000000000000110000002710\")})]), id: Num(64) }) failed: InvalidResponse(\"Server: 'https://polygon-rpc.com/', error: RPC error: Error { code: ServerError(-32000), message: \\\"execution reverted\\\", data: None }\"); InvalidResponse(\"Server: 'https://polygon.blockpi.network/v1/rpc/public', error: RPC error: Error { code: ServerError(-32000), message: \\\"execution reverted\\\", data: None }\"); Transport(\"Server: 'https://node.komodo.earth:8080/polygon', response !200: 502 Bad Gateway, <html>..<head><title>502 Bad Gateway</title></head>..<body>..<center><h1>502 Bad Gateway</h1></center>..<hr><center>nginx/1.18.0 (Ubuntu)</center>..</body>..</html>..\"); InvalidResponse(\"Server: 'https://polygon.llamarpc.com/', error: RPC error: Error { code: ServerError(-32000), message: \\\"execution reverted\\\", data: None }\"); ", + "id": null + } + ``` + + #### NotEnoughNftsAmount (trying to send more NFTs than you have) + + ``` + { + "mmrpc": "2.0", + "error": "Not enough NFTs amount with token_address: 0x2953399124f0cbb46d2cbacd8a89cf0599974963 and token_id 110473361632261669912565539602449606788298723469812631769659886404530570536720. Available 1, required 2", + "error_path": "eth", + "error_trace": "eth:897]", + "error_type": "NotEnoughNftsAmount", + "error_data": { + "token_address": "0x2953399124f0cbb46d2cbacd8a89cf0599974963", + "token_id": "110473361632261669912565539602449606788298723469812631769659886404530570536720", + "available": "1", + "required": "2" + }, + "id": null + } + ``` + + + + View the source code at: [https://github.com/KomodoPlatform/komodo-defi-framework/blob/main/mm2src/coins/nft.rs](https://github.com/KomodoPlatform/komodo-defi-framework/blob/main/mm2src/coins/nft.rs) + diff --git a/src/pages/atomicdex/api/v20/enable_bch_with_tokens/index.mdx b/src/pages/atomicdex/api/v20/enable_bch_with_tokens/index.mdx index 86614597..a1b30eb6 100644 --- a/src/pages/atomicdex/api/v20/enable_bch_with_tokens/index.mdx +++ b/src/pages/atomicdex/api/v20/enable_bch_with_tokens/index.mdx @@ -13,7 +13,7 @@ The AtomicDEX-API supports Bitcoin Cash SLP tokens. Using this method, you can e | bchd\_urls | array of strings | A list of BCHD gRPC API server URLs, used for validation of SLP token transactions. It's recommended to add as many servers as possible. The URLs list can be found at [https://bchd.fountainhead.cash/](https://bchd.fountainhead.cash/). | | mode | object | A standard [ActivationMode](/atomicdex/api/common_structures/activation/#activation-mode) object. | | tx\_history | boolean | If `true`, spawns a background loop to store the local cache of address(es) transactions. Defaults to `false`. | -| slp\_tokens\_requests | array of objects | A list of standard [TokensRequest](/atomicdex/api/common_structures/nfts/#tokens-request) objects. | +| slp\_tokens\_requests | array of objects | A list of standard [TokensRequest](/atomicdex/api/common_structures/activation/#tokens-request) objects. | | address\_format | object | Optional. Overwrites the address format from coins file, if set. A standard [AddressFormat](/atomicdex/api/common_structures/#address-format) object. | | allow\_slp\_unsafe\_conf | boolean | Optional, defaults to `false`. If `true`, allows bchd\_urls to be empty. **Warning:** it is highly unsafe to do so as it may lead to invalid SLP transactions generation and tokens burning. | | get\_balances | boolean | Optional, defaults to `true`. If `false`, coin and token balances will not be returned in the response, and the response will be returned more quickly. | diff --git a/src/pages/atomicdex/api/v20/enable_eth_with_tokens/index.mdx b/src/pages/atomicdex/api/v20/enable_eth_with_tokens/index.mdx index c02f3618..b1a009b4 100644 --- a/src/pages/atomicdex/api/v20/enable_eth_with_tokens/index.mdx +++ b/src/pages/atomicdex/api/v20/enable_eth_with_tokens/index.mdx @@ -15,7 +15,7 @@ Additionally, it supports ERC20 tokens on the ETH chain and associated ERC20 lik | swap\_contract\_address | string | Address of etomic swap smart contract | | fallback\_swap\_contract | string | Address of backup etomic swap smart contract | | nodes | array of objects | A list of standard [EvmNode](/atomicdex/api/common_structures/activation/#evm-node) objects. | -| erc20\_tokens\_requests | array of objects | A list of standard [TokensRequest](/atomicdex/api/common_structures/nfts/#tokens-request) objects. | +| erc20\_tokens\_requests | array of objects | A list of standard [TokensRequest](/atomicdex/api/common_structures/activation/#tokens-request) objects. | | gas\_station\_decimals | integer | Optional, for ETH/ERC20 and other gas model chains. Defaults to `8`. Defines the decimals used to denominate the gas station response to gwei units. For example, the ETH gas station uses 8 decimals, which means that "average": 860 is equal to 86 gwei. While the Matic gas station uses 9 decimals, so 860 would mean 860 gwei exactly. | | gas\_station\_policy.policy | string | Optional, for ETH/ERC20 and other gas model chains. Defaults to `"MeanAverageFast"`. Defines the method of gas price calculation from the station response. `"MeanAverageFast"` will use the mean between average and fast fields. `"Average"` will return a simple average value. | | get\_balances | boolean | Optional, defaults to `true`. If `false`, coin and token balances will not be returned in the response, and the response will be returned more quickly. | diff --git a/src/pages/atomicdex/api/v20/enable_tendermint_with_assets/index.mdx b/src/pages/atomicdex/api/v20/enable_tendermint_with_assets/index.mdx index f2d15de0..5d59aaf6 100644 --- a/src/pages/atomicdex/api/v20/enable_tendermint_with_assets/index.mdx +++ b/src/pages/atomicdex/api/v20/enable_tendermint_with_assets/index.mdx @@ -11,7 +11,7 @@ Use this method to activate Tendermint coins (COSMOS/IRIS/OSMOSIS) and IBC asset | ----------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ticker | string | Ticker of the platform protocol coin. Options: `ATOM`, `IRIS`, `OSMOSIS` | | mm2 | integer | Required if not set in `coins` file. Informs the AtomicDEX API whether or not the coin is expected to function. Accepted values are `0` or `1` | -| tokens\_params | array of objects | A list of standard [TokensRequest](/atomicdex/api/common_structures/nfts/#tokens-request) objects. | +| tokens\_params | array of objects | A list of standard [TokensRequest](/atomicdex/api/common_structures/activation/#tokens-request) objects. | | priv\_key\_policy | string | Optional, defaults to `ContextPrivKey`. value can be `ContextPrivKey`,`Trezor` when AtomicDEX-API is built for native platforms. value can be `ContextPrivKey`, `Trezor`, `Metamask` when the AtomicDEX-API is built targeting `wasm` | | tx\_history | boolean | Optional, defaults to `false`. If `true` the AtomicDEX API will preload transaction history as a background process. Must be set to `true` to use the [my\_tx\_history](/atomicdex/api/legacy/my_tx_history/#my-tx-history) method | | required\_confirmations | integer | Optional, defaults to `3`. When the platform coin is involved, the number of confirmations for the AtomicDEX API to wait during the transaction steps of an atomic swap | diff --git a/src/pages/atomicdex/api/v20/index.mdx b/src/pages/atomicdex/api/v20/index.mdx index 6771cdb2..32d9aac5 100644 --- a/src/pages/atomicdex/api/v20/index.mdx +++ b/src/pages/atomicdex/api/v20/index.mdx @@ -101,3 +101,12 @@ It includes a uniform request, successful and error response formats. At the mom } ``` + +## Common Komodo DeFi SDK Request / Response Objects + +There are some common objects that are used in the Komodo DeFi SDK RPC protocol. These standard objects have been collected and grouped into the following sections: + +* [Activation](/atomicdex/api/common_structures/activation) +* [Swaps](/atomicdex/api/common_structures/swaps/) +* [Lightning Network](/atomicdex/api/common_structures/lightning/) +* [Non-fungible Tokens](/atomicdex/api/common_structures/nfts/) diff --git a/templates/atomicdex_method.mdx b/templates/atomicdex_method.mdx index a8e61a12..92427cef 100644 --- a/templates/atomicdex_method.mdx +++ b/templates/atomicdex_method.mdx @@ -26,20 +26,6 @@ If there are optional paramaters which need a more detailed explanation, it shou | optionalParam | boolean | Optional, defaults to `something`. What difference does it make? | -### Response Parameters - -| Parameter | Type | Description | -| --------------| ---------------- | ----------------------------------------------------------------------------------------------- | -| someText | string | This text string has a purpose and here it is. | -| numberText | string (numeric) | This text string has a purpose and here it is. | -| wholeNumber | integer | What is the reason for this number? | -| decimalNumber | float | What is the reason for this number? | -| someObject | object | There should be a link here to a separate table for this object | -| listOfObjects | array of objects | There should be a link here to a separate table for an instance of the object within this array | -| isOrIsNot | boolean | What does this turn on or off? | -| optionalParam | boolean | Optional, defaults to `something`. What difference does it make? | - - #### ๐Ÿ“Œ Example(s) @@ -64,6 +50,20 @@ If there are optional paramaters which need a more detailed explanation, it shou +### Response Parameters + +| Parameter | Type | Description | +| --------------| ---------------- | ----------------------------------------------------------------------------------------------- | +| someText | string | This text string has a purpose and here it is. | +| numberText | string (numeric) | This text string has a purpose and here it is. | +| wholeNumber | integer | What is the reason for this number? | +| decimalNumber | float | What is the reason for this number? | +| someObject | object | There should be a link here to a separate table for this object | +| listOfObjects | array of objects | There should be a link here to a separate table for an instance of the object within this array | +| isOrIsNot | boolean | What does this turn on or off? | +| optionalParam | boolean | Optional, defaults to `something`. What difference does it make? | + + #### Response @@ -73,7 +73,6 @@ If there are optional paramaters which need a more detailed explanation, it shou "key": "value", } ``` - @@ -115,3 +114,7 @@ This and other errors all sit within the same `CollapsibleSection` tags. ``` + + +View the source code at: https://github.com/KomodoPlatform/repo/blob/branch/folder/file.ext + \ No newline at end of file diff --git a/utils/_fileData.json b/utils/_fileData.json index 7cee713f..a62ea6d6 100644 --- a/utils/_fileData.json +++ b/utils/_fileData.json @@ -29,7 +29,7 @@ } }, "/antara/api/channels": { - "dateModified": "2023-09-11T05:33:19.000Z", + "dateModified": "2023-09-09T21:56:24.000Z", "contributors": [ { "name": "\"gcharang\"", @@ -1523,7 +1523,7 @@ } }, "/atomicdex/api/common_structures/activation": { - "dateModified": "2023-10-05T07:16:36.000Z", + "dateModified": "2024-02-25T08:36:44.000Z", "contributors": [ { "name": "\"smk762\"", @@ -1536,7 +1536,7 @@ } }, "/atomicdex/api/common_structures": { - "dateModified": "2023-12-22T05:16:08.000Z", + "dateModified": "2024-02-25T08:36:44.000Z", "contributors": [ { "name": "\"smk762\"", @@ -1549,24 +1549,24 @@ } }, "/atomicdex/api/common_structures/lightning": { - "dateModified": "2023-11-10T06:44:47.000Z", + "dateModified": "2024-02-25T07:56:30.000Z", "contributors": [ - { - "name": "\"gcharang\"", - "email": "21151592+gcharang@users.noreply.github.com" - }, { "name": "\"smk762\"", "email": "smk762@iinet.net.au" + }, + { + "name": "\"gcharang\"", + "email": "21151592+gcharang@users.noreply.github.com" } ], "lastContributor": { - "name": "\"gcharang\"", - "email": "21151592+gcharang@users.noreply.github.com" + "name": "\"smk762\"", + "email": "smk762@iinet.net.au" } }, "/atomicdex/api/common_structures/nfts": { - "dateModified": "2023-10-04T08:31:28.000Z", + "dateModified": "2024-02-25T08:36:44.000Z", "contributors": [ { "name": "\"smk762\"", @@ -1631,12 +1631,8 @@ } }, "/atomicdex/api": { - "dateModified": "2023-10-04T06:26:45.000Z", + "dateModified": "2023-11-23T06:27:52.000Z", "contributors": [ - { - "name": "\"gcharang\"", - "email": "gcharang@users.noreply.github.com" - }, { "name": "\"smk762\"", "email": "smk762@iinet.net.au" @@ -1645,6 +1641,10 @@ "name": "\"gcharang\"", "email": "21151592+gcharang@users.noreply.github.com" }, + { + "name": "\"gcharang\"", + "email": "gcharang@users.noreply.github.com" + }, { "name": "\"gaeacodes\"", "email": "gaeacodes@gmail.com" @@ -1659,8 +1659,8 @@ } ], "lastContributor": { - "name": "\"gcharang\"", - "email": "gcharang@users.noreply.github.com" + "name": "\"smk762\"", + "email": "smk762@iinet.net.au" } }, "/atomicdex/api/legacy/active_swaps": { @@ -1751,12 +1751,8 @@ } }, "/atomicdex/api/legacy/batch_requests": { - "dateModified": "2023-10-06T04:54:44.000Z", + "dateModified": "2023-09-09T13:48:49.000Z", "contributors": [ - { - "name": "\"smk762\"", - "email": "smk762@iinet.net.au" - }, { "name": "\"gcharang\"", "email": "21151592+gcharang@users.noreply.github.com" @@ -1769,14 +1765,18 @@ "name": "\"gaeacodes\"", "email": "gaeacodes@gmail.com" }, + { + "name": "\"smk762\"", + "email": "smk762@iinet.net.au" + }, { "name": "\"gcharang\"", "email": "mrgcharang@gmail.com" } ], "lastContributor": { - "name": "\"smk762\"", - "email": "smk762@iinet.net.au" + "name": "\"gcharang\"", + "email": "21151592+gcharang@users.noreply.github.com" } }, "/atomicdex/api/legacy/best_orders": { @@ -3256,7 +3256,7 @@ } }, "/atomicdex/api/v20/enable_bch_with_tokens": { - "dateModified": "2023-10-05T07:16:36.000Z", + "dateModified": "2024-02-25T08:36:44.000Z", "contributors": [ { "name": "\"smk762\"", @@ -3314,7 +3314,7 @@ } }, "/atomicdex/api/v20/enable_eth_with_tokens": { - "dateModified": "2023-10-05T07:16:36.000Z", + "dateModified": "2024-02-25T08:36:44.000Z", "contributors": [ { "name": "\"smk762\"", @@ -3401,7 +3401,7 @@ } }, "/atomicdex/api/v20/enable_tendermint_with_assets": { - "dateModified": "2023-10-05T07:16:36.000Z", + "dateModified": "2024-02-25T08:36:44.000Z", "contributors": [ { "name": "\"smk762\"", @@ -3534,16 +3534,24 @@ } }, "/atomicdex/api/v20": { - "dateModified": "2023-10-04T08:31:28.000Z", + "dateModified": "2024-02-25T07:56:30.000Z", "contributors": [ { "name": "\"smk762\"", "email": "smk762@iinet.net.au" }, + { + "name": "\"laruh\"", + "email": "oblomoff616@gmail.com" + }, { "name": "\"gaeacodes\"", "email": "gaeacodes@gmail.com" }, + { + "name": "\"laruh\"", + "email": "laruh@users.noreply.github.com" + }, { "name": "\"gcharang\"", "email": "21151592+gcharang@users.noreply.github.com" @@ -4235,6 +4243,130 @@ "email": "smk762@users.noreply.github.com" } }, + "/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_list": { + "dateModified": "2024-02-25T08:36:44.000Z", + "contributors": [ + { + "name": "\"smk762\"", + "email": "smk762@iinet.net.au" + } + ], + "lastContributor": { + "name": "\"smk762\"", + "email": "smk762@iinet.net.au" + } + }, + "/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_metadata": { + "dateModified": "2024-02-25T08:36:44.000Z", + "contributors": [ + { + "name": "\"smk762\"", + "email": "smk762@iinet.net.au" + } + ], + "lastContributor": { + "name": "\"smk762\"", + "email": "smk762@iinet.net.au" + } + }, + "/atomicdex/api/v20-dev/non_fungible_tokens/get_nft_transfers": { + "dateModified": "2024-02-25T08:36:44.000Z", + "contributors": [ + { + "name": "\"smk762\"", + "email": "smk762@iinet.net.au" + } + ], + "lastContributor": { + "name": "\"smk762\"", + "email": "smk762@iinet.net.au" + } + }, + "/atomicdex/api/v20-dev/non_fungible_tokens": { + "dateModified": "2023-12-04T12:57:01.000Z", + "contributors": [ + { + "name": "\"smk762\"", + "email": "smk762@iinet.net.au" + }, + { + "name": "\"gcharang\"", + "email": "21151592+gcharang@users.noreply.github.com" + }, + { + "name": "\"laruh\"", + "email": "oblomoff616@gmail.com" + }, + { + "name": "\"laruh\"", + "email": "laruh@users.noreply.github.com" + }, + { + "name": "\"smk762\"", + "email": "35845239+smk762@users.noreply.github.com" + } + ], + "lastContributor": { + "name": "\"smk762\"", + "email": "smk762@iinet.net.au" + } + }, + "/atomicdex/api/v20-dev/non_fungible_tokens/query_nft_database_tables": { + "dateModified": "2024-02-27T17:32:37.000Z", + "contributors": [ + { + "name": "\"gcharang\"", + "email": "21151592+gcharang@users.noreply.github.com" + }, + { + "name": "\"smk762\"", + "email": "smk762@iinet.net.au" + } + ], + "lastContributor": { + "name": "\"gcharang\"", + "email": "21151592+gcharang@users.noreply.github.com" + } + }, + "/atomicdex/api/v20-dev/non_fungible_tokens/refresh_nft_metadata": { + "dateModified": "2023-12-04T18:03:09.000Z", + "contributors": [ + { + "name": "\"smk762\"", + "email": "smk762@iinet.net.au" + } + ], + "lastContributor": { + "name": "\"smk762\"", + "email": "smk762@iinet.net.au" + } + }, + "/atomicdex/api/v20-dev/non_fungible_tokens/update_nft": { + "dateModified": "2023-12-04T14:26:29.000Z", + "contributors": [ + { + "name": "\"smk762\"", + "email": "smk762@iinet.net.au" + } + ], + "lastContributor": { + "name": "\"smk762\"", + "email": "smk762@iinet.net.au" + } + }, + "/atomicdex/api/v20-dev/non_fungible_tokens/withdraw_nft": { + "dateModified": "2024-02-25T08:36:44.000Z", + "contributors": [ + { + "name": "\"smk762\"", + "email": "smk762@iinet.net.au" + } + ], + "lastContributor": { + "name": "\"smk762\"", + "email": "smk762@iinet.net.au" + } + }, "/atomicdex/api/v20-dev/task_account_balance": { "dateModified": "2023-09-27T20:43:30.000Z", "contributors": [ diff --git a/utils/js/package-lock.json b/utils/js/package-lock.json index f27d459e..443c5854 100644 --- a/utils/js/package-lock.json +++ b/utils/js/package-lock.json @@ -562,6 +562,19 @@ "integrity": "sha512-d0XxK3YTObnWVp6rZuev3c49+j4Lo8g4L1ZRm9z5L0xpoZycUPshHgczK5gsUMaZOstjVYYi09p5gYvUtfChYw==", "dev": true }, + "node_modules/mdast-util-from-markdown/node_modules/mdast-util-to-string": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/mdast-util-to-string/-/mdast-util-to-string-3.2.0.tgz", + "integrity": "sha512-V4Zn/ncyN1QNSqSBxTrMOLpjr+IKdHl2v3KVLoWmDPscP4r9GcCi71gjgvUV1SFSKh92AjAG4peFuBl2/YgCJg==", + "dev": true, + "dependencies": { + "@types/mdast": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, "node_modules/mdast-util-gfm": { "version": "2.0.2", "resolved": "https://registry.npmjs.org/mdast-util-gfm/-/mdast-util-gfm-2.0.2.tgz", @@ -796,6 +809,19 @@ "integrity": "sha512-d0XxK3YTObnWVp6rZuev3c49+j4Lo8g4L1ZRm9z5L0xpoZycUPshHgczK5gsUMaZOstjVYYi09p5gYvUtfChYw==", "dev": true }, + "node_modules/mdast-util-to-markdown/node_modules/mdast-util-to-string": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/mdast-util-to-string/-/mdast-util-to-string-3.2.0.tgz", + "integrity": "sha512-V4Zn/ncyN1QNSqSBxTrMOLpjr+IKdHl2v3KVLoWmDPscP4r9GcCi71gjgvUV1SFSKh92AjAG4peFuBl2/YgCJg==", + "dev": true, + "dependencies": { + "@types/mdast": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, "node_modules/mdast-util-to-markdown/node_modules/unist-util-is": { "version": "5.2.1", "resolved": "https://registry.npmjs.org/unist-util-is/-/unist-util-is-5.2.1.tgz", @@ -839,12 +865,80 @@ } }, "node_modules/mdast-util-to-string": { - "version": "3.2.0", - "resolved": "https://registry.npmjs.org/mdast-util-to-string/-/mdast-util-to-string-3.2.0.tgz", - "integrity": "sha512-V4Zn/ncyN1QNSqSBxTrMOLpjr+IKdHl2v3KVLoWmDPscP4r9GcCi71gjgvUV1SFSKh92AjAG4peFuBl2/YgCJg==", + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/mdast-util-to-string/-/mdast-util-to-string-4.0.0.tgz", + "integrity": "sha512-0H44vDimn51F0YwvxSJSm0eCDOJTRlmN0R1yBh4HLj9wiV1Dn0QoXGbvFAWj2hSItVTlCmBF1hqKlIyUBVFLPg==", "dev": true, "dependencies": { - "@types/mdast": "^3.0.0" + "@types/mdast": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-to-string/node_modules/@types/mdast": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/@types/mdast/-/mdast-4.0.0.tgz", + "integrity": "sha512-YLeG8CujC9adtj/kuDzq1N4tCDYKoZ5l/bnjq8d74+t/3q/tHquJOJKUQXJrLCflOHpKjXgcI/a929gpmLOEng==", + "dev": true, + "dependencies": { + "@types/unist": "*" + } + }, + "node_modules/mdx-annotations": { + "version": "0.1.3", + "resolved": "https://registry.npmjs.org/mdx-annotations/-/mdx-annotations-0.1.3.tgz", + "integrity": "sha512-2XrOlQeBDUa8GirNHy/Y7BR1h/P+vzk+1G2rzAfqJ+lg6JcEOKMCqsVkpVFSw0hdzpVuj9BnoNeA+aU1XPTkoA==", + "dev": true, + "dependencies": { + "acorn": "^8.8.1", + "estree-util-visit": "^1.2.0", + "unist-util-visit": "^4.1.1" + } + }, + "node_modules/mdx-annotations/node_modules/@types/unist": { + "version": "2.0.8", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-2.0.8.tgz", + "integrity": "sha512-d0XxK3YTObnWVp6rZuev3c49+j4Lo8g4L1ZRm9z5L0xpoZycUPshHgczK5gsUMaZOstjVYYi09p5gYvUtfChYw==", + "dev": true + }, + "node_modules/mdx-annotations/node_modules/unist-util-is": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/unist-util-is/-/unist-util-is-5.2.1.tgz", + "integrity": "sha512-u9njyyfEh43npf1M+yGKDGVPbY/JWEemg5nH05ncKPfi+kBbKBJoTdsogMu33uhytuLlv9y0O7GH7fEdwLdLQw==", + "dev": true, + "dependencies": { + "@types/unist": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdx-annotations/node_modules/unist-util-visit": { + "version": "4.1.2", + "resolved": "https://registry.npmjs.org/unist-util-visit/-/unist-util-visit-4.1.2.tgz", + "integrity": "sha512-MSd8OUGISqHdVvfY9TPhyK2VdUrPgxkUtWSuMHF6XAAFuL4LokseigBnZtPnJMu+FbynTkFNnFlyjxpVKujMRg==", + "dev": true, + "dependencies": { + "@types/unist": "^2.0.0", + "unist-util-is": "^5.0.0", + "unist-util-visit-parents": "^5.1.1" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdx-annotations/node_modules/unist-util-visit-parents": { + "version": "5.1.3", + "resolved": "https://registry.npmjs.org/unist-util-visit-parents/-/unist-util-visit-parents-5.1.3.tgz", + "integrity": "sha512-x6+y8g7wWMyQhL1iZfhIPhDAs7Xwbn9nRosDXl7qoPTSCy0yNxnKc+hWokFifWQIDGi154rdUqKvbCa4+1kLhg==", + "dev": true, + "dependencies": { + "@types/unist": "^2.0.0", + "unist-util-is": "^5.0.0" }, "funding": { "type": "opencollective",