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

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