/swap

Overview

Unlike most DEX aggregators, our swap endpoint provides graph-based routing plans with optional on-demand calldata generation. Each routing plan specifies the exact amounts and tokens to trade with various liquidity sources, including AMMs and market maker liquidity.

When calldata is not requested, clients can use an encoder to convert the routing plans into transaction calldata for any compatible router contract. This flexibility allows you to choose the most suitable router for your specific use case.

By establishing a standardized format for routing plans, our approach decouples the aggregator API from specific router contracts. This standardization enables seamless encoding and settlement of routing results from any compatible aggregator using any supported router contract.

API schema

Swap endpoint

https://app.swap-net.xyz/api/v1.0/swap

Parameters

Name
Required?
Description
Valid values

chainId

Yes

Integer ID of the blockchain

Chain IDs defined here

sellToken

Yes

Address of sell token¹

Blockchain addresses

buyToken

Yes

Address of buy token¹

Blockchain addresses

sellAmount

Yes²

Amount of sellToken to sell (in base units)

Positive integers

buyAmount

Yes²

Amount of buyToken to buy (in base units)

Positive integers

useRfq

No (default: false)

Whether to use market maker RFQ liquidity

boolean

router

No (default: default-router)

Router contract unique name

Router unique names defined here

includeCalldata

No (default: false)

Whether to include calldata in the response

boolean

userAddress

Yes if includeCalldata=true

User’s wallet address

Blockchain addresses

slippageTolerance

Yes if includeCalldata=true

Slippage tolerance (0.01 = 1%)

Decimal numbers between 0 and 1

apiKey

Yes

Your API key

string

¹ For native tokens, use either 0x0000000000000000000000000000000000000000 or 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee as the token address.

² Exactly one of sellAmount or buyAmount must be provided, but not both. Specify sellAmount for exact-input swaps or buyAmount for exact-output swaps.

Simple query example

curl "https://app.swap-net.xyz/api/v1.0/swap\
?chainId=1\
&sellToken=0x853d955acef822db058eb8505911ed77f175b99e\
&buyToken=0x1f9840a85d5af5bf1d1762f925bdaddc4201f984\
&sellAmount=10000000000000000000000\
&apiKey=<Your API Key>"

Response includes:

Field name
Description

tokens

Metadata of a list of tokens involved in the routing result. Including token's address, name, symbol, decimals, usdPrice, and a referenceId used to refer to the token.

sell

Contains referenceId and amount of the token the user wants to sell, and may include a wrapFromNative boolean field if the sell token is native token.

buy

Contains referenceId and amount of the token the user wants to buy, and may include an unwrapToNative boolean field if the buy token is native token.

nativeTokenUsdPrice

Current price of the native token on this chain.

routes

A collection of swaps forming a directed acyclic graph that converts all sell tokens into buy tokens. Note that the order of the routes is not guaranteed.

route.name

Name of the liquidity source used by this route (swap).

route.address

Address of the liquidity pool.

route.fromTokens

Array containing referenceId and amount of tokens to swap from.

route.toTokens

Array containing referenceId and amount of tokens to swap to.

route.details

Additional information about this route (swap) which is used during encoding.

