1 of 6

OMNISTON

This section contains information about OMNISTON protocol

Overview

Omniston is a decentralized liquidity aggregation protocol designed specifically for TON Blockchain. It aggregates liquidity from various sources, including:

AMM DEXs
On-chain RFQ resolvers (TON)

The Request for Quote (RFQ) mechanism allows users to get the most competitive price quote from resolvers, including external DEX platforms.

Omniston demo App is live! See omniston.ston.fi

Key benefits

Omniston offers several advantages:

Provides users with the best pricing conditions
Access to a wide range of tokens across different liquidity sources within the ecosystem
Flexibility to set fees
Allows seamless integration by providing access to all liquidity sources in one unified platform, eliminating the need for third-party solutions

Use Case

For example, when a user wants to swap Token A for Token B, they initiate a swap request through Omniston. The protocol aggregates quotes from all connected liquidity sources, including external DEX platforms, and presents the user with the most favorable offer.

Swap

For instructions on performing a swap using the Omniston protocol, see the Swap overview.

SDK

Omniston SDK packages for developers:

Node.js SDK for JavaScript/TypeScript applications.
React SDK for use in React or Next.js applications.

Application

Source code for the demo App for application developers.

Resolvers (How to become a resolver)

This guide explains how to become a resolver (Market Maker) in the Omniston protocol and integrate with its gRPC API.

Overview

A resolver is a service that provides token exchange rates and executes trades. To become a resolver, you need to:

Register by obtaining a Soul-Bound Token (SBT)
Connect to the gRPC API
Handle quote requests and trades

Registration Process

Step 1: Generate Keys

First, generate one or more Ed25519 key pairs that will be used for authentication:

JavaScript implementation

Rust implementation

For other languages, you can use any standard Ed25519 implementation library available in your preferred programming language

Step 2: Prepare Metadata

Create a JSON document containing:

Your resolver name
Your public key(s)

Example:

{
  "name": "MyResolver",
  "publicKeys": [
    "b951254b184fae6906a61ab01e37296fbb28961494cacf7befac9f638fcfe40c",
    "9397ddd52a0d6033da4a32e654b4afbddcc5d832575e396c0a6f5b213faa199f"
  ]
}

Step 3: Submit Registration

Link to google form

Your metadata will be stored in an SBT NFT collection
You'll receive your SBT stake address for API authentication

Connecting to the API

Authentication

Create a connection payload:

message ConnectPayload {
  uint64 connect_timestamp = 1;  // Current timestamp in milliseconds
  string stake_address = 2;      // Your SBT stake address
}

Sign the payload:

Serialize the ConnectPayload to bytes
Sign using your Ed25519 private key
Base64 encode the signature

Send a ConnectRequest:

message ConnectRequest {
  bytes payload = 1;    // Serialized ConnectPayload
  bytes public_key = 2; // Your Ed25519 public key
  bytes signature = 3;  // Signature of the payload
}

Example connection request:

{
  "connect": {
    "payload": "CPKnlt2xYxIwRVFDWFNzMnhaMmRoazlUQXh6R3pYcmEyRWJHX1MyU3F5TjhUZmk2Zko4MkVZaVZq",
    "public_key": "TAPsnPvWhlOvxEK19rONv4sueMeQzOzlrrIFUOKsi34=",
    "signature": "us7nMd9wmUOkuPk0otg6dvUojZwj8VcyXU6HD13BDQhVrzV8sKgyXtKze+9+j9FC1Ghxkx7Jo5FIDeE8ljbADQjyp5bdsWMSMEVRQ1hTczJ4WjJkaGs5VEF4ekd6WHJhMkViR19TMlNxeU44VGZpNmZKODJFWWlWag=="
  },
  "seqno": 1
}

Message Flow

The resolver API uses a bidirectional gRPC stream. After connecting:

1. Incoming Events

You'll receive these events from the server:

message ResolverEvent {
  oneof mux {
    uint64 seqno = 1;    // Server-generated event ID
    uint64 reply_to = 2;  // References your request seqno
  }

  oneof event {
    QuoteRequestedEvent quote_requested = 10;
    QuoteRequestCancelledEvent quote_request_cancelled = 11;
    QuoteAcceptedEvent quote_accepted = 20;
    QuoteRejectedEvent quote_rejected = 21;
    QuoteInvalidatedEvent quote_invalidated = 22;
    KeepAlive keep_alive = 100;
  }
}

