/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
recipientAddress	No	The address to receive buyToken³	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.

³ If not set, buyToken will be sent to msg.sender.

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"
}