> 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/models.md).

# Models

## The PublicTokenItemApiDto object

```json
{"openapi":"3.0.0","info":{"title":"YiFi Swap Public API","version":"1.0"},"components":{"schemas":{"PublicTokenItemApiDto":{"type":"object","properties":{"uuid":{"type":"string","description":"Internal coin UUID (used by workflows; not required on public query params)"},"network":{"type":"string","description":"Canonical chain slug (`GET /v1/chains` → `id`)"},"ticker":{"type":"string","description":"Token ticker"},"name":{"type":"string","description":"Display name"},"supportsFixedRate":{"type":"boolean","description":"Whether any catalogued route supports a fixed rate for this asset"},"contractAddress":{"type":"object","description":"Contract address; `null` for native coins","nullable":true},"engineSupport":{"description":"Engines that support this token: `on-chain` (DEX), `off-chain` (CEX), and sometimes `private`","type":"array","items":{"type":"string"}},"logoUrlCoin":{"type":"string","description":"Token logo URL"},"regexAddress":{"type":"string","description":"JavaScript regex source used to validate addresses of this asset (`receiveAddress` / `refundAddress` on swap)"},"explorerAddressUrl":{"type":"string","description":"Block-explorer URL template for an address"},"explorerTransactionUrl":{"type":"string","description":"Block-explorer URL template for a transaction"},"decimals":{"type":"object","nullable":true,"description":"Token decimals"},"logoUrlsNetwork":{"type":"object","nullable":true,"description":"Network / chain logo URL"},"coingeckoCoinId":{"type":"object","nullable":true,"description":"CoinGecko coin id (`bitcoin`, `ethereum`, `usd-coin`)"},"currentPriceUsd":{"type":"object","nullable":true,"description":"Spot price in USD from CoinGecko (numeric string)"}},"required":["uuid","network","ticker","name","supportsFixedRate","contractAddress"]}}}}
```

## The TokenListApiResponseDto object

```json
{"openapi":"3.0.0","info":{"title":"YiFi Swap Public API","version":"1.0"},"components":{"schemas":{"TokenListApiResponseDto":{"type":"object","properties":{"tokens":{"type":"array","items":{"$ref":"#/components/schemas/PublicTokenItemApiDto"}},"totalTokens":{"type":"number","description":"Number of token objects in this response page (matches `tokens.length`)"},"limit":{"type":"number","description":"Page size for this response"},"offset":{"type":"number","description":"Pagination offset"},"total":{"type":"number","description":"Total tokens matching filters before pagination"}},"required":["tokens","totalTokens","limit","offset","total"]},"PublicTokenItemApiDto":{"type":"object","properties":{"uuid":{"type":"string","description":"Internal coin UUID (used by workflows; not required on public query params)"},"network":{"type":"string","description":"Canonical chain slug (`GET /v1/chains` → `id`)"},"ticker":{"type":"string","description":"Token ticker"},"name":{"type":"string","description":"Display name"},"supportsFixedRate":{"type":"boolean","description":"Whether any catalogued route supports a fixed rate for this asset"},"contractAddress":{"type":"object","description":"Contract address; `null` for native coins","nullable":true},"engineSupport":{"description":"Engines that support this token: `on-chain` (DEX), `off-chain` (CEX), and sometimes `private`","type":"array","items":{"type":"string"}},"logoUrlCoin":{"type":"string","description":"Token logo URL"},"regexAddress":{"type":"string","description":"JavaScript regex source used to validate addresses of this asset (`receiveAddress` / `refundAddress` on swap)"},"explorerAddressUrl":{"type":"string","description":"Block-explorer URL template for an address"},"explorerTransactionUrl":{"type":"string","description":"Block-explorer URL template for a transaction"},"decimals":{"type":"object","nullable":true,"description":"Token decimals"},"logoUrlsNetwork":{"type":"object","nullable":true,"description":"Network / chain logo URL"},"coingeckoCoinId":{"type":"object","nullable":true,"description":"CoinGecko coin id (`bitcoin`, `ethereum`, `usd-coin`)"},"currentPriceUsd":{"type":"object","nullable":true,"description":"Spot price in USD from CoinGecko (numeric string)"}},"required":["uuid","network","ticker","name","supportsFixedRate","contractAddress"]}}}}
```

