1 of 1

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
}

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

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
    }
  }
}

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

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
}

Swap overview

Swap settlement method

Actors

Trader

Resolver

WebSocket API

API Methods

Subscription method quote

Subscription method trade.track

Object Descriptions

Method transaction.build_transfer

Swap overview

Swap settlement method

Actors

Trader

Resolver

WebSocket API

API Methods

Subscription method quote

Subscription method trade.track

Object Descriptions

Method transaction.build_transfer

Subscription method `quote`

Subscription method `trade.track`

Method `transaction.build_transfer`

Subscription method `quote`

Subscription method `trade.track`

Method `transaction.build_transfer`