Skip to main content
Version: 1.0

GET /tx-relay/v1/swap/price

Indicative pricing can be obtained by submitting a GET request to /tx-relay/v1/swap/price. This endpoint should be used when the end-user does not necessarily want to trade, as it can handle more traffic than the other endpoints.

Request​

Example Request​

info

An API key should always be specified when requesting any Gasless API endpoint. API keys are specified via a header parameter called 0x-api-key. Chain ids are specified via a header parameter called 0x-chain-id which currently supports 1 (Ethereum), 137 (Polygon), 42161 (Arbitrum), 8453 (Base) and 10 (Optimism).

info

sellToken, buyToken, takerAddress and one of [sellAmount ,buyAmount] must be present

curl 'https://api.0x.org/tx-relay/v1/swap/price?buyToken=0x0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270&sellAmount=100000000&sellToken=0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174&takerAddress=<TAKER_ADDRESS>&priceImpactProtectionPercentage=0.95&feeType=volume&feeSellTokenPercentage=0.01&feeRecipient=<FEE_RECIPIENT_ADDRESS>' \
--header '0x-api-key: <API_KEY>' \
--header '0x-chain-id: 137'

Request Params​

Query ParamDescription
buyTokenThe contract address of the token being bought. Use 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee for native token.
sellTokenThe contract address of token being sold. On Ethereum mainnet, it is restricted to the list of tokens here (Set 0x-chain-id to 1).
buyAmountThe amount of buyToken to buy. Can only be present if sellAmount is not present.
sellAmountThe amount of sellToken to sell. Can only be present if buyAmount is not present.
takerAddressThe address of the taker.
acceptedTypes[optional] Comma delimited string of the types of order the caller is willing to receive.

Currently, metatransaction_v2 and otc are supported and allowed. More details about order types are covered in /quote documentation.

This is useful if the caller only wants to receive types the caller specifies. If not provided, it means the caller accepts any types whose default value is currently set to metatransaction_v2 and otc.
slippagePercentage[optional] The maximum amount of slippage acceptable to the user; any slippage beyond that specified will cause the transaction to revert on chain. Default is 1% and minimal value allowed is 0.1%. The value of the field is on scale of 1. For example, setting slippagePercentage to set to 0.01 means 1% slippage allowed.
priceImpactProtectionPercentage[optional] The maximum amount of price impact acceptable to the user; Any price impact beyond that specified will cause the endpoint to return error if the endpoint is able to calculate the price impact. The value of the field is on scale of 1. For example, setting priceImpactProtectionPercentage to set to 0.01 means 1% price impact allowed.

This is an opt-in feature, the default value of 1.0 will disable the feature. When it is set to 1.0 (100%) it means that every transaction is allowed to pass.

Price impact calculation includes fees and could be unavailable. Read more about price impact at 0x documentation.
feeType[optional] The type of integrator fee to charge. The allowed value is volume.

Currently, the endpoint does not support integrator fees if the order type otc is chosen due to better pricing. Callers can opt-out of otc by explicitly passing in acceptedTypes query param without otc. otc order would, however, potentially improve the pricing the endpoint returned as there are more sources for liquidity.
feeRecipient[optional] The address the integrator fee would be transferred to. This is the address you’d like to receive the fee. This must be present if feeType is provided
feeSellTokenPercentage[optional] If feeType is volume, then feeSellTokenPercentage must be provided. feeSellTokenPercentage is the percentage (on scale of 1) of sellToken integrator charges as fee. For example, setting it to 0.01 means 1% of the sellToken would be charged as fee for the integrator.

Response​

Response Params​

Query ParamsDescription
liquidityAvailableValidates that liquidity is available. This would always been present.
The rest of the fields would only be present if liquidityAvailable is true
priceIf buyAmount was specified in the request, this parameter provide the price of buyToken, denominated in sellToken, or vice-versa.
Note fees are baked in the price calculation.
grossPriceSimilar to price but with fees removed in the price calculation. This is the price as if no fee is charged.
estimatedPriceImpactThe estimated change in the price of the specified asset that would be caused by the executed swap due to price impact.
Note that if the API is not able to estimate price change, the field will be null.
For otc order type, price impact is not available currently. More details about order types are covered in /quote documentation.
grossEstimatedPriceImpactSimilar to estimatedPriceImpact but with fees removed. This is the estimatedPriceImpact as if no fee is charged.
buyTokenAddressThe ERC20 token address of the token you want to receive in quote.
buyAmountThe amount of buyToken to buy with fees baked in.
grossBuyAmountSimilar to buyAmount but with fees removed. This is the buyAmount as if no fee is charged.
sellTokenAddressThe ERC20 token address of the token you want to sell with quote.
sellAmountThe amount of sellToken to sell with fees baked in.
grossSellAmountSimilar to sellAmount but with fees removed. This is the sellAmount as if no fee is charged.
allowanceTargetThe target contract address for which the user needs to have an allowance in order to be able to complete the swap.
sourcesThe underlying sources for the liquidity. The format will be:
[{ name: string; proportion: string }]
An example: [{"name": "Uniswap_V2", "proportion": "0.87"}, {"name": "Balancer", "proportion": "0.13"}]
fees[optional] Fees that would be charged. It can optionally contain integratorFee, zeroExFee and gasFee. See details about each fee type below.
integratorFeeRelated to fees param above.

