Documentation - Notus API

This endpoint provides a real-time quote for a token swap, detailing the estimated destination token amount, fees, and other relevant parameters.

Request Body

amountInstring

The amount to be swapped, expressed as a decimal string.

chainIdInnumber

The blockchain network where the swap originates. Supported EVM chains:

Arbitrum One: 42161
Avalanche: 43114
Base: 8453
BNB Smart Chain: 56
Ethereum: 1
Gnosis: 100
OP Mainnet: 10
Polygon: 137

chainIdOutnumber

The blockchain network where the swapped asset will be sent to. Supported chains:

Arbitrum One: 42161
Avalanche: 43114
Base: 8453
BNB Smart Chain: 56
Ethereum: 1
Gnosis: 100
OP Mainnet: 10
Polygon: 137
Bitcoin: 0

routeProfile?string

Route profiles define the order and which quotes are returned in the array. The order is always from the "best" to the "worst". The following profiles are available:

QUICKEST_QUOTE: Returns a quote as soon as one that works is found. This is the quickest endpoint as it returns the first that can be executed, if none can be executed it returns all of them to show the reason they could not execute.
FASTEST_BRIDGE: Useful only for cross-chain swaps. Returns the cross-chain route that should execute on all chains at the fastest time possible. This is a slow query, refrain from calling it too frequently.
BEST_OUTPUT: Aggregates multiple swap providers to find the optimal path, that maximizes the returns by considering the guaranteed minimum output and deducting execution fees. This is a slow query, refrain from calling it too frequently.

Default"QUICKEST_QUOTE"

Value in"QUICKEST_QUOTE" | "FASTEST_BRIDGE" | "BEST_OUTPUT"

gasFeePaymentMethodstring

Defines how the fee will be paid: "ADD_TO_AMOUNT" adds it to the input amount, while "DEDUCT_FROM_AMOUNT" subtracts it from the input amount.

Value in"ADD_TO_AMOUNT" | "DEDUCT_FROM_AMOUNT"

payGasFeeTokenstring

The token address (in hexadecimal format) used to pay the transaction fee.

Match^0x[a-fA-F0-9]{40}$

tokenInstring

The address (in hexadecimal format) of the token being swapped from.

Match^0x[a-fA-F0-9]{40}$

tokenOutstring

The address (in hexadecimal format) of the token being swapped to.

Match^0x[a-fA-F0-9]{40}$

walletAddressstring

The wallet address (in hexadecimal format) initiating the swap.

Match^0x[a-fA-F0-9]{40}$

toAddressstring

The address (EVM address or Bitcoin address) receiving the swap. Generally equal to the walletAddress, but can be another address.

transactionFeePercent?number

Percentage fee to be charged (0 to 99%). The fee is deducted from the input token and sent to the treasuryAddress if configured. If not configured the value is zero.

Rangevalue <= 99.99

slippage?number

Optional parameter controlling the maximum deviation allowed of the expected price of a trade and the actual price at which the trade is executed, with a minimum value of 0.5 and a maximum value of 99, default is 0.5, where 1 unit equals 1%.

Default0.5

Range0.5 <= value <= 99

metadata?object

Custom metadata for the entity. Key-value pairs with string values. Max 1KB size.

Empty Object

Response Body

curl -X POST "https://api.notus.team/api/v1/crypto/swap" \
  -H "Content-Type: application/json" \
  -d '{
    "amountIn": "1.2",
    "chainIdIn": 42161,
    "chainIdOut": 43114,
    "gasFeePaymentMethod": "ADD_TO_AMOUNT",
    "payGasFeeToken": "0xc2132d05d31c914a87c6611c10748aeb04b58e8f",
    "tokenIn": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
    "tokenOut": "0x1bfd67037b42cf73acf2047067bd4f2c47d9bfd6",
    "walletAddress": "0x6e397ddf51d9f15dbe0414538e7529f51f2e5464",
    "toAddress": "0x6e397ddf51d9f15dbe0414538e7529f51f2e5464"
  }'

