> For the complete documentation index, see [llms.txt](https://docs.yifi.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.yifi.io/api-reference/general.md).

# General

## GET /

>

```json
{"openapi":"3.0.0","info":{"title":"YiFi Swap Public API","version":"1.0.0"},"tags":[{"name":"General"}],"paths":{"/":{"get":{"operationId":"AppController_getHello","parameters":[],"responses":{"200":{"description":""}},"tags":["General"]}}}}
```

## Get token list

> Returns a list of tokens from cache with filtering and pagination support

```json
{"openapi":"3.0.0","info":{"title":"YiFi Swap Public API","version":"1.0.0"},"tags":[{"name":"General"}],"paths":{"/tokens":{"get":{"description":"Returns a list of tokens from cache with filtering and pagination support","operationId":"AppController_getCoins","parameters":[{"name":"search","required":false,"in":"query","description":"Search by contractAddress, ticker, name, network and aliases (erc20, trc20, arb, etc.)","schema":{"type":"string"}},{"name":"network","required":false,"in":"query","description":"Filter by network (slug: ethereum, arbitrum, tron, etc.)","schema":{"type":"string"}},{"name":"supportsFixedRate","required":false,"in":"query","description":"Filter by fixed-rate support","schema":{"type":"boolean"}},{"name":"engine","required":false,"in":"query","description":"Filter by exchanger type: cex (off-chain) or dex (on-chain). Keeps only coins that support the specified engine.","schema":{"type":"string","enum":["cex","dex"]}},{"name":"limit","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":20,"type":"number"}},{"name":"offset","required":false,"in":"query","description":"Pagination offset","schema":{"minimum":0,"default":0,"type":"number"}},{"name":"isPopular","required":false,"in":"query","description":"Filter by popularity","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Token list retrieved successfully"}},"summary":"Get token list","tags":["General"]}}}}
```

## GET /chains

>

```json
{"openapi":"3.0.0","info":{"title":"YiFi Swap Public API","version":"1.0.0"},"tags":[{"name":"General"}],"paths":{"/chains":{"get":{"operationId":"AppController_getChains","parameters":[{"name":"engine","required":false,"in":"query","description":"Filter by engine type","schema":{"type":"string","enum":["on-chain","off-chain","private"]}}],"responses":{"200":{"description":""}},"tags":["General"]}}}}
```

## Latest private orders

> Returns the most recent orders with engine \`private\` from the database (Temporal → admin-service / core-api). Defaults to 10 records.

```json
{"openapi":"3.0.0","info":{"title":"YiFi Swap Public API","version":"1.0.0"},"tags":[{"name":"General"}],"paths":{"/last-private-order":{"get":{"description":"Returns the most recent orders with engine `private` from the database (Temporal → admin-service / core-api). Defaults to 10 records.","operationId":"AppController_getLastPrivateOrders","parameters":[{"name":"limit","required":false,"in":"query","description":"Maximum number of records (1–100), default 10","schema":{"type":"string"}}],"responses":{"200":{"description":"List of the latest private orders"}},"summary":"Latest private orders","tags":["General"]}}}}
```

## Get transaction status

> Returns the detailed status of a transaction by id (uuid or transaction\_id). Requires the \`access\_token\` query parameter — the same secret issued when the swap was created.

```json
{"openapi":"3.0.0","info":{"title":"YiFi Swap Public API","version":"1.0.0"},"tags":[{"name":"General"}],"paths":{"/transaction/{id}":{"get":{"description":"Returns the detailed status of a transaction by id (uuid or transaction_id). Requires the `access_token` query parameter — the same secret issued when the swap was created.","operationId":"AppController_getTransactionStatus","parameters":[{"name":"id","required":true,"in":"path","description":"Transaction ID to check the status of","schema":{"type":"string"}},{"name":"access_token","required":true,"in":"query","description":"Secret access token for the transaction","schema":{"type":"string"}}],"responses":{"200":{"description":"Transaction status retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionStatusResponseDto"}}}},"404":{"description":"Transaction not found","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number"},"message":{"type":"string"},"error":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number"},"message":{"type":"string"},"error":{"type":"string"}}}}}}},"summary":"Get transaction status","tags":["General"]}}},"components":{"schemas":{"TransactionStatusResponseDto":{"type":"object","properties":{"uuid":{"type":"string","description":"Transaction UUID"},"transactionId":{"type":"string","description":"Provider-side transaction ID"},"status":{"type":"string","description":"Transaction status","enum":["pending","processing","completed","failed","cancelled"]},"statusList":{"type":"object","description":"Detailed status by stage"},"engine":{"type":"string","description":"Engine type"},"provider":{"type":"string","description":"Provider (exchanger) slug"},"logoProvider":{"type":"object","description":"Provider logo URL"},"fromToken":{"description":"Source token","allOf":[{"$ref":"#/components/schemas/TransactionTokenDto"}]},"toToken":{"description":"Target token","allOf":[{"$ref":"#/components/schemas/TransactionTokenDto"}]},"inputAmount":{"type":"string","description":"Deposit amount (the amount sent by the user)"},"receiveAmount":{"type":"string","description":"Receive amount"},"fee":{"type":"string","description":"Fee"},"startTime":{"type":"string","description":"Transaction start time"},"completionTime":{"type":"string","description":"Transaction completion time"},"exchangeRate":{"type":"object","description":"Exchange rate (receiveAmount / inputAmount)","nullable":true},"expirationTime":{"type":"object","description":"Order expiration time (same as on creation; from the provider response via expirationTimePath)","nullable":true},"txCreateMeta":{"type":"object","description":"Transaction creation metadata from the provider"},"transactionTransfer":{"type":"object","description":"Data for the ERC20 transfer (only for cex/private when fromNetwork is EVM and the token has a contractAddress)"}},"required":["uuid","transactionId","status","engine","provider","fromToken","toToken","inputAmount","receiveAmount","fee"]},"TransactionTokenDto":{"type":"object","properties":{"ticker":{"type":"string","description":"Token ticker"},"network":{"type":"string","description":"Network"},"logoTicker":{"type":"object","description":"Token logo URL"},"logoNetwork":{"type":"object","description":"Network logo URL"},"contractAddress":{"type":"object","description":"Token contract address on the network (null for a native coin)","nullable":true},"chainId":{"type":"object","description":"EVM chainId of the network (null if the network is not EVM or the chainId is unknown)","nullable":true},"decimals":{"type":"object","description":"Number of token decimals","nullable":true}},"required":["ticker","network"]}}}}
```

## Recover the access\_token by transaction and receive address

> If the transaction exists in the admin database and the stored receive\_address matches the one provided, returns the access\_token. Otherwise returns 404 without specifying the reason.

```json
{"openapi":"3.0.0","info":{"title":"YiFi Swap Public API","version":"1.0.0"},"tags":[{"name":"General"}],"paths":{"/transaction/recover-access":{"post":{"description":"If the transaction exists in the admin database and the stored receive_address matches the one provided, returns the access_token. Otherwise returns 404 without specifying the reason.","operationId":"AppController_recoverTransactionAccess","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecoverTransactionAccessBodyDto"}}}},"responses":{"200":{"description":"Access token issued successfully","content":{"application/json":{"schema":{"type":"object","required":["access_token"],"properties":{"access_token":{"type":"string"}}}}}},"404":{"description":"Transaction not found or the receive address does not match"}},"summary":"Recover the access_token by transaction and receive address","tags":["General"]}}},"components":{"schemas":{"RecoverTransactionAccessBodyDto":{"type":"object","properties":{"id":{"type":"string","description":"Transaction UUID or provider-side transaction_id"},"receive_address":{"type":"string","description":"Receive address (must match the one stored in the transaction)"}},"required":["id","receive_address"]}}}}
```

## Set email for a transaction

> Accepts a transaction uuid and email and stores them in the admin database via Temporal

```json
{"openapi":"3.0.0","info":{"title":"YiFi Swap Public API","version":"1.0.0"},"tags":[{"name":"General"}],"paths":{"/transaction/set-email":{"post":{"description":"Accepts a transaction uuid and email and stores them in the admin database via Temporal","operationId":"AppController_setTransactionEmail","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["uuid","email"],"properties":{"uuid":{"type":"string"},"email":{"type":"string"}}}}}},"responses":{"200":{"description":"Email set successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}}},"summary":"Set email for a transaction","tags":["General"]}}}}
```

## Get the list of swap pairs

> Returns the full list of swap pairs from cache

```json
{"openapi":"3.0.0","info":{"title":"YiFi Swap Public API","version":"1.0.0"},"tags":[{"name":"General"}],"paths":{"/explore-pairs":{"get":{"description":"Returns the full list of swap pairs from cache","operationId":"AppController_getExplorePairs","parameters":[],"responses":{"200":{"description":"Swap pairs list retrieved successfully"}},"summary":"Get the list of swap pairs","tags":["General"]}}}}
```

## List of private directions

> \`?priority=true\` — popular directions only (both coins from BTC/XMR/ETH/LTC/USDT/SOL/USDC, across all their networks). Without the parameter — all other directions. Pagination is supported via \`limit\` (1..200, default 20) and \`offset\` (>=0, default 0). Routes are deduplicated by the (fromCoinUuid, toCoinUuid) pair.

```json
{"openapi":"3.0.0","info":{"title":"YiFi Swap Public API","version":"1.0.0"},"tags":[{"name":"General"}],"paths":{"/private-pairs":{"get":{"description":"`?priority=true` — popular directions only (both coins from BTC/XMR/ETH/LTC/USDT/SOL/USDC, across all their networks). Without the parameter — all other directions. Pagination is supported via `limit` (1..200, default 20) and `offset` (>=0, default 0). Routes are deduplicated by the (fromCoinUuid, toCoinUuid) pair.","operationId":"AppController_getPrivatePairs","parameters":[{"name":"priority","required":false,"in":"query","description":"true — popular directions only (both coins from BTC/XMR/ETH/LTC/USDT/SOL/USDC); false/unset — all others","schema":{"type":"boolean"}},{"name":"limit","required":false,"in":"query","description":"Number of directions per page","schema":{"minimum":1,"maximum":200,"default":20,"type":"number"}},{"name":"offset","required":false,"in":"query","description":"Pagination offset","schema":{"minimum":0,"default":0,"type":"number"}}],"responses":{"200":{"description":"List of private directions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrivatePairsResponseDto"}}}}},"summary":"List of private directions","tags":["General"]}}},"components":{"schemas":{"PrivatePairsResponseDto":{"type":"object","properties":{"pairs":{"type":"array","items":{"$ref":"#/components/schemas/PrivatePairDto"}},"total":{"type":"number","description":"Total number of directions in the selection (popular or other) before pagination"},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["pairs","total","limit","offset"]},"PrivatePairDto":{"type":"object","properties":{"from":{"$ref":"#/components/schemas/PrivatePairCoinDto"},"to":{"$ref":"#/components/schemas/PrivatePairCoinDto"}},"required":["from","to"]},"PrivatePairCoinDto":{"type":"object","properties":{"ticker":{"type":"string"},"network":{"type":"string"},"logoTicker":{"type":"string","nullable":true},"logoNetwork":{"type":"string","nullable":true}},"required":["ticker","network"]}}}}
```

## Telegram user's swap history

> Reads \`X-Telegram-Init-Data\` (like createSwap), validates the HMAC and returns swaps for the \`telegram\_user\_id\` with pagination (\`items\` + \`total\`). If the header is missing, an empty page is returned.

```json
{"openapi":"3.0.0","info":{"title":"YiFi Swap Public API","version":"1.0.0"},"tags":[{"name":"General"}],"paths":{"/telegram/history":{"get":{"description":"Reads `X-Telegram-Init-Data` (like createSwap), validates the HMAC and returns swaps for the `telegram_user_id` with pagination (`items` + `total`). If the header is missing, an empty page is returned.","operationId":"AppController_getTelegramHistory","parameters":[{"name":"limit","required":false,"in":"query","description":"Maximum number of records (1–100), default 50","schema":{"type":"string"}},{"name":"offset","required":false,"in":"query","description":"Offset (for pagination), default 0","schema":{"type":"string"}},{"name":"X-Telegram-Init-Data","in":"header","description":"Telegram Mini App initData (window.Telegram.WebApp.initData). When present, the HMAC is validated and telegram_user_id is taken from user.id.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"A page of the user's swap history (items + total)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TelegramUserSwapHistoryResponseDto"}}}}},"summary":"Telegram user's swap history","tags":["General"]}}},"components":{"schemas":{"TelegramUserSwapHistoryResponseDto":{"type":"object","properties":{"items":{"description":"History records (page)","type":"array","items":{"$ref":"#/components/schemas/TelegramUserSwapHistoryItemDto"}},"total":{"type":"number","description":"Total number of the user's records (ignoring limit/offset)"},"limit":{"type":"number","description":"Applied limit"},"offset":{"type":"number","description":"Applied offset"}},"required":["items","total","limit","offset"]},"TelegramUserSwapHistoryItemDto":{"type":"object","properties":{"uuid":{"type":"string"},"transactionId":{"type":"string"},"status":{"type":"string"},"engine":{"type":"string"},"provider":{"type":"string"},"logoProvider":{"type":"object","description":"Provider logo URL","nullable":true},"fromToken":{"description":"Source token (ticker, network, logos, contract, chainId, decimals)","allOf":[{"$ref":"#/components/schemas/TransactionTokenDto"}]},"toToken":{"description":"Target token (ticker, network, logos, contract, chainId, decimals)","allOf":[{"$ref":"#/components/schemas/TransactionTokenDto"}]},"depositAmount":{"type":"string"},"receiveAmount":{"type":"object","nullable":true},"createdAt":{"type":"string"},"accessToken":{"type":"string","description":"Secret for GET /transaction/:id?access_token=…"}},"required":["uuid","transactionId","status","engine","provider","fromToken","toToken","depositAmount","createdAt","accessToken"]},"TransactionTokenDto":{"type":"object","properties":{"ticker":{"type":"string","description":"Token ticker"},"network":{"type":"string","description":"Network"},"logoTicker":{"type":"object","description":"Token logo URL"},"logoNetwork":{"type":"object","description":"Network logo URL"},"contractAddress":{"type":"object","description":"Token contract address on the network (null for a native coin)","nullable":true},"chainId":{"type":"object","description":"EVM chainId of the network (null if the network is not EVM or the chainId is unknown)","nullable":true},"decimals":{"type":"object","description":"Number of token decimals","nullable":true}},"required":["ticker","network"]}}}}
```