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

application/json

TypeScript Definitions

Use the request body type in TypeScript.

amountIn*string

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

chainIdIn*number

The blockchain network where the swap originates. Supported chains:

Arbitrum One: 42161
Avalanche: 43114
Base: 8453
BNB Smart Chain: 56
Ethereum: 1
Gnosis: 100
OP Mainnet: 10
Polygon: 137
X Layer Mainnet: 196
Robinhood Chain: 4663
Bitcoin: 0
Stellar: -1

chainIdOut*number

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
X Layer Mainnet: 196
Robinhood Chain: 4663
Bitcoin: 0
Stellar: -1

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"

gasFeePaymentMethod*string

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"

payGasFeeToken*string

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

tokenIn*string

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

tokenOut*string

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

walletAddress*|

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

EVM
- pattern: ^0x[a-fA-F0-9]{40}$
- example: 0x6e397ddf51d9f15dbe0414538e7529f51f2e5464
Bitcoin
- pattern: ^(?:[13][a-km-zA-HJ-NP-Z1-9]{25,35}|bc1q[02-9ac-hj-np-z]{38}|bc1q[02-9ac-hj-np-z]{58}|bc1p[02-9ac-hj-np-z]{10,70})$
- example: bc1ql3s9y4gyvlgardeklm9e4d8n83ytyzgwgh88tk

toAddress*||

The address (EVM, Bitcoin or Stellar) receiving the swap. Generally equal to the walletAddress, but can be another address. A Stellar account is only accepted for a USDC transfer to chainIdOut -1, settled through Circle CCTP, and it must already be active and hold an authorized USDC trustline. Accepted formats:

EVM
- pattern: ^0x[a-fA-F0-9]{40}$
- example: 0x6e397ddf51d9f15dbe0414538e7529f51f2e5464
Bitcoin
- pattern: ^(?:[13][a-km-zA-HJ-NP-Z1-9]{25,35}|bc1q[02-9ac-hj-np-z]{38}|bc1q[02-9ac-hj-np-z]{58}|bc1p[02-9ac-hj-np-z]{10,70})$
- example: bc1ql3s9y4gyvlgardeklm9e4d8n83ytyzgwgh88tk
Stellar
- pattern: ^G[A-Z2-7]{55}$
- example: GCNHC2KY3QLJYXJCTY64TWDFHZWMOUYRD6AGMWUZOSK2VHK7D5MYUYZA

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.

Range0 <= value <= 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%.

Range0.5 <= value <= 99

Default0.5

extraFee?

Optional extra fee that can be charged in addition to the transaction fee (configured in the dashboard or via transactionFeePercent). This extra fee is deducted from the input token and sent to the specified toAddress, allowing you to define a custom recipient for this additional charge.

minAmountOut?string

Optional minimum output amount as a decimal string. When provided, the current swap endpoint returns a limit-order quote instead of a market quote.

expiration?integer

Optional limit-order expiration time in seconds from quote creation.

Range0 < value <= 9007199254740991

partialFillable?boolean

Optional flag for limit orders. Defaults to true. When true, the order may be filled in multiple partial executions instead of a single all-or-nothing fill.

Defaulttrue

metadata?

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

individualId?array<string>

Optional Notus KYC individual identifier. Required when tokenIn or tokenOut is a Global Investments/RWA token.

Response Body

`application/json`

curl -X POST "https://example.com/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"  }'

{  "quotes": [    {      "metadata": {        "key": "value"      },      "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"      },      "tokenIn": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",      "amountIn": "1.26",      "tokenOut": "0x1bfd67037b42cf73acf2047067bd4f2c47d9bfd6",      "chainIn": 42161,      "chainOut": 43114,      "minAmountOut": "23.48",      "amountOut": "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": "0xc2132d05d31c914a87c6611c10748aeb04b58e8f",        "collectedFee": "string",        "collectedFeePercent": "string",        "notusCollectedFee": "string",        "notusCollectedFeePercent": "string"      },      "amountInUSD": "23.4921",      "amountOutUSD": "23.502",      "tokenInPrice": "1.736",      "swapProvider": "CCTP",      "expiresAt": 1751469204210,      "fees": [        {          "amount": "100.5",          "token": "0x1234567890123456789012345678901234567890",          "toAddress": "0x1234567890123456789012345678901234567890",          "type": "NOTUS",          "percentage": "2"        }      ],      "typedData": {        "domain": {          "name": "Portikus",          "version": "2.0.0",          "chainId": 137,          "verifyingContract": "0x6e397ddf51d9f15dbe0414538e7529f51f2e5464"        },        "types": {          "Kernel": [            {              "name": "hash",              "type": "bytes32"            }          ]        },        "primaryType": "Order",        "message": {          "owner": "0x6e397ddf51d9f15dbe0414538e7529f51f2e5464",          "srcAmount": "1000000000000000000"        }      },      "userOperationHash": "0x2aac7a66d5331454eafc9b981be3596ad08a40dad24883e3b9c4a5362cd7f7e1",      "quoteId": "0x2aac7a66d5331454eafc9b981be3596ad08a40dad24883e3b9c4a5362cd7f7e1",      "authorization": {        "chainId": 42161,        "address": "0xd6cedde84be40893d153be9d467cd6ad37875b28",        "nonce": 10,        "hash": "0x777811ae5d51875409b9978ddc1b40a9da1bbe9570040bdd7c5f186d70ceceba"      },      "rwaApproveUserOperation": {        "userOperationHash": "string",        "authorization": {          "chainId": 42161,          "address": "0xd6cedde84be40893d153be9d467cd6ad37875b28",          "nonce": 10,          "hash": "0x777811ae5d51875409b9978ddc1b40a9da1bbe9570040bdd7c5f186d70ceceba"        }      },      "walletAddress": "0x6e397ddf51d9f15dbe0414538e7529f51f2e5464",      "toAddress": "0x6e397ddf51d9f15dbe0414538e7529f51f2e5464"    }  ]}

Create Swap

Authorization

Request Body

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Create Swap

Authorization

Request Body

Response Body

200application/json

400application/json

403application/json

404application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`