Key events:

QuoteRequestedEvent: New quote request from a trader
QuoteRequestCancelledEvent: Trader cancelled their request
QuoteAcceptedEvent: Your quote was accepted
QuoteRejectedEvent: Your quote was rejected
QuoteInvalidatedEvent: Confirmation of quote invalidation

2. Outgoing Requests

You can send these requests to the server:

message ResolverRequest {
  oneof mux {
    uint64 seqno = 1;    // Your request ID
    uint64 reply_to = 2;  // References server event seqno
  }

  oneof request {
    ConnectRequest connect = 10;
    UpdateQuoteRequest update_quote = 11;
    InvalidateQuoteRequest invalidate_quote = 12;
  }
}

Key requests:

UpdateQuoteRequest: Provide or update a quote
InvalidateQuoteRequest: Cancel a previously provided quote

Quote Flow

1. Receiving Quote Requests

When you receive a QuoteRequestedEvent:

message QuoteRequestedEvent {
  string rfq_id = 1;                      // Quote request ID
  QuoteRequest quote_request = 2;         // The actual request
  uint32 protocol_fee_bps = 3;           // Protocol fee in basis points
  sint64 request_timestamp = 4;          // When request was made
  sint64 quote_validity_timeout = 5;     // How long quote should be valid
  sint64 deposit_settling_delay = 6;     // Min delay before settlement
  sint64 resolve_timeout = 7;            // Max time to complete trade
}

2. Providing Quotes

Respond with an UpdateQuoteRequest:

message UpdateQuoteRequest {
  string rfq_id = 1;                    // From QuoteRequestedEvent
  string offer_units = 2;               // Amount trader pays
  string ask_units = 3;                 // Amount trader receives
  uint64 trade_start_deadline = 4;      // Quote expiration time

  oneof params {
    ResolverSwapParams swap = 20;       // For swap settlement
    ResolverEscrowParams escrow = 21;   // For escrow settlement
    ResolverHtlcParams htlc = 22;       // For HTLC settlement
  }
}

For swap settlement, include route information:

message ResolverSwapParams {
  repeated SwapRoute routes = 1;  // Possible swap paths
}

3. Quote Lifecycle

You receive QuoteRequestedEvent
You send UpdateQuoteRequest
The server validates your quote and responds with:
- QuoteAcceptedEvent: Your quote was validated and accepted, includes quote_id.
- QuoteRejectedEvent: Your quote was rejected. The event includes a code field from the QuoteRejectedCode enum. Possible reasons include:
  - UNDEFINED (0) - Uncategorized error
  - INVALID_PARAMETERS (1) - Invalid value of a parameter
  - INVALID_AMOUNTS (2) - Asset amount restrictions don't pass RFQ requirements
  - ROUTE_PROHIBITED (3) - Route uses a prohibited intermediate asset
  - POOL_PROHIBITED (4) - Route uses a unverified or prohibited liquidity pool
  - EMULATION_RESULT_MISMATCH (5) - Transaction emulation produced a result different from the quote
  - INTERNAL_ERROR (101) - Server errors
At any time, you can:
- Send new UpdateQuoteRequest to update the quote
- Send InvalidateQuoteRequest to cancel the quote

Best Practices

Sequence Numbers
- Use monotonically increasing seqno for your requests
- Match reply_to with event seqno when responding
- Track request/response correlation using seqno
Quote Management
- Honor your quotes until trade_start_deadline
- Invalidate quotes you can't fulfill
- Include all fees in your quoted amounts
Error Handling
- Reconnect on connection loss
- Handle all event types
- Log rejected quotes for monitoring
Performance
- Maintain a single gRPC connection
- Process events asynchronously
- Buffer outgoing requests

API Endpoint

Connect to: https://omni-grpc.ston.fi

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:

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:

For Swap settlement method the params is:

Object SwapRoute:

Object SwapStep:

Object SwapChunk:

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:

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:

Object Descriptions

RouteStatus

steps - Array of StepStatus objects.

StepStatus

chunks - Array of ChunkStatus objects.

ChunkStatus

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:

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:

Each Message object contains:

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

Swap extra

This document explains how to populate and interpret the extra field in SwapChunk (as referenced in omniston-swap.md), specifically when using protocols like StonFiV1, StonFiV2, or DeDust.

Overview

In the Omniston Swap protocol, each SwapChunk contains two fields for protocol-specific data:

