> For the complete documentation index, see [llms.txt](https://docs.ston.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ston.fi/developer-section/widget/configuration.md).

# Configuration

Configure TON Connect, assets, integrator fees, and Omniston connections for the STON.fi Widget.

Pass the initial configuration to the `OmnistonWidget` constructor. At runtime, call `widget.updateConfig()` to update the `widget` options and read `widget.config` to get their effective values. Set TON Connect and Omniston connection options when creating the widget.

The constructor accepts three configuration sections:

| Section      | Required | Runtime updatable | Purpose                                                 |
| ------------ | -------- | ----------------- | ------------------------------------------------------- |
| `tonconnect` | Yes      | No                | Configure TON wallet connections.                       |
| `widget`     | No       | Yes               | Configure assets and integrator fees.                   |
| `omniston`   | No       | No                | Configure the Omniston endpoint, logger, and transport. |

## TON Connect

[TON Connect](https://docs.ton.org/applications/ton-connect/overview) connects your application to TON wallets. The widget uses the connected wallet address to fetch asset balances and requests transaction signing through TON Connect. Choose standalone mode to let the widget manage the connection, or integrated mode to share your application's existing connection.

Both modes require a [TON Connect manifest](https://docs.ton.org/applications/ton-connect/core-concepts#manifest). This JSON file identifies your application to wallets through its URL, name, and icon. Host it at a public HTTPS URL that wallets can access without authentication, and provide that URL as `manifestUrl`.

### Standalone mode

Use `type: 'standalone'` when your application does not already manage TON Connect. The widget automatically loads the latest version of TON Connect UI from its CDN and creates an instance using `tonconnect.options`. You do not need to install, load, or upgrade TON Connect separately.

```js
const tonconnect = {
  type: 'standalone',
  options: {
    manifestUrl: 'https://your-app.com/tonconnect-manifest.json',
  },
};

const widget = new OmnistonWidget({ tonconnect });
```

The `options` object accepts [TON Connect UI constructor options](https://docs.ton-connect.io/sdk/modules/_tonconnect_ui.html#create-tonconnectui-instance), including your manifest URL.

### Integrated mode

Use `type: 'integrated'` when your application already manages a `TonConnectUI` instance. Pass it as `tonconnect.instance` to share the wallet connection and account state. Configure the manifest URL when creating that instance.

The following example uses `TonConnectUI` from `@tonconnect/ui`. If your application already has an instance, pass that instance instead of creating another one:

```js
import { TonConnectUI } from '@tonconnect/ui';

const tonConnectUI = new TonConnectUI({
  manifestUrl: 'https://your-app.com/tonconnect-manifest.json',
});

const widget = new OmnistonWidget({
  tonconnect: {
    type: 'integrated',
    instance: tonConnectUI,
  },
});
```

In React, you can pass the `TonConnectUI` instance returned by `useTonConnectUI()` from `@tonconnect/ui-react`. Integrated mode requires the UI instance, including its wallet selection modal API.

## Widget options

Use the `widget` section to configure the asset list, initial asset pair, and integrator fees. You can also use the [visual constructor](https://widget.ston.fi/constructor) to configure these options through a web interface and export JavaScript configuration.

### Assets

The widget supports native TON and jettons. Use TON address strings for asset options. For jettons, use the jetton master address. Token symbols such as `TON` or `STON` are not accepted.

| Option            | Type       | Default | Purpose                                                                            |
| ----------------- | ---------- | ------- | ---------------------------------------------------------------------------------- |
| `defaultAssets`   | `boolean`  | `true`  | Include STON.fi's curated asset selection.                                         |
| `customAssets`    | `string[]` | None    | Add assets by address. With `defaultAssets: false`, use these as your custom list. |
| `defaultBidAsset` | `string`   | USD₮    | Preselect the asset to sell.                                                       |
| `defaultAskAsset` | `string`   | TON     | Preselect the asset to receive.                                                    |

With `defaultAssets: true`, users can select from assets that STON.fi considers suitable for trading. STON.fi maintains the selection criteria, so you do not need to manage your own default asset list.

Custom and preselected assets are added separately from this default selection. Assets must be available through the [STON.fi API](https://api.ston.fi/swagger-ui/) with metadata for their symbol and number of decimal places.

The examples below reuse the `tonconnect` configuration from the standalone example. They use these asset addresses:

```js
const TON = 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c';
const STON = 'EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO';
```

#### Use the defaults

Omit `widget` or provide an empty object (`widget: {}`) to use the defaults. The widget includes STON.fi's curated asset selection (`defaultAssets: true`) and preselects USD₮ to sell and TON to receive:

```js
const widget = new OmnistonWidget({
  tonconnect,
  widget: {},
});
```

#### Extend the default list

Keep `defaultAssets` enabled and add addresses through `customAssets`. This example adds STON if it is not already in the default list:

```js
const widget = new OmnistonWidget({
  tonconnect,
  widget: {
    defaultAssets: true,
    customAssets: [STON],
  },
});
```

#### Use only two assets

Disable the default list and provide your custom assets. Set both preselected assets to addresses from that list, since the widget also includes preselected assets in asset requests. This example starts with only TON and STON:

```js
const widget = new OmnistonWidget({
  tonconnect,
  widget: {
    defaultAssets: false,
    customAssets: [TON, STON],
    defaultBidAsset: TON,
    defaultAskAsset: STON,
  },
});
```

With `defaultAssets: false`, search is limited to your custom asset list.

### Integrator fees

Configure an integrator fee to receive a commission on trades through your widget.

| Option            | Type     | Default                            | Purpose                                                                 |
| ----------------- | -------- | ---------------------------------- | ----------------------------------------------------------------------- |
| `referrerAddress` | `string` | None                               | TON wallet address that receives the integrator fee.                    |
| `referrerFeeBps`  | `number` | `10` when `referrerAddress` is set | Requested integrator fee in basis points, from `0` to `100` (0% to 1%). |

One basis point is 0.01%, so `50` requests a 0.5% integrator fee. Without `referrerAddress`, the widget does not request an integrator fee. Set both fields to choose the recipient and rate explicitly.

```js
const widget = new OmnistonWidget({
  tonconnect,
  widget: {
    referrerAddress: 'EQ...',
    referrerFeeBps: 50,
  },
});
```

The widget enables Omniston's [`flexibleIntegratorFee`](https://docs.ston.fi/developer-section/omniston/referral-fees.md#effective-amounts) parameter for swap routes. The effective integrator fee rate may vary from your configured rate depending on the route's fee constraints. See [Integrator fees](https://docs.ston.fi/developer-section/omniston/referral-fees.md) for fee amounts and payout details.

## Omniston options

The optional `omniston` object accepts constructor parameters for `Omniston` from the [Omniston SDK](https://docs.ston.fi/developer-section/omniston/sdk/nodejs.md#configuration). The widget passes these options to the SDK constructor and uses the following defaults for omitted values:

| Option      | Type                                                    | Default                                         | Purpose                                              |
| ----------- | ------------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------- |
| `apiUrl`    | `string` or `URL`                                       | `wss://omni-ws.ston.fi`                         | Omniston WebSocket endpoint.                         |
| `logger`    | Object with `log`, `debug`, `warn`, and `error` methods | Logging disabled                                | Use `console` or a custom logger with these methods. |
| `transport` | Omniston SDK `Transport`                                | WebSocket transport with automatic reconnection | Override the client's network transport.             |

For example, connect to the sandbox environment and enable console logging:

```js
const widget = new OmnistonWidget({
  tonconnect,
  omniston: {
    apiUrl: 'wss://omni-ws-sandbox.ston.fi',
    logger: console,
  },
});
```

## Update and read the configuration

Call `widget.updateConfig()` with the `widget` fields you want to change. Pass them directly, without a `widget` wrapper. The method updates the supplied fields and preserves omitted fields:

```js
widget.updateConfig({
  defaultBidAsset: TON,
  defaultAskAsset: STON,
});

const currentConfig = widget.config;

console.log(currentConfig.defaultBidAsset);
```

The `config` getter returns the effective widget options, including defaults. It does not return the `tonconnect` or `omniston` sections.

## Next step

See [Customization](https://docs.ston.fi/developer-section/widget/customization.md) to configure the widget's appearance.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ston.fi/developer-section/widget/configuration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