## The ChainItemApiDto object

```json
{"openapi":"3.0.0","info":{"title":"YiFi Swap Public API","version":"1.0"},"components":{"schemas":{"ChainItemApiDto":{"type":"object","properties":{"id":{"type":"string","description":"Canonical slug. Use this value as `network`, `networkFrom`, `fromNetwork`, etc."},"name":{"type":"string","description":"Human-readable network name"},"chainId":{"type":"number","nullable":true},"status":{"type":"string","enum":["active","inactive","maintenance"]},"supportedEngines":{"type":"array","items":{"type":"string"}},"aliases":{"type":"array","items":{"type":"string"}},"nativeToken":{"type":"string"},"blockTime":{"type":"string","nullable":true},"providers":{"type":"object","description":"Liquidity provider slugs keyed by engine category","additionalProperties":true},"explorerUrl":{"type":"string"},"logoUrl":{"type":"object","nullable":true},"memoNeeded":{"type":"boolean","description":"Whether transfers on this chain require a memo/tag (derived from active coins with extraId)."}},"required":["id","name","chainId","status","supportedEngines","aliases","nativeToken"]}}}}
```

## The ChainsListApiResponseDto object

```json
{"openapi":"3.0.0","info":{"title":"YiFi Swap Public API","version":"1.0"},"components":{"schemas":{"ChainsListApiResponseDto":{"type":"object","properties":{"chains":{"type":"array","items":{"$ref":"#/components/schemas/ChainItemApiDto"}}},"required":["chains"]},"ChainItemApiDto":{"type":"object","properties":{"id":{"type":"string","description":"Canonical slug. Use this value as `network`, `networkFrom`, `fromNetwork`, etc."},"name":{"type":"string","description":"Human-readable network name"},"chainId":{"type":"number","nullable":true},"status":{"type":"string","enum":["active","inactive","maintenance"]},"supportedEngines":{"type":"array","items":{"type":"string"}},"aliases":{"type":"array","items":{"type":"string"}},"nativeToken":{"type":"string"},"blockTime":{"type":"string","nullable":true},"providers":{"type":"object","description":"Liquidity provider slugs keyed by engine category","additionalProperties":true},"explorerUrl":{"type":"string"},"logoUrl":{"type":"object","nullable":true},"memoNeeded":{"type":"boolean","description":"Whether transfers on this chain require a memo/tag (derived from active coins with extraId)."}},"required":["id","name","chainId","status","supportedEngines","aliases","nativeToken"]}}}}
```

## The TransactionTokenDto object

```json
{"openapi":"3.0.0","info":{"title":"YiFi Swap Public API","version":"1.0"},"components":{"schemas":{"TransactionTokenDto":{"type":"object","properties":{"ticker":{"type":"string","description":"Token ticker"},"network":{"type":"string","description":"Chain slug"},"logoTicker":{"type":"object","description":"Token logo URL or structured logo payload. May be an empty object `{}` while not loaded."},"logoNetwork":{"type":"object","description":"Network logo URL or structured logo payload. May be an empty object `{}` while not loaded."},"contractAddress":{"type":"object","description":"Token contract address (null for native coins)","nullable":true},"chainId":{"type":"object","description":"EVM chainId of the network (null when unknown or non-EVM)","nullable":true},"decimals":{"type":"object","description":"Token decimals","nullable":true}},"required":["ticker","network"]}}}}
```

## The TransactionStatusResponseDto object