extra_version (integer) - Indicates the version of the data structure being used
extra (bytes) - Contains the protocol-specific data as a base64-encoded byte array

These fields allow different DEX protocols to include their own parameters and configuration for executing swaps. This document describes the format of that data and how to encode it properly.

Protocol Definitions

message ExtraData {
  oneof extra {
    StonFiV1Extra ston_fi_v1 = 1;
    StonFiV2Extra ston_fi_v2 = 2;
    DeDustExtra de_dust = 3;
  }
}

message StonFiV1Extra {
  string pool_address = 1;
  string min_ask_amount = 2;
}

message StonFiV2Extra {
  string pool_address = 1;
  string min_ask_amount = 2;
}

message DeDustExtra {
  string pool_address = 1;
  string min_ask_amount = 2;
  string referrer_address = 3;  // Specified in `referralAddress` swap parameter in DeDust SDK
}

Field Descriptions

Common Fields

All protocol extras share these common fields:

pool_address (string)
- The address of the DEX pool contract that will execute the swap
- This is specific to the token pair being swapped and the protocol being used
min_ask_amount (string)
- The minimum amount of ask tokens that must be received for this chunk
- If the protocol cannot provide at least this amount, the swap will be aborted
- Used to protect against slippage and ensure minimum received amount

Protocol-Specific Fields

DeDust Protocol

The DeDust protocol includes an additional field:

referrer_address (string)
- Optional address that may receive referral rewards/fees according to DeDust's rules
- This is specified in the referralAddress parameter when using the DeDust SDK

Usage Example

Here's an example of how to construct and encode the extra data for a StonFiV2 swap:

// 1. Create the protocol-specific extra data
const stonFiV2Extra = {
  pool_address: "EQA...", // Address of the StonFi pool
  min_ask_amount: "1000000", // Minimum tokens to receive
};

// 2. Wrap in ExtraData message
const extraData = {
  extra: {
    oneofKind: "ston_fi_v2",
    ston_fi_v2: stonFiV2Extra,
  },
};

// 3. Serialize to protobuf bytes
const extraBytes = ExtraData.encode(extraData).finish();

// 4. Base64 encode for JSON transport
const extraBase64 = Buffer.from(extraBytes).toString("base64");

// 5. Use in SwapChunk
const chunk = {
  protocol: "StonFiV2",
  offer_amount: "2000000",
  ask_amount: "1950000",
  extra_version: 1,
  extra: extraBase64,
};

Integration with Swap Flow

When the Omniston server processes a swap request:

It examines the protocol field of each SwapChunk to determine which DEX to use
Based on the extra_version, it knows how to decode the extra field
The decoded data provides the necessary parameters (pool address, minimum amounts, etc.) to execute the swap through the chosen DEX

For more details on the overall swap flow and how chunks fit into routes and steps, see omniston-swap.md.

Version History

Version 1: Initial version supporting StonFiV1, StonFiV2, and DeDust protocols

React

Getting started

This package provides binding for omniston-sdk to the React ecosystem. Using this package, you can access all Omniston methods as hooks powered by TanStack react query (out-of-box loading states, retries, error handling, and match more)

You can find all supported methods in our docs or take a look onto our demo app that use NextJs and omniston-sdk-react package

Installation

via NPM

npm install @ston-fi/omniston-sdk-react

via YARN

yarn add @ston-fi/omniston-sdk-react

via PNPM

pnpm install @ston-fi/omniston-sdk-react

Wrap you app in Omniston provider

You can pass custom queryClient if you want to apply shared behaviour to all of the queries

import { OmnistonProvider } from "@ston-fi/omniston-sdk-react";

const App = () => (
  <OmnistonProvider apiUrl="wss://omni-ws.ston.fi">{children}</OmnistonProvider>
);

The provider takes the following parameters:

Name

Type

Description

client

ApiClient | undefined

Optional. Provide this if you want to override the default API client. By default, this will be an ApiClient using ReconnectingTransport

apiUrl

URL | string

Omniston WebSocket API URL.

Send a quote request

Send a request for quote to swap an asset to another asset.

import { useRfq } from "@ston-fi/omniston-sdk-react";

