Swap overview

Swap settlement method

Settlement of the trade by direct swap using third-party contracts.

Actors

Trader

A protocol user who performs the token exchange.

Resolver

Service providing a token exchange rate, also known as Market Maker.

WebSocket API

Data types used:

• Blockchain Number. Blockchain code as defined by SLIP-044. (https://github.com/satoshilabs/slips/blob/master/slip-0044.md) For TON, it is 607.

• Address Object. It consists two fields:

• blockhain - blockhain of the asset,

• address - address of assets, wallets in specified Blockchain.

For example:

{
  "blockchain": 607,
  "address": "EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO"
}

• Amount String. Amount of assets in units.

• SettlementMethod Number. The method of trade settlement. Value of enum of settlement methods. Currently, supports only Swap settlement method, which is 0.

• Protocol String. The protocol of swap settlement. Now it supports only StonFiV1 = 0, DeDust = 1

• Number Integer number.

API Methods

Every method name contains version of API. Now it is v1beta4.

Method asset.query

Allows you to get a list of available assets. Sample:

{
    "jsonrpc": "2.0",
    "id": "3",
    "method": "v1beta4.asset.query",
    "params": {}
}

The response consists: Object assets that consist a blockchain specific asset list. Each asset info consists:

Name	Type	Description
address	Address	Address of an asset
tags	Array(String)	Tags of asset
symbol	String	Symbol of an asset
name	String	Name of an asset
image_url	String	Asset's image url
decimals	Number	The number of decimals the asset uses - e.g. 8, means to divide the asset amount by 100000000 to get its user representation. If not specified, 9 is used by default.
metadata	Object	Custom medata of the asset

Sample:

{
  "jsonrpc": "2.0",
  "result": {
    "assets": [
      {
        "address": {
          "blockchain": 607,
          "address": "EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c"
        },
        "tags": [
          "native"
        ],
        "symbol": "TON",
        "name": "TON",
        "image_url": "https://asset-stage.ston.fi/img/EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c/4ecd4687e0b5b8ff21a7fbe03f9d281c26a2dc13eac7b7d16048cc693fe0ec39",
        "decimals": 9,
        "metadata": {}
      },
      {
        "address": {
          "blockchain": 607,
          "address": "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs"
        },
        "tags": [],
        "symbol": "USDT",
        "name": "Tether USD",
        "image_url": "https://assets.dedust.io/images/usdt.webp",
        "decimals": 6,
        "metadata": {}
      },
      {
        "address": {
          "blockchain": 607,
          "address": "EQBlqsm144Dq6SjbPI4jjZvA1hqTIP3CvHovbIfW_t-SCALE"
        },
        "tags": [],
        "symbol": "SCALE",
        "name": "Scaleton",
        "image_url": "https://assets.dedust.io/images/scale.webp",
        "decimals": 9,
        "metadata": {}
      }
    ]
  },
  "id": "1"
}

Subscription method quote

Allows you to create a new request for quote (RFQ).

Accepts the following parameters as input:

Name	Type	Description
offer_asset_address	Address	Blockchain-specific address of offer asset.
ask_asset_address	Address	Blockchain-specific address of ask asset.
amount	Amount	Either the amount of offer asset or ask asset: offer_units - The amount of offer asset the trader wants to pay, including all fees. ask_units - The amount of ask asset the trader wants to get after all fees.
referrer_address	Address	The address of referrer that will receive the fees or empty string if referrer is not specified.
referrer_fee_bps	Number	The amount of fees required by the referrer in basis points (1/10000 or 0.01%)
settlement_methods	Array(SettlementMethod)	Supported methods of swap settlement. The protocol limits settlement methods in quotes to specified methods. Different combinations of offer & ask chains might support different methods.

Sample:

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "v1beta4.quote",
  "params": {
    "offer_asset_address": {
      "blockchain": 607,
      "address": "EQDB8JYMzpiOxjCx7leP5nYkchF72PdbWT1LV7ym1uAedINh"
    },
    "amount": {
      "ask_units": "1000"
    },
    "ask_asset_address": {
      "blockchain": 607,
      "address": "EQCH-yP4S3nA_j7K7EIV1QIhVTWMyNJfxeYzacUH76ks2hUF"
    },
    "referrer_address": {
      "blockchain": 607,
      "address": "EQCXSs2xZ2dhk9TAxzGzXra2EbG_S2SqyN8Tfi6fJ82EYiVj"
    },
    "referrer_fee_bps": 10,
    "settlement_methods": [
      0
    ]
  }
}

