API Issues

To help provide developers a smooth build experience, 0x API v2 will do as much validation as it can and report all issues it finds in the issues object in the API reponse.

This object returns a list of potential validation issues detected with the quote. In rare cases where we are unable to validate the quote, we’ll return true in issues.simulationIncomplete. We strongly encourage using this object to provide the best experience for your users.

// Sample response from /swap/permit2/quote highlighting the issues object
...
"issues":{
   "allowance":{
      "actual":"0",
      "spender":"0x000000000022d473030f116ddee9f6b43ac78ba3"
   },
   "balance":{
      "token":"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "actual":"0",
      "expected":"100000000"
   },
   "simulationIncomplete":false,
   "invalidSourcesPassed": [ ]
},
...

Issues Types

Today, there are 4 types of issues that can be returned for /price and /quote in API v2

• allowance: When the taker does not have sufficient allowance to the target contract, this returns the details required for the swap to execute. Otherwise, it will be set as null.
• balance : When the taker does not have sufficient balance of the sell token, this returns the details required for the swap to execute. Otherwise, it will be set as null.
• simulationIncomplete : Set to true when 0x cannot validate the transaction. This happens when the taker has an insufficient balance of the sellToken and 0x is unable to peform ehanced quote validation with the low balance. Note that this does not necessarily mean that the trade will revert.
• invalidSourcesPassed: a list of invalid sources present in excludedSources
  • Valid list of source names will be available in GET /sources

Below is a screenshot summarizing the API issues. See the latest details in response sections of the API references:

Guidance on Using the Issues Object

Note the following about the issues object for Price and Quote:

• Price

  • allowance: If this field is not null, prompt the user to set the allowance.
  • balance: If this field is not null, do not proceed to get a quote.
  • simulationIncomplete: This field can be ignored for price since when calling price means aren't close to submitting a transaction (versus calling quote). Typically simulationIncomplete: true won't occur if the taker address is set and the taker has a sufficient balance of the sell token.

• Quote

  • allowance: This field should not appear if the quote is sent after the token allowance is set.
  • balance: This field will not be returned if the taker has sufficient balance when the quote request is sent.
  • simulationIncomplete: true: This field will not be returned if the taker has sufficient balance when the quote request is sent.