const {
  isLoading,
  error,
  data: quote,
  ...restQuery
} = useRfq({
  settlementMethods: [SettlementMethod.SETTLEMENT_METHOD_SWAP],
  askAssetAddress: {
    blockchain: Blockchain.TON,
    address: "EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO", // STON
  },
  offerAssetAddress: {
    blockchain: Blockchain.TON,
    address: "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs", // USDT
  },
  amount: {
    offerUnits: "1000000", // 1 USDT
  },
  settlementParams: {
    maxPriceSlippageBps: 500, // 5% max slippage
    maxOutgoingMessages: 4, // default for TON
  },
});

A QuoteRequest has the following properties:

Name

Type

Description

settlementMethods

SettlementMethod[]

Supported methods of swap settlement

askAssetAddress

Address

Blockchain-specific address of ask asset

offerAssetAddress

Address

Blockchain-specific address of offer asset

amount

{ offerUnits: string } | { askUnits: string }

Either the amount of offer asset or ask asset

amount.offerUnits

string

The amount of offer asset the trader wants to pay, including all fees, in base asset units

amount.askUnits

string

The amount of ask asset the trader wants to get after all fees, in base asset units

referrerAddress

Address | undefined

The address of referrer that will receive the fees

referrerFeeBps

number | undefined

The amount of fees required by the referrer in basis points (1/10000 = 0.01%)

settlementParams

RequestSettlementParams | undefined

Additional parameters of RFQ related to settlement. See the table below.

RequestSettlementParams

Name

Type

Description

max_price_slippage_bps

number | undefined

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

max_outgoing_messages

number | undefined

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

Note: Some parameters in RequestSettlementParams may only be relevant for certain blockchains or certain settlement methods. If your settlement method or wallet does not require them, you can omit them or set them to default values.

The server returns Observable<QuoteResponseEvent>, which is a stream of quote updates.

A QuoteResponseEvent might be one of the following:

{ type: "quoteUpdated"; quote: Quote; }
{ type: "noQuote"; }
{ type: "unsubscribed"; }

A Quote has the following properties:

Name

Type

Description

quoteId

string

ID of the quote generated by the platform (32 characters)

resolverId

string

ID of the resolver

resolverName

string

Name of the resolver

offerAssetAddress

Address

Blockchain-specific address of offer asset

askAssetAddress

Address

Blockchain-specific address of ask asset

offerUnits

string

The amount of offer asset the trader must pay, including all fees

askUnits

string

The amount of ask asset the trader will get after all fees

referrerAddress

Address | undefined

The address of referrer that will receive the fees

referrerFeeUnits

string

The amount of fees that the referrer will get (in units of offerAssetAddress)

protocolFeeUnits

string

The amount of fees charged by the protocol (in units of offerAssetAddress).

quoteTimestamp

number

The timestamp (UTC seconds) of Quote sent by resolver

tradeStartDeadline

number

Max timestamp (UTC seconds) of start of the trade

gasBudget

string

The amount of gas budget for the trade

params

object | undefined

Various parameters specific to the settlement method. See the source code for more details.

Build a transaction

Now that we have a quote, we should request a server to build a transaction to initiate the trade that the user can verify and sign.

import { useOmniston } from "@ston-fi/omniston-sdk-react";

const omniston = useOmniston();

const tx = await omniston.buildTransfer({
  quote,
  sourceAddress: {
    blockchain: Blockchain.TON,
    address: "", // sender wallet address on `offerBlockchain`
  },
  destinationAddress: {
    blockchain: Blockchain.TON,
    address: "", // receiver wallet address on `askBlockchain`
  },
});

const messages = tx.ton?.messages ?? [];

The buildTransfer method takes a TransactionRequest object as a parameter, having the following properties:

Name

Type

Description

quote

Quote

The valid quote received from Omniston.requestForQuote

sourceAddress

Address

The address on offerBlockchain that will send initial transaction to start the trade

destinationAddress

Address

The address on askBlockchain that will receive result of the trade

Sign the transaction

You can found the instruction on how to send transaction using the @tonconnect/ui-react package here.

import { useTonConnectUI } from "@tonconnect/ui-react";

const [tonConnect] = useTonConnectUI();

await tonConnect.sendTransaction({
  validUntil: Date.now() + 1000000,
  messages: messages.map((message) => ({
    address: message.targetAddress,
    amount: message.sendAmount,
    payload: message.payload,
  })),
});

Get the outgoing transaction hash

See TON Cookbook for detailed instructions.

For tutorial purposes, we'll use the @ton/core package to get the external transaction hash and find the internal hash with TonAPI v2.

import { Cell } from "@ton/core";

