Get a Quote

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

Prerequisites

API Key

Get your API key for authentication at Deframe

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 Deframe 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`, `uniswap`, `deframe`, `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 Deframe bridge routes (`deframe` provider). Defaults to `false`.	`false`

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.deframe.io/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.deframe.io/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.deframe.io/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.deframe.io/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 Deframe bridge routes (deframe provider) still use a single provider; preferredProvider must be deframe 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,
    "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"
      },
      "lines": [
        {
          "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 returned on GET /v2/swap/quote only (not on GET /v2/swap/status/:id). Line labels are in English; localize in your UI. The bridgeAndSlippage line is signed — a negative amountRaw means favorable price impact vs spot. Platform fees (pods, customer) are deducted from tokenIn before the provider quote; see docs/swap-quote-fee-breakdown-spec.md in the API repo.

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 line (source: spotUsdAtQuoteTime or unavailable). Zero fees use amountRaw "0" and amountInUSD 0.

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.

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.

feeBreakdown

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).
lines — Array of individual fee lines, each with kind (pods | customer | bridgeAndSlippage), label, amountRaw, decimals, symbol, asset (tokenIn | tokenOut), and amountInUSD.
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.

Supported Chains

Ethereum

ethereum

Base

base

Optimism

optimism

Arbitrum

arbitrum

Solana

solana

Polygon

polygon

Gnosis

gnosis

Bitcoin

bitcoin

HyperEVM

hyperevm

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",
    "httpStatus": 400,
    "details": null
  }
}

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

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

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

​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