# Swap

Swap endpoint: `/chains/{chainId}/swap` 

## **Query**

### **Description of query parameters**

All parameters with asterisks `*` are **REQUIRED**.

<table><thead><tr><th width="190.22265625">Parameter name</th><th width="149.96875">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>chainId</code>*</td><td>integer</td><td>Network chain ID of the target blockchain.<br>Example: <code>42161</code> (Arbitrum).</td></tr><tr><td><code>tokenIn</code>*</td><td><code>string</code></td><td>Contract address of the ERC20 token to <strong>swap from</strong>.<br>Example: <code>0xaf88d065e77c8cC2239327C5EDb3A432268e5831</code> (USDC on Arbitrum).</td></tr><tr><td><code>tokenOut</code>*</td><td><code>string</code></td><td>Contract address of the ERC20 token to <strong>swap to</strong>.<br>Example: <code>0x82aF49447D8a07e3bd95BD0d56f35241523fBab1</code> (WETH on Arbitrum).</td></tr><tr><td><code>amountIn</code>*</td><td><code>integer</code></td><td>Amount of <code>tokenIn</code> to sell, in minimal divisible units.<br>Example: <code>1.00 USDC</code> → <code>1000000</code></td></tr><tr><td><code>maxSlippage</code></td><td><code>float</code></td><td>Maximum acceptable slippage (percentage). Default: <code>0.5</code> (e.g. <code>0.5 = 0.5%</code>).</td></tr><tr><td><code>fromAddress</code>*</td><td><code>string</code></td><td>Address executing the swap transaction.</td></tr><tr><td><code>toAddress</code></td><td><code>string</code></td><td>Optional recipient address of the output tokens. If omitted, defaults to <code>fromAddress</code>.</td></tr><tr><td><code>deadline</code></td><td><code>integer</code></td><td>Optional Unix timestamp after which the swap is invalid. Defaults to 30 minutes from now.</td></tr></tbody></table>

### **Example request**

#### **HTTP GET**

```bash
GET /chains/42161/swap?tokenIn=0xaf88d065e77c8cC2239327C5EDb3A432268e5831&tokenOut=0x82aF49447D8a07e3bd95BD0d56f35241523fBab1&amountIn=500000000&maxSlippage=0.5&fromAddress=0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
```

#### curl

```bash
curl -X GET "https://swap-api.nabla.fi/chains/42161/swap?tokenIn=0xaf88d065e77c8cC2239327C5EDb3A432268e5831&tokenOut=0x82aF49447D8a07e3bd95BD0d56f35241523fBab1&amountIn=500000000&maxSlippage=0.5&fromAddress=0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266" \
  -H "accept: application/json"
```

## Response

### **Response fields**

<table><thead><tr><th width="190.07421875">Field</th><th width="149.9765625">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>chainId</code></td><td><code>integer</code></td><td>Network chain ID.</td></tr><tr><td><code>tokenIn</code></td><td><code>string</code></td><td>Contract address of the input token (ERC20).</td></tr><tr><td><code>tokenOut</code></td><td><code>string</code></td><td>Contract address of the output token (ERC20).</td></tr><tr><td><code>amountIn</code></td><td><code>integer</code></td><td>Amount of <code>tokenIn</code> to sell (in minimal divisible units).</td></tr><tr><td><code>maxSlippage</code></td><td><code>float</code></td><td>Maximum acceptable slippage for this swap (percentage).</td></tr><tr><td><code>fromAddress</code></td><td><code>string</code></td><td>Address initiating the swap transaction.</td></tr><tr><td><code>toAddress</code></td><td><code>string</code></td><td>Recipient address of the output tokens.</td></tr><tr><td><code>deadline</code></td><td><code>integer</code></td><td>Unix timestamp after which the swap is invalid.</td></tr><tr><td><code>amountOut</code></td><td><code>integer</code></td><td>Estimated amount of output tokens to receive (in minimal divisible units).</td></tr><tr><td><code>estimatedSlippage</code></td><td><code>float</code></td><td>Estimated slippage for this swap, in percent.</td></tr><tr><td><code>amountOutMin</code></td><td><code>integer</code></td><td>Minimum amount of output tokens guaranteed to be received (in minimal divisible units).</td></tr><tr><td><code>routerPath</code></td><td><code>array[string]</code></td><td>Ordered list of NablaRouter addresses used in the route.</td></tr><tr><td><code>tokenPath</code></td><td><code>array[string]</code></td><td>Ordered list of token addresses used in the route.</td></tr><tr><td><code>tx</code></td><td><code>object</code></td><td>Transaction data object to execute the swap (includes <code>to</code>, <code>data</code>, <code>value</code>, etc.).</td></tr></tbody></table>

### **Example response**

```json
{
  "chainId": 42161,
  "tokenIn": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
  "tokenOut": "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1",
  "amountIn": 500000000,
  "maxSlippage": 0.5,
  "fromAddress": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
  "toAddress": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
  "deadline": 1760439036,
  "amountOut": 126612259354618762,
  "estimatedSlippage": 0.0302,
  "amountOutMin": 125979198057845680,
  "routerPath": [
    "0x7bcFc8b8ff61456ad7C5E2be8517D01df006d18d"
  ],
  "tokenPath": [
    "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
    "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1"
  ],
  "tx": {
    "to": "0xcB94Eee869a2041F3B44da423F78134aFb6b676B",
    "data": "0xabcdef1234...",
    "value": "0",
    "gas": null,
    "gasPrice": null
  }
}

```

## Notes

* This endpoint **generates calldata** for an on-chain swap but **does not execute** the transaction.
* The returned `tx` object can be directly passed to a wallet or smart contract for execution.
* Prices and slippage are **estimated at the time of request** — execute the transaction promptly for best accuracy.
* Use `maxSlippage` to define your tolerance against price movement before swap execution.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.nabla.fi/developers/swap-api/swap.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.