Create а quote

Retrieves the best available swap quote for a given source token, destination token, and amount. Also, returns pricing details, limits, and metadata required to proceed with a swap.

Quotes has time limits and must be executed before their expiration.

HTTP request

POST /v1/quotes/

Request

Header parameters

Requires authentication.

Body parameters

Name	Type	Required	Description
from	Object	Required	Base token information to receive a quote.
from.token_id	Number	Conditional required	Part of the from object. Required only if network_id and token are not provided. To receive token_id, use the GET /v1/tokens endpoint.
from.network_id	Number	Conditional required	Part of the from object. Required only if token_id is not provided. To receive network_id, use the GET /v1/networks endpoint.
from.contract_address	String	Conditional required	Part of the from object. Required only if token_id is not provided.
from.decimals	Number	Conditional required	Part of the from object. Required only if token_id is not provided.
to	Object	Required	Quote token information for receiving quote.
to.token_id	Number	Conditional required	Part of the to object. Required only if network_id and token are not provided. To receive token_id, use the GET /v1/tokens endpoint.
to.network_id	Number	Conditional required	Part of the to object. Required only if token_id is not provided. To receive network_id, use the GET /v1/networks endpoint.
to.contract_address	String	Conditional required	Part of the to object. Required only if token_id is not provided.
amount	Decimals in string	Required	Amount to swap.
slippage_bps	String	Optional	Slippage expressed in basis points. Value must be from 100 to 10000 bps.
fees	Object	Optional	Applied custom partner fees for current quote.
fees.affiliate	Object	Optional	Part of the fees object. Affiliate fee information.
fees.affiliate.token_id	Number	Optional	Part of the fees.affiliate object. Unique identifier of the token in which the affiliate fee is collected. To receive token_id, use the GET /v1/tokens endpoint.
fees.affiliate.fee	Decimal in string	Optional	Part of the fees.affiliate object. The custom affiliate fee value, specified in basis points (e.g., "100" = 1%).

info

The custom affiliate fee value in basis points must be in increments of 5 (or 0.05%) and cannot exceed 3% (300 bps).

Sample request

application/json

{
  "from": {
      "token_id": 278
  },
  "to": {
      "token_id": 4
  },
  "amount": "100000000",
  "slippage_bps": "100",
  "fees": {
      "affiliate": {
          "token_id": 4669,
          "fee": "100"
      }
  }
}

Response

Successful response

Name	Type	Required	Description
id	Number	Required	Quote id.
from	Object	Required	Base token information to receive a quote.
from.network_id	Number	Optional	Part of the from object.
from.contract_address	String	Optional	Part of the from object.
from.token_id	Number	Optional	Part of the from object.
from.address	String	Optional	Part of the from object. Sender address.
from.amount	Decimals in string	Required	Part of the from object. Amount to swap.
from.decimals	Number	Required	Part of the from object.
to	Object	Required	Quote token information for receiving quote.
to.network_id	Number	Optional	Part of the to object.
to.contract_address	String	Optional	Part of the to object.
to.token_id	Number	Optional	Part of the to object.
to.min_amount	Decimals in string	Required	Part of the to object. Minimal quote amount expressed in basis points.
to.amount	Decimals in string	Required	Part of the to object. Maximum quote amount expressed in basis points.
to.decimals	Number	Optional	Part of the to object.
slippage_bps	String	Optional	Slippage expressed in basis points.
expires_at	Timestamp	Optional	Quote expiration time. After this timestamp, the quote is no longer valid and must be refreshed. Quotes should always be executed before expiry to guarantee pricing.
fees	Object	Required	Applied fees for current quote.
fees.changelly	Object	Optional	Part of the fees object. Changelly fee information.
fees.changelly.network_id	Number	Optional	Part of the fees.changelly object. Network relation.
fees.changelly.contract_address	String	Optional	Part of the fees.changelly object. Token contract address.
fees.changelly.token_id	Number	Optional	Part of the fees.changelly object. Token ID.
fees.changelly.decimals	Number	Optional	Part of the fees.changelly object. Token decimals to adjust amount.
fees.changelly.amount	Decimals in string	Optional	Part of the fees.changelly object. Changelly fee amount.
fees.changelly.bps	String	Optional	Part of the fees.changelly object. Amount of basis points.
fees.affiliate	Object	Optional	Part of the fees object. Affiliate fee information.
fees.affiliate.network_id	Number	Optional	Part of the fees.affiliate object. Network relation.
fees.affiliate.contract_address	String	Optional	Part of the fees.affiliate object. Affiliate token contract address.
fees.affiliate.token_id	Number	Optional	Part of the fees.affiliate object. Affiliate token ID.
fees.affiliate.decimals	Number	Optional	Part of the fees.affiliate object. Affiliate token decimals to adjust amount.
fees.affiliate.amount	Decimals in string	Optional	Part of the fees.affiliate object. Affiliate fee amount.
fees.affiliate.bps	String	Optional	Part of the fees.affiliate object. Affiliate amount of basis points.
approval_type	String	Optional	The approval mechanism required for the intent. Supported values: htlc, cosign, or permit2.
approve_to	String	Optional	Address of the smart contract to which token allowance must be granted before executing the swap.
requires_wrap	Bool	Optional	Indicates whether the source native token must be wrapped before initiating the swap or intent execution.

