# Quote and Swap Implementation flow

An important part of our service is the possibility of including transaction data in a `/swap` response.\
After already implementing our [/providers](https://docs.swapkit.dev/swapkit-api/providers-request-supported-chains-by-a-swap-provider) and their [/tokens](https://docs.swapkit.dev/swapkit-api/tokens-request-supported-tokens-by-a-swap-provider), you will use the [/quote](https://docs.swapkit.dev/swapkit-api/v3-quote-request-a-swap-quote) and [/swap](https://docs.swapkit.dev/swapkit-api/v3-swap-obtain-swap-transaction-details) endpoints to process transactions for your users.

### 1. Initial Quote Request

First, fetch quotes with . For this step,  `"sourceAddress"` and `"destinationAddress"` are not needed and instead you are just quoting the price of a swap:

```bash
curl -X POST "https://api.swapkit.dev/v3/quote" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_VARIABLE_HERE" \
  -d '{
    "sellAsset": "BTC.BTC",
    "buyAsset": "ETH.ETH",
    "sellAmount": "0.1",
    "slippage": 3
  }'
```

You can filter for the providers you have integrated using the `"providers"` argument if you want to limit the options shown.

This returns a regular quote response including pricing information, estimated timing and fees, and route details with the available providers, but without transaction data. The `"nextActions"` object will inform you of the following steps to take. Generally, you will provide the `routeId` into the `/swap` endpoint.

### 2. Identify the Provider route you want to use

After offering a price to the user of your application, the user would then accept it. This identifies what provider offers the best match for the route you quoted for. We identify the different providers offered with the `"RECOMMENDED"`, `"FASTEST"` and `"CHEAPEST"` tags.

Before the user gets offered a transaction to sign though, you will use the `/swap` endpoint referencing the quote used by using the `routeId`.

### 3. Request a /swap - Transaction Building

When the user is ready to execute the swap, request the `/swap` endpoint with the selected `routeId` and the addresses the user is using:

```bash
curl -X POST "https://api.swapkit.dev/v3/swap" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_VARIABLE_HERE" \
  -d '{
    "routeId": "eed91159-86bd-4674-9558-48f7e4f8bac0",
    "sourceAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "destinationAddress": "357a3So9CbsNfBBgFYACGvxxS6tMaDoa1P"
}'
```

This endpoint can take a bit longer to reply. SwapKit builds the transaction payload, including fetching UTXOs and building PSBT when required, does a balance check and also performs **address screening on every `/swap` call automatically**.

The `routeId` is valid for 60 seconds. Past that time, a new quote will be obtained with the initial parameters before processing the swap request.

The swap will include transaction related fields under `tx`, which could be an object or a string. It also includes the price so you can show it to the user again for signing or compare internally to the previous value before offering it:

```json
{
  // ... all fields from above, plus:
  "targetAddress": "1FSHYruFaYjm5FQrzB3LmF15FMC3QwUFmy",
  "inboundAddress": "1FSHYruFaYjm5FQrzB3LmF15FMC3QwUFmy",
  "tx": "cHNidP8BAHUCAAAAAc86GvpcKcJoCV1YpX9orAcE/ZckHbLzuTXOPl0McccZAAAAAAD/////AoCWmAAAAAAAGXapFJ5Z+YVfu2g/WM/XGmu9FBGSeS5wiKx/LhEm4wAAABepFFKL8plEPOVGF9/52YVT+SKl3opehwAAAAAAAQEg/8SpJuMAAAAXqRRSi/KZRDzlRhff+dmFU/kipd6KXocAAAA=",
  "meta": {
    // ... existing meta fields, plus:
    "txType": "PSBT"
  }
}
```

***

### Transaction Building Process

When calling the `/swap` endpoint, the system performs the following validations:

#### 1. Balance Verification

SwapKit first checks if the source address has sufficient balance to cover the `sellAmount`. If insufficient funds are detected, an `insufficientBalance` error is thrown for the entire request.

#### 2. Transaction Building

If the balance check passes, the system attempts to build the transaction. In certain edge cases, the wallet may have enough balance to match the `sellAmount` but insufficient funds to cover network fees. Since different providers have varying transaction sizes, some may return valid transaction data while others might fail with an `unableToBuildTransaction` error.

#### 3. Successful Response

If all validations pass, you'll receive a complete route with transaction data that can be directly signed and broadcast.

### Key Fields

* `targetAddress` The deposit address where funds should be sent, or the address of the contract that should be called.
* `inboundAddress` The address monitoring for incoming transactions.
* `tx` The transaction data ready for signing.
* `txType` The format of the transaction data (e.g., "PSBT" for Bitcoin or "EVM" for EVM chains).

### Error Handling

Be prepared to handle the different the errors that could be returned. You can see them in more detail in the [swap endpoint page](https://app.gitbook.com/o/amdCeBqeAzowzd0wBh9E/s/l88kbsjWGhgdARxzgqCE/~/edit/~/changes/60/swapkit-api/v3-swap-obtain-swap-transaction-details#swap-errors).

* `insufficientBalance` The source address doesn't have enough tokens for the swap.
* `insufficientAllowance`: The source address doesn't have enough tokens approved for the contract interaction. Relevant for tokens in EVM networks.
* `unableToBuildTransaction` The wallet has sufficient tokens but insufficient funds for network fees.

This is an example error for a wallet without enough balance:

```json
{
  "message": "Cannot build transaction. Insufficient balance for asset ETH.USDC-0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 amount 700 address 0x...",
  "error": "insufficientBalance",
  "data": {
    "chain": "ETH.USDC-0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "amount": "700",
    "address": "0x..."
  }
}
```