Get a Quote

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

Prerequisites

API Key

Get your API key for authentication at Pods

Token Addresses

Contract addresses for the tokens you want to swap

Chain IDs

Chain IDs for source and destination chains

Authentication

Include your API key in the x-api-key header

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.

Same-chain Swap: When originChain equals destinationChain Cross-chain Swap: When originChain differs from destinationChain

Getting a Quote

Endpoint

GET /v2/swap/quote

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.

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`, `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` or `pixKey`, the response also includes transaction bytecode (`id` + `transactionData`) — no separate call to `POST /v2/swap/bytecode` needed.	`0x…`
`destinationAddress`	string	Recipient on the destination chain. Provide this for crypto destinations. Must be a real wallet address — omit the parameter entirely if you only want a price quote without bytecode generation. Any address value passed here is used as-is as the destination.	`0x…`
`pixKey`	string	PIX key for fiat off-ramp destinations. Use instead of `destinationAddress` when `destinationChain` is `fiat`.	`[email protected]`
`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`
`transferSpeed`	string	Transfer speed for CCTP cross-chain swaps. `fast` (default) or `standard`. Ignored for non-CCTP routes.	`fast`
`thirdParty`	boolean	When true, the fiat off-ramp quote is requested as a third-party payment (`outputThirdParty=true` sent to the provider). Only relevant for PIX/fiat off-ramp routes. Defaults to `false`. Must match the value passed to `POST /v2/swap/bytecode`; a mismatch returns `PIX_THIRD_PARTY_QUOTE_MISMATCH`.	`false`
`webhookURL`	string (URI)	Optional per-quote webhook endpoint. When set, quote lifecycle webhooks are delivered to this URL instead of the customer default webhook URL.	`https://example.com/webhooks/swap-quote`

Either amountIn OR amountOut is required (not both). Use amountOut for exact output swaps (“I want to receive exactly X tokens”).

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.

Example Requests

Same-Chain Swap (Ethereum USDT to USDC)

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)

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

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):

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:

{
  "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,
    "deadlineDate": "2024-01-24T12:55:00.000Z",
    "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
      }
    }
  }
}

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.

Response Fields

quoteId

Unique identifier for this quote. Use this when executing the swap.

chainIdIn & chainIdOut

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.

originChain & destinationChain

Source and destination chain names (e.g., ethereum, polygon, arbitrum). These remain supported; numeric chainIdIn / chainIdOut are preferred for new integrations.

tokenIn & tokenOut

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.

feeBreakdown

Itemized costs: Pods fee, Customer fee, and Bridge fee + slippage (combined, signed on tokenOut). reference explains the spot baseline used for the bridge charge. Zero-value charge lines are omitted; use summary for aggregate totals that may be zero.

provider

Name of the swap provider used (e.g., 1inch, Jupiter, TeleSwap, Mayan, relay, lifi)

deadline

Quote expiration as a Unix timestamp in seconds. Execute the swap before this time.

deadlineDate

Quote expiration as an ISO 8601 UTC string (e.g. 2024-01-20T12:30:00.000Z). Human-readable alternative to deadline.

rawQuote

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.

Supported Chains

Ethereum

ethereum

Base

base

Optimism

optimism

Arbitrum

arbitrum

Solana

solana

Polygon

polygon

Gnosis

gnosis

Bitcoin

bitcoin

HyperEVM

hyperevm

Monad

monad

Fiat

fiat (off-ramp/on-ramp routes)

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)
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:

{
  "error": {
    "code": "NO_ROUTE_FOUND",
    "message": "No swap route available between specified chains"
  }
}

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

Overview

Guides

Integrations

Agents

Prerequisites

API Key

Token Addresses

Chain IDs

Authentication

Overview

Getting a Quote

Endpoint

Required Parameters

Optional Parameters

Example Requests

Same-Chain Swap (Ethereum USDT to USDC)

Cross-Chain Swap (Ethereum to Polygon)

Same route using chain IDs

Cross-chain with a preferred provider

Multi-route aggregation

Response Format

Response Fields

Supported Chains

Ethereum

Base

Optimism

Arbitrum

Solana

Polygon

Gnosis

Bitcoin

HyperEVM

Monad

Fiat

Error Handling

Next Steps

Execute Swap

API Reference

​Prerequisites

API Key

Token Addresses

Chain IDs

Authentication

​Overview

​Getting a Quote

​Endpoint

​Required Parameters

​Optional Parameters

​Example Requests

​Same-Chain Swap (Ethereum USDT to USDC)

​Cross-Chain Swap (Ethereum to Polygon)

​Same route using chain IDs

​Cross-chain with a preferred provider

​Multi-route aggregation

​Response Format

​Response Fields

​Supported Chains

Ethereum

Base

Optimism

Arbitrum

Solana

Polygon

Gnosis

Bitcoin

HyperEVM

Monad

Fiat

​Error Handling

​Next Steps

Execute Swap

API Reference

Prerequisites

Overview

Getting a Quote

Endpoint

Required Parameters

Optional Parameters

Example Requests

Same-Chain Swap (Ethereum USDT to USDC)

Cross-Chain Swap (Ethereum to Polygon)

Same route using chain IDs

Cross-chain with a preferred provider

Multi-route aggregation

Response Format

Response Fields

Supported Chains

Error Handling

Next Steps