```json
{"openapi":"3.0.0","info":{"title":"YiFi Swap Public API","version":"1.0"},"components":{"schemas":{"TransactionStatusResponseDto":{"type":"object","properties":{"uuid":{"type":"string","description":"YiFi UUID. Same value as `POST /v1/swap` → `transactionId` and as the path `{id}` you queried."},"transactionId":{"type":"string","description":"Provider-side transaction id (may differ from `uuid`)"},"status":{"type":"string","description":"Current top-level swap status","enum":["pending","processing","completed","failed","cancelled"]},"statusList":{"type":"object","description":"Granular step-by-step status map. Keys vary by provider and engine."},"engine":{"type":"string","description":"Swap engine used for this transaction","enum":["on-chain","off-chain","private"]},"provider":{"type":"string","description":"Provider slug executing this swap"},"logoProvider":{"type":"object","description":"Provider logo URL"},"fromToken":{"description":"Source token details","allOf":[{"$ref":"#/components/schemas/TransactionTokenDto"}]},"toToken":{"description":"Target token details","allOf":[{"$ref":"#/components/schemas/TransactionTokenDto"}]},"inputAmount":{"type":"string","description":"Amount sent by the user in source token units"},"receiveAmount":{"type":"string","description":"Amount received (or expected) in target token units"},"startTime":{"type":"string","description":"Timestamp when the transaction was created"},"completionTime":{"type":"string","description":"Timestamp when the transaction reached a terminal state (`completed`, `failed`, or `cancelled`). `null` while in progress."},"exchangeRate":{"type":"object","description":"Effective exchange rate (`receiveAmount / inputAmount`). Populated once the swap reaches `completed` status.","nullable":true},"expirationTime":{"type":"object","description":"Order expiration captured at swap creation (same as in create-swap response; mapped via exchanger expirationTimePath)","nullable":true},"txCreateMeta":{"type":"object","description":"Raw provider metadata from transaction creation. May be an empty object or JSON string."},"txDepositHash":{"type":"object","description":"On-chain deposit hash once known. `null` / omitted while waiting.","nullable":true},"txOutputHash":{"type":"object","description":"On-chain output / payout hash once known. `null` / omitted while waiting.","nullable":true},"depositAddress":{"type":"object","description":"Deposit address the user must send to (CEX / private)","nullable":true},"receiveAddress":{"type":"object","description":"Destination address that receives the output token","nullable":true}},"required":["uuid","transactionId","status","engine","provider","fromToken","toToken","inputAmount","receiveAmount"]},"TransactionTokenDto":{"type":"object","properties":{"ticker":{"type":"string","description":"Token ticker"},"network":{"type":"string","description":"Chain slug"},"logoTicker":{"type":"object","description":"Token logo URL or structured logo payload. May be an empty object `{}` while not loaded."},"logoNetwork":{"type":"object","description":"Network logo URL or structured logo payload. May be an empty object `{}` while not loaded."},"contractAddress":{"type":"object","description":"Token contract address (null for native coins)","nullable":true},"chainId":{"type":"object","description":"EVM chainId of the network (null when unknown or non-EVM)","nullable":true},"decimals":{"type":"object","description":"Token decimals","nullable":true}},"required":["ticker","network"]}}}}
```

## The SetDepositHashDto object

```json
{"openapi":"3.0.0","info":{"title":"YiFi Swap Public API","version":"1.0"},"components":{"schemas":{"SetDepositHashDto":{"type":"object","properties":{"from":{"type":"string","description":"Sender wallet address that broadcast the deposit"},"to":{"type":"string","description":"Deposit destination: provider deposit address (CEX/private) or the contract the user sent to (DEX)"},"hash":{"type":"string","description":"On-chain transaction hash of the broadcast deposit"},"input":{"type":"object","description":"Optional raw input forwarded to the provider workflow as `meta.data`. Shape is provider-specific."}},"required":["from","to","hash"]}}}}
```

## The ProviderLegalDocumentDto object

```json
{"openapi":"3.0.0","info":{"title":"YiFi Swap Public API","version":"1.0"},"components":{"schemas":{"ProviderLegalDocumentDto":{"type":"object","properties":{"docName":{"type":"string","description":"Document title"},"docLink":{"type":"string","description":"Official document URL"}},"required":["docName","docLink"]}}}}
```

## The AggregatorProviderDto object