const body = JSON.stringify({
  "amountIn": "1.2",
  "chainIdIn": 42161,
  "chainIdOut": 43114,
  "gasFeePaymentMethod": "ADD_TO_AMOUNT",
  "payGasFeeToken": "0xc2132d05d31c914a87c6611c10748aeb04b58e8f",
  "tokenIn": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
  "tokenOut": "0x1bfd67037b42cf73acf2047067bd4f2c47d9bfd6",
  "walletAddress": "0x6e397ddf51d9f15dbe0414538e7529f51f2e5464",
  "toAddress": "0x6e397ddf51d9f15dbe0414538e7529f51f2e5464"
})

fetch("https://api.notus.team/api/v1/crypto/swap", {
  body
})

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
  "strings"
)

func main() {
  url := "https://api.notus.team/api/v1/crypto/swap"
  body := strings.NewReader(`{
    "amountIn": "1.2",
    "chainIdIn": 42161,
    "chainIdOut": 43114,
    "gasFeePaymentMethod": "ADD_TO_AMOUNT",
    "payGasFeeToken": "0xc2132d05d31c914a87c6611c10748aeb04b58e8f",
    "tokenIn": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
    "tokenOut": "0x1bfd67037b42cf73acf2047067bd4f2c47d9bfd6",
    "walletAddress": "0x6e397ddf51d9f15dbe0414538e7529f51f2e5464",
    "toAddress": "0x6e397ddf51d9f15dbe0414538e7529f51f2e5464"
  }`)
  req, _ := http.NewRequest("POST", url, body)
  req.Header.Add("Content-Type", "application/json")
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}

import requests

url = "https://api.notus.team/api/v1/crypto/swap"
body = {
  "amountIn": "1.2",
  "chainIdIn": 42161,
  "chainIdOut": 43114,
  "gasFeePaymentMethod": "ADD_TO_AMOUNT",
  "payGasFeeToken": "0xc2132d05d31c914a87c6611c10748aeb04b58e8f",
  "tokenIn": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
  "tokenOut": "0x1bfd67037b42cf73acf2047067bd4f2c47d9bfd6",
  "walletAddress": "0x6e397ddf51d9f15dbe0414538e7529f51f2e5464",
  "toAddress": "0x6e397ddf51d9f15dbe0414538e7529f51f2e5464"
}
response = requests.request("POST", url, json = body, headers = {
  "Content-Type": "application/json"
})

print(response.text)

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.time.Duration;
import java.net.http.HttpRequest.BodyPublishers;

var body = BodyPublishers.ofString("""{
  "amountIn": "1.2",
  "chainIdIn": 42161,
  "chainIdOut": 43114,
  "gasFeePaymentMethod": "ADD_TO_AMOUNT",
  "payGasFeeToken": "0xc2132d05d31c914a87c6611c10748aeb04b58e8f",
  "tokenIn": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
  "tokenOut": "0x1bfd67037b42cf73acf2047067bd4f2c47d9bfd6",
  "walletAddress": "0x6e397ddf51d9f15dbe0414538e7529f51f2e5464",
  "toAddress": "0x6e397ddf51d9f15dbe0414538e7529f51f2e5464"
}""");
HttpClient client = HttpClient.newBuilder()
  .connectTimeout(Duration.ofSeconds(10))
  .build();

HttpRequest.Builder requestBuilder = HttpRequest.newBuilder()
  .uri(URI.create("https://api.notus.team/api/v1/crypto/swap"))
  .header("Content-Type", "application/json")
  .POST(body)
  .build();

try {
  HttpResponse<String> response = client.send(requestBuilder.build(), BodyHandlers.ofString());
  System.out.println("Status code: " + response.statusCode());
  System.out.println("Response body: " + response.body());
} catch (Exception e) {
  e.printStackTrace();
}

using System;
using System.Net.Http;
using System.Text;