const externalTxHash = Cell.fromBase64(boc).hash().toString("hex");
const response = await fetch(`https://tonapi.io/v2/traces/${externalTxHash}`);
const outgoingTxHash = (await response.json()).transaction.hash;

Listen for trade status updates

After the user has signed and initiated the transaction, we can track the trade status.

import { useTrackTrade } from "@ston-fi/omniston-sdk-react";
import { useTonAddress } from "@tonconnect/ui-react";

const walletAddress = useTonAddress();

const {
  isLoading,
  error,
  data: status,
  ...restQuery
} = useTrackTrade({
  quoteId: quote.quoteId,
  traderWalletAddress: {
    blockchain: Blockchain.TON,
    address: walletAddress,
  },
  outgoingTxHash: "", // Replace with the actual outgoingTxHash
});

The trackTrade method has the following parameters:

Name

Type

Description

quoteId

string

ID of the quote received from Omniston.requestFromQuote

traderWalletAddress

Address

The address of trader's wallet that initiated transaction

outgoingTxHash

string

Hash of the transaction that initiated the trade

It returns Observable<TrackTradeStatus>. For the different trade status values, see the source code. We are interested in the trade result enum which can be read from status.tradeSettled?.result? field. The enum has the following values:

Name

Description

TRADE_RESULT_FULLY_FILLED

The trade has been completed and fully filled.

TRADE_RESULT_PARTIALLY_FILLED

The trade has been partially filled. Something went wrong.

TRADE_RESULT_ABORTED

The trade has been aborted.

TRADE_RESULT_UNKNOWN

UNRECOGNIZED

Nodejs

Getting started

This package acts as a typescript wrapper on top of the Ston.fi and provides RxJS styled observables on top of the WebSocket API connection

Installation

via NPM

npm install @ston-fi/omniston-sdk

via YARN

yarn add @ston-fi/omniston-sdk

via PNPM

pnpm install @ston-fi/omniston-sdk

Create an instance

Create an Omniston instance, specifying the API URL.

import { Omniston } from "@ston-fi/omniston-sdk";

const omniston = new Omniston({
  apiUrl: "wss://omni-ws.ston.fi",
});

The constructor takes the following parameters:

Send a quote request

Send a request for quote to swap an asset to another asset.

omniston
  .requestForQuote({
    settlementMethods: [SettlementMethod.SETTLEMENT_METHOD_SWAP],
    askAssetAddress: {
      blockchain: Blockchain.TON,
      address: "EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO", // STON
    },
    offerAssetAddress: {
      blockchain: Blockchain.TON,
      address: "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs", // USDT
    },
    amount: {
      offerUnits: "1000000", // 1 USDT
    },
    settlementParams: {
      maxPriceSlippageBps: 500, // 5% max slippage
      maxOutgoingMessages: 4, // default for TON
    },
  })
  .subscribe((quoteResponseEvent) => {
    // process the quote event
  });

A QuoteRequest has the following properties:

RequestSettlementParams

The server returns Observable<QuoteResponseEvent>, which is a stream of quote updates.

A QuoteResponseEvent might be one of the following:

{ type: "quoteUpdated"; quote: Quote; }
{ type: "noQuote"; }
{ type: "unsubscribed"; }

A Quote has the following properties:

Build a transaction

Now that we have a quote, we should request a server to build a transaction to initiate the trade that the user can verify and sign.

const tx = await omniston.buildTransfer({
  quote,
  sourceAddress: {
    blockchain: Blockchain.TON,
    address: "", // sender wallet address on `offerBlockchain`
  },
  destinationAddress: {
    blockchain: Blockchain.TON,
    address: "", // receiver wallet address on `askBlockchain`
  },
});

const messages = tx.ton?.messages ?? [];

The buildTransfer method takes a TransactionRequest object as a parameter, having the following properties:

Sign the transaction

Listen for trade status updates

After the user has signed and initiated the transaction, we can track the trade status.

const tradeStatus = omniston.trackTrade({
  quoteId: quote.quoteId,
  traderWalletAddress: {
    blockchain: Blockchain.TON,
    address: "", // sender wallet address on `offerBlockchain`
  },
  outgoingTxHash: "", // Replace with the actual outgoingTxHash
});

tradeStatus.subscribe((status) => {
  console.log(JSON.stringify(status));
});

The trackTrade method has the following parameters:

React

Getting started

You can find all supported methods in our docs or take a look onto our demo app that use NextJs and omniston-sdk-react package