Integrator fee (in amount of sellToken) would be provided if feeType and the corresponding query params are provided in the request:
  - feeType: The type of the integrator fee. This is always the same as the feeType in the request. It can only be volume currently.
  - feeToken: The ERC20 token address to charge fee. This is always the same as sellToken in the request.
  - feeAmount: The amount of feeToken to be charged as integrator fee.
  - billingType: The method that integrator fee is transferred. It can only be on-chain which means integrator fee can only be transferred on-chain to feeRecipient query param provided.

The endpoint currently does not support integrator fees if the order type otc is chosen due to better pricing. Callers can opt-out of otc by explicitly passing in acceptedTypes query param without otc. otc order would, however, potentially improve the pricing the endpoint returned as there are more sources for liquidity.
zeroExFeeRelated to fees param above.

Fee that 0x charges:
  - feeType: volume or integrator_share which varies per integrator. volume means 0x would charge a certain percentage of the trade independently. integrator_share means 0x would change a certain percentage of what the integrator charges.
  - feeToken: The ERC20 token address to charge fee. The token could be either sellToken or buyToken.
  - feeAmount: The amount of feeToken to be charged as 0x fee.
  - billingType: The method that 0x fee is transferred. It can be either on-chain, off-chain or liquidity which varies per integrator. on-chain means the fee would be charged on-chain. off-chain means the fee would be charged to the integrator via off-chain payment. liquidity means the fee would be charged off-chain but not to the integrator.

Please reach out to us if you'd like more details on the feeType and billingType.
gasFeeRelated to fees. See param above.

Gas fee to compensate for the transaction submission performed by our relayers:
  - feeType: The value is always gas.
  - feeToken: The ERC20 token address to charge gas fee. The token could be either sellToken or buyToken.
  - feeAmount: The amount of feeToken to be charged as gas fee.
  - billingType: The method that gas compensation is transferred. It can be either on-chain, off-chain or liquidity which has the same meaning as described above in zeroExFee section.

Please reach out to us if you'd like more details on the billingType.

Example Responses​

Liquidity Unavailable Response​

{
    "liquidityAvailable": false
}

Response if liquidity is available (feeToken is sellToken)​

{
    "liquidityAvailable": true,
    "buyAmount": "99887369",
    "buyTokenAddress": "0xc2132d05d31c914a87c6611c10748aeb04b58e8f",
    "estimatedPriceImpact": "0",
    "price": "0.998873",
    "sellAmount": "100000000",
    "sellTokenAddress": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
    "grossBuyAmount": "100005950",
    "grossSellAmount": "100000000",
    "grossPrice": "1.000059",
    "grossEstimatedPriceImpact": "0",
    "sources": [
        {
            "name": "DODO",
            "proportion": "1"
        }
    ],
    "fees": {
        "zeroExFee": {
            "feeType": "volume",
            "feeToken": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
            "feeAmount": "100000",
            "billingType": "on-chain"
        },
        "gasFee": {
            "feeType": "gas",
            "feeToken": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
            "feeAmount": "18574",
            "billingType": "on-chain"
        }
    },
    "allowanceTarget": "0xdef1c0ded9bec7f1a1670819833240f027b25eff"
}

Response if liquidity is available (feeToken is buyToken)​

{
    "liquidityAvailable": true,
    "price": "0.9989278",
    "buyAmount": "99892788",
    "buyTokenAddress": "0xc2132d05d31c914a87c6611c10748aeb04b58e8f",
    "sellAmount": "100000000",
    "sellTokenAddress": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
    "allowanceTarget": "0xdef1c0ded9bec7f1a1670819833240f027b25eff",
    "grossBuyAmount": "99999998",
    "grossSellAmount": "100000000",
    "grossPrice": "0.9999999",
    "estimatedPriceImpact": null,
    "grossEstimatedPriceImpact": null,
    "sources": [
        {
            "name": "0x",
            "proportion": "1"
        }
    ],
    "fees": {
        "zeroExFee": {
            "feeType": "volume",
            "feeToken": "0xc2132d05d31c914a87c6611c10748aeb04b58e8f",
            "feeAmount": "100108",
            "billingType": "liquidity"
        },
        "gasFee": {
            "feeType": "gas",
            "feeToken": "0xc2132d05d31c914a87c6611c10748aeb04b58e8f",
            "feeAmount": "7102",
            "billingType": "liquidity"
        }
    }
}

Status Codes​

  • 200 if successful.
  • 400:
    • If sellAmount / buyAmount provided is too small to execute or cover the cost.
    • If the actual price impact exceeds priceImpactProtectionPercentage supplied in the query param when the API is able to calculate price impact. The endpoint would not return 400 when it's not able to calculate price impact even though priceImpactProtectionPercentage is supplied.
    • If the query params are not able to pass validation.
  • 500 if there is an internal server error.