var body = new StringContent("""
{
  "amountIn": "1.2",
  "chainIdIn": 42161,
  "chainIdOut": 43114,
  "gasFeePaymentMethod": "ADD_TO_AMOUNT",
  "payGasFeeToken": "0xc2132d05d31c914a87c6611c10748aeb04b58e8f",
  "tokenIn": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
  "tokenOut": "0x1bfd67037b42cf73acf2047067bd4f2c47d9bfd6",
  "walletAddress": "0x6e397ddf51d9f15dbe0414538e7529f51f2e5464",
  "toAddress": "0x6e397ddf51d9f15dbe0414538e7529f51f2e5464"
}
""", Encoding.UTF8, "application/json");

var client = new HttpClient();
var response = await client.PostAsync("https://api.notus.team/api/v1/crypto/swap", body);
var responseBody = await response.Content.ReadAsStringAsync();

{
  "quotes": [
    {
      "metadata": {
        "key": "value"
      },
      "userOperationHash": "0x2aac7a66d5331454eafc9b981be3596ad08a40dad24883e3b9c4a5362cd7f7e1",
      "quoteId": "0x2aac7a66d5331454eafc9b981be3596ad08a40dad24883e3b9c4a5362cd7f7e1",
      "revertReason": {
        "decoded": "ERC-20 insufficient balance. Address 0xf12534a4939c7fbda50f893774a9525265fe1a9a has 120. The operation requested 200.",
        "raw": "0xe450d38c000000000000000000000000f12534a4939c7fbda50f893774a9525265fe1a9a0000000000000000000000000000000000000000000000068155a43676e0000000000000000000000000000000000000000000000000000ad78ebc5ac6200000",
        "utf8": "\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000�%4�����\u000f�7t�RRe�\u001a�\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0006�U�6v�\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\u0000\n׎�Z� \u0000\u0000"
      },
      "authorization": {
        "chainId": 42161,
        "address": "0xd6cedde84be40893d153be9d467cd6ad37875b28",
        "nonce": 10,
        "hash": "0x777811ae5d51875409b9978ddc1b40a9da1bbe9570040bdd7c5f186d70ceceba"
      },
      "walletAddress": "0x6e397ddf51d9f15dbe0414538e7529f51f2e5464",
      "tokenIn": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
      "amountIn": "1.26",
      "tokenOut": "0x1bfd67037b42cf73acf2047067bd4f2c47d9bfd6",
      "chainIn": 42161,
      "chainOut": 43114,
      "minAmountOut": "23.48",
      "estimatedExecutionTime": "2026-04-12T14:49:12.762Z",
      "estimatedGasFees": {
        "payGasFeeToken": "0xc2132d05d31c914a87c6611c10748aeb04b58e8f",
        "maxGasFeeToken": "12.345",
        "gasFeeTokenAmount": "12.345",
        "gasFeeTokenAmountUSD": "0.321",
        "maxGasFeeNative": "string"
      },
      "estimatedCollectedFee": {
        "collectedFeeToken": "string",
        "collectedFee": "string",
        "collectedFeePercent": "string",
        "notusCollectedFee": "string",
        "notusCollectedFeePercent": "string"
      },
      "amountInUSD": "23.4921",
      "amountOutUSD": "23.502",
      "tokenInPrice": "1.736",
      "swapProvider": "ENSO",
      "expiresAt": 1751469204210
    }
  ]
}

{
  "statusCode": 400,
  "id": "NOT_AUTHORIZED_TOKENS",
  "message": "The tokens '[0x1bfd67037b42cf73acf2047067bd4f2c47d9bfd6]' are not authorized yet."
}

{
  "statusCode": 403,
  "id": "UNAVAILABLE_COMPUTE_UNITS",
  "message": "The project doesn't have enough compute units to perform this action. Please upgrade your plan."
}

{
  "statusCode": 404,
  "id": "ACCOUNT_ABSTRACTION_ADDRESS_NOT_REGISTERED_WITH_PROJECT",
  "message": "The requested wallet \"0x335e110f9aa64deef43b646b4bdf90aac3c7844c\" is not registered with the project"
}

{
  "statusCode": 500,
  "id": "SWAP_QUOTE",
  "message": "Failed to get a swap quote. Please try again later"
}

Create Swap

Authorization

Request Body

Response Body