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
}
PreviousHow to become a resolverNextReact

Last updated