# Overview (Swap) > **💡 Recommended Approach**: For most integrations, we recommend using our [Node.js SDK](https://docs.ston.fi/developer-section/omniston/sdk/nodejs) or [React SDK](https://docs.ston.fi/developer-section/omniston/sdk/react). The SDKs handle WebSocket connections, quote streaming, transaction building, and error handling automatically. The documentation below is for developers who need low-level protocol access or are implementing in other languages. ### WebSocket Base Endpoints (JSON-RPC) **Production:** `wss://omni-ws.ston.fi` **Sandbox:** `wss://omni-ws-sandbox.ston.fi` Use sandbox for development/testing only. ### 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 > **Note**: The WebSocket API details below are provided for reference. If you're implementing low-level integration, see our [Python Quickstart Guide](https://docs.ston.fi/developer-section/quickstart/python) for a complete working example. You can also explore the [open-source SDK repository](https://github.com/ston-fi/omniston-sdk) to study the actual low-level implementation code. Data types used: * **`Blockchain`**\ Number. Blockchain code as defined by SLIP-044. ( 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: ```json { "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`**\\ * **WebSocket API** uses a numeric code: * `StonFiV1` = 1 * `StonFiV2` = 2 * `DeDust` = 3 * `TonCo` = 4 For gRPC usage, see the [Resolver Integration Guide](https://docs.ston.fi/developer-section/omniston/resolvers/guide). * **`GaslessSettlement`**\\ * **WebSocket API** uses a numeric code: * `GASLESS_SETTLEMENT_PROHIBITED` = 0 — Gasless settlement either unsupported or prohibited by trader. * `GASLESS_SETTLEMENT_POSSIBLE` = 1 — Gasless settlement is allowed if supported by the resolver. * `GASLESS_SETTLEMENT_REQUIRED` = 2 — Gasless settlement is mandatory. * **`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. * `gasless_settlement`: GaslessSettlement enum value specifying trader preference for gasless settlement (see GaslessSettlement above). * `flexible_referrer_fee`: Boolean flag allowing resolvers to lower the effective referrer fee below `referrer_fee_bps` when it yields a better swap rate. Defaults to `false`. See [Flexible Referrer Fee](https://docs.ston.fi/developer-section/referral-fees#flexible-referrer-fee) for details. 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: * `bid_asset_address`: Address object for the bid asset * `ask_asset_address`: Address object for the asset being requested * `chunks`: Array of `SwapChunk` objects describing each step in the swap route. **Note on Steps vs. Chunks**: * A "step" transforms from one asset to another (e.g. TON → USDC). * Each step may contain one or more "chunks," each representing an individual swap operation for that step. * On the TON blockchain, you will generally see exactly **one** chunk per step. We keep the ability to specify multiple chunks in a single step for other blockchains if needed. Each `SwapChunk` represents a single swap operation: * `protocol`: Protocol used for this swap operation. In this doc, numeric codes are used for the WebSocket API. For gRPC usage, see [Resolver Integration Guide](https://docs.ston.fi/developer-section/omniston/resolvers/guide). * `bid_amount`: Amount of the bid asset * `ask_amount`: Expected amount of the asked asset * `extra_version`: Currently, only `1` is supported. * `extra`: **Bytes array** used by the underlying protocol to coordinate the swap (base64-encoded in JSON). See [Swap Extra doc](https://docs.ston.fi/developer-section/omniston/swap/advanced) * **`quote_id`**\ String. A 32-byte identifier of the quote. ### API Methods Every method name contains version of API. The latest version is `v1beta7`. Previous versions may be supported for backward compatibility. #### Subscription method `quote` Allows you to create a new request for quote (`RFQ`). When you send a quote request, the server will: 1. **First**, immediately send a `QuoteRequestAck` message containing the `rfq_id` (a SHA-256 hex string) that uniquely identifies your quote request 2. **Then**, start sending `quote_updated` events from resolvers as quotes become available Accepts the following parameters as input: | Name | Type | Description | | ------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | bid\_asset\_address | Address | Blockchain-specific address of bid asset. | | ask\_asset\_address | Address | Blockchain-specific address of ask asset. | | amount | Amount |

