Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.1tx.fi/llms.txt

Use this file to discover all available pages before exploring further.

​
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

ParameterTypeRequiredDescription
instrumentIdstringYesThe target instrument ID
directionstringYesEither deposit (USDC → token) or withdraw (token → USDC)
amountstringYesThe input amount in raw units (e.g., 10000000 for 10 USDC)
chainIdnumberYesChain 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

FieldTypeDescription
needsSwapbooleanWhether a swap is required (false if input matches instrument token)
fromTokenobjectSource token information
fromToken.addressstringToken contract address
fromToken.symbolstringToken symbol (e.g., “USDC”)
fromToken.decimalsnumberToken decimals (e.g., 6 for USDC)
toTokenobjectDestination token information
toToken.addressstringToken contract address
toToken.symbolstringToken symbol (e.g., “GHO”)
toToken.decimalsnumberToken decimals (e.g., 18 for GHO)
amountInstringInput amount in raw units
amountOutstringExpected output amount in raw units
minAmountOutstringMinimum output with 0.5% slippage protection
priceImpactstringPrice 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

StatusErrorDescription
400No swap pool configuredNo Uniswap V4 pool exists for token pair
400Pool is not initializedPool exists but has no liquidity
400Instrument not foundInvalid 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