```json
{"openapi":"3.0.0","info":{"title":"YiFi Swap Public API","version":"1.0"},"components":{"schemas":{"AggregatorProviderDto":{"type":"object","properties":{"id":{"type":"string","description":"Provider slug used in quote and swap requests"},"name":{"type":"string","description":"Display name of the provider"},"logoUrl":{"type":"object","description":"Provider logo URL","nullable":true},"engine":{"type":"string","description":"Swap engine for this provider","enum":["on-chain","off-chain","private"]},"status":{"type":"string","description":"Current operational status","enum":["active","inactive","maintenance"]},"kycLevel":{"type":"number","description":"KYC level inherited from the provider: 0 = No KYC, 1 = Rare KYC, 2 = Regular KYC","enum":[0,1,2]},"kycLevelName":{"type":"string","description":"KYC level display name"},"legal":{"description":"Provider legal documents (Terms of Use, etc.)","type":"array","items":{"$ref":"#/components/schemas/ProviderLegalDocumentDto"}},"description":{"type":"string","description":"Provider description for the public catalog"}},"required":["id","name","engine","status"]},"ProviderLegalDocumentDto":{"type":"object","properties":{"docName":{"type":"string","description":"Document title"},"docLink":{"type":"string","description":"Official document URL"}},"required":["docName","docLink"]}}}}
```

## The AggregatorInfoResponseDto object

```json
{"openapi":"3.0.0","info":{"title":"YiFi Swap Public API","version":"1.0"},"components":{"schemas":{"AggregatorInfoResponseDto":{"type":"object","properties":{"providers":{"description":"Active liquidity providers","type":"array","items":{"$ref":"#/components/schemas/AggregatorProviderDto"}},"totalProviders":{"type":"number","description":"Total number of providers in the response"},"aggregatedFrom":{"description":"Engine categories represented in the catalog","type":"array","items":{"type":"string"}},"breakdown":{"type":"object","description":"Count of providers per engine type"}},"required":["providers","totalProviders","aggregatedFrom","breakdown"]},"AggregatorProviderDto":{"type":"object","properties":{"id":{"type":"string","description":"Provider slug used in quote and swap requests"},"name":{"type":"string","description":"Display name of the provider"},"logoUrl":{"type":"object","description":"Provider logo URL","nullable":true},"engine":{"type":"string","description":"Swap engine for this provider","enum":["on-chain","off-chain","private"]},"status":{"type":"string","description":"Current operational status","enum":["active","inactive","maintenance"]},"kycLevel":{"type":"number","description":"KYC level inherited from the provider: 0 = No KYC, 1 = Rare KYC, 2 = Regular KYC","enum":[0,1,2]},"kycLevelName":{"type":"string","description":"KYC level display name"},"legal":{"description":"Provider legal documents (Terms of Use, etc.)","type":"array","items":{"$ref":"#/components/schemas/ProviderLegalDocumentDto"}},"description":{"type":"string","description":"Provider description for the public catalog"}},"required":["id","name","engine","status"]},"ProviderLegalDocumentDto":{"type":"object","properties":{"docName":{"type":"string","description":"Document title"},"docLink":{"type":"string","description":"Official document URL"}},"required":["docName","docLink"]}}}}
```

## The QuoteItemDto object

