Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .cspell.jsonc
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,7 @@
},
{
"filename": "content/**/appkit/reference/appkit*.mdx",
"ignoreWords": ["providerId", "AppkitUIToken"],
"ignoreWords": ["providerId", "AppkitUIToken", "LayerswapCryptoOnrampProvider"],
},
{
"filename": "content/**/foundations/whitepapers/overview.mdx",
Expand Down
4 changes: 3 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -42,5 +42,7 @@ next-env.d.ts
/build
*.tsbuildinfo

# Temporary folders cloned for technical accuracy checks
# Temporary folders or files for technical accuracy checks
/.ctx
/AGENTS.md
/CLAUDE.md
16 changes: 7 additions & 9 deletions content/api/price.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,14 +7,9 @@ Each swap operation, whether between a native asset (Gram) and Jetton or between

## Off-chain API

The most common use case for the price API is to fetch Jetton info on the web2 backend and use aggregated data inside the service. There are several historical Jetton price providers in TON:
The most common use case for the price API is to fetch Jetton info on the web2 backend and use aggregated data inside the service. There are [several](https://www.coingecko.com/en/api/ton) [historical](https://dyor.io/tonapi) Jetton price providers in TON.

- [CoinGecko](https://www.coingecko.com/en/api/ton)
- [Dyor.io](https://dyor.io/tonapi)

You can find detailed information about API usage and technical details in the provider docs.

There is no established solution for real-time jetton swap market data; however, one can explore [CoinGecko websocket API](https://docs.coingecko.com/websocket).
There is no established solution for real-time jetton swap market data; however, one can explore [this websocket API](https://docs.coingecko.com/websocket).

## On-chain API

Expand All @@ -24,16 +19,19 @@ Currently, it is not possible to retrieve **historical** jetton prices on-chain
Since the TON [execution model is asynchronous](/from-ethereum#execution-model), the jetton price might change between the moment of the response from the price provider and the moment the contract processes the response. Consider this factor in smart contract logic.
</Callout>

For example, on the [DeDust](https://dedust.io) DEX, it is possible to retrieve pool information on-chain using an internal message with the following [TL-B](/foundations/tlb/overview) schema:
For example, on a [popular DEX](https://dedust.io), it is possible to retrieve pool information on-chain using an internal message with the following [TL-B](/foundations/tlb/overview) schema:

```tlb
provide_pool_state#6e24728d query_id:uint64 include_assets:Bool = InMsgBody;

take_pool_state#bddd4954 query_id:uint64 reserve0:Coins reserve1:Coins total_supply:Coins
assets:(Maybe ^[ asset0:Asset asset1:Asset ]) = InMsgBody;

# See:
# https://hub.dedust.io/contracts/v2/reference/core/pool#operation-provide_pool_stat
```

Here is a smart contract snippet in [Tolk](/tolk/overview) illustrating how you can send the 'provide' message:
Here is a smart contract snippet in [Tolk](/tolk/overview) illustrating how one can send the `provide_pool_state` message:

```tolk title="Tolk"
struct (0x6e24728d) ProvideDeDustPool {
Expand Down
4 changes: 2 additions & 2 deletions content/applications/appkit/get-started/providers.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -28,15 +28,15 @@ export const appKit = new AppKit({
});
```

Omniston requires its own SDK package — install it before registering the provider:
Some providers require their own SDK package — install it before registering the provider:

```bash
npm i @ston-fi/omniston-sdk
```

## Add a staking provider

Use `createTonstakersProvider({})` from `@ton/appkit/staking/tonstakers` the same way:
Use the provider from `@ton/appkit/staking/tonstakers` the same way:

```ts
import { AppKit } from '@ton/appkit';
Expand Down
8 changes: 4 additions & 4 deletions content/applications/appkit/howto/providers.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -20,21 +20,21 @@ A provider is not a wallet and not a connector. The wallet still signs every tra

## Swaps

A swap provider integrates a DEX or aggregator. It returns a **quote** for a route (input asset, output asset, amount, fees, and execution assumptions), then builds a `TransactionRequest` when the user accepts the quote. AppKit does not price markets itself; `SwapManager` coordinates the registered providers. Bundled options include Omniston and DeDust. See [Perform swaps](/applications/appkit/howto/swaps) for the full quote-then-build flow.
A swap provider integrates a DEX or aggregator. It returns a **quote** for a route (input asset, output asset, amount, fees, and execution assumptions), then builds a `TransactionRequest` when the user accepts the quote. AppKit does not price markets itself; `SwapManager` coordinates the registered providers. Bundled options include popular DEX platforms. See [Perform swaps](/applications/appkit/howto/swaps) for the full quote-then-build flow.

## Staking

A staking provider quotes a stake or unstake intent for a specific pool or protocol, then builds the matching `TransactionRequest`.

Liquid-staking positions may appear in the wallet as derivative balances, such as tsTON. AppKit exposes pool metadata and APY as provider-supplied **display data**, not a guarantee of future yield or redemption timing.

Unstake mechanics — instant, delayed, or round-end — are provider-specific. The bundled staking provider is Tonstakers. See [Stake and unstake](/applications/appkit/howto/staking) for the full flow.
Unstake mechanics — instant, delayed, or round-end — are provider-specific. See [Stake and unstake](/applications/appkit/howto/staking) for the full flow.

## How they are registered

Provider setup uses three registration paths. **API clients** are bound to a network through the `networks` field of `AppKitConfig`. **Streaming providers** are also network-specific and are registered directly on `appKit.streamingManager`. **Swap** and **staking** providers are network-aware DeFi providers: pass them in `providers` at construction or register them later with `registerProvider`. Each DeFi provider declares its `type` so AppKit can route it to the correct manager.

Omniston requires its own SDK package — install it before registering the provider:
Some providers require their own SDK package — install it before registering the provider:

```bash
npm i @ston-fi/omniston-sdk
Expand All @@ -60,7 +60,7 @@ const appKit = new AppKit({
registerProvider(appKit, createTonstakersProvider());
```

When a network entry does not provide a custom API client, AppKit creates a TON Center client for that network. TON Center streaming provider is available through WalletKit and can be registered on `appKit.streamingManager`. Omniston and DeDust are available as swap providers, and Tonstakers is available as a staking provider. Custom DeFi backends can use the same `registerProvider` path by implementing the swap or staking interface.
When a network entry does not provide a custom API client, AppKit creates a TON Center client for that network. TON Center streaming provider is available through WalletKit and can be registered on `appKit.streamingManager`. Custom DeFi backends can use the same `registerProvider` path by implementing the swap or staking interface.

`registerProvider` returns `void`. To replace a provider, call `registerProvider` again with the same `providerId` — the registry entry is overwritten. If the previous provider owns resources you need to clean up, hold the reference and dispose of it yourself before re-registering.

Expand Down
4 changes: 2 additions & 2 deletions content/applications/appkit/howto/staking.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,11 @@ Quote a stake or unstake, build the transaction, and send it through the connect

The `StakingManager` routes each quote call and each build call to a single registered staking provider — by default the first one you registered, or the one you pass as `providerId`. `setDefaultProvider` on the manager overrides the default; an unknown `providerId` throws. A quote describes the intent (`direction: 'stake' | 'unstake'`, `amount`, optional `unstakeMode`), and `useBuildStakeTransaction` turns an accepted quote into a `TransactionRequest`.

The protocol shape — derivative jetton, unstake modes, settlement timing, pool model — is provider-specific. Tonstakers, the bundled provider, issues `tsTON` and supports `INSTANT`, `WHEN_AVAILABLE`, and `ROUND_END` unstake modes. Read the user's staked-token balance with `useStakedBalance`, or query the jetton balance directly. `apy` and `instantUnstakeAvailable` from `useStakingProviderInfo` are provider-supplied display data, not guarantees of future yield or withdrawal timing.
The protocol shape — derivative jetton, unstake modes, settlement timing, pool model — is provider-specific. The bundled provider issues `tsTON` and supports `INSTANT`, `WHEN_AVAILABLE`, and `ROUND_END` unstake modes. Read the user's staked-token balance with `useStakedBalance`, or query the jetton balance directly. `apy` and `instantUnstakeAvailable` from `useStakingProviderInfo` are provider-supplied display data, not guarantees of future yield or withdrawal timing.

## Before you begin

You need a connected wallet and a staking provider registered on the AppKit instance. Tonstakers ships bundled — see [Use providers → How they are registered](/applications/appkit/howto/providers#how-they-are-registered).
You need a connected wallet and a staking provider registered on the AppKit instance. Some popular staking providers are bundled — see [Use providers → How they are registered](/applications/appkit/howto/providers#how-they-are-registered).

## Hooks

Expand Down
2 changes: 1 addition & 1 deletion content/applications/appkit/howto/swaps.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ The quote is provider-supplied data and can expire. Refresh it close to the mome

## Before you begin

You need a connected wallet and at least one swap provider registered on the AppKit instance. Omniston and DeDust ship bundled — see [Use providers → How they are registered](/applications/appkit/howto/providers#how-they-are-registered).
You need a connected wallet and at least one swap provider registered on the AppKit instance. Some popular swap providers are bundled — see [Use providers → How they are registered](/applications/appkit/howto/providers#how-they-are-registered).

## Hooks

Expand Down
2 changes: 1 addition & 1 deletion content/applications/appkit/howto/use-ui-widgets.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -180,7 +180,7 @@ The required prop is `tokens`. `defaultFromSymbol`, `defaultToSymbol`, `defaultS

## Staking widget

`<StakingWidget />` is the complete staking UI: stake/unstake tabs, amount input, balance readout, current APY, exchange rate, and provider. The widget reads the registered staking provider (Tonstakers ships bundled — see [Use providers → How they are registered](/applications/appkit/howto/providers#how-they-are-registered)) and handles quote, build, and the wallet call internally.
`<StakingWidget />` is the complete staking UI: stake/unstake tabs, amount input, balance readout, current APY, exchange rate, and provider. The widget reads the [registered staking provider](/applications/appkit/howto/providers#how-they-are-registered) and handles quote, build, and the wallet call internally.

```tsx
import { StakingWidget } from '@ton/appkit-react';
Expand Down
6 changes: 3 additions & 3 deletions content/applications/appkit/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -60,9 +60,9 @@ AppKit builds on top of the following components:
| `@ton/appkit/queries` | Query and mutation helpers for data fetching |
| `@ton/appkit-react` | React provider, hooks, components, and core re-exports |
| `@ton/appkit-react/styles.css` | Default component styles |
| `@ton/appkit/swap/omniston` | Omniston swap provider |
| `@ton/appkit/swap/dedust` | DeDust swap provider |
| `@ton/appkit/staking/tonstakers` | Tonstakers staking provider |
| `@ton/appkit/swap/omniston` | Swap provider |
| `@ton/appkit/swap/dedust` | Swap provider |
| `@ton/appkit/staking/tonstakers` | Staking provider |

## Examples

Expand Down
4 changes: 2 additions & 2 deletions content/applications/appkit/reference/appkit-react.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -1167,7 +1167,7 @@ Drop-in widget for buying TON-side tokens with a crypto payment from another cha

```tsx
// Uses built-in defaults for tokens, payment methods and chain display info.
// Make sure a crypto-onramp provider (Layerswap / swaps.xyz) is registered on AppKit.
// Make sure a crypto-onramp provider is registered in AppKit.
return <CryptoOnrampWidget defaultTokenId="gram" />;
```

Expand Down Expand Up @@ -1758,7 +1758,7 @@ Drop-in swap UI that walks the user through picking the source/target tokens, en
**Example**

```tsx
// Make sure a swap provider (e.g. DeDust / Omniston) is registered on AppKit.
// Make sure a swap provider is registered in AppKit.
return <SwapWidget tokens={tokens} defaultFromSymbol="GRAM" defaultToSymbol="USDT" defaultSlippage={100} />;
```

Expand Down
Loading