> For the complete documentation index, see [llms.txt](https://dexhunter.gitbook.io/dexhunter-partners/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dexhunter.gitbook.io/dexhunter-partners/trading/swap.md).

# Swap

Execute instant market swaps.

{% hint style="warning" %}
**Required:** Include `X-Partner-Id` header with your API key on all requests.

**Base URL:** `https://api-us.dexhunterv3.app`
{% endhint %}

***

## Build Swap

Build a swap transaction.

**Endpoint**

`POST /swap/build`

**Payload**

| Field               | Type   | Required | Description                    |
| ------------------- | ------ | -------- | ------------------------------ |
| `buyer_address`     | string | ✓        | User's Cardano address         |
| `token_in`          | string | ✓        | Token to sell (`""` for ADA)   |
| `token_out`         | string | ✓        | Token to buy                   |
| `amount_in`         | number | ✓        | Amount in ADA (or token units) |
| `slippage`          | number | ✓        | Slippage tolerance %           |
| `blacklisted_dexes` | array  |          | DEXes to exclude               |

**Response**

| Field          | Type   | Description              |
| -------------- | ------ | ------------------------ |
| `cbor`         | string | Transaction CBOR to sign |
| `total_input`  | number | Input amount             |
| `total_output` | number | Expected output          |
| `splits`       | array  | DEX routing breakdown    |

**Split Object**

| Field             | Type   | Description     |
| ----------------- | ------ | --------------- |
| `dex`             | string | DEX identifier  |
| `amount_in`       | number | Input amount    |
| `expected_output` | number | Expected output |

{% tabs %}
{% tab title="Example: Buy 100 ADA of NIGHT" %}

```javascript
const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://api-us.dexhunterv3.app';
const headers = { 'X-Partner-Id': API_KEY };

const payload = {
  buyer_address: 'addr1qx2kd28nq8ac5pr...',
  token_in: '',
  token_out:
    '0691b2fecca1ac4f53cb6dfb00b7013e561d1f34403b957cbb5af1fa4e49474854',
  amount_in: 100,
  slippage: 2,
  blacklisted_dexes: [],
};

const { data: swap } = await axios.post(`${BASE_URL}/swap/build`, payload, {
  headers,
});
const signatures = await wallet.signTx(swap.cbor, true);
const { data: signed } = await axios.post(
  `${BASE_URL}/swap/sign`,
  { txCbor: swap.cbor, signatures },
  { headers }
);
const txHash = await wallet.submitTx(signed.cbor);
```

{% endtab %}

{% tab title="Example: Sell 1000 NIGHT" %}

```javascript
const payload = {
  buyer_address: 'addr1qx2kd28nq8ac5pr...',
  token_in:
    '0691b2fecca1ac4f53cb6dfb00b7013e561d1f34403b957cbb5af1fa4e49474854',
  token_out: '',
  amount_in: 1000,
  slippage: 2,
  blacklisted_dexes: [],
};
```

{% endtab %}
{% endtabs %}

***

## Estimate Swap

Get price quote without building a transaction.

**Endpoint**

`POST /swap/estimate`

**Payload**

| Field               | Type   | Required | Description                    |
| ------------------- | ------ | -------- | ------------------------------ |
| `token_in`          | string | ✓        | Token to sell (`""` for ADA)   |
| `token_out`         | string | ✓        | Token to buy                   |
| `amount_in`         | number | ✓        | Amount in ADA (or token units) |
| `slippage`          | number | ✓        | Slippage tolerance %           |
| `blacklisted_dexes` | array  |          | DEXes to exclude               |

**Response**

| Field                           | Type   | Description            |
| ------------------------------- | ------ | ---------------------- |
| `total_output`                  | number | Expected output        |
| `total_output_without_slippage` | number | Output before slippage |
| `possible_routes`               | array  | Available DEX routes   |

**Route Object**

| Field             | Type   | Description     |
| ----------------- | ------ | --------------- |
| `dex`             | string | DEX identifier  |
| `amount_in`       | number | Input amount    |
| `expected_output` | number | Expected output |

{% tabs %}
{% tab title="Example" %}

```javascript
const { data: quote } = await axios.post(
  `${BASE_URL}/swap/estimate`,
  {
    token_in: '',
    token_out:
      '0691b2fecca1ac4f53cb6dfb00b7013e561d1f34403b957cbb5af1fa4e49474854',
    amount_in: 100,
    slippage: 2,
    blacklisted_dexes: [],
  },
  { headers }
);

console.log(`You will receive ~${quote.total_output_without_slippage} NIGHT`);
```

{% endtab %}
{% endtabs %}

***

## DEX Identifiers

Available values for `blacklisted_dexes`:

| Code           | Name           |
| -------------- | -------------- |
| `MINSWAP`      | MinSwap V1     |
| `MINSWAPV2`    | Minswap V2     |
| `MS2HOP`       | Minswap V2 Hop |
| `SUNDAESWAP`   | Sundae V1      |
| `SUNDAESWAPV3` | Sundae V3      |
| `WINGRIDER`    | WingRiders     |
| `WINGRIDERV2`  | WingRiders V2  |
| `SPLASH`       | Splash         |
| `VYFI`         | VyFinance      |
| `MUESLISWAP`   | MuesliSwap     |
| `CSWAP`        | CSWAP          |
| `CHADSWAP`     | ChadSwap       |
| `SNEKFUN`      | SnekFun        |
| `CHAKRA`       | Chakra         |
| `SHADOWBOOK`   | Shadow Book    |