> ## 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.

# Quotes API

> Get swap quotes for deposits and withdrawals

## Get Swap Quote

<span style={{color: '#10B981', fontWeight: 'bold'}}>GET</span> `/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

```bash theme={null}
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

```json theme={null}
{
  "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)

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

**Response:**

```json theme={null}
{
  "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)

```bash theme={null}
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:

```json theme={null}
{
  "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

```typescript theme={null}
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                    |

```json theme={null}
{
  "error": "Bad Request",
  "message": "No swap pool configured for USDC → DAI",
  "statusCode": 400
}
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Instruments API" icon="fingerprint" href="/api-reference/endpoints/instruments">
    Query available instruments
  </Card>

  <Card title="Positions API" icon="wallet" href="/api-reference/endpoints/positions">
    Check user positions
  </Card>

  <Card title="How It Works" icon="gears" href="/how-it-works">
    Understand the transaction flow
  </Card>

  <Card title="Integration Guide" icon="book" href="/integration/overview">
    Full integration walkthrough
  </Card>
</CardGroup>