Installation

via NPM

npm install @ston-fi/omniston-sdk-react

via YARN

yarn add @ston-fi/omniston-sdk-react

via PNPM

pnpm install @ston-fi/omniston-sdk-react

Wrap you app in Omniston provider

You can pass custom queryClient if you want to apply shared behaviour to all of the queries

import { OmnistonProvider } from "@ston-fi/omniston-sdk-react";

const App = () => (
  <OmnistonProvider apiUrl="wss://omni-ws.ston.fi">{children}</OmnistonProvider>
);

The provider takes the following parameters:

Name

Type

Description

client

ApiClient | undefined

Optional. Provide this if you want to override the default API client. By default, this will be an ApiClient using ReconnectingTransport

apiUrl

URL | string

Omniston WebSocket API URL.

Send a quote request

Send a request for quote to swap an asset to another asset.

import { useRfq } from "@ston-fi/omniston-sdk-react";

const {
  isLoading,
  error,
  data: quote,
  ...restQuery
} = useRfq({
  settlementMethods: [SettlementMethod.SETTLEMENT_METHOD_SWAP],
  askAssetAddress: {
    blockchain: Blockchain.TON,
    address: "EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO", // STON
  },
  offerAssetAddress: {
    blockchain: Blockchain.TON,
    address: "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs", // USDT
  },
  amount: {
    offerUnits: "1000000", // 1 USDT
  },
  settlementParams: {
    maxPriceSlippageBps: 500, // 5% max slippage
    maxOutgoingMessages: 4, // default for TON
  },
});

A QuoteRequest has the following properties:

Name

Type

Description

settlementMethods

SettlementMethod[]

Supported methods of swap settlement

askAssetAddress

Address

Blockchain-specific address of ask asset

offerAssetAddress

Address

Blockchain-specific address of offer asset

amount

{ offerUnits: string } | { askUnits: string }

Either the amount of offer asset or ask asset

amount.offerUnits

string

The amount of offer asset the trader wants to pay, including all fees, in base asset units

amount.askUnits

string

The amount of ask asset the trader wants to get after all fees, in base asset units

referrerAddress

Address | undefined

The address of referrer that will receive the fees

referrerFeeBps

number | undefined

The amount of fees required by the referrer in basis points (1/10000 = 0.01%)

settlementParams

RequestSettlementParams | undefined

Additional parameters of RFQ related to settlement. See the table below.

RequestSettlementParams

Name

Type

Description

max_price_slippage_bps

number | undefined

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

max_outgoing_messages

number | undefined

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

The server returns Observable<QuoteResponseEvent>, which is a stream of quote updates.

A QuoteResponseEvent might be one of the following:

{ type: "quoteUpdated"; quote: Quote; }
{ type: "noQuote"; }
{ type: "unsubscribed"; }

A Quote has the following properties:

Name

Type

Description

quoteId

string

ID of the quote generated by the platform (32 characters)

resolverId

string

ID of the resolver

resolverName

string

Name of the resolver

offerAssetAddress

Address

Blockchain-specific address of offer asset

askAssetAddress

Address

Blockchain-specific address of ask asset

offerUnits

string

The amount of offer asset the trader must pay, including all fees

askUnits

string

The amount of ask asset the trader will get after all fees

referrerAddress

Address | undefined

The address of referrer that will receive the fees

referrerFeeUnits

string

The amount of fees that the referrer will get (in units of offerAssetAddress)

protocolFeeUnits

string

The amount of fees charged by the protocol (in units of offerAssetAddress).

quoteTimestamp

number

The timestamp (UTC seconds) of Quote sent by resolver

tradeStartDeadline

number

Max timestamp (UTC seconds) of start of the trade

gasBudget

string

The amount of gas budget for the trade

params

object | undefined

Various parameters specific to the settlement method. See the source code for more details.

Build a transaction

Now that we have a quote, we should request a server to build a transaction to initiate the trade that the user can verify and sign.

import { useOmniston } from "@ston-fi/omniston-sdk-react";

const omniston = useOmniston();

const tx = await omniston.buildTransfer({
  quote,
  sourceAddress: {
    blockchain: Blockchain.TON,
    address: "", // sender wallet address on `offerBlockchain`
  },
  destinationAddress: {
    blockchain: Blockchain.TON,
    address: "", // receiver wallet address on `askBlockchain`
  },
});

