> 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/dex/smart-contracts/v2/examples/swap.md).
# Swap Examples
Swap implementation examples - various swap schemes and patterns using v2 smart contracts
## Simple swap with referral
Simple swap of one token to another.
`Bob` is user doing the swap, `Alice` is referrer, `Send` is send token, `Receive` is receive token.
```mermaid
flowchart LR
A0(("Bob"))
A1["Bob
Send
Wallet"]
A2["Router
Send
Wallet"]
A3{"Router"}
A4(["Pool
Send-Receive"])
A5>"Alice
Receive
Vault"]
A6["Router
Receive
Wallet"]
A7["Bob
Receive
Wallet"]
A0 --> |index: 0
op::transfer|A1
A1 --> |index: 1
op::internal_transfer|A2
A2 --> |index: 2
op::transfer_notification|A3
A2 -.-> |index: 3
op::excesses|A0
A3 --> |index: 4
op::swap|A4
A4 -.-> |index: 5
op::pay_vault|A3
A4 -.-> |index: 6
op::pay_to|A3
A3 --> |index: 7
op::deposit_ref_fee|A5
A3 --> |index: 8
op::transfer|A6
A5 -.-> |index: 9
op::excesses|A0
A6 --> |index: 10
op::internal_transfer|A7
A7 -.-> |index: 11
op::excesses|A0
linkStyle 0 stroke:#ff4747,color:#ff4747
linkStyle 1 stroke:#ff4747,color:#ff4747
linkStyle 2 stroke:#ff4747,color:#ff4747
linkStyle 3 stroke:#0400f0,color:#0400f0
linkStyle 4 stroke:#ff4747,color:#ff4747
linkStyle 5 stroke:#02dbdb,color:#02dbdb
linkStyle 6 stroke:#02dbdb,color:#02dbdb
linkStyle 7 stroke:#ff4747,color:#ff4747
linkStyle 8 stroke:#ff4747,color:#ff4747
linkStyle 9 stroke:#0400f0,color:#0400f0
linkStyle 10 stroke:#ff4747,color:#ff4747
linkStyle 11 stroke:#0400f0,color:#0400f0
```
## Cross-swap on the same Router
Swap of one token to another using an intermediary token. This method is used if there's no available pool for a pair of tokens but there're pools for each token and some other (the same for both) intermediary token. This type of swap is not limited to 1 intermediary: in practice an arbitrary amount of intermediaries can be used. This type of swap can be combined with cross-swap using multiple `Routers`.
`Bob` is user doing the swap, `Send` is send token, `Mid` is intermediary token, `Receive` is receive token.
```mermaid
flowchart LR
A0(("Bob"))
A1["Bob
Send
Wallet"]
A2["Router
Send
Wallet"]
A3{"Router"}
A4(["Pool
Send-Mid"])
A5(["Pool
Mid-Receive"])
A6["Router
Receive
Wallet"]
A7["Bob
Receive
Wallet"]
A0 --> |index: 0
op::transfer|A1
A1 --> |index: 1
op::internal_transfer|A2
A2 --> |index: 2
op::transfer_notification|A3
A2 -.-> |index: 3
op::excesses|A0
A3 --> |index: 4
op::swap|A4
A4 -.-> |index: 5
op::pay_to|A3
A3 --> |index: 6
op::swap|A5
A5 -.-> |index: 7
op::pay_to|A3
A3 --> |index: 8
op::transfer|A6
A6 --> |index: 9
op::internal_transfer|A7
A7 -.-> |index: 10
op::excesses|A0
linkStyle 0 stroke:#ff4747,color:#ff4747
linkStyle 1 stroke:#ff4747,color:#ff4747
linkStyle 2 stroke:#ff4747,color:#ff4747
linkStyle 3 stroke:#0400f0,color:#0400f0
linkStyle 4 stroke:#ff4747,color:#ff4747
linkStyle 5 stroke:#02dbdb,color:#02dbdb
linkStyle 6 stroke:#ff4747,color:#ff4747
linkStyle 7 stroke:#02dbdb,color:#02dbdb
linkStyle 8 stroke:#ff4747,color:#ff4747
linkStyle 9 stroke:#ff4747,color:#ff4747
linkStyle 10 stroke:#0400f0,color:#0400f0
```
## Cross-swap using multiple Routers
Swap of one token to another using different `Routers`. This method is used if there's no available pool for a pair of tokens on the same Router but there're pools for each token and some other (the same for both) intermediary token on both `Routers`. This type of swap is not limited to 1 intermediary: in practice an arbitrary amount of intermediaries can be used. This type of swap can be combined with cross-swap on the same `Router`.
`Bob` is user doing the swap, `Send` is send token, `Mid` is intermediary token, `Receive` is receive token.
```mermaid
flowchart LR
A0(("Bob"))
A1["Bob
Send
Wallet"]
A2["Router1
Send
Wallet"]
A3{"Router1"}
A4(["Pool1
Send-Mid"])
A5["Router1
Mid
Wallet"]
A6["Router2
Mid
Wallet"]
A7{"Router2"}
A8(["Pool2
Mid-Receive"])
A9["Router2
Receive
Wallet"]
A10["Bob
Receive
Wallet"]
A0 --> |index: 0
op::transfer|A1
A1 --> |index: 1
op::internal_transfer|A2
A2 --> |index: 2
op::transfer_notification|A3
A2 -.-> |index: 3
op::excesses|A0
A3 --> |index: 4
op::swap|A4
A4 -.-> |index: 5
op::pay_to|A3
A3 --> |index: 6
op::transfer|A5
A5 --> |index: 7
op::internal_transfer|A6
A6 --> |index: 8
op::transfer_notification|A7
A6 -.-> |index: 9
op::excesses|A0
A7 --> |index: 10
op::swap|A8
A8 -.-> |index: 11
op::pay_to|A7
A7 --> |index: 12
op::transfer|A9
A9 --> |index: 13
op::internal_transfer|A10
A10 -.-> |index: 14
op::excesses|A0
linkStyle 0 stroke:#ff4747,color:#ff4747
linkStyle 1 stroke:#ff4747,color:#ff4747
linkStyle 2 stroke:#ff4747,color:#ff4747
linkStyle 3 stroke:#0400f0,color:#0400f0
linkStyle 4 stroke:#ff4747,color:#ff4747
linkStyle 5 stroke:#02dbdb,color:#02dbdb
linkStyle 6 stroke:#ff4747,color:#ff4747
linkStyle 7 stroke:#ff4747,color:#ff4747
linkStyle 8 stroke:#ff4747,color:#ff4747
linkStyle 9 stroke:#0400f0,color:#0400f0
linkStyle 10 stroke:#ff4747,color:#ff4747
linkStyle 11 stroke:#02dbdb,color:#02dbdb
linkStyle 12 stroke:#ff4747,color:#ff4747
linkStyle 13 stroke:#ff4747,color:#ff4747
linkStyle 14 stroke:#0400f0,color:#0400f0
```
## Refund swap
Refund swap if there's not enough liquidity in the pool or the expected amount of receive tokens is less than expected minimum. Since multi-contract transactions in TON are not atomic it is not possible to fully refund cross swap (on the same router or multiple), in such event the user will receive some intermediate token based on the pool used to route the swap.
`Bob` is user doing the swap, `Send` is send token, `Receive` is receive token.
```mermaid
flowchart LR
A0(("Bob"))
A1["Bob
Send
Wallet"]
A2["Router
Send
Wallet"]
A3{"Router"}
A4(["Pool
Send-Receive"])
A0 --> |index: 0
op::transfer|A1
A1 --> |index: 1
op::internal_transfer|A2
A2 --> |index: 2
op::transfer_notification|A3
A2 -.-> |index: 3
op::excesses|A0
A3 --> |index: 4
op::swap|A4
A4 -.-> |index: 5
op::pay_to|A3
A3 -.-> |index: 6
op::transfer|A2
A2 -.-> |index: 7
op::internal_transfer|A1
A1 -.-> |index: 8
op::excesses|A0
linkStyle 0 stroke:#ff4747,color:#ff4747
linkStyle 1 stroke:#ff4747,color:#ff4747
linkStyle 2 stroke:#ff4747,color:#ff4747
linkStyle 3 stroke:#0400f0,color:#0400f0
linkStyle 4 stroke:#ff4747,color:#ff4747
linkStyle 5 stroke:#02dbdb,color:#02dbdb
linkStyle 6 stroke:#02dbdb,color:#02dbdb
linkStyle 7 stroke:#02dbdb,color:#02dbdb
linkStyle 8 stroke:#0400f0,color:#0400f0
```
---
# 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/dex/smart-contracts/v2/examples/swap.md?ask=&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.