After the request (RFQ), the channel will start receiving quote_updated events from resolvers, which consist of a quote. A Quote in the channel is updated if a more profitable deal for the trader comes in. The Quote includes the following fields:

Name	Type	Description
quote_id	String	ID of the quote generated by the platform
resolver_id	String	ID of the Resolver
resolver_name	String	Name of the Resolver
offer_asset_address	Address	Blockchain-specific address of offer asset.
ask_asset_address	Address	Blockchain-specific address of ask asset.
offer_units	Amount	The amount of offer asset the trader must pay, including all fees.
ask_units	Amount	The amount of ask asset the trader will get after all fees.
quote_timestamp	Number	The timestamp (UTC seconds) of Quote sent by resolver.
referrer_address	Address	The address of referrer that will receive the fees or empty string if referrer is not specified.
referrer_fee_bps	Number	The amount of fees that the referrer will get (in units of offer_asset_address).
protocol_fee_units	Number	The amount of fees charged by the protocol (in units of offer_asset_address).
params	Object	Additional parameters specific to settlement method. Details see below

For Swap settlement method the params is:

Name	Type	Description
routes	Array(SwapRoute)	Array of Swap routes

Object SwapRoute:

Name	Type	Description
steps	Array(SwapStep)	Array of Swap steps
gas_budget	Amount	The amount of gas budget to complete transfer
extra_data_json	String	The extra data specified by protocol of swap in JSON format

Object SwapStep:

Name	Type	Description
offer_asset_address	Address	Blockchain-specific address of offer asset.
ask_asset_address	Address	Blockchain-specific address of ask asset.
chunks	Array(SwapChunk)	Array of swap chunks
extra_data_json	String	The extra data specified by protocol of swap in JSON format

Object SwapChunk:

Name	Type	Description
protocol	Protocol	Protocol of this swap operation
offer_amount	Amount	The amount of offer asset the trader must pay, including all fees.
ask_amount	Amount	The expected amount of ask asset the trader will get after all fees.
extra_data_json	String	The extra data specified by protocol of swap in JSON format

Sample:

{
  "jsonrpc": "2.0",
  "method": "event",
  "params": {
    "subscription": 608688935135881,
    "result": {
      "event": {
        "quote_updated": {
          "quote_id": "98616cab2097d3f9e64e9447f2f3b736",
          "offer_asset_address": {
            "blockchain": 607,
            "address": "EQAIcb1WqNr0E7rOXgO0cbAZQnVbS06mgH2vgBvtBE6p0T2a"
          },
          "ask_asset_address": {
            "blockchain": 607,
            "address": "EQDk2VTvn04SUKJrW7rXahzdF8_Qi6utb0wj43InCu9vdjrR"
          },
          "offer_units": "100000",
          "ask_units": "33757",
          "quote_timestamp": 1723144166,
          "referrer_address": {
            "blockchain": 607,
            "address": "EQCXSs2xZ2dhk9TAxzGzXra2EbG_S2SqyN8Tfi6fJ82EYiVj"
          },
          "referrer_fee_units": "0",
          "protocol_fee_units": "0",
          "params": {
            "swap": {
              "routes": [
                {
                  "steps": [
                    {
                      "offer_asset_address": {
                        "blockchain": 607,
                        "address": "EQAIcb1WqNr0E7rOXgO0cbAZQnVbS06mgH2vgBvtBE6p0T2a"
                      },
                      "ask_asset_address": {
                        "blockchain": 607,
                        "address": "EQDk2VTvn04SUKJrW7rXahzdF8_Qi6utb0wj43InCu9vdjrR"
                      },
                      "chunks": [
                        {
                          "protocol": "StonFiV1",
                          "offer_amount": "100000",
                          "ask_amount": "33757",
                          "extra_data_json": "{\"router_address\": \"EQCezwB0TIDf-4__Lo4OSTCERAOWKnR9E5IUA-vjS7UbVvyA\"}"
                        }
                      ],
                      "extra_data_json": ""
                    }
                  ],
                  "gas_budget": "300000000",
                  "extra_data_json": ""
                }
              ]
            }
          }
        }
      }
    }
  }
}