Either the amount of bid asset or ask asset:
bid\_units - The amount of bid 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 bid & ask chains might support different methods. | Sample: ```json { "jsonrpc": "2.0", "id": "1", "method": "v1beta7.quote", "params": { "bid_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, "gasless_settlement": 1, "flexible_referrer_fee": false } } } ``` > **📘 Practical Example**: See the [Python Quickstart Guide](https://docs.ston.fi/developer-section/quickstart/python) for a complete implementation showing how to request quotes, handle responses, build transactions, and execute swaps. The Python code can be adapted to any programming language. **Quote Request Acknowledgment** Upon receiving your RFQ, the server immediately responds with: | Name | Type | Description | | ------- | ------ | ----------------------------------------------- | | rfq\_id | String | SHA-256 hex string uniquely identifying the RFQ | This acknowledgment confirms your request was received and is being processed. **Quote Updates** After the acknowledgment, 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 | | bid\_asset\_address | Address | Blockchain-specific address of bid asset. | | ask\_asset\_address | Address | Blockchain-specific address of ask asset. | | bid\_units | Amount | The amount of bid 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\_asset | Address | The asset of the fees that the referrer will get | | referrer\_fee\_units | Number | The amount of fees that the referrer will get (in units of `referrer_fee_asset`) | | protocol\_fee\_asset | Address | The asset of the fees charged by the protocol (always ASK jetton) | | protocol\_fee\_units | Number | The amount of fees charged by the protocol (in units of `protocol_fee_asset`, which is ASK jetton). | | 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 bid asset by the corresponding smart contract. The resolver may still settle the trades started after this deadline has passed at own discretion. | | estimated\_gas\_consumption | Number | Estimated amount of gas units that will be spent to perform the trade | | 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 | | min\_ask\_amount | Amount | Minimum amount to receive (filled by Omniston service) | | recommended\_min\_ask\_amount | Amount | Recommended minimum amount (filled by Omniston service) | | recommended\_slippage\_bps | Number | Recommended slippage in basis points | 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 | | ------------------- | ---------------- | ----------------------------------------- | | bid\_asset\_address | Address | Blockchain-specific address of bid 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 used for this swap operation. In this doc, numeric codes are used for the WebSocket API. For gRPC usage, see [Resolver Integration Guide](https://docs.ston.fi/developer-section/omniston/resolvers/guide). | | `bid_amount` | Amount | The amount of bid 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 | Currently, only `1` is supported. Attempts to use any other version will be rejected. | | `extra` | bytes | **Bytes array** used by the underlying protocol to coordinate the swap (base64-encoded in JSON). See [Swap Extra doc](https://docs.ston.fi/developer-section/omniston/swap/advanced) | For more details on how to populate or interpret the `extra` field for these protocols, see the ([Swap Extra doc](https://docs.ston.fi/developer-section/omniston/swap/advanced)). Sample: ```json { "jsonrpc": "2.0", "method": "event", "params": { "subscription": 608688935135881, "result": { "event": { "quote_updated": { "quote_id": "98616cab2097d3f9e64e9447f2f3b736", "bid_asset_address": { "blockchain": 607, "address": "EQAIcb1WqNr0E7rOXgO0cbAZQnVbS06mgH2vgBvtBE6p0T2a" }, "ask_asset_address": { "blockchain": 607, "address": "EQDk2VTvn04SUKJrW7rXahzdF8_Qi6utb0wj43InCu9vdjrR" }, "bid_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": [ { "bid_asset_address": { "blockchain": 607, "address": "EQAIcb1WqNr0E7rOXgO0cbAZQnVbS06mgH2vgBvtBE6p0T2a" }, "ask_asset_address": { "blockchain": 607, "address": "EQDk2VTvn04SUKJrW7rXahzdF8_Qi6utb0wj43InCu9vdjrR" }, "chunks": [ { "protocol": "StonFiV1", "bid_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: ```json { "jsonrpc": "2.0", "id": "1", "method": "v1beta7.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. | | | `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. | | | `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 bid tokens. More specifically, it might be the address of a protocol or liquidity pool. | | bid\_units | Amount | The amount of bid 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: ```json { "jsonrpc": "2.0", "method": "status", "params": { "subscription": 4374307320472544, "result": { "status": { "awaiting_transfer": {} } } } } ``` ```json { "jsonrpc": "2.0", "method": "status", "params": { "subscription": 8556742379230871, "result": { "status": { "transferring": {} } } } } ``` ```json { "jsonrpc": "2.0", "method": "status", "params": { "subscription": 8556742379230871, "result": { "status": { "trade_settled": { "result": 1, "routes": [ { "steps": [ { "chunks": [ { "target_address": { "blockchain": 607, "address": "EQACpXPHyLueReUMCmStesRXA77IK_ZAhHnLKAsQ5MjMUliK" }, "bid_units": "1000000", "expected_ask_units": "3379", "actual_ask_units": "3378", "result": 1, "protocol": "StonFiV1", "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 bid\_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 | | gas\_excess\_address | Address | The address that will receive the gas not spent by the trade | | refund\_address | Address | (Optional) The address where funds should be returned if the transaction fails. If not specified, funds are returned to the sender's wallet. Currently only works for swaps through STON.fi | | quote | Quote | The valid quote received from `quote` subscription | | use\_recommended\_slippage | Boolean | Use the slippage recommended by Omniston instead of trader-provided slippage | Sample: ```json { "jsonrpc": "2.0", "id": 3, "method": "v1beta7.transaction.build_transfer", "params": { "source_address": { "blockchain": 607, "address": "0:02a573c7c8bb9e45e50c0a64ad7ac45703bec82bf6408479cb280b10e4c8cc52" }, "destination_address": { "blockchain": 607, "address": "0:02a573c7c8bb9e45e50c0a64ad7ac45703bec82bf6408479cb280b10e4c8cc52" }, "gas_excess_address": { "blockchain": 607, "address": "0:02a573c7c8bb9e45e50c0a64ad7ac45703bec82bf6408479cb280b10e4c8cc52" }, "refund_address": { "blockchain": 607, "address": "0:02a573c7c8bb9e45e50c0a64ad7ac45703bec82bf6408479cb280b10e4c8cc52" }, "quote": { "quote_id": "3d1d9ad4656f883ce63cb80c67b8698c", "bid_asset_address": { "blockchain": 607, "address": "EQAIcb1WqNr0E7rOXgO0cbAZQnVbS06mgH2vgBvtBE6p0T2a" }, "ask_asset_address": { "blockchain": 607, "address": "EQDk2VTvn04SUKJrW7rXahzdF8_Qi6utb0wj43InCu9vdjrR" }, "bid_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": [ { "bid_asset_address": { "blockchain": 607, "address": "EQAIcb1WqNr0E7rOXgO0cbAZQnVbS06mgH2vgBvtBE6p0T2a" }, "ask_asset_address": { "blockchain": 607, "address": "EQDk2VTvn04SUKJrW7rXahzdF8_Qi6utb0wj43InCu9vdjrR" }, "chunks": [ { "protocol": 0, "bid_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 | ```json { "jsonrpc": "2.0", "result": { "ton": { "messages": [ { "target_address": "EQCJ7SWUt1weFuOCN32XNzT6dOM2stAe2LZZtOelF0hyoIRv", "send_amount": "300000000", "payload": "b5ee9c7241010201008800016d0f8a7ea5e63cb80c67b8698c405f5e1008013d9e00e89901bff71ffe5d1c1c92610888072c54e8fa27242807d7c6976a36ac103b9aca0301009725938561801af7bf08bea0d52dcdcf23d2c039f33a4184f23406bf0351e922a6bf6431e78ba803d391610000a95cf1f22ee791794302992b5eb115c0efb20afd90211e72ca02c43932331490056baf1e" } ] } }, "id": 3 } ``` *** ## Next Steps Choose your integration path based on your needs: | If you want to... | Use this | | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | Build a **frontend app** quickly | [React SDK](https://docs.ston.fi/developer-section/omniston/sdk/react) - Ready-to-use hooks | | Build a **backend service** or bot | [Node.js SDK](https://docs.ston.fi/developer-section/omniston/sdk/nodejs) - Full TypeScript support | | Implement in **Python** or another language | [Python Quickstart](https://docs.ston.fi/developer-section/quickstart/python) - Adapt to your language | | Study the **low-level implementation** | [SDK Source Code](https://github.com/ston-fi/omniston-sdk) - Open-source reference | | Understand the **protocol deeply** | Continue reading above and [Advanced Features](https://docs.ston.fi/developer-section/omniston/swap/advanced) | | Use **high-performance gRPC** | [gRPC Integration](https://docs.ston.fi/developer-section/omniston/swap/grpc) | ### SDK Quick Start ```bash # Node.js npm install @ston-fi/omniston-sdk # React npm install @ston-fi/omniston-sdk-react ``` See the [SDK documentation](https://docs.ston.fi/developer-section/omniston/sdk) for complete examples and API reference. > **💡 Open Source**: Our SDKs are fully open-source at [github.com/ston-fi/omniston-sdk](https://github.com/ston-fi/omniston-sdk). You can study the implementation, contribute improvements, or use it as a reference for building integrations in other languages.