Sample response

application/json

{
  "id": "7573f623-d4e8-484c-8119-693161bf51f6",
  "from": {
      "network_id": 3,
      "token_id": 278,
      "contract_address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
      "amount": "100000000",
      "decimals": 6
  },
  "to": {
      "network_id": 3,
      "token_id": 4,
      "contract_address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
      "amount": "51520895861721835",
      "decimals": 18,
      "min_amount": "51005686903104616"
  },
  "slippage_bps": "100",
  "expires_at": 1786077376,
  "fees": {
      "changelly": {
          "decimals": 18,
          "amount": "526200855939373",
          "bps": "100",
          "network_id": 3,
          "contract_address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
          "token_id": 4669
      },
      "affiliate": {
          "decimals": 18,
          "amount": "526200855939373",
          "bps": "100",
          "network_id": 3,
          "contract_address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
          "token_id": 4669
      }
  },
  "approval_type": "htlc",
  "approve_to": null,
  "requires_wrap": true
}

Error response

Check the error response schema.

Error codes

Error code	Error type	Error description
400	bad_request_error	Invalid body parameters.
400	unprocessable_entity_error	Slippage value cannot be processed.
401	authentication_error	Authentication error.
404	http_error	Incorrect HTTP request.
422	unprocessable_entity_error	Configuration error.
422	unprocessable_entity_error	Invalid amount.
422	unprocessable_entity_error	Network or token could not be processed.
422	unprocessable_entity_error	Only wrapped tokens can be used as source.
422	unprocessable_entity_error	Quotes not available.
422	unprocessable_entity_error	Requested pair could not be processed.
422	unprocessable_entity_error	Swap amount is too large.
422	unprocessable_entity_error	Swap amount is too small.
500	internal_error	Internal configuration error.

400

Sample error response with the unprocessable_entity_error type

{
  "code": 400,
  "type": "creation_error",
  "message": "Slippage value cannot be processed"
}

Sample error response with the bad_request_error type

{
  "code": 400,
  "type": "bad_request_error",
  "message": "body.from.QuoteDirectionByTokenId.token_id must be an integer"
}

401

{
  "code": 401,
  "type": "authentication_error",
  "message": "Authentication error"
}

404

{
  "code": 404,
  "type": "http_error",
  "message": "HTTP error"
}

422

{
  "code": 422,
  "type": "unprocessable_entity_error",
  "message": "Configuration error"
}

500

{
  "code": 500,
  "type": "internal_error",
  "message": "Internal configuration error"
}

---