> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pods.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Get a Quote

> Learn how to request quotes for swapping tokens on same-chain or cross-chain

In this section, you'll learn how to request quotes for swapping between tokens using the Pods API.

## Prerequisites

<CardGroup cols={2}>
  <Card title="API Key" icon="key">
    Get your API key for authentication at
    [Pods](https://www.pods.finance/plg/select-plan)
  </Card>

  <Card title="Token Addresses" icon="coins">
    Contract addresses for the tokens you want to swap
  </Card>

  <Card title="Chain IDs" icon="link">
    Chain IDs for source and destination chains
  </Card>

  <Card title="Authentication" icon="shield-check">
    Include your API key in the `x-api-key` header
  </Card>
</CardGroup>

## Overview

The Pods API supports both same-chain and cross-chain token swaps. The system automatically detects the swap type based on the chain IDs provided and routes to the appropriate provider.

<Info>
  **Same-chain Swap**: When `originChain` equals `destinationChain`
  **Cross-chain Swap**: When `originChain` differs from `destinationChain`
</Info>

## Getting a Quote

### Endpoint

```http theme={null}
GET /v2/swap/quote
```

<Info>
  This is a **v2** endpoint. Always use `/v2/swap/quote` for new integrations —
  it saves quotes to the database and returns a `quoteId` required by `POST
      /v2/swap/bytecode`.
</Info>

### Required Parameters

| Parameter                          | Type             | Description                                                               | Example                                             |
| ---------------------------------- | ---------------- | ------------------------------------------------------------------------- | --------------------------------------------------- |
| `originChain` or `chainIdIn`       | string or number | Source chain name, or source chain ID. Use one of these fields.           | `ethereum`, `1`                                     |
| `destinationChain` or `chainIdOut` | string or number | Destination chain name, or destination chain ID. Use one of these fields. | `polygon`, `137`                                    |
| `tokenIn`                          | string           | Contract address of input token                                           | `0xdAC17F958D2ee523a2206206994597C13D831ec7` (USDT) |
| `tokenOut`                         | string           | Contract address of output token                                          | `0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174` (USDC) |
| `amountIn` or `amountOut`          | string           | Amount in the token's smallest unit. Provide exactly one of these fields. | `1000000`                                           |

### Optional Parameters

| Parameter            | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Example |
| -------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `preferredProvider`  | string  | Force a specific swap provider for the returned quote when multiple providers support the route. Case-insensitive. Must be a registered provider name (`relay`, `mayan`, `lifi`, `cctp`, `1inch`, `jupiter`, `teleswap`, `uniswap`, `pods`, `symbiosis-bitcoin`). The provider must be eligible for the token pair and chains. When omitted, the API returns and persists the quote with the highest `tokenOut.expectedAmountOut`. Returns `INVALID_PREFERRED_PROVIDER` (400) if the name is not registered, `PREFERRED_PROVIDER_NOT_ELIGIBLE` (400) if the provider does not support the route, or `PREFERRED_PROVIDER_QUOTE_UNAVAILABLE` (400) if the provider returned no quote. | `relay` |
| `slippage`           | number  | Max slippage as a **fraction of 1** (e.g. `0.01` = 1%). Range `0.0001`–`0.5`. Passed to the selected provider; omit to use each provider’s default. Returns `INVALID_SLIPPAGE` (400) when out of range.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `0.01`  |
| `originAddress`      | string  | Sender address on the origin chain. When provided together with `destinationAddress`, the response also includes transaction bytecode (`id` + `transactionData`) — no separate call to `POST /v2/swap/bytecode` needed.                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `0x…`   |
| `transferSpeed`      | string  | Transfer speed for CCTP cross-chain swaps. `fast` (default) or `standard`. Ignored for non-CCTP routes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `fast`  |
| `originAddress`      | string  | Address of the sender on the origin chain. When provided together with `destinationAddress`, the endpoint returns transaction bytecode in the same response — no separate call to `POST /v2/swap/bytecode` is needed.                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `0x…`   |
| `destinationAddress` | string  | Recipient on the destination chain. When provided together with `originAddress`, the endpoint returns transaction bytecode in the same response.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `0x…`   |
| `refundAddress`      | string  | Refund address if the swap fails                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `0x…`   |
| `feeSponsorship`     | boolean | Request fee sponsorship on eligible Pods bridge routes (`pods` provider). Defaults to `false`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `false` |

<Info>
  Either `amountIn` OR `amountOut` is required (not both). Use `amountOut` for
  exact output swaps ("I want to receive exactly X tokens").
</Info>

<Tip>
  Provide **either** named chains (`originChain` + `destinationChain`) **or**
  numeric IDs (`chainIdIn` + `chainIdOut`). Responses always include canonical
  **`chainIdIn`** / **`chainIdOut`** on the quote when the API can resolve them;
  prefer these for storage and UI over string names or legacy `fromChainId` /
  `toChainId`.
</Tip>

## Example Requests

### Same-Chain Swap (Ethereum USDT to USDC)

```bash theme={null}
curl --request GET \
  --url 'https://api.pods.finance/v2/swap/quote?originChain=ethereum&destinationChain=ethereum&tokenIn=0xdAC17F958D2ee523a2206206994597C13D831ec7&tokenOut=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48&amountIn=1000000' \
  --header 'x-api-key: YOUR_API_KEY'
```

### Cross-Chain Swap (Ethereum to Polygon)

```bash theme={null}
curl --request GET \
  --url 'https://api.pods.finance/v2/swap/quote?originChain=ethereum&destinationChain=polygon&tokenIn=0xdAC17F958D2ee523a2206206994597C13D831ec7&tokenOut=0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174&amountIn=1000000' \
  --header 'x-api-key: YOUR_API_KEY'
```

### Same route using chain IDs

```bash theme={null}
curl --request GET \
  --url 'https://api.pods.finance/v2/swap/quote?chainIdIn=1&chainIdOut=137&tokenIn=0xdAC17F958D2ee523a2206206994597C13D831ec7&tokenOut=0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174&amountIn=1000000' \
  --header 'x-api-key: YOUR_API_KEY'
```

### Cross-chain with a preferred provider

When several providers can quote the same route, pass `preferredProvider` to persist and return that provider’s quote (for example, to keep routing consistent with your UI or compliance rules):

```bash theme={null}
curl --request GET \
  --url 'https://api.pods.finance/v2/swap/quote?originChain=polygon&destinationChain=arbitrum&tokenIn=0x3c499c542cef5e3811e1192ce70d8cc03d5c3359&tokenOut=0xaf88d065e77c8cc2239327c5edb3a432268e5831&amountIn=1000000&preferredProvider=relay' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Multi-route aggregation

For routes supported by more than one provider, the API requests quotes in parallel, ranks them by `tokenOut.expectedAmountOut`, and **returns a single `quote` object** — the best route by default, or the `preferredProvider` when set.

* Only that quote is saved to the database. Use the quote `quoteId` (or the quote object's `id` when present) with `POST /v2/swap/bytecode`.
* Fixed-quote Pods bridge routes (`pods` provider) still use a single provider; `preferredProvider` must be `pods` or omitted on those paths.

## Response Format

The API returns a JSON object with one persisted quote. When both `originAddress` and `destinationAddress` are supplied, the response also includes transaction bytecode fields (`id`, `chainId`, `transactionData`) — equivalent to calling `POST /v2/swap/bytecode` separately. The quote always includes a `feeBreakdown` object that itemizes platform fees (Pods fee, customer markup fee) and the estimated bridge/slippage impact:

```json theme={null}
{
  "quote": {
    "quoteId": "550e8400-e29b-41d4-a716-446655440000",
    "chainIdIn": 1,
    "chainIdOut": 137,
    "originChain": "ethereum",
    "destinationChain": "polygon",
    "tokenIn": {
      "contract": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
      "symbol": "USDT",
      "decimals": 6,
      "amount": "1000000",
      "chainId": 1
    },
    "tokenOut": {
      "contract": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
      "symbol": "USDC",
      "decimals": 6,
      "amount": "998500",
      "chainId": 137
    },
    "provider": "relay",
    "deadline": 1706098500,
    "status": "pending",
    "feeSponsorship": false,
    "feeBreakdown": {
      "chargeableAmountInRaw": "1000000",
      "amountInAfterPlatformFeesRaw": "985000",
      "reference": {
        "amountOutRaw": "998600",
        "source": "spotUsdAtQuoteTime",
        "pricedAt": "2026-05-28T14:32:10.000Z",
        "tokenInPriceInUSD": 1,
        "tokenOutPriceInUSD": 1,
        "amountInAfterPlatformFeesRaw": "985000"
      },
      "charges": [
        {
          "kind": "pods",
          "label": "Pods fee",
          "amountRaw": "5000",
          "amountInUSD": 0.005,
          "asset": "tokenIn",
          "decimals": 6,
          "symbol": "USDT"
        },
        {
          "kind": "customer",
          "label": "Customer fee",
          "amountRaw": "10000",
          "amountInUSD": 0.01,
          "asset": "tokenIn",
          "decimals": 6,
          "symbol": "USDT"
        },
        {
          "kind": "bridgeAndSlippage",
          "label": "Bridge fee + slippage",
          "amountRaw": "100",
          "amountInUSD": 0.0001,
          "asset": "tokenOut",
          "decimals": 6,
          "symbol": "USDC",
          "signed": true
        }
      ],
      "summary": {
        "platformFeesTotalInRaw": "15000",
        "platformFeesTotalInUSD": 0.015,
        "bridgeAndSlippageImpactOutRaw": "100",
        "bridgeAndSlippageImpactOutUSD": 0.0001
      }
    }
  }
}
```

<Info>
  **Fee breakdown** (`feeBreakdown`) is the **canonical source** for all quote
  fees on every route — platform fees (Pods, customer markup) and bridge/spread
  impact. It is returned on **`GET /v2/swap/quote` only** (not on
  `GET /v2/swap/status/:id`). Charge labels are in English; localize in your UI.
  The `bridgeAndSlippage` charge is **signed** — a negative `amountRaw` means
  favorable price impact vs spot. Platform fees (`pods`, `customer`) are deducted
  from `tokenIn` before the provider quote.
</Info>

## Response Fields

<AccordionGroup>
  <Accordion title="quoteId" icon="fingerprint">
    Unique identifier for this quote. Use this when executing the swap.
  </Accordion>

  <Accordion title="chainIdIn & chainIdOut" icon="link">
    Canonical numeric chain IDs for the swap route (source → destination). Prefer
    these for new code; string `originChain` / `destinationChain` and legacy
    `fromChainId` / `toChainId` remain for compatibility.
  </Accordion>

  <Accordion title="originChain & destinationChain" icon="bridge">
    Source and destination chain names (e.g., `ethereum`, `polygon`, `arbitrum`).
    These remain supported; numeric `chainIdIn` / `chainIdOut` are preferred for
    new integrations.
  </Accordion>

  <Accordion title="tokenIn & tokenOut" icon="coins">
    Complete token information including contract address, symbol, decimals,
    amount, and chain ID. `tokenOut.expectedAmountOut` and `tokenOut.minAmountOut`
    are the provider guarantees after platform fees are taken from the input.
  </Accordion>

  <Accordion title="feeBreakdown" icon="receipt">
    Itemized costs: **Pods fee**, **Customer fee**, and **Bridge fee + slippage**
    (combined, signed on `tokenOut`). `reference` explains the spot baseline used
    for the bridge charge (`source`: `spotUsdAtQuoteTime` or `unavailable`). Zero
    fees use `amountRaw` `"0"` and `amountInUSD` `0`.
  </Accordion>

  <Accordion title="provider" icon="server">
    Name of the swap provider used (e.g., `1inch`, `Jupiter`, `TeleSwap`, `Mayan`,
    `relay`, `lifi`)
  </Accordion>

  <Accordion title="deadline" icon="clock">
    Quote expiration as a Unix timestamp in **seconds**. Execute the swap before
    this time.
  </Accordion>

  <Accordion title="rawQuote" icon="code">
    Provider-specific quote data (stringified JSON). Some bridge providers require
    this for bytecode generation. This field is omitted from the response when
    null — only pass it to the bytecode endpoint when present.
  </Accordion>

  <Accordion title="feeBreakdown" icon="receipt">
    Itemized cost breakdown for the swap. Always present on quote responses.

    * **`chargeableAmountInRaw`** — Full input amount subject to fees (string, smallest unit).
    * **`amountInAfterPlatformFeesRaw`** — Input amount after Pods + customer fees are deducted (string, smallest unit).
    * **`charges`** — Array of individual fee lines, each with `kind` (`pods` | `customer` | `bridgeAndSlippage`), `label`, `amountRaw`, `decimals`, `symbol`, `asset` (`tokenIn` | `tokenOut`), and `amountInUSD`.

    > **Note:** Some bridge routes may include a legacy top-level `fees` object in the API response for backward compatibility. Do not rely on it in new integrations — use `feeBreakdown` only.

    * **`reference`** — Spot-price reference output used to calculate bridge/slippage impact: `amountOutRaw`, `source` (`spotUsdAtQuoteTime` | `unavailable`), `pricedAt` (ISO 8601), `tokenInPriceInUSD`, `tokenOutPriceInUSD`, `amountInAfterPlatformFeesRaw`.
    * **`summary`** — Aggregated totals: `platformFeesTotalInRaw`, `platformFeesTotalInUSD`, `bridgeAndSlippageImpactOutRaw`, `bridgeAndSlippageImpactOutUSD`.
  </Accordion>
</AccordionGroup>

## Supported Chains

<CardGroup cols={3}>
  <Card title="Ethereum" icon="ethereum">
    `ethereum`
  </Card>

  <Card title="Base" icon="https://mintcdn.com/pods-322144f0/VaCfstjR8UDukAyQ/images/networks/base.svg?fit=max&auto=format&n=VaCfstjR8UDukAyQ&q=85&s=756b940eb5231e1cc1e73f57ce2404f2" width="1280" height="1280" data-path="images/networks/base.svg">
    `base`
  </Card>

  <Card title="Optimism" icon="https://mintcdn.com/pods-322144f0/VaCfstjR8UDukAyQ/images/networks/optimism.svg?fit=max&auto=format&n=VaCfstjR8UDukAyQ&q=85&s=ebc2c01e20f0ea367f9f3a01ff78d388" width="500" height="500" data-path="images/networks/optimism.svg">
    `optimism`
  </Card>

  <Card title="Arbitrum" icon="https://mintcdn.com/pods-322144f0/VaCfstjR8UDukAyQ/images/networks/arbitrum.svg?fit=max&auto=format&n=VaCfstjR8UDukAyQ&q=85&s=64fe30eadfd3165f4cf0a26a65a3983c" width="2500" height="2500" data-path="images/networks/arbitrum.svg">
    `arbitrum`
  </Card>

  <Card title="Solana" icon="https://mintcdn.com/pods-322144f0/Gg0nLDDM2P07rs2j/images/networks/solana.svg?fit=max&auto=format&n=Gg0nLDDM2P07rs2j&q=85&s=6877e57fdb7a0750b73dfd45cd0a20d2" width="398" height="312" data-path="images/networks/solana.svg">
    `solana`
  </Card>

  <Card title="Polygon" icon="https://mintcdn.com/pods-322144f0/VaCfstjR8UDukAyQ/images/networks/polygon.svg?fit=max&auto=format&n=VaCfstjR8UDukAyQ&q=85&s=f07eb2cb5771381174b2457ccc35f430" width="178" height="161" data-path="images/networks/polygon.svg">
    `polygon`
  </Card>

  <Card title="Gnosis" icon="https://mintcdn.com/pods-322144f0/VaCfstjR8UDukAyQ/images/networks/gnosis.svg?fit=max&auto=format&n=VaCfstjR8UDukAyQ&q=85&s=1d3db921f11b6e2fcc8abf98a3f60539" width="428" height="428" data-path="images/networks/gnosis.svg">
    `gnosis`
  </Card>

  <Card title="Bitcoin" icon="https://mintcdn.com/pods-322144f0/Gg0nLDDM2P07rs2j/images/networks/bitcoin.svg?fit=max&auto=format&n=Gg0nLDDM2P07rs2j&q=85&s=a99da267f35c620d61f14be441ddec86" width="4091" height="4092" data-path="images/networks/bitcoin.svg">
    `bitcoin`
  </Card>

  <Card title="HyperEVM" icon="https://mintlify.s3.us-west-1.amazonaws.com/pods-322144f0/images/networks/hyperevm.svg">
    `hyperevm`
  </Card>
</CardGroup>

## Error Handling

The API returns appropriate error messages for:

* Missing required parameters
* Invalid chain names or token addresses
* No available swap provider for the requested route
* Invalid or ineligible `preferredProvider` (see [Error Codes](/error-codes))
* Provider-specific errors during quote generation

| Code                                   | When                                                                          |
| -------------------------------------- | ----------------------------------------------------------------------------- |
| `INVALID_PREFERRED_PROVIDER`           | `preferredProvider` is not a registered provider name                         |
| `PREFERRED_PROVIDER_NOT_ELIGIBLE`      | Provider exists but does not support this chain/token route                   |
| `PREFERRED_PROVIDER_QUOTE_UNAVAILABLE` | Provider is eligible but did not return a quote (timeout or upstream failure) |
| `AMOUNT_IN_TOO_LOW`                    | AmountIn is below the minimum for this route                                  |
| `AMOUNT_IN_TOO_HIGH`                   | AmountIn exceeds available liquidity for this route. Try a smaller amount.    |

**Example Error Response:**

```json theme={null}
{
  "error": {
    "code": "NO_ROUTE_FOUND",
    "message": "No swap route available between specified chains"
  }
}
```

<Warning>
  Quotes have an expiration time (typically 5 minutes). Make sure to execute the
  swap before the `deadline` timestamp.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Execute Swap" icon="play" href="/guides/swaps/execute-swap">
    Use the quote to generate bytecode and execute the swap
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    View detailed API documentation
  </Card>
</CardGroup>