Quotes API Reference

API Developer Docs

The /quotes API provides swap quote information for cross-chain and same-chain token swaps. It returns multiple quote options with routing paths, estimated amounts, fees, and gas costs.

Base URL

⚠️ DEVELOPMENT VERSION WARNING

This is a development version of the API and documentation. Endpoints, parameters, response formats, and other details are subject to change without notice.

Please contact the team for the latest API status and production-ready documentation.

https://dev.tesseract.finance

Notes

To contact the team please join our Discord here and open a ticket via the support-ticketing channel.
An additional confirmation endpoint will be added for certain quotes, for example those routed via Dexalot, which will be a required call in order to finalise the quote and return the tx params.
Please get in touch if you would like to added as a source so that we can correctly attribute any volume generated from your use of the API.

Endpoint

GET /api/quotes

Query Parameters

Parameter	Type	Required	Description	Example
`srcToken`	string	Yes	Source token identifier in `chainId:address` format	`43114:0xC09a033927f9fD558C92CF7AeAbE34B71ce4B31E`
`dstToken`	string	Yes	Destination token identifier in `chainId:address` format	`16180:0x0000000000000000000000000000000000000000`
`amount`	string	Yes	Amount to swap (as BigInt string, in source token's smallest unit)	`1000000000000000000`
`slippageBps`	string	Yes	Slippage tolerance in basis points (as BigInt string, e.g., 100 = 1%)	`100`
`source`	string	Yes	Quote source: `tesseract` or `api`	`tesseract`
`srcChain`	number	No	Source chain ID (auto-detected from srcToken if not provided)	`43114`
`srcDecimals`	number	No	Source token decimals (auto-detected if token is supported). Required for unsupported tokens.	`18`
`dstChain`	number	No	Destination chain ID (auto-detected from dstToken if not provided)	`16180`
`dstDecimals`	number	No	Destination token decimals (auto-detected if token is supported). Required for unsupported tokens.	`18`
`accountAddress`	string	No	Account address for the swap (affects fee calculations). Required to return txParams for quotes.	`0x1234...5678`
`recipientAddress`	string	No	Recipient address (defaults to accountAddress if not provided)	`0x1234...5678`
`maxHops`	number	No	Maximum number of hops/routing steps (default: 3)	`3`

Token Identification

Tokens are identified using the chainId:address format:

Format: <chainId>:<address>
Example: 43114:0xC09a033927f9fD558C92CF7AeAbE34B71ce4B31E (PLYR on Avalanche C-Chain)
Example: 16180:0x0000000000000000000000000000000000000000 (Native PLYR on PLYR PHI)

Amount Format

Amounts are specified as BigInt strings in the token's smallest unit (wei for AVAX, smallest decimal for ERC20 tokens):

1 AVAX = 1000000000000000000 (18 decimals)
1 USDC = 1000000 (6 decimals)
1 USDT = 1000000 (6 decimals)

Slippage Format

Slippage is specified in basis points (1 basis point = 0.01%):

0.5% slippage = 50
1% slippage = 100
5% slippage = 500

Examples

Example 1: Cross-chain swap from Avalanche to PLYR PHI

Parameters

Parameter	Value
`srcToken`	`43114:0xC09a033927f9fD558C92CF7AeAbE34B71ce4B31E`
`dstToken`	`16180:0x0000000000000000000000000000000000000000`
`amount`	`1000000000000000000`
`slippageBps`	`100`
`source`	`tesseract`

Note: Optional parameters (srcChain, srcDecimals, dstChain, dstDecimals, accountAddress, recipientAddress, maxHops) are not provided in this example.

Request

GET /api/quotes?srcToken=43114:0xC09a033927f9fD558C92CF7AeAbE34B71ce4B31E&dstToken=16180:0x0000000000000000000000000000000000000000&amount=1000000000000000000&slippageBps=100&source=tesseract

Response

{
  "data": {
    "srcData": {
      "chain": 43114,
      "tokenAddress": "0xC09a033927f9fD558C92CF7AeAbE34B71ce4B31E"
    },
    "dstData": {
      "chain": 16180,
      "tokenAddress": "0x0000000000000000000000000000000000000000"
    },
    "timestamp": 1709123456789,
    "maxDstAmount": "998500000000000000",
    "minDuration": 120,
    "quotes": [
      {
        "id": "quote-1",
        "srcData": {
          "chain": 43114,
          "tokenAddress": "0xC09a033927f9fD558C92CF7AeAbE34B71ce4B31E",
          "cell": "43114:0x87260775905e83689958a1491bc0C47396B2B21c",
          "estAmount": "1000000000000000000",
          "minAmount": "1000000000000000000"
        },
        "dstData": {
          "chain": 16180,
          "tokenAddress": "0x0000000000000000000000000000000000000000"
        },
        "type": "swap",
        "hops": [
          {
            "srcData": {
              "chain": 43114,
              "tokenAddress": "0xC09a033927f9fD558C92CF7AeAbE34B71ce4B31E",
              "cell": "43114:0x87260775905e83689958a1491bc0C47396B2B21c",
              "estAmount": "1000000000000000000",
              "minAmount": "1000000000000000000"
            },
            "dstData": {
              "chain": 16180,
              "tokenAddress": "0x0000000000000000000000000000000000000000",
              "cell": "16180:0xB952F9f97aECB40659386Af83957aE8D730f7EBD",
              "estAmount": "998500000000000000",
              "minAmount": "990000000000000000"
            },
            "type": "swapAndHop",
            "index": 0,
            "estGasUnits": "500000",
            "bridgePath": {
              "srcData": {
                "chainId": 43114,
                "tokenAddress": "0xC09a033927f9fD558C92CF7AeAbE34B71ce4B31E",
                "address": "0x8fa3B51e876CE26eA43c6d0Cf886050bF580118e",
                "type": "erc20"
              },
              "dstData": {
                "chainId": 16180,
                "tokenAddress": "0x0000000000000000000000000000000000000000",
                "address": "0xAAAaBe49A72EcF0804292CE8e889016d9D05767c",
                "type": "native"
              },
              "provider": "ictt"
            },
            "encodedTrade": "0x..."
          }
        ],
        "events": [
          {
            "srcData": {
              "chain": 43114,
              "tokenAddress": "0xC09a033927f9fD558C92CF7AeAbE34B71ce4B31E"
            },
            "dstData": {
              "chain": 16180,
              "tokenAddress": "0x0000000000000000000000000000000000000000"
            },
            "type": "transfer",
            "index": 0,
            "hopIndex": 0,
            "bridge": "ictt"
          }
        ],
        "srcAmount": "1000000000000000000",
        "estDstAmount": "998500000000000000",
        "minDstAmount": "990000000000000000",
        "estDuration": 120,
        "feeData": {
          "fixedNativeFee": "25000000000000000",
          "baseFee": "15000000000000000"
        },
        "estGasFee": "50000000000000000",
        "estGasUnits": "500000",
        "timestamp": 1709123456789
      }
    ]
  }
}

Example 2: Same-chain swap on Avalanche with account address

Parameters

Parameter	Value
`srcToken`	`43114:0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E`
`dstToken`	`43114:0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7`
`amount`	`1000000000`
`slippageBps`	`100`
`source`	`tesseract`
`accountAddress`	`0x1234567890123456789012345678901234567890`
`maxHops`	`2`

Note: Optional parameters (srcChain, srcDecimals, dstChain, dstDecimals, recipientAddress) are not provided in this example.

Request

GET /api/quotes?srcToken=43114:0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E&dstToken=43114:0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7&amount=1000000000&slippageBps=100&source=tesseract&accountAddress=0x1234567890123456789012345678901234567890&maxHops=2

Response

{
  "data": {
    "srcData": {
      "chain": 43114,
      "tokenAddress": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
      "cell": "43114:0x1234567890123456789012345678901234567890"
    },
    "dstData": {
      "chain": 43114,
      "tokenAddress": "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7"
    },
    "timestamp": 1709123456789,
    "maxDstAmount": "998000000",
    "minDuration": 30,
    "quotes": [
      {
        "id": "quote-1",
        "srcData": {
          "chain": 43114,
          "tokenAddress": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
          "cell": "43114:0x1234567890123456789012345678901234567890",
          "estAmount": "1000000000",
          "minAmount": "1000000000"
        },
        "dstData": {
          "chain": 43114,
          "tokenAddress": "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7",
          "cell": "43114:0x1234567890123456789012345678901234567890",
          "estAmount": "998000000",
          "minAmount": "990000000"
        },
        "type": "swap",
        "hops": [
          {
            "srcData": {
              "chain": 43114,
              "tokenAddress": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
              "cell": "43114:0x1234567890123456789012345678901234567890",
              "estAmount": "1000000000",
              "minAmount": "1000000000"
            },
            "dstData": {
              "chain": 43114,
              "tokenAddress": "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7",
              "cell": "43114:0x1234567890123456789012345678901234567890",
              "estAmount": "998000000",
              "minAmount": "990000000"
            },
            "type": "swapAndTransfer",
            "index": 0,
            "estGasUnits": "200000",
            "trade": {
              "amountIn": "1000000000",
              "amountOut": "998000000",
              "minAmountOut": "990000000",
              "path": ["0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E", "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7"],
              "adapters": ["0x3333333333333333333333333333333333333333"]
            },
            "encodedTrade": "0x..."
          }
        ],
        "events": [
          {
            "srcData": {
              "chain": 43114,
              "tokenAddress": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E"
            },
            "dstData": {
              "chain": 43114,
              "tokenAddress": "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7"
            },
            "type": "swap",
            "index": 0,
            "hopIndex": 0,
            "adapterAddress": "0x3333333333333333333333333333333333333333",
            "adapter": {
              "address": "0x3333333333333333333333333333333333333333",
              "name": "Uniswap V2",
              "platform": "uniswap"
            }
          }
        ],
        "accountAddress": "0x1234567890123456789012345678901234567890",
        "srcAmount": "1000000000",
        "estDstAmount": "998000000",
        "minDstAmount": "990000000",
        "estDuration": 30,
        "feeData": {
          "fixedNativeFee": "0",
          "baseFee": "500000"
        },
        "estGasFee": "20000000000000000",
        "estGasUnits": "200000",
        "timestamp": 1709123456789,
        "txParams": {
          "chainId": 43114,
          "address": "0x87260775905e83689958a1491bc0C47396B2B21c",
          "account": "0x1234567890123456789012345678901234567890",
          "functionName": "initiate",
          "args": [
            "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
            "1000000000",
            {
              "receiver": "0x1234567890123456789012345678901234567890",
              "rollbackReceiver": "0x1234567890123456789012345678901234567890",
              "payableReceiver": false,
              "rollbackTeleporterFee": "0",
              "rollbackGasLimit": "0",
              "hops": [
                {
                  "action": 3,
                  "requiredGasLimit": "200000",
                  "recipientGasLimit": "0",
                  "trade": "0x..."
                }
              ],
              "sourceId": "1"
            }
          ],
          "value": "0",
          "data": "0x..."
        }
      }
    ]
  }
}

Response Schema

Success Response

Field	Type	Description
`data.srcData`	object	Source token and chain information
`data.srcData.chain`	number	Source chain ID
`data.srcData.tokenAddress`	string	Source token contract address
`data.srcData.cell`	string	Cell contract address (if applicable)
`data.dstData`	object	Destination token and chain information
`data.dstData.chain`	number	Destination chain ID
`data.dstData.tokenAddress`	string	Destination token contract address
`data.dstData.cell`	string	Cell contract address (if applicable)
`data.timestamp`	number	Unix timestamp (milliseconds) of when quote was generated
`data.maxDstAmount`	string	Maximum estimated destination amount across all quotes (BigInt string)
`data.minDuration`	number	Minimum estimated duration in seconds across all quotes
`data.quotes`	array	Array of swap quote options
`data.quotes[].id`	string	Unique identifier for the quote
`data.quotes[].srcData`	object	Source token data with cell, estAmount, and minAmount
`data.quotes[].dstData`	object	Destination token data
`data.quotes[].type`	string	Swap type: `"swap"` or `"transfer"`
`data.quotes[].hops`	array	Array of routing hops
`data.quotes[].hops[].srcData`	object	Source data for the hop
`data.quotes[].hops[].dstData`	object	Destination data for the hop
`data.quotes[].hops[].type`	string	Hop type: `"hop"`, `"hopAndCall"`, `"swapAndHop"`, or `"swapAndTransfer"`
`data.quotes[].hops[].index`	number	Hop index in the routing path
`data.quotes[].hops[].estGasUnits`	string	Estimated gas units for this hop (BigInt string)
`data.quotes[].hops[].trade`	object	Trade details (for swap hops)
`data.quotes[].hops[].encodedTrade`	string	Encoded trade data (hex string)
`data.quotes[].hops[].bridgePath`	object	Bridge path information (for cross-chain hops)
`data.quotes[].events`	array	Array of swap/transfer events
`data.quotes[].events[].type`	string	Event type: `"swap"` or `"transfer"`
`data.quotes[].events[].hopIndex`	number	Index of the hop this event belongs to
`data.quotes[].events[].adapterAddress`	string	DEX adapter address (for swap events)
`data.quotes[].events[].bridge`	string	Bridge provider name (for transfer events)
`data.quotes[].srcAmount`	string	Source amount (BigInt string)
`data.quotes[].estDstAmount`	string	Estimated destination amount (BigInt string)
`data.quotes[].minDstAmount`	string	Minimum guaranteed destination amount (BigInt string)
`data.quotes[].estDuration`	number	Estimated duration in seconds
`data.quotes[].feeData`	object	Fee information
`data.quotes[].feeData.fixedNativeFee`	string	Fixed native token fee (BigInt string)
`data.quotes[].feeData.baseFee`	string	Base token fee (BigInt string)
`data.quotes[].estGasFee`	string	Estimated gas fee in native token (BigInt string)
`data.quotes[].estGasUnits`	string	Total estimated gas units (BigInt string)
`data.quotes[].timestamp`	number	Unix timestamp (milliseconds)
`data.quotes[].accountAddress`	string	Account address (if provided)
`data.quotes[].recipientAddress`	string	Recipient address (if provided)
`data.quotes[].txParams`	object	Data to initiate the quote transaction (only present when `accountAddress` is provided)
`data.quotes[].txParams.chainId`	number	Source chain ID
`data.quotes[].txParams.address`	string	Source cell contract address
`data.quotes[].txParams.account`	string	Account address initiating the transaction
`data.quotes[].txParams.functionName`	string	Function name: `"initiate"`
`data.quotes[].txParams.args`	tuple	Raw parameters for the transaction
`data.quotes[].txParams.args[0]`	string	Source token address
`data.quotes[].txParams.args[1]`	string	Source amount (BigInt string)
`data.quotes[].txParams.args[2]`	object	Cell instructions for each hop
`data.quotes[].txParams.args[2].receiver`	string	Recipient address
`data.quotes[].txParams.args[2].rollbackReceiver`	string	Recipient address in event of rollback
`data.quotes[].txParams.args[2].payableReceiver`	boolean	`true` when dstToken is native token
`data.quotes[].txParams.args[2].rollbackTeleporterFee`	string	Amount of token charged as a fee in event of rollback (BigInt string)
`data.quotes[].txParams.args[2].rollbackGasLimit`	string	Gas limit for rollback transactions (BigInt string)
`data.quotes[].txParams.args[2].hops`	array	Array of objects containing instructions for each hop
`data.quotes[].txParams.args[2].hops[].action`	number	Corresponding to hop type: 0 = hop, 1 = hopAndCall, 2 = swapAndHop, 3 = swapAndTransfer
`data.quotes[].txParams.args[2].hops[].requiredGasLimit`	string	Gas limit for all hop transactions (BigInt string)
`data.quotes[].txParams.args[2].hops[].recipientGasLimit`	string	Gas limit for recipient contract calls (BigInt string)
`data.quotes[].txParams.args[2].hops[].trade`	string	Encoded swap route instructions (if applicable, hex string)
`data.quotes[].txParams.args[2].hops[].bridgePath`	object	Data relating to any cross-chain transfers
`data.quotes[].txParams.args[2].hops[].bridgePath.bridgeSourceChain`	string	Address of the token bridge contract on the source chain
`data.quotes[].txParams.args[2].hops[].bridgePath.sourceBridgeIsNative`	boolean	`true` if the source bridge contract is nativeHome or nativeRemote
`data.quotes[].txParams.args[2].hops[].bridgePath.bridgeDestinationChain`	string	Address of the token bridge contract on the destination chain
`data.quotes[].txParams.args[2].hops[].bridgePath.cellDestinationChain`	string	Address of the cell contract on the destination chain
`data.quotes[].txParams.args[2].hops[].bridgePath.destinationBlockchainID`	string	Unique blockchain ID (hex string)
`data.quotes[].txParams.args[2].hops[].bridgePath.teleporterFee`	string	Primary fee for Teleporter service (BigInt string)
`data.quotes[].txParams.args[2].hops[].bridgePath.secondaryTeleporterFee`	string	Secondary fee for Teleporter service (BigInt string)
`data.quotes[].txParams.args[2].sourceId`	string	Numerical representation of the source, 1 = tesseract, 2 = api (BigInt string)
`data.quotes[].txParams.value`	string	Native token amount (if applicable, BigInt string)
`data.quotes[].txParams.data`	string	Encoded version of the above (hex string)

Error Response Schema

All error responses follow a standard format:

{
  "error": "Human-readable error message"
}

The error field contains a string describing what went wrong.

Error Response Examples

Invalid Parameters Error

{
  "error": "srcToken is required, dstToken is required, amount must be a valid integer"
}

No Swap Paths Found Error

{
  "error": "no swap paths found for route"
}

No Quotes Found Error

{
  "error": "no quotes found"
}

Enumerated Values

Swap Source

The source parameter accepts the following values:

tesseract: Use Tesseract quote source
api: Use API quote source

Swap Type

The type field in quote responses indicates the type of swap:

swap: Token swap operation
transfer: Token transfer operation

Hop Types

The API supports different hop types for routing:

hop: Simple cross-chain transfer without swapping
hopAndCall: Cross-chain transfer with additional call data
swapAndHop: Swap on source chain then bridge to destination
swapAndTransfer: Same-chain swap (no bridging)

Event Types

The type field in event objects indicates the event type:

swap: DEX swap event
transfer: Cross-chain bridge transfer event

Bridge Providers

The provider field in bridge path objects indicates the bridge provider:

ictt: Inter-Chain Token Transfer bridge
teleporter: Teleporter bridge (deprecated/legacy)

Fee Structure

Fees are calculated based on:

fixedNativeFee: Fixed fee in the native token of the source chain (e.g., AVAX, PLYR)
baseFee: Base fee in the input token (if no swap) or output token (if swapped)

The fixedNativeFee must be included in the transaction value when initiating the swap. The baseFee must be accounted for in the token approval amount.

Notes

Quotes are estimates and actual amounts may vary slightly due to market conditions
The minDstAmount is calculated based on the provided slippageBps parameter
Quotes include gas estimates but actual gas costs may vary based on network conditions
Cross-chain swaps typically take longer than same-chain swaps
The API returns multiple quote options; clients should select the best option based on their criteria (best rate, lowest fees, fastest, etc.)