Quotes API - 1tx Documentation

Get Swap Quote

GET /quotes/swap Get a quote for swapping tokens when depositing into or withdrawing from a DeFi instrument. Returns the expected output amount, token information, minimum output with slippage protection, and price impact.

Request

curl "https://api.1tx.fi/api/v1/quotes/swap?instrumentId=0x000021059958277ec7a7f000b6b04b905f3f48cf85c08bb0c762bba74dce3be8&direction=deposit&amount=10000000&chainId=8453"

Query Parameters

Parameter	Type	Required	Description
`instrumentId`	string	Yes	The target instrument ID
`direction`	string	Yes	Either `deposit` (USDC → token) or `withdraw` (token → USDC)
`amount`	string	Yes	The input amount in raw units (e.g., `10000000` for 10 USDC)
`chainId`	number	Yes	Chain ID (e.g., `8453` for Base mainnet)

Response

{
  "needsSwap": true,
  "fromToken": {
    "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "symbol": "USDC",
    "decimals": 6
  },
  "toToken": {
    "address": "0x6Bb7a212910682DCFdbd5BCBb3e28FB4E8da10Ee",
    "symbol": "GHO",
    "decimals": 18
  },
  "amountIn": "10000000",
  "amountOut": "10001276903584562876",
  "minAmountOut": "9951270338666639661",
  "priceImpact": "0.0127"
}

Response Fields

Field	Type	Description
`needsSwap`	boolean	Whether a swap is required (`false` if input matches instrument token)
`fromToken`	object	Source token information
`fromToken.address`	string	Token contract address
`fromToken.symbol`	string	Token symbol (e.g., “USDC”)
`fromToken.decimals`	number	Token decimals (e.g., 6 for USDC)
`toToken`	object	Destination token information
`toToken.address`	string	Token contract address
`toToken.symbol`	string	Token symbol (e.g., “GHO”)
`toToken.decimals`	number	Token decimals (e.g., 18 for GHO)
`amountIn`	string	Input amount in raw units
`amountOut`	string	Expected output amount in raw units
`minAmountOut`	string	Minimum output with 0.5% slippage protection
`priceImpact`	string	Price impact as a percentage (e.g., “0.0127” = 0.0127%)

Notes

When needsSwap is false, no swap is needed - the input amount equals output amount
The minAmountOut applies 0.5% slippage tolerance for transaction protection
Price impact is calculated based on current Uniswap V4 pool liquidity
Use toToken.decimals to format amounts for display (e.g., divide by 10^decimals)

Examples

Deposit Quote (USDC → GHO)

curl "https://api.1tx.fi/api/v1/quotes/swap?instrumentId=0x000021059958277ec7a7f000b6b04b905f3f48cf85c08bb0c762bba74dce3be8&direction=deposit&amount=10000000&chainId=8453"

Response:

{
  "needsSwap": true,
  "fromToken": { "address": "0x833589f...", "symbol": "USDC", "decimals": 6 },
  "toToken": { "address": "0x6Bb7a21...", "symbol": "GHO", "decimals": 18 },
  "amountIn": "10000000",
  "amountOut": "10001276903584562876",
  "minAmountOut": "9951270338666639661",
  "priceImpact": "0.0127"
}

Convert to human-readable:

Input: 10 USDC (10000000 ÷ 10^6)
Output: ~10.001 GHO (10001276903584562876 ÷ 10^18)
Price: 1 USDC ≈ 1.0001 GHO

Withdraw Quote (GHO → USDC)

curl "https://api.1tx.fi/api/v1/quotes/swap?instrumentId=0x000021059958277ec7a7f000b6b04b905f3f48cf85c08bb0c762bba74dce3be8&direction=withdraw&amount=10000000000000000000&chainId=8453"

No Swap Needed (USDC instrument)

When depositing USDC into a USDC-based instrument:

{
  "needsSwap": false,
  "fromToken": { "symbol": "USDC", "decimals": 6, "address": "0x833589f..." },
  "toToken": { "symbol": "USDC", "decimals": 6, "address": "0x833589f..." },
  "amountIn": "10000000",
  "amountOut": "10000000",
  "minAmountOut": "10000000",
  "priceImpact": "0"
}

TypeScript Example

interface TokenInfo {
  address: string;
  symbol: string;
  decimals: number;
}

interface SwapQuote {
  needsSwap: boolean;
  fromToken: TokenInfo;
  toToken: TokenInfo;
  amountIn: string;
  amountOut: string;
  minAmountOut: string;
  priceImpact: string;
}

async function getSwapQuote(params: {
  instrumentId: string;
  direction: 'deposit' | 'withdraw';
  amount: string;
  chainId?: number;
}): Promise<SwapQuote> {
  const searchParams = new URLSearchParams({
    instrumentId: params.instrumentId,
    direction: params.direction,
    amount: params.amount,
    chainId: String(params.chainId || 8453),
  });

  const response = await fetch(`/api/quotes/swap?${searchParams}`);

  if (!response.ok) {
    throw new Error(`Failed to get quote: ${response.status}`);
  }

  return response.json();
}

// Usage - Get quote for 100 USDC deposit
const quote = await getSwapQuote({
  instrumentId: '0x000021059958277ec7a7f000b6b04b905f3f48cf85c08bb0c762bba74dce3be8',
  direction: 'deposit',
  amount: '100000000', // 100 USDC (6 decimals)
  chainId: 8453,
});

// Format for display
const inputAmount = Number(quote.amountIn) / Math.pow(10, quote.fromToken.decimals);
const outputAmount = Number(quote.amountOut) / Math.pow(10, quote.toToken.decimals);
const priceRatio = outputAmount / inputAmount;

console.log(`${inputAmount} ${quote.fromToken.symbol} → ${outputAmount.toFixed(4)} ${quote.toToken.symbol}`);
console.log(`Price: 1 ${quote.fromToken.symbol} = ${priceRatio.toFixed(4)} ${quote.toToken.symbol}`);

Error Responses

Status	Error	Description
400	`No swap pool configured`	No Uniswap V4 pool exists for token pair
400	`Pool is not initialized`	Pool exists but has no liquidity
400	`Instrument not found`	Invalid instrument ID

{
  "error": "Bad Request",
  "message": "No swap pool configured for USDC → DAI",
  "statusCode": 400
}

Next Steps

Instruments API

Query available instruments

Positions API

Check user positions

How It Works

Understand the transaction flow

Integration Guide

Full integration walkthrough

​Get Swap Quote

​Request

​Query Parameters

​Response

​Response Fields

​Notes

​Examples

​Deposit Quote (USDC → GHO)

​Withdraw Quote (GHO → USDC)

​No Swap Needed (USDC instrument)

​TypeScript Example

​Error Responses

​Next Steps