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`
`transferSpeed`	string	Transfer speed for CCTP cross-chain swaps. `fast` (default) or `standard`. Ignored for non-CCTP routes.	`fast`
`destinationAddress`	string	Recipient on the destination chain	`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:

{
  "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
  }
}

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

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.

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)

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

Documentation Index

​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