> For the complete documentation index, see [llms.txt](https://docs.swapkit.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.swapkit.dev/swapkit-api/quote-and-swap-implementation-flow.md).

# Quote and Swap Implementation flow

A key part of our service is the ability to include transaction data in a `/swap` response.\
After already implementing our [/providers](/swapkit-api/providers-providers-status-and-identifiers-mapping.md) and their [/tokens](/swapkit-api/tokens-list-and-search-supported-tokens.md), you will use the [/quote](/swapkit-api/v3-quote-request-a-swap-quote.md) and [/swap](/swapkit-api/v3-swap-obtain-swap-transaction-details.md) endpoints to process transactions for your users.

### 1. Initial Quote Request

First, fetch quotes with the [/v3/quote](/swapkit-api/v3-quote-request-a-swap-quote.md) endpoint. 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

Once you have presented a price to the user, they would then accept it. This determines which provider offers the best match for the route you quoted. The available providers are labeled with the `"RECOMMENDED"`, `"FASTEST"` and `"CHEAPEST"` tags.

Then, before presenting the user with a transaction to sign, you will call the `/swap` endpoint, referencing the chosen quote via its `routeId`.

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

When the user is ready to execute the swap, request the [/v3/swap](/swapkit-api/v3-swap-obtain-swap-transaction-details.md) endpoint with the selected `routeId` along with the user's  `sourceAddress`  and `destinationAddress`

```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 5 minutes. After it expires, a new quote is fetched using the original parameters before the swap request is processed.

The swap will include transaction-related fields under `tx`, which may be either an object or a string. It also includes the price, so you can display it to the user again before signing or compare it internally against the previous value before presenting 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"
  }
}
```

If [SLIP-0024 signing](/spotlights/slip-0024-transaction-payload-signing.md) is enabled for your API key, the response also includes a signed payload ready for verification.

***

### 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 will receive a complete route with transaction data that can be directly signed and broadcasted.

### 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 errors that can be returned. You can find more details on 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..."
  }
}
```