const messages = tx.ton?.messages ?? [];

The buildTransfer method takes a TransactionRequest object as a parameter, having the following properties:

Name

Type

Description

quote

Quote

The valid quote received from Omniston.requestForQuote

sourceAddress

Address

The address on offerBlockchain that will send initial transaction to start the trade

destinationAddress

Address

The address on askBlockchain that will receive result of the trade

Sign the transaction

You can found the instruction on how to send transaction using the @tonconnect/ui-react package here.

import { useTonConnectUI } from "@tonconnect/ui-react";

const [tonConnect] = useTonConnectUI();

await tonConnect.sendTransaction({
  validUntil: Date.now() + 1000000,
  messages: messages.map((message) => ({
    address: message.targetAddress,
    amount: message.sendAmount,
    payload: message.payload,
  })),
});

Get the outgoing transaction hash

See TON Cookbook for detailed instructions.

For tutorial purposes, we'll use the @ton/core package to get the external transaction hash and find the internal hash with TonAPI v2.

import { Cell } from "@ton/core";

const externalTxHash = Cell.fromBase64(boc).hash().toString("hex");
const response = await fetch(`https://tonapi.io/v2/traces/${externalTxHash}`);
const outgoingTxHash = (await response.json()).transaction.hash;

Listen for trade status updates

After the user has signed and initiated the transaction, we can track the trade status.

import { useTrackTrade } from "@ston-fi/omniston-sdk-react";
import { useTonAddress } from "@tonconnect/ui-react";

const walletAddress = useTonAddress();

const {
  isLoading,
  error,
  data: status,
  ...restQuery
} = useTrackTrade({
  quoteId: quote.quoteId,
  traderWalletAddress: {
    blockchain: Blockchain.TON,
    address: walletAddress,
  },
  outgoingTxHash: "", // Replace with the actual outgoingTxHash
});

The trackTrade method has the following parameters:

Name

Type

Description

quoteId

string

ID of the quote received from Omniston.requestFromQuote

traderWalletAddress

Address

The address of trader's wallet that initiated transaction

outgoingTxHash

string

Hash of the transaction that initiated the trade

Name

Description

TRADE_RESULT_FULLY_FILLED

The trade has been completed and fully filled.

TRADE_RESULT_PARTIALLY_FILLED

The trade has been partially filled. Something went wrong.

TRADE_RESULT_ABORTED

The trade has been aborted.

TRADE_RESULT_UNKNOWN

UNRECOGNIZED

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

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

For Swap settlement method the params is:

Name

Type

Description

Object SwapRoute:

Name

Type

Description

Object SwapStep:

Name

Type

Description

Object SwapChunk:

Name

Type

Description

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

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

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

Object Descriptions

RouteStatus

steps - Array of StepStatus objects.

StepStatus

chunks - Array of ChunkStatus objects.

ChunkStatus

Name

Type

Description

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

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

Each Message object contains:

Name

Type

Description

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

OMNISTON

Overview

Key benefits

Use Case

Swap

SDK

Application

Resolvers (How to become a resolver)

Overview

Registration Process

Step 1: Generate Keys

Step 2: Prepare Metadata

Step 3: Submit Registration

Connecting to the API

Authentication

Message Flow

1. Incoming Events

2. Outgoing Requests

Quote Flow

1. Receiving Quote Requests

2. Providing Quotes

3. Quote Lifecycle

Best Practices

API Endpoint

See Also

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 extra

Overview

Protocol Definitions

Field Descriptions

Common Fields

Protocol-Specific Fields

DeDust Protocol

Usage Example

Integration with Swap Flow

Version History

See Also

React

Getting started

Installation

via NPM

via YARN

via PNPM

Wrap you app in Omniston provider

Send a quote request

Build a transaction

Sign the transaction

Get the outgoing transaction hash

Listen for trade status updates

Nodejs

Getting started

Installation

via NPM

via YARN

via PNPM

Create an instance

Send a quote request

Build a transaction

Sign the transaction

Listen for trade status updates

Resolvers (How to become a resolver)

Overview

Registration Process

Step 1: Generate Keys

Step 2: Prepare Metadata

Step 3: Submit Registration

Connecting to the API

Authentication

Message Flow

1. Incoming Events

Subscription method `quote`

Subscription method `trade.track`

Method `transaction.build_transfer`

Subscription method `quote`

Subscription method `trade.track`

Method `transaction.build_transfer`