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.
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).
quote_timestamp	Number	The timestamp (UTC seconds) of Quote sent by resolver.
trade_start_deadline	Number	Max timestamp (UTC seconds) of start of the trade. The start of the trade is defined as the reception of offer asset by the corresponding smart contract. The resolver may still settle the trades started after this deadline has passed at own discretion.
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",
          "referrer_address": {
            "blockchain": 607,
            "address": "EQCXSs2xZ2dhk9TAxzGzXra2EbG_S2SqyN8Tfi6fJ82EYiVj"
          },
          "referrer_fee_units": "0",
          "protocol_fee_units": "0",
          "quote_timestamp": 1723144166,
          "trade_start_deadline": 1723144766,
          "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",
      "referrer_address": "",
      "referrer_fee_units": "0",
      "protocol_fee_units": "0",
      "quote_timestamp": 1723146414,
      "trade_start_deadline": 1723144766,
      "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
}