Click to view example response
{
  "aggregator": "swapnet",
  "router": "default-router",
  "sell": {
    "referenceId": 7,
    "amount": "10000000000000000000000"
  },
  "buy": {
    "referenceId": 6,
    "amount": "1034955025987043448356"
  },
  "nativeTokenUsdPrice": 4622.638914277432,
  "tokens": [
    {
      "referenceId": 7,
      "address": "0x853d955acef822db058eb8505911ed77f175b99e",
      "name": "Frax",
      "symbol": "FRAX",
      "decimals": 18,
      "usdPrice": 0.9985832349359104
    },
    {
      "referenceId": 1,
      "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "name": "USDCoin",
      "symbol": "USDC",
      "decimals": 6,
      "usdPrice": 1
    },
    {
      "referenceId": 0,
      "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "name": "Wrapped Ether",
      "symbol": "WETH",
      "decimals": 18,
      "usdPrice": 4622.638914277432
    },
    {
      "referenceId": 2,
      "address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
      "name": "Tether USD",
      "symbol": "USDT",
      "decimals": 6,
      "usdPrice": 1.0005286652107792
    },
    {
      "referenceId": 6,
      "address": "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984",
      "name": "Uniswap",
      "symbol": "UNI",
      "decimals": 18,
      "usdPrice": 9.632281172169868
    }
  ],
  "routes": [
    {
      "address": "0xc63b0708e2f7e69cb8a1df0e1389a98c35a76d52",
      "name": "UniswapV3",
      "details": {
        "fee": 500
      },
      "fromTokens": [
        {
          "referenceId": 7,
          "amount": "10000000000000000000000"
        }
      ],
      "toTokens": [
        {
          "referenceId": 1,
          "amount": "9980414364"
        }
      ]
    },
    {
      "address": "0xc7bbec68d12a0d1830360f8ec58fa599ba1b0e9b",
      "name": "UniswapV3",
      "details": {
        "fee": 100
      },
      "fromTokens": [
        {
          "referenceId": 2,
          "amount": "9973989690"
        }
      ],
      "toTokens": [
        {
          "referenceId": 0,
          "amount": "2162884170453897195"
        }
      ]
    },
    {
      "address": "0x3416cf6c708da44db2624d63ea0aaef7113527c6",
      "name": "UniswapV3",
      "details": {
        "fee": 100
      },
      "fromTokens": [
        {
          "referenceId": 1,
          "amount": "9980414291"
        }
      ],
      "toTokens": [
        {
          "referenceId": 2,
          "amount": "9973989608"
        }
      ]
    },
    {
      "address": "0x8626be23f128f5985a5d76359b10bf3db84a7306",
      "name": "RingswapV2",
      "details": {
        "feeInBps": 30,
        "fromFewWrappedTokenAddress": "0xa250cc729bb3323e7933022a67b52200fe354767",
        "toFewWrappedTokenAddress": "0xe8e1f50392bd61d0f8f48e8e7af51d3b8a52090a"
      },
      "fromTokens": [
        {
          "referenceId": 0,
          "amount": "2162884172944070813"
        }
      ],
      "toTokens": [
        {
          "referenceId": 6,
          "amount": "1034955025987043448356"
        }
      ]
    }
  ]
}

Example with includeCalldata=true

curl "https://app.swap-net.xyz/api/v1.0/swap\
?chainId=999\
&sellToken=0xb8ce59fc3717ada4c02eadf9682a9e934f625ebb\
&buyToken=0x5555555555555555555555555555555555555555\
&sellAmount=10000000000\
&useRfq=true\
&includeCalldata=true\
&userAddress=0x11b86991c6218b36c1d19d4a2e9eb0ce3606eb49\
&slippageTolerance=0.01\
&router=swapnet-router\
&apiKey=<Your API Key>"

Response includes three more fields:

Field name
Description

routerAddress

Address of router contract

calldata

Calldata to settle the trade with the router contract

gasLimit

An estimated upper bound of gas consumption, used to config the TX