```json
{"openapi":"3.0.0","info":{"title":"YiFi Swap Public API","version":"1.0"},"components":{"schemas":{"QuoteItemDto":{"type":"object","properties":{"rateId":{"type":"string","description":"Internal rate ID. Pass this in `rateId` to `/v1/swap` to record exactly which quote the user saw. Snapshot is kept in cache for 5 minutes."},"engine":{"type":"string","description":"Swap engine used for this quote","enum":["on-chain","off-chain","private"]},"provider":{"type":"string","description":"Provider slug – use this value in the `provider` field when calling `/v1/swap`"},"exchangerName":{"type":"string","description":"Display name of the provider"},"logoUrl":{"type":"string","description":"Provider logo URL. May be absent for some providers."},"rate":{"type":"string","description":"Exchange rate expressed as output per 1 unit of input token"},"estimatedOutput":{"type":"string","description":"Estimated amount the recipient will receive after all fees"},"inUsdValue":{"type":"number","description":"USD equivalent of the IN amount. Rate is taken from the etalon provider to USDT (TRON, then ETH, then BSC), with a fallback to a quote provider if the etalon is unavailable. `null` when the rate cannot be fetched.","nullable":true},"inUsdRateError":{"type":"string","description":"Set to `\"Can't fetch USD-rate\"` when the IN USD rate cannot be fetched. The quote itself is still returned.","nullable":true},"outUsdValue":{"type":"number","description":"USD equivalent of `estimatedOutput`. Rate is taken from this quote’s provider to USDT (TRON, then ETH, then BSC). `null` when unavailable (including private routes).","nullable":true},"outUsdDeviationPercent":{"type":"number","description":"Percent deviation of `outUsdValue` from `inUsdValue`. Negative means the user receives fewer USD than they sent.","nullable":true},"fromTokenUsdtRate":{"type":"number","description":"Raw USDT rate of 1 IN token. Taken from the etalon provider (USDT TRON → ETH → BSC), with a fallback to a quote provider if the etalon is unavailable. `null` when the IN USD rate cannot be fetched.","nullable":true},"toTokenUsdtRate":{"type":"number","description":"Raw USDT rate of 1 OUT token via this quote’s provider (USDT TRON → ETH → BSC). `null` when unavailable (including private routes).","nullable":true},"rateReversed":{"type":"number","description":"Inverse of `rate`: 1 OUT coin = Y IN coin"},"quoteId":{"type":"string","description":"Quote ID from the provider. Pass this in `quoteId` when calling `/v1/swap` to lock in the rate. `null` for providers that do not support rate locking."},"gasEstimated":{"type":"string","description":"Estimated gas cost in native token units. Present for DEX routes only. `null` for CEX and private routes."},"protocolFee":{"type":"string","description":"Protocol-level fee amount. Present for some DEX routes only."},"providerFee":{"type":"string","description":"Provider-level fee on top of the protocol fee. Present for some DEX routes only."},"slippageTolerance":{"type":"string","description":"Slippage tolerance applied to this quote in percent. Present for DEX routes only."},"estimatedTime":{"type":"string","description":"Expected time to complete the swap via this provider"},"kycLevel":{"type":"number","description":"KYC level inherited from the provider: 0 = No KYC, 1 = Rare KYC, 2 = Regular KYC","enum":[0,1,2]},"kycLevelName":{"type":"string","description":"KYC level display name inherited from the provider"},"legal":{"description":"Provider legal documents (Terms of Use, etc.) inherited from the provider","type":"array","items":{"$ref":"#/components/schemas/ProviderLegalDocumentDto"}},"label":{"type":"string","description":"Label assigned to the best quote (e.g. `\"best price\"`). `null` for all other quotes in `allQuotes`."},"dataForSign":{"type":"object","description":"EIP-712 typed data for client-side signing. Present only for CoW Swap DEX routes."},"schemeSign":{"type":"string","description":"Signing scheme identifier. Present only for CoW Swap routes. Always `\"eip712\"`."},"version":{"type":"string","description":"Private route version: v1 — Monero intermediate hop; v2 — stablecoin / non-XMR. Only when engine=private.","enum":["v1","v2"]},"routeKind":{"type":"string","description":"Private route shape: `direct` is one Quickex private swap; `two_leg` is the deposit+withdraw hop. Only when engine=private. `version` stays v1 or v2.","enum":["direct","two_leg"]}},"required":["rateId","engine","provider","exchangerName","rate","estimatedOutput","inUsdValue","inUsdRateError","outUsdValue","outUsdDeviationPercent","fromTokenUsdtRate","toTokenUsdtRate","rateReversed","estimatedTime"]},"ProviderLegalDocumentDto":{"type":"object","properties":{"docName":{"type":"string","description":"Document title"},"docLink":{"type":"string","description":"Official document URL"}},"required":["docName","docLink"]}}}}
```

## The QuoteResponseDto object

```json
{"openapi":"3.0.0","info":{"title":"YiFi Swap Public API","version":"1.0"},"components":{"schemas":{"QuoteResponseDto":{"type":"object","properties":{"bestQuote":{"description":"Best quote across all sources – array with a single element (or empty if no quotes are available).","type":"array","items":{"$ref":"#/components/schemas/QuoteItemDto"}},"allQuotes":{"description":"Remaining quotes. Private best v1 and v2 (when present and not picked as the global best) are placed first, then other quotes sorted by `rate` descending.","type":"array","items":{"$ref":"#/components/schemas/QuoteItemDto"}}},"required":["bestQuote","allQuotes"]},"QuoteItemDto":{"type":"object","properties":{"rateId":{"type":"string","description":"Internal rate ID. Pass this in `rateId` to `/v1/swap` to record exactly which quote the user saw. Snapshot is kept in cache for 5 minutes."},"engine":{"type":"string","description":"Swap engine used for this quote","enum":["on-chain","off-chain","private"]},"provider":{"type":"string","description":"Provider slug – use this value in the `provider` field when calling `/v1/swap`"},"exchangerName":{"type":"string","description":"Display name of the provider"},"logoUrl":{"type":"string","description":"Provider logo URL. May be absent for some providers."},"rate":{"type":"string","description":"Exchange rate expressed as output per 1 unit of input token"},"estimatedOutput":{"type":"string","description":"Estimated amount the recipient will receive after all fees"},"inUsdValue":{"type":"number","description":"USD equivalent of the IN amount. Rate is taken from the etalon provider to USDT (TRON, then ETH, then BSC), with a fallback to a quote provider if the etalon is unavailable. `null` when the rate cannot be fetched.","nullable":true},"inUsdRateError":{"type":"string","description":"Set to `\"Can't fetch USD-rate\"` when the IN USD rate cannot be fetched. The quote itself is still returned.","nullable":true},"outUsdValue":{"type":"number","description":"USD equivalent of `estimatedOutput`. Rate is taken from this quote’s provider to USDT (TRON, then ETH, then BSC). `null` when unavailable (including private routes).","nullable":true},"outUsdDeviationPercent":{"type":"number","description":"Percent deviation of `outUsdValue` from `inUsdValue`. Negative means the user receives fewer USD than they sent.","nullable":true},"fromTokenUsdtRate":{"type":"number","description":"Raw USDT rate of 1 IN token. Taken from the etalon provider (USDT TRON → ETH → BSC), with a fallback to a quote provider if the etalon is unavailable. `null` when the IN USD rate cannot be fetched.","nullable":true},"toTokenUsdtRate":{"type":"number","description":"Raw USDT rate of 1 OUT token via this quote’s provider (USDT TRON → ETH → BSC). `null` when unavailable (including private routes).","nullable":true},"rateReversed":{"type":"number","description":"Inverse of `rate`: 1 OUT coin = Y IN coin"},"quoteId":{"type":"string","description":"Quote ID from the provider. Pass this in `quoteId` when calling `/v1/swap` to lock in the rate. `null` for providers that do not support rate locking."},"gasEstimated":{"type":"string","description":"Estimated gas cost in native token units. Present for DEX routes only. `null` for CEX and private routes."},"protocolFee":{"type":"string","description":"Protocol-level fee amount. Present for some DEX routes only."},"providerFee":{"type":"string","description":"Provider-level fee on top of the protocol fee. Present for some DEX routes only."},"slippageTolerance":{"type":"string","description":"Slippage tolerance applied to this quote in percent. Present for DEX routes only."},"estimatedTime":{"type":"string","description":"Expected time to complete the swap via this provider"},"kycLevel":{"type":"number","description":"KYC level inherited from the provider: 0 = No KYC, 1 = Rare KYC, 2 = Regular KYC","enum":[0,1,2]},"kycLevelName":{"type":"string","description":"KYC level display name inherited from the provider"},"legal":{"description":"Provider legal documents (Terms of Use, etc.) inherited from the provider","type":"array","items":{"$ref":"#/components/schemas/ProviderLegalDocumentDto"}},"label":{"type":"string","description":"Label assigned to the best quote (e.g. `\"best price\"`). `null` for all other quotes in `allQuotes`."},"dataForSign":{"type":"object","description":"EIP-712 typed data for client-side signing. Present only for CoW Swap DEX routes."},"schemeSign":{"type":"string","description":"Signing scheme identifier. Present only for CoW Swap routes. Always `\"eip712\"`."},"version":{"type":"string","description":"Private route version: v1 — Monero intermediate hop; v2 — stablecoin / non-XMR. Only when engine=private.","enum":["v1","v2"]},"routeKind":{"type":"string","description":"Private route shape: `direct` is one Quickex private swap; `two_leg` is the deposit+withdraw hop. Only when engine=private. `version` stays v1 or v2.","enum":["direct","two_leg"]}},"required":["rateId","engine","provider","exchangerName","rate","estimatedOutput","inUsdValue","inUsdRateError","outUsdValue","outUsdDeviationPercent","fromTokenUsdtRate","toTokenUsdtRate","rateReversed","estimatedTime"]},"ProviderLegalDocumentDto":{"type":"object","properties":{"docName":{"type":"string","description":"Document title"},"docLink":{"type":"string","description":"Official document URL"}},"required":["docName","docLink"]}}}}
```

## The TokenPairDto object

```json
{"openapi":"3.0.0","info":{"title":"YiFi Swap Public API","version":"1.0"},"components":{"schemas":{"TokenPairDto":{"type":"object","properties":{"fromToken":{"type":"string","description":"Source token ticker"},"fromNetwork":{"type":"string","description":"Source chain slug"},"toToken":{"type":"string","description":"Target token ticker"},"toNetwork":{"type":"string","description":"Target chain slug"},"availableEngines":{"description":"Available engines for this pair","type":"array","items":{"type":"string"}},"providers":{"description":"Provider IDs supporting this pair","type":"array","items":{"type":"string"}},"minAmount":{"type":"string","description":"Minimum exchange amount"},"maxAmount":{"type":"string","description":"Maximum exchange amount"}},"required":["fromToken","fromNetwork","toToken","toNetwork","availableEngines","providers","minAmount","maxAmount"]}}}}
```

## The TokenPairsResponseDto object

```json
{"openapi":"3.0.0","info":{"title":"YiFi Swap Public API","version":"1.0"},"components":{"schemas":{"TokenPairsResponseDto":{"type":"object","properties":{"tokenPairs":{"description":"List of token pairs","type":"array","items":{"$ref":"#/components/schemas/TokenPairDto"}},"totalPairs":{"type":"number","description":"Total number of token pairs found"}},"required":["tokenPairs","totalPairs"]},"TokenPairDto":{"type":"object","properties":{"fromToken":{"type":"string","description":"Source token ticker"},"fromNetwork":{"type":"string","description":"Source chain slug"},"toToken":{"type":"string","description":"Target token ticker"},"toNetwork":{"type":"string","description":"Target chain slug"},"availableEngines":{"description":"Available engines for this pair","type":"array","items":{"type":"string"}},"providers":{"description":"Provider IDs supporting this pair","type":"array","items":{"type":"string"}},"minAmount":{"type":"string","description":"Minimum exchange amount"},"maxAmount":{"type":"string","description":"Maximum exchange amount"}},"required":["fromToken","fromNetwork","toToken","toNetwork","availableEngines","providers","minAmount","maxAmount"]}}}}
```

## The CreateSwapDto object

```json
{"openapi":"3.0.0","info":{"title":"YiFi Swap Public API","version":"1.0"},"components":{"schemas":{"CreateSwapDto":{"type":"object","properties":{"provider":{"type":"string","description":"Provider slug from the chosen quote's `provider` field"},"fromToken":{"type":"string","description":"Source token ticker"},"fromNetwork":{"type":"string","description":"Source chain slug — same as `GET /v1/chains` → `id` (case-insensitive)"},"toToken":{"type":"string","description":"Target token ticker"},"toNetwork":{"type":"string","description":"Target chain slug — same as `GET /v1/chains` → `id` (case-insensitive)"},"engine":{"type":"string","description":"Swap engine to use. Must match the engine from the selected quote.\n\n- `cex` – off-chain CEX swap\n\n- `dex` – on-chain DEX swap\n\n- `private` – two-rail private swap (no JWT required on this API)","enum":["cex","dex","private"]},"amount":{"type":"number","description":"Amount to exchange in source token units","minimum":1e-8},"quoteId":{"type":"string","description":"Quote ID from `/v1/quote`. Locks in the rate with providers that support it."},"rateId":{"type":"string","description":"Internal rate ID from `/v1/quote` response. Use to record the exact quote shown to the user in the transaction history. The snapshot expires 5 minutes after the quote was issued. If you pass an expired or unknown ID the request will be rejected with `RATE_EXPIRED`."},"receiveAddress":{"type":"string","description":"Destination wallet address for the output token"},"addressFrom":{"type":"string","description":"Legacy field. Accepted (not rejected by validation) but **not used** by `createSwap`."},"slippageTolerance":{"type":"string","description":"Slippage tolerance in percent. Default `\"0.5\"`. **Applies to DEX routes only** (`engine=dex`). Ignored for CEX and private.","default":"0.5"},"extraIdTo":{"type":"string","description":"Memo / tag for the destination address. Required for tokens that need it (e.g. XRP, XLM, TON)."},"refundAddress":{"type":"string","description":"Address to receive a refund if the swap fails. Recommended when the chosen provider or route requires it — follow provider documentation and support guidance. Strongly recommended for private swaps."},"refundExtraId":{"type":"string","description":"Memo / tag for the refund address, if required by the source network"},"ref":{"type":"string","description":"Partner affiliate referral code (alias of `refCode`). Optional: without a code the swap is created as usual. Attributes the swap to the partner via their affiliate referral node."},"refCode":{"type":"string","description":"Partner affiliate referral code. Attributes the swap to the partner via their affiliate referral node. Optional. If both `ref` and `refCode` are sent, `ref` wins. An unknown code is rejected with `REFERRAL_CODE_NOT_FOUND`."}},"required":["provider","fromToken","fromNetwork","toToken","toNetwork","engine","amount","receiveAddress"]}}}}
```

## The SwapResponseDto object

```json
{"openapi":"3.0.0","info":{"title":"YiFi Swap Public API","version":"1.0"},"components":{"schemas":{"SwapResponseDto":{"type":"object","properties":{"fromToken":{"type":"string","description":"Source token ticker"},"fromNetwork":{"type":"string","description":"Source chain slug as sent in the request"},"toToken":{"type":"string","description":"Target token ticker"},"toNetwork":{"type":"string","description":"Target chain slug as sent in the request"},"provider":{"type":"string","description":"Provider slug executing this swap"},"transactionId":{"type":"string","description":"YiFi transaction ID. Use this to poll `/v1/transactions/{id}` for status updates."},"accessToken":{"type":"string","description":"Issued once at swap creation. Store securely client-side (used for private flows and client-side transaction operations)."},"externalTransactionId":{"type":"string","description":"Provider-side transaction id when it differs from the YiFi UUID in `transactionId`."},"status":{"type":"string","description":"Initial swap status – always `pending` at the moment of creation","enum":["pending","processing","completed","failed"]},"statusList":{"type":"object","description":"Granular step-by-step status map. All values are `false` at creation. Keys vary by provider and engine."},"receiveAmount":{"type":"string","description":"Expected output amount the recipient will receive"},"expirationTime":{"type":"object","description":"Order expiration from provider response (JSON path configured as expirationTimePath on create-exchange endpoint)","nullable":true},"estimatedOutput":{"type":"string","description":"Legacy: expected output amount (prefer `receiveAmount`)"},"estimatedTime":{"type":"string","description":"Expected time to complete the swap"},"depositAddress":{"type":"object","description":"Address to send source funds to. Present for CEX and private routes. `null` for DEX routes where funds are pulled via smart contract.","nullable":true},"extraIdTo":{"type":"string","description":"Memo / tag for the destination address, if required"},"refundAddress":{"type":"string","description":"Address that will receive funds if the swap fails"},"refundExtraId":{"type":"string","description":"Memo / tag for the refund address, if required"},"txCreateMeta":{"type":"object","description":"Raw transaction metadata returned by the provider at creation (e.g. `hash`, `nonce`). May be a JSON string.","nullable":true},"extraIdDeposit":{"type":"string","description":"Memo / tag for the deposit address, if required by the source network"},"tokenForTx":{"type":"string","description":"Ticker of the token as returned by the provider's internal `createExchange` response. May differ from `fromToken` in multi-hop DEX routes."}},"required":["fromToken","fromNetwork","toToken","toNetwork","provider","transactionId","accessToken","status","receiveAmount","estimatedTime"]}}}}
```