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 of two fields:

• blockchain - blockchain of the asset,

• address - address of assets, wallets in the 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 Number. The protocol of swap settlement. Currently, it supports:

  • StonFiV1 = 1: STON.fi DEX v1 protocol

  • StonFiV2 = 2: STON.fi DEX v2 protocol

  • DeDust = 3: DeDust DEX protocol

• Number Integer number.

• RequestSettlementParams Object. Additional parameters for the quote request (RFQ):

  • max_price_slippage_bps: Maximum price slippage, in basis points (0.01%). For example, 100 = 1% slippage.

  • max_outgoing_messages: Maximum number of outgoing messages supported by the wallet. For TON blockchain, this defaults to 4 if omitted.

  Note: These parameters are general RFQ settings and may be used across different settlement methods. They are not specific to any particular settlement method.

• SwapSettlementParams Object. Settlement parameters specific to the swap settlement method. This type is used in the Quote's params field when the settlement method is swap. Contains:

  • routes: Array of SwapRoute objects that define the possible paths for the swap.

  Each SwapRoute consists of:

  • steps: Array of SwapStep objects describing each step in the swap route

  • gas_budget: String indicating the gas budget to complete the transfer

  Each SwapStep contains:

  • offer_asset_address: Address object for the asset being offered

  • ask_asset_address: Address object for the asset being requested

  • chunks: Array of SwapChunk objects breaking down the swap into smaller operations

  Each SwapChunk represents a single swap operation:

  • protocol: Protocol used for this swap operation (e.g., "1")

  • offer_amount: Amount of the offered asset

  • ask_amount: Expected amount of the asked asset

  • extra_version: Version of the extra data format

  • extra: Protocol-specific data as a base64-encoded byte array

• quote_id String. A 32-byte identifier of the quote.

API Methods

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

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": "v1beta6.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],
    "settlement_params": {
      "max_price_slippage_bps": 100,
      "max_outgoing_messages": 4
    }
  }
}

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 (32 bytes)
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

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

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_version	Number	Version of the extra data format
extra	bytes	Bytes array used by the underlying protocol to coordinate the swap. In JSON form, it is typically base64-encoded. It is not JSON.

For more details on how to populate or interpret the extra field for these protocols, see the (Swap Extra doc).

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": "1",
                          "offer_amount": "100000",
                          "ask_amount": "33757",
                          "extra_version": 1,
                          "extra": "SGVsbG8sIHRoaXMgaXMgYW4gZXhhbXBsZSBiYXNlNjQgZW5jb2RlZCBzdHJpbmcgZm9yIHRoZSBleHRyYSBmaWVsZC4="
                        }
                      ]
                    }
                  ],
                  "gas_budget": "300000000"
                }
              ]
            }
          }
        }
      }
    }
  }
}

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	(32 bytes) ID of the quote
trader_wallet_address	Address	The address of trader's wallet that initiated transaction
outgoing_tx_hash	String	Hash of the transaction that initiated the trade

Sample:

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

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

Status	Description	Additional Fields
awaiting_transfer	Waiting for the trader to initiate the trade.
transferring	Initial transaction found, waiting for transfer of funds to complete.
swapping	(SWAP method only) Awaiting swap transactions in the pools.	routes - Info about partial filling of the trade. Array of RouteStatus.
awaiting_fill	(ESCROW / HTLC only) Waiting for the trade to be filled.
claim_available	(HTLC only) Resolver's deposit is claimable.
refund_available	(ESCROW / HTLC) Deposit timeout has expired, need to refund it.
receiving_funds	The transaction with incoming funds found, waiting for it to mine.	routes - Info about partial filling of the trade.
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 Descriptions

RouteStatus

• steps - Array of StepStatus objects.

StepStatus

• chunks - Array of ChunkStatus objects.

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 transferred from trader wallet
expected_ask_units	Amount	The expected amount of ask asset to be transferred to trader wallet
actual_ask_units	Amount	The actual amount of ask asset transferred to trader wallet
result	Number	Result of the chunk: - 0 - Processing - 1 - Filled - 2 - Aborted
protocol	Protocol	Protocol of this swap operation
tx_hash	String	Hash of the transaction that executed this chunk

Samples:

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

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

{
  "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,
                      "protocol": "1",
                      "tx_hash": "97c06867d0e891369fa0f621e0b7d549c888af8f34e4bde6752d580c6da508c2"
                    }
                  ]
                }
              ]
            }
          ]
        }
      }
    }
  }
}

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
quote	Quote	The valid quote received from quote subscription

Sample:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "v1beta6.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": "SGVsbG8sIHRoaXMgaXMgYW4gZXhhbXBsZSBiYXNlNjQgZW5jb2RlZCBzdHJpbmcgZm9yIHRoZSBleHRyYSBmaWVsZC4=",
                      "extra_version": 1
                    }
                  ]
                }
              ],
              "gas_budget": "300000000"
            }
          ]
        }
      }
    }
  }
}

The response contains a ton object with the blockchain-specific transaction data:

Name	Type	Description
ton	Object	Contains TON-specific transaction data
ton.messages	Array(Message)	Array of messages to be sent

Each Message object contains:

Name	Type	Description
target_address	String	The address of the recipient
send_amount	String	Amount in nanotons to send as attached value
payload	String	Hex-encoded or base64-encoded transaction data

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