Click to view example response with calldata
{
  "aggregator": "swapnet",
  "router": "swapnet-router",
  "sell": {
    "referenceId": 1,
    "amount": "10000000000"
  },
  "buy": {
    "referenceId": 0,
    "amount": "170261032657489111452"
  },
  "nativeTokenUsdPrice": 58.75669929845798,
  "tokens": [
    {
      "referenceId": 0,
      "address": "0x5555555555555555555555555555555555555555",
      "name": "Wrapped HYPE",
      "symbol": "WHYPE",
      "decimals": 18,
      "usdPrice": 58.75669929845798
    },
    {
      "referenceId": 1,
      "address": "0xb8ce59fc3717ada4c02eadf9682a9e934f625ebb",
      "name": "USD₮0",
      "symbol": "USD₮0",
      "decimals": 6,
      "usdPrice": 1
    },
    {
      "referenceId": 2,
      "address": "0xfd739d4e423301ce9385c1fb8850539d657c296d",
      "name": "Kinetiq Staked HYPE",
      "symbol": "kHYPE",
      "decimals": 18,
      "usdPrice": 58.87736177694538
    }
  ],
  "routes": [
    {
      "address": "0xbd19e19e4b70eb7f248695a42208bc1edbbfb57d",
      "name": "ProjectxV3",
      "details": {
        "fee": 500
      },
      "fromTokens": [
        {
          "referenceId": 1,
          "amount": "2791261914"
        }
      ],
      "toTokens": [
        {
          "referenceId": 0,
          "amount": "47522431692592024830"
        }
      ]
    },
    {
      "address": "0x337b56d87a6185cd46af3ac2cdf03cbc37070c30",
      "name": "HyperswapV3",
      "details": {
        "fee": 500
      },
      "fromTokens": [
        {
          "referenceId": 1,
          "amount": "3589899622"
        }
      ],
      "toTokens": [
        {
          "referenceId": 0,
          "amount": "61123086039943950988"
        }
      ]
    },
    {
      "address": "0x09de938d3e788af06fd6d0819db9226150d4a0f3",
      "name": "ProjectxV3",
      "details": {
        "fee": 500
      },
      "fromTokens": [
        {
          "referenceId": 1,
          "amount": "3618838464"
        }
      ],
      "toTokens": [
        {
          "referenceId": 2,
          "amount": "61487009617903382007"
        }
      ]
    },
    {
      "address": "0x7a37621a2a490214f03e6ce7199aeca9b7c565cc",
      "name": "KittenswapV4",
      "fromTokens": [
        {
          "referenceId": 2,
          "amount": "16811648469114239656"
        }
      ],
      "toTokens": [
        {
          "referenceId": 0,
          "amount": "16846708650432222804"
        }
      ]
    },
    {
      "address": "0x5a716e045421b0977ca5bfb4f3394139c6a069bc",
      "name": "HybraV3",
      "details": {
        "fee": 25
      },
      "fromTokens": [
        {
          "referenceId": 2,
          "amount": "44675364046738217721"
        }
      ],
      "toTokens": [
        {
          "referenceId": 0,
          "amount": "44768806274520912829"
        }
      ]
    }
  ],
  "routerAddress": "0x616000e384Ef1C2B52f5f3A88D57a3B64F23757e",
  "calldata": "0x87395540000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000001c00000000000000000000000000000000000000000000000092337d00c9669a93100000000000000000000000011b86991c6218b36c1d19d4a2e9eb0ce3606eb490000000000000000000000000000000000000000000000000000000000000003000000000000000000000000b8ce59fc3717ada4c02eadf9682a9e934f625ebb00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000fd739d4e423301ce9385c1fb8850539d657c296d00000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000001000000000000000000000000555555555555555555555555555555555555555500000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000005000000000000000000000000000000000000000000000000000000000000000500000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000180000000000000000000000000000000000000000000000000000000000000026000000000000000000000000000000000000000000000000000000000000003400000000000000000000000000000000000000000000000000000000000000420000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000d7b317c000000000000000000000000009de938d3e788af06fd6d0819db9226150d4a0f3000000000000000000000000000000000000000000000000000000000000000e00000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000000030001f40000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000a65f46da000000000000000000000000bd19e19e4b70eb7f248695a42208bc1edbbfb57d000000000000000000000000000000000000000000000000000000000000000e00000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000000030001f40000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000d5f98566000000000000000000000000337b56d87a6185cd46af3ac2cdf03cbc37070c30000000000000000000000000000000000000000000000000000000000000000d00000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000000030001f400000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000e94ef935f24b3aa80000000000000000000000007a37621a2a490214f03e6ce7199aeca9b7c565cc000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000000030000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000000000000000000000000000005a716e045421b0977ca5bfb4f3394139c6a069bc000000000000000000000000000000000000000000000000000000000000000f00000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000000030000190000000000000000000000000000000000000000000000000000000000",
  "gasLimit": "1200000"
}
PreviousNext stepsNext/chains

Last updated