Subscription method trade.track

Method that allows you to track the status of a token exchange.

Accepts the following parameters as input:

Name	Type	Description
quote_id	String	ID of the quote
trader_wallet_address	Address	The address of trader's wallet that initiated transaction

Sample:

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "v1beta4.trade.track",
  "params": {
    "quote_id": "cf1f9bf159a26a7be14616da637882df",
    "trader_wallet_address": {
      "blockchain": 607,
      "address": "0QCXSs2xZ2dhk9TAxzGzXra2EbG_S2SqyN8Tfi6fJ82EYsMs"
    }
  }
}

The channel will start receiving records about the current status of the transfer. The following statuses are available for the SWAP method:

Name	Description	Fields
awaiting_transfer	Waiting for the trader to initiate the trade.
transferring	Initial transaction found, waiting for transfer of funds to complete.	outgoing_tx_hash - Hash of transaction that initiated the trade.
filling_trade	Awaiting trade to fill. For SWAP: awaiting swap transactions in the pools.	outgoing_tx_hash - Hash of transaction that initiated the trade. routes - Info about partial filling of the trade. Array of RouteStatus
trade_settled	The trade has completed (fully or partially filled or fully aborted)	result - Result of the trade: - 0 - Unknown - 1 - fully filled - 2 - partially filled - 3 - aborted routes - Info about partial filling of the trade. Array of RouteStatus

Object RouterStatus consists:

steps - Array of StepStatus objects

Object StepStatus consists:

chunks - Array of ChunkStatus objects

Object ChunkStatus:

Name	Type	Description
target_address	Address	Address of the contract that processes this chunk. Generally, this address receives offer tokens. More specifically, it might be the address of a protocol or liquidity pool.
offer_units	Amount	The amount of offer asset was transferred from trader wallet
expected_ask_units	Amount	The expected amount of ask asset will be transferred to trader wallet
actual_ask_units	Amount	The actual amount of ask asset was transferred to trader wallet
result	Number	Result of the chunk: - 0 - Processing - 1 - Filled - 2 - Aborted
result_details_json	String	The extra data in JSON format

Samples:

{
  "jsonrpc": "2.0",
  "method": "status",
  "params": {
    "subscription": 4374307320472544,
    "result": {
      "status": {
        "awaiting_transfer": {}
      }
    }
  }
}

{
  "jsonrpc": "2.0",
  "method": "status",
  "params": {
    "subscription": 8556742379230871,
    "result": {
      "status": {
        "transferring": {
          "outgoing_tx_hash": "b35fb27b0aa9867e4072905cb967c3d08c6be8b0a66398fe08d2a72cb7c45082"
        }
      }
    }
  }
}

{
  "jsonrpc": "2.0",
  "method": "status",
  "params": {
    "subscription": 8556742379230871,
    "result": {
      "status": {
        "trade_settled": {
          "result": 1,
          "routes": [
            {
              "steps": [
                {
                  "chunks": [
                    {
                      "target_address": {
                        "blockchain": 607,
                        "address": "EQACpXPHyLueReUMCmStesRXA77IK_ZAhHnLKAsQ5MjMUliK"
                      },
                      "offer_units": "1000000",
                      "expected_ask_units": "3379",
                      "actual_ask_units": "3378",
                      "result": 1,
                      "result_details_json": "{\"exit_code\":3326308581}"
                    }
                  ]
                }
              ]
            }
          ]
        }
      }
    }
  }
}

Method transaction.build_transfer

A request to generate unsigned transfer to initiate the trade.

Accepts the following parameters as input:

Name	Type	Description
source_address	Address	The address on offer_blockchain that will send initial transaction to start the trade
destination_address	Address	The address on ask_blockchain that will receive result of the trade
max_slippage_bps	Number	Max price slippage in basis points (0.01%)
quote	Quote	The valid quote received from quote subscription

Sample:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "v1beta4.transaction.build_transfer",
  "params": {
    "source_address": {
      "blockchain": 607,
      "address": "0:02a573c7c8bb9e45e50c0a64ad7ac45703bec82bf6408479cb280b10e4c8cc52"
    },
    "destination_address": {
      "blockchain": 607,
      "address": "0:02a573c7c8bb9e45e50c0a64ad7ac45703bec82bf6408479cb280b10e4c8cc52"
    },
    "quote": {
      "quote_id": "3d1d9ad4656f883ce63cb80c67b8698c",
      "offer_asset_address": {
        "blockchain": 607,
        "address": "EQAIcb1WqNr0E7rOXgO0cbAZQnVbS06mgH2vgBvtBE6p0T2a"
      },
      "ask_asset_address": {
        "blockchain": 607,
        "address": "EQDk2VTvn04SUKJrW7rXahzdF8_Qi6utb0wj43InCu9vdjrR"
      },
      "offer_units": "100000000",
      "ask_units": "33787874",
      "quote_timestamp": 1723146414,
      "referrer_address": "",
      "referrer_fee_units": "0",
      "protocol_fee_units": "0",
      "params": {
        "swap": {
          "routes": [
            {
              "steps": [
                {
                  "offer_asset_address": {
                    "blockchain": 607,
                    "address": "EQAIcb1WqNr0E7rOXgO0cbAZQnVbS06mgH2vgBvtBE6p0T2a"
                  },
                  "ask_asset_address": {
                    "blockchain": 607,
                    "address": "EQDk2VTvn04SUKJrW7rXahzdF8_Qi6utb0wj43InCu9vdjrR"
                  },
                  "chunks": [
                    {
                      "protocol": 0,
                      "offer_amount": "100000",
                      "ask_amount": "33757",
                      "extra_data_json": "{\"router_address\": \"EQCezwB0TIDf-4__Lo4OSTCERAOWKnR9E5IUA-vjS7UbVvyA\"}"
                    }
                  ],
                  "extra_data_json": ""
                }
              ],
              "gas_budget": "300000000",
              "extra_data_json": ""
            }
          ]
        }
      }
    },
    "max_slippage_bps": 500
  }
}

The response consists:

Object transaction that consist a blockchain specific transaction object, for TON it is:

Name	Type	Description
messages	Array(Message)	Array of transfer messages

Object Message is:

• target_address - String. Represents the address of the recipient wallet. This address is where the transfer will be directed.

• send_amount - Number. Specifies the amount of gas required to complete the transfer. This value determines the computational resources allocated for the transaction.

• payload - String. Contains the hex-encoded data to be sent along with the transfer. This payload can include transaction details or other relevant information in a hexadecimal format.

{
  "jsonrpc": "2.0",
  "result": {
    "transaction": {
      "ton": {
        "messages": [
          {
            "target_address": "EQCJ7SWUt1weFuOCN32XNzT6dOM2stAe2LZZtOelF0hyoIRv",
            "send_amount": "300000000",
            "payload": "b5ee9c7241010201008800016d0f8a7ea5e63cb80c67b8698c405f5e1008013d9e00e89901bff71ffe5d1c1c92610888072c54e8fa27242807d7c6976a36ac103b9aca0301009725938561801af7bf08bea0d52dcdcf23d2c039f33a4184f23406bf0351e922a6bf6431e78ba803d391610000a95cf1f22ee791794302992b5eb115c0efb20afd90211e72ca02c43932331490056baf1e"
          }
        ]
      }
    }
  },
  "id": 3
}