diff --git a/fern/openapi.json b/fern/openapi.json index ead35f80..02af9117 100644 --- a/fern/openapi.json +++ b/fern/openapi.json @@ -65,11 +65,18 @@ { "name": "sellAmount", "in": "query", - "required": true, + "required": false, "schema": { "type": "string" }, "description": "The amount of `sellToken` in `sellToken` base units to sell", "example": "100000000" }, + { + "name": "buyAmount", + "in": "query", + "required": false, + "schema": { "type": "string" }, + "description": "The exact amount of `buyToken` in `buyToken` base units to buy" + }, { "name": "taker", "in": "query", @@ -196,491 +203,1082 @@ "schema": { "anyOf": [ { - "type": "object", - "properties": { - "allowanceTarget": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "nullable": true, - "description": "The target contract address for which the `taker` needs to have an allowance in order to be able to complete the swap. For swaps with the native asset (ie \"ETH\" or \"BNB\") as the `sellToken`, wrapping the native asset (i.e. \"ETH\" to \"WETH\") or unwrapping, no allowance is needed" - }, - "blockNumber": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" - } - ], - "description": "The block number at which the liquidity sources were sampled to generate the quote. This indicates the freshness of the quote" - }, - "buyAmount": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" - } - ], - "description": "The amount of `buyToken` (in `buyToken` units) that will be bought in the swap" - }, - "buyToken": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The contract address of the token to buy in the swap" - }, - "fees": { + "anyOf": [ + { "type": "object", "properties": { - "integratorFee": { + "allowanceTarget": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "nullable": true, + "description": "The target contract address for which the `taker` needs to have an allowance in order to be able to complete the swap. For swaps with the native asset (ie \"ETH\" or \"BNB\") as the `sellToken`, wrapping the native asset (i.e. \"ETH\" to \"WETH\") or unwrapping, no allowance is needed" + }, + "blockNumber": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The block number at which the liquidity sources were sampled to generate the quote. This indicates the freshness of the quote" + }, + "buyAmount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of `buyToken` (in `buyToken` units) that will be bought in the swap" + }, + "buyToken": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the token to buy in the swap" + }, + "fees": { "type": "object", "properties": { - "amount": { - "allOf": [ - {}, - { + "integratorFee": { + "type": "object", + "properties": { + "amount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of token charged as the integrator fee" + }, + "token": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the token charged as the integrator fee" + }, + "type": { + "type": "string", + "enum": ["volume"] } - ], - "description": "The amount of token charged as the integrator fee" - }, - "token": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The address of the token charged as the integrator fee" + }, + "required": ["amount", "token", "type"], + "additionalProperties": false, + "nullable": true, + "description": "The specified fee to charge and deliver to the `swapFeeRecipient`." }, - "type": { "type": "string", "enum": ["volume"] } - }, - "required": ["amount", "token", "type"], - "additionalProperties": false, - "nullable": true, - "description": "The specified fee to charge and deliver to the `swapFeeRecipient`." - }, - "integratorFees": { - "type": "array", - "items": { - "type": "object", - "properties": { - "amount": { - "allOf": [ - {}, - { + "integratorFees": { + "type": "array", + "items": { + "type": "object", + "properties": { + "amount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of token charged as the integrator fee" + }, + "token": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the token charged as the integrator fee" + }, + "type": { + "type": "string", + "enum": ["volume"] } - ], - "description": "The amount of token charged as the integrator fee" - }, - "token": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The address of the token charged as the integrator fee" + }, + "required": ["amount", "token", "type"], + "additionalProperties": false }, - "type": { - "type": "string", - "enum": ["volume"] - } + "nullable": true, + "description": "The specified fees to charge and deliver to the `swapFeesRecipient`." }, - "required": ["amount", "token", "type"], - "additionalProperties": false - }, - "nullable": true, - "description": "The specified fees to charge and deliver to the `swapFeesRecipient`." - }, - "zeroExFee": { - "type": "object", - "properties": { - "amount": { - "allOf": [ - {}, - { + "zeroExFee": { + "type": "object", + "properties": { + "amount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of token charged as the 0x fee" + }, + "token": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the token charged as the 0x fee" + }, + "type": { + "type": "string", + "enum": ["volume"] } - ], - "description": "The amount of token charged as the 0x fee" - }, - "token": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The address of the token charged as the 0x fee" + }, + "required": ["amount", "token", "type"], + "additionalProperties": false, + "nullable": true, + "description": "The fee charged by 0x for the trade." }, - "type": { "type": "string", "enum": ["volume"] } + "gasFee": { + "type": "object", + "properties": { + "amount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of token charged as the gas fee" + }, + "token": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the token charged as the gas fee" + }, + "type": { + "type": "string", + "enum": ["gas"] + } + }, + "required": ["amount", "token", "type"], + "additionalProperties": false, + "nullable": true, + "description": "The gas fee to be used in submitting the transaction." + } }, - "required": ["amount", "token", "type"], + "required": [ + "integratorFee", + "integratorFees", + "zeroExFee", + "gasFee" + ], "additionalProperties": false, - "nullable": true, - "description": "The fee charged by 0x for the trade." + "description": "Fees to be deducted in this transaction. It contains the `integratorFee`, `zeroExFee` and `gasFee`" }, - "gasFee": { + "issues": { "type": "object", "properties": { - "amount": { - "allOf": [ - {}, - { + "allowance": { + "type": "object", + "properties": { + "actual": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The `taker`'s current allowance of the `spender`" + }, + "spender": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address to set the allowance on" } - ], - "description": "The amount of token charged as the gas fee" - }, - "token": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The address of the token charged as the gas fee" + }, + "required": ["actual", "spender"], + "additionalProperties": false, + "description": "Details of allowances that the `taker` must set for in order to execute the swap successfully. Null if no allowance is required", + "nullable": true }, - "type": { "type": "string", "enum": ["gas"] } - }, - "required": ["amount", "token", "type"], - "additionalProperties": false, - "nullable": true, - "description": "The gas fee to be used in submitting the transaction." - } - }, - "required": [ - "integratorFee", - "integratorFees", - "zeroExFee", - "gasFee" - ], - "additionalProperties": false, - "description": "Fees to be deducted in this transaction. It contains the `integratorFee`, `zeroExFee` and `gasFee`" - }, - "gas": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" - } - ], - "nullable": true, - "description": "The estimated gas limit that should be used to send the transaction to guarantee settlement" - }, - "gasPrice": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" - } - ], - "description": "The gas price (in wei) that should be used to send the transaction. The transaction needs to be sent with this `gasPrice` for the transaction to be successful" - }, - "issues": { - "type": "object", - "properties": { - "allowance": { - "type": "object", - "properties": { - "actual": { - "allOf": [ - {}, - { + "balance": { + "type": "object", + "properties": { + "token": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the `sellToken`" + }, + "actual": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The current balance of the `sellToken` in the `taker` address" + }, + "expected": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The balance of the `sellToken` required for the swap to execute successfully" } - ], - "description": "The `taker`'s current allowance of the `spender`" + }, + "required": ["token", "actual", "expected"], + "additionalProperties": false, + "description": "Details of balance of the `sellToken` that the `taker` must hold. Null if the `taker` has sufficient balance", + "nullable": true }, - "spender": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The address to set the allowance on" + "simulationIncomplete": { + "type": "boolean", + "description": "This is 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": { + "type": "array", + "items": { "type": "string" }, + "description": "A list of invalid sources present in `excludedSources` request. See `https://api.0x.org/sources?chainId=` with the desired chain's ID for the list of valid sources" } }, - "required": ["actual", "spender"], + "required": [ + "allowance", + "balance", + "simulationIncomplete", + "invalidSourcesPassed" + ], "additionalProperties": false, - "description": "Details of allowances that the `taker` must set for in order to execute the swap successfully. Null if no allowance is required", - "nullable": true + "description": "An object containing potential issues discovered during 0x validation that can prevent the swap from being executed successfully by the `taker`" }, - "balance": { - "type": "object", - "properties": { - "token": { + "liquidityAvailable": { + "type": "boolean", + "enum": [true], + "description": "This validates the availability of liquidity for the quote requested. The rest of the fields will only be returned if `true`" + }, + "minBuyAmount": { + "allOf": [ + {}, + { "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The contract address of the `sellToken`" + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The price which must be met or else the entire transaction will revert. This price is influenced by the `slippageBps` parameter. On-chain sources may encounter price movements from quote to settlement" + }, + "mode": { "type": "string", "enum": ["exact-in"] }, + "route": { + "type": "object", + "properties": { + "fills": { + "type": "array", + "items": { + "type": "object", + "properties": { + "from": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the input token" + }, + "to": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the output token" + }, + "source": { + "type": "string", + "description": "The liquidity source used in the route" + }, + "proportionBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The proportion of the trade to be filled by the `source`" + } + }, + "required": [ + "from", + "to", + "source", + "proportionBps" + ], + "additionalProperties": false + }, + "description": "Details of each segment that 0x routes the swap through" }, - "actual": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "tokens": { + "type": "array", + "items": { + "type": "object", + "properties": { + "address": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The token address. This is the unique identifier of the token" + }, + "symbol": { + "type": "string", + "description": "The token symbol. This is not guaranteed to be unique, as multiple tokens can have the same symbol" + } + }, + "required": ["address", "symbol"], + "additionalProperties": false, + "description": "Properties of the tokens involved in the swap" + }, + "description": "Properties of the tokens involved in the swap" + } + }, + "required": ["fills", "tokens"], + "additionalProperties": false, + "description": "The path of liquidity sources to be used in executing this swap" + }, + "sellAmount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of `sellToken` (in `sellToken` units) that will be sold in this swap" + }, + "sellToken": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the token to sell in the swap" + }, + "tokenMetadata": { + "type": "object", + "properties": { + "buyToken": { + "type": "object", + "properties": { + "buyTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The buy tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "sellTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The sell tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "transferTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The transfer tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" } + }, + "required": [ + "buyTaxBps", + "sellTaxBps", + "transferTaxBps" ], - "description": "The current balance of the `sellToken` in the `taker` address" + "additionalProperties": false, + "description": "Swap-related metadata for the buy token" }, - "expected": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "sellToken": { + "type": "object", + "properties": { + "buyTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The buy tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "sellTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The sell tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "transferTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The transfer tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" } + }, + "required": [ + "buyTaxBps", + "sellTaxBps", + "transferTaxBps" ], - "description": "The balance of the `sellToken` required for the swap to execute successfully" + "additionalProperties": false, + "description": "Swap-related metadata for the sell token" } }, - "required": ["token", "actual", "expected"], + "required": ["buyToken", "sellToken"], "additionalProperties": false, - "description": "Details of balance of the `sellToken` that the `taker` must hold. Null if the `taker` has sufficient balance", - "nullable": true + "description": "Swap-related metadata for the buy and sell token in the swap" }, - "simulationIncomplete": { - "type": "boolean", - "description": "This is 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" + "totalNetworkFee": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The estimated total network cost of the swap. On chains where there is no L1 data cost, it is calculated as `gas` * `gasPrice`. On chains where there is an L1 data cost, it is calculated as `gas` * `gasPrice` + L1 data cost." }, - "invalidSourcesPassed": { - "type": "array", - "items": { "type": "string" }, - "description": "A list of invalid sources present in `excludedSources` request. See `https://api.0x.org/sources?chainId=` with the desired chain's ID for the list of valid sources" - } - }, - "required": [ - "allowance", - "balance", - "simulationIncomplete", - "invalidSourcesPassed" - ], - "additionalProperties": false, - "description": "An object containing potential issues discovered during 0x validation that can prevent the swap from being executed successfully by the `taker`" - }, - "liquidityAvailable": { - "type": "boolean", - "enum": [true], - "description": "This validates the availability of liquidity for the quote requested. The rest of the fields will only be returned if `true`" - }, - "minBuyAmount": { - "allOf": [ - {}, - { + "zid": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" - } - ], - "description": "The price which must be met or else the entire transaction will revert. This price is influenced by the `slippageBps` parameter. On-chain sources may encounter price movements from quote to settlement" - }, - "route": { - "type": "object", - "properties": { - "fills": { - "type": "array", - "items": { - "type": "object", - "properties": { - "from": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The contract address of the input token" - }, - "to": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The contract address of the output token" - }, - "source": { - "type": "string", - "description": "The liquidity source used in the route" - }, - "proportionBps": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" - } - ], - "description": "The proportion of the trade to be filled by the `source`" - } - }, - "required": [ - "from", - "to", - "source", - "proportionBps" - ], - "additionalProperties": false - }, - "description": "Details of each segment that 0x routes the swap through" + "description": "The unique ZeroEx identifier of the request" }, - "tokens": { - "type": "array", - "items": { - "type": "object", - "properties": { - "address": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The token address. This is the unique identifier of the token" - }, - "symbol": { - "type": "string", - "description": "The token symbol. This is not guaranteed to be unique, as multiple tokens can have the same symbol" - } - }, - "required": ["address", "symbol"], - "additionalProperties": false, - "description": "Properties of the tokens involved in the swap" - }, - "description": "Properties of the tokens involved in the swap" + "gas": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The estimated gas limit that should be used to send the transaction to guarantee settlement" + }, + "gasPrice": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The gas price (in wei) that should be used to send the transaction. The transaction needs to be sent with this `gasPrice` for the transaction to be successful" } }, - "required": ["fills", "tokens"], - "additionalProperties": false, - "description": "The path of liquidity sources to be used in executing this swap" - }, - "sellAmount": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" - } + "required": [ + "allowanceTarget", + "blockNumber", + "buyAmount", + "buyToken", + "fees", + "issues", + "liquidityAvailable", + "minBuyAmount", + "mode", + "route", + "sellAmount", + "sellToken", + "tokenMetadata", + "totalNetworkFee", + "zid", + "gas", + "gasPrice" ], - "description": "The amount of `sellToken` (in `sellToken` units) that will be sold in this swap" - }, - "sellToken": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The contract address of the token to sell in the swap" + "additionalProperties": false }, - "tokenMetadata": { + { "type": "object", "properties": { + "allowanceTarget": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "nullable": true, + "description": "The target contract address for which the `taker` needs to have an allowance in order to be able to complete the swap." + }, + "blockNumber": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The block number at which the liquidity sources were sampled to generate the quote. This indicates the freshness of the quote" + }, + "buyAmount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The exact amount of `buyToken` (in `buyToken` units) requested for the swap" + }, "buyToken": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the token to buy in the swap" + }, + "estimatedNetSellAmount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The estimated net amount of `sellToken` spent after any exact-out refund route executes" + }, + "fees": { "type": "object", "properties": { - "buyTaxBps": { - "allOf": [ - {}, - { + "integratorFee": { + "type": "object", + "properties": { + "amount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of token charged as the integrator fee" + }, + "token": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the token charged as the integrator fee" + }, + "type": { + "type": "string", + "enum": ["volume"] } - ], + }, + "required": ["amount", "token", "type"], + "additionalProperties": false, "nullable": true, - "description": "The buy tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + "description": "The specified fee to charge and deliver to the `swapFeeRecipient`." }, - "sellTaxBps": { - "allOf": [ - {}, - { + "integratorFees": { + "type": "array", + "items": { + "type": "object", + "properties": { + "amount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of token charged as the integrator fee" + }, + "token": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the token charged as the integrator fee" + }, + "type": { + "type": "string", + "enum": ["volume"] + } + }, + "required": ["amount", "token", "type"], + "additionalProperties": false + }, + "nullable": true, + "description": "The specified fees to charge and deliver to the `swapFeesRecipient`." + }, + "zeroExFee": { + "type": "object", + "properties": { + "amount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of token charged as the 0x fee" + }, + "token": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the token charged as the 0x fee" + }, + "type": { + "type": "string", + "enum": ["volume"] } - ], + }, + "required": ["amount", "token", "type"], + "additionalProperties": false, "nullable": true, - "description": "The sell tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + "description": "The fee charged by 0x for the trade." }, - "transferTaxBps": { - "allOf": [ - {}, - { + "gasFee": { + "type": "object", + "properties": { + "amount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of token charged as the gas fee" + }, + "token": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the token charged as the gas fee" + }, + "type": { + "type": "string", + "enum": ["gas"] } - ], + }, + "required": ["amount", "token", "type"], + "additionalProperties": false, "nullable": true, - "description": "The transfer tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + "description": "The gas fee to be used in submitting the transaction." } }, "required": [ - "buyTaxBps", - "sellTaxBps", - "transferTaxBps" + "integratorFee", + "integratorFees", + "zeroExFee", + "gasFee" ], "additionalProperties": false, - "description": "Swap-related metadata for the buy token" + "description": "Fees to be deducted in this transaction. Exact-out v1 does not support fees." }, - "sellToken": { + "issues": { "type": "object", "properties": { - "buyTaxBps": { - "allOf": [ - {}, - { + "allowance": { + "type": "object", + "properties": { + "actual": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The `taker`'s current allowance of the `spender`" + }, + "spender": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address to set the allowance on" } - ], - "nullable": true, - "description": "The buy tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "required": ["actual", "spender"], + "additionalProperties": false, + "description": "Details of allowances that the `taker` must set for in order to execute the swap successfully. Null if no allowance is required", + "nullable": true }, - "sellTaxBps": { - "allOf": [ - {}, - { + "balance": { + "type": "object", + "properties": { + "token": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the `sellToken`" + }, + "actual": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The current balance of the `sellToken` in the `taker` address" + }, + "expected": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The balance of the `sellToken` required for the swap to execute successfully" } - ], + }, + "required": ["token", "actual", "expected"], + "additionalProperties": false, + "description": "Details of balance of the `sellToken` that the `taker` must hold. Null if the `taker` has sufficient balance", + "nullable": true + }, + "simulationIncomplete": { + "type": "boolean", + "description": "This is 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": { + "type": "array", + "items": { "type": "string" }, + "description": "A list of invalid sources present in `excludedSources` request. See `https://api.0x.org/sources?chainId=` with the desired chain's ID for the list of valid sources" + } + }, + "required": [ + "allowance", + "balance", + "simulationIncomplete", + "invalidSourcesPassed" + ], + "additionalProperties": false, + "description": "An object containing potential issues discovered during 0x validation that can prevent the swap from being executed successfully by the `taker`" + }, + "liquidityAvailable": { + "type": "boolean", + "enum": [true], + "description": "This validates the availability of liquidity for the quote requested. The rest of the fields will only be returned if `true`" + }, + "mode": { "type": "string", "enum": ["exact-out"] }, + "routes": { + "type": "object", + "properties": { + "forward": { + "type": "object", + "properties": { + "fills": { + "type": "array", + "items": { + "type": "object", + "properties": { + "from": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the input token" + }, + "to": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the output token" + }, + "source": { + "type": "string", + "description": "The liquidity source used in the route" + }, + "proportionBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The proportion of the trade to be filled by the `source`" + } + }, + "required": [ + "from", + "to", + "source", + "proportionBps" + ], + "additionalProperties": false + }, + "description": "Details of each segment that 0x routes the swap through" + }, + "tokens": { + "type": "array", + "items": { + "type": "object", + "properties": { + "address": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The token address. This is the unique identifier of the token" + }, + "symbol": { + "type": "string", + "description": "The token symbol. This is not guaranteed to be unique, as multiple tokens can have the same symbol" + } + }, + "required": ["address", "symbol"], + "additionalProperties": false, + "description": "Properties of the tokens involved in the swap" + }, + "description": "Properties of the tokens involved in the swap" + } + }, + "required": ["fills", "tokens"], + "additionalProperties": false, + "description": "The forward route used to acquire at least the requested buy amount" + }, + "refund": { + "type": "object", + "properties": { + "fills": { + "type": "array", + "items": { + "type": "object", + "properties": { + "from": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the input token" + }, + "to": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the output token" + }, + "source": { + "type": "string", + "description": "The liquidity source used in the route" + }, + "proportionBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The proportion of the trade to be filled by the `source`" + } + }, + "required": [ + "from", + "to", + "source", + "proportionBps" + ], + "additionalProperties": false + }, + "description": "Details of each segment that 0x routes the swap through" + }, + "tokens": { + "type": "array", + "items": { + "type": "object", + "properties": { + "address": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The token address. This is the unique identifier of the token" + }, + "symbol": { + "type": "string", + "description": "The token symbol. This is not guaranteed to be unique, as multiple tokens can have the same symbol" + } + }, + "required": ["address", "symbol"], + "additionalProperties": false, + "description": "Properties of the tokens involved in the swap" + }, + "description": "Properties of the tokens involved in the swap" + } + }, + "required": ["fills", "tokens"], + "additionalProperties": false, "nullable": true, - "description": "The sell tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + "description": "The optional refund route used to convert buy-token surplus back to the sell token" + } + }, + "required": ["forward", "refund"], + "additionalProperties": false, + "description": "The exact-out forward and refund routes" + }, + "maxSellAmount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The maximum amount of `sellToken` that may be spent by the exact-out swap" + }, + "sellToken": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the token to sell in the swap" + }, + "tokenMetadata": { + "type": "object", + "properties": { + "buyToken": { + "type": "object", + "properties": { + "buyTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The buy tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "sellTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The sell tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "transferTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The transfer tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + } + }, + "required": [ + "buyTaxBps", + "sellTaxBps", + "transferTaxBps" + ], + "additionalProperties": false, + "description": "Swap-related metadata for the buy token" }, - "transferTaxBps": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "sellToken": { + "type": "object", + "properties": { + "buyTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The buy tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "sellTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The sell tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "transferTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The transfer tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" } + }, + "required": [ + "buyTaxBps", + "sellTaxBps", + "transferTaxBps" ], - "nullable": true, - "description": "The transfer tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + "additionalProperties": false, + "description": "Swap-related metadata for the sell token" + } + }, + "required": ["buyToken", "sellToken"], + "additionalProperties": false, + "description": "Swap-related metadata for the buy and sell token in the swap" + }, + "totalNetworkFee": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The estimated total network cost of the swap. On chains where there is no L1 data cost, it is calculated as `gas` * `gasPrice`. On chains where there is an L1 data cost, it is calculated as `gas` * `gasPrice` + L1 data cost." + }, + "zid": { + "type": "string", + "description": "The unique ZeroEx identifier of the request" + }, + "gas": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" } - }, - "required": [ - "buyTaxBps", - "sellTaxBps", - "transferTaxBps" ], - "additionalProperties": false, - "description": "Swap-related metadata for the sell token" + "nullable": true, + "description": "The estimated gas limit that should be used to send the transaction to guarantee settlement" + }, + "gasPrice": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The gas price (in wei) that should be used to send the transaction. The transaction needs to be sent with this `gasPrice` for the transaction to be successful" } }, - "required": ["buyToken", "sellToken"], - "additionalProperties": false, - "description": "Swap-related metadata for the buy and sell token in the swap" - }, - "totalNetworkFee": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" - } + "required": [ + "allowanceTarget", + "blockNumber", + "buyAmount", + "buyToken", + "estimatedNetSellAmount", + "fees", + "issues", + "liquidityAvailable", + "mode", + "routes", + "maxSellAmount", + "sellToken", + "tokenMetadata", + "totalNetworkFee", + "zid", + "gas", + "gasPrice" ], - "nullable": true, - "description": "The estimated total network cost of the swap. On chains where there is no L1 data cost, it is calculated as `gas` * `gasPrice`. On chains where there is an L1 data cost, it is calculated as `gas` * `gasPrice` + L1 data cost." - }, - "zid": { - "type": "string", - "description": "The unique ZeroEx identifier of the request" + "additionalProperties": false } - }, - "required": [ - "allowanceTarget", - "blockNumber", - "buyAmount", - "buyToken", - "fees", - "gas", - "gasPrice", - "issues", - "liquidityAvailable", - "minBuyAmount", - "route", - "sellAmount", - "sellToken", - "tokenMetadata", - "totalNetworkFee", - "zid" - ], - "additionalProperties": false + ] }, { "type": "object", @@ -726,6 +1324,7 @@ "invalidSourcesPassed": [] }, "liquidityAvailable": true, + "mode": "exact-in", "minBuyAmount": "99032421", "route": { "fills": [ @@ -884,11 +1483,18 @@ { "name": "sellAmount", "in": "query", - "required": true, + "required": false, "schema": { "type": "string" }, "description": "The amount of `sellToken` in `sellToken` base units to sell", "example": "100000000" }, + { + "name": "buyAmount", + "in": "query", + "required": false, + "schema": { "type": "string" }, + "description": "The exact amount of `buyToken` in `buyToken` base units to buy" + }, { "name": "taker", "in": "query", @@ -1015,388 +1621,475 @@ "schema": { "anyOf": [ { - "type": "object", - "properties": { - "allowanceTarget": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "nullable": true, - "description": "The target contract address for which the `taker` needs to have an allowance in order to be able to complete the swap. For swaps with the native asset (ie \"ETH\" or \"BNB\") as the `sellToken`, wrapping the native asset (i.e. \"ETH\" to \"WETH\") or unwrapping, no allowance is needed" - }, - "blockNumber": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" - } - ], - "description": "The block number at which the liquidity sources were sampled to generate the quote. This indicates the freshness of the quote" - }, - "buyAmount": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" - } - ], - "description": "The amount of `buyToken` (in `buyToken` units) that will be bought in the swap" - }, - "buyToken": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The contract address of the token to buy in the swap" - }, - "fees": { + "anyOf": [ + { "type": "object", "properties": { - "integratorFee": { + "allowanceTarget": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "nullable": true, + "description": "The target contract address for which the `taker` needs to have an allowance in order to be able to complete the swap. For swaps with the native asset (ie \"ETH\" or \"BNB\") as the `sellToken`, wrapping the native asset (i.e. \"ETH\" to \"WETH\") or unwrapping, no allowance is needed" + }, + "blockNumber": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The block number at which the liquidity sources were sampled to generate the quote. This indicates the freshness of the quote" + }, + "buyAmount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of `buyToken` (in `buyToken` units) that will be bought in the swap" + }, + "buyToken": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the token to buy in the swap" + }, + "fees": { "type": "object", "properties": { - "amount": { - "allOf": [ - {}, - { + "integratorFee": { + "type": "object", + "properties": { + "amount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of token charged as the integrator fee" + }, + "token": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the token charged as the integrator fee" + }, + "type": { + "type": "string", + "enum": ["volume"] } - ], - "description": "The amount of token charged as the integrator fee" - }, - "token": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The address of the token charged as the integrator fee" + }, + "required": ["amount", "token", "type"], + "additionalProperties": false, + "nullable": true, + "description": "The specified fee to charge and deliver to the `swapFeeRecipient`." }, - "type": { "type": "string", "enum": ["volume"] } - }, - "required": ["amount", "token", "type"], - "additionalProperties": false, - "nullable": true, - "description": "The specified fee to charge and deliver to the `swapFeeRecipient`." - }, - "integratorFees": { - "type": "array", - "items": { - "type": "object", - "properties": { - "amount": { - "allOf": [ - {}, - { + "integratorFees": { + "type": "array", + "items": { + "type": "object", + "properties": { + "amount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of token charged as the integrator fee" + }, + "token": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the token charged as the integrator fee" + }, + "type": { + "type": "string", + "enum": ["volume"] } - ], - "description": "The amount of token charged as the integrator fee" - }, - "token": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The address of the token charged as the integrator fee" + }, + "required": ["amount", "token", "type"], + "additionalProperties": false }, - "type": { - "type": "string", - "enum": ["volume"] - } + "nullable": true, + "description": "The specified fees to charge and deliver to the `swapFeesRecipient`." }, - "required": ["amount", "token", "type"], - "additionalProperties": false - }, - "nullable": true, - "description": "The specified fees to charge and deliver to the `swapFeesRecipient`." - }, - "zeroExFee": { - "type": "object", - "properties": { - "amount": { - "allOf": [ - {}, - { + "zeroExFee": { + "type": "object", + "properties": { + "amount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of token charged as the 0x fee" + }, + "token": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" - } - ], - "description": "The amount of token charged as the 0x fee" - }, - "token": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The address of the token charged as the 0x fee" - }, - "type": { "type": "string", "enum": ["volume"] } - }, - "required": ["amount", "token", "type"], - "additionalProperties": false, - "nullable": true, - "description": "The fee charged by 0x for the trade." - }, - "gasFee": { - "type": "object", - "properties": { - "amount": { - "allOf": [ - {}, - { + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the token charged as the 0x fee" + }, + "type": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "enum": ["volume"] } - ], - "description": "The amount of token charged as the gas fee" - }, - "token": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The address of the token charged as the gas fee" + }, + "required": ["amount", "token", "type"], + "additionalProperties": false, + "nullable": true, + "description": "The fee charged by 0x for the trade." }, - "type": { "type": "string", "enum": ["gas"] } - }, - "required": ["amount", "token", "type"], - "additionalProperties": false, - "nullable": true, - "description": "The gas fee to be used in submitting the transaction." - } - }, - "required": [ - "integratorFee", - "integratorFees", - "zeroExFee", - "gasFee" - ], - "additionalProperties": false - }, - "issues": { - "type": "object", - "properties": { - "allowance": { - "type": "object", - "properties": { - "actual": { - "allOf": [ - {}, - { + "gasFee": { + "type": "object", + "properties": { + "amount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of token charged as the gas fee" + }, + "token": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the token charged as the gas fee" + }, + "type": { + "type": "string", + "enum": ["gas"] } - ], - "description": "The `taker`'s current allowance of the `spender`" - }, - "spender": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The address to set the allowance on" + }, + "required": ["amount", "token", "type"], + "additionalProperties": false, + "nullable": true, + "description": "The gas fee to be used in submitting the transaction." } }, - "required": ["actual", "spender"], + "required": [ + "integratorFee", + "integratorFees", + "zeroExFee", + "gasFee" + ], "additionalProperties": false, - "description": "Details of allowances that the `taker` must set for in order to execute the swap successfully. Null if no allowance is required", - "nullable": true + "description": "Fees to be deducted in this transaction. It contains the `integratorFee`, `zeroExFee` and `gasFee`" }, - "balance": { + "issues": { "type": "object", "properties": { - "token": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The contract address of the `sellToken`" - }, - "actual": { - "allOf": [ - {}, - { + "allowance": { + "type": "object", + "properties": { + "actual": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The `taker`'s current allowance of the `spender`" + }, + "spender": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address to set the allowance on" } - ], - "description": "The current balance of the `sellToken` in the `taker` address" + }, + "required": ["actual", "spender"], + "additionalProperties": false, + "description": "Details of allowances that the `taker` must set for in order to execute the swap successfully. Null if no allowance is required", + "nullable": true }, - "expected": { - "allOf": [ - {}, - { + "balance": { + "type": "object", + "properties": { + "token": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the `sellToken`" + }, + "actual": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The current balance of the `sellToken` in the `taker` address" + }, + "expected": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The balance of the `sellToken` required for the swap to execute successfully" } - ], - "description": "The balance of the `sellToken` required for the swap to execute successfully" + }, + "required": ["token", "actual", "expected"], + "additionalProperties": false, + "description": "Details of balance of the `sellToken` that the `taker` must hold. Null if the `taker` has sufficient balance", + "nullable": true + }, + "simulationIncomplete": { + "type": "boolean", + "description": "This is 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": { + "type": "array", + "items": { "type": "string" }, + "description": "A list of invalid sources present in `excludedSources` request. See `https://api.0x.org/sources?chainId=` with the desired chain's ID for the list of valid sources" } }, - "required": ["token", "actual", "expected"], + "required": [ + "allowance", + "balance", + "simulationIncomplete", + "invalidSourcesPassed" + ], "additionalProperties": false, - "description": "Details of balance of the `sellToken` that the `taker` must hold. Null if the `taker` has sufficient balance", - "nullable": true + "description": "An object containing potential issues discovered during 0x validation that can prevent the swap from being executed successfully by the `taker`" }, - "simulationIncomplete": { + "liquidityAvailable": { "type": "boolean", - "description": "This is 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" + "enum": [true], + "description": "This validates the availability of liquidity for the quote requested. The rest of the fields will only be returned if `true`" }, - "invalidSourcesPassed": { - "type": "array", - "items": { "type": "string" }, - "description": "A list of invalid sources present in `excludedSources` request. See `https://api.0x.org/sources?chainId=` with the desired chain's ID for the list of valid sources" - } - }, - "required": [ - "allowance", - "balance", - "simulationIncomplete", - "invalidSourcesPassed" - ], - "additionalProperties": false, - "description": "An object containing potential issues discovered during 0x validation that can prevent the swap from being executed successfully by the `taker`" - }, - "liquidityAvailable": { - "type": "boolean", - "enum": [true], - "description": "This validates the availability of liquidity for the quote requested. The rest of the fields will only be returned if `true`" - }, - "minBuyAmount": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" - } - ], - "description": "The price which must be met or else the transaction will revert. This price is influenced by the `slippageBps` parameter. On-chain sources may encounter price movements from quote to settlement" - }, - "route": { - "type": "object", - "properties": { - "fills": { - "type": "array", - "items": { - "type": "object", - "properties": { - "from": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The contract address of the input token" - }, - "to": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The contract address of the output token" - }, - "source": { - "type": "string", - "description": "The liquidity source used in the route" - }, - "proportionBps": { - "allOf": [ - {}, - { + "minBuyAmount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The price which must be met or else the entire transaction will revert. This price is influenced by the `slippageBps` parameter. On-chain sources may encounter price movements from quote to settlement" + }, + "mode": { "type": "string", "enum": ["exact-in"] }, + "route": { + "type": "object", + "properties": { + "fills": { + "type": "array", + "items": { + "type": "object", + "properties": { + "from": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the input token" + }, + "to": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the output token" + }, + "source": { + "type": "string", + "description": "The liquidity source used in the route" + }, + "proportionBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The proportion of the trade to be filled by the `source`" } + }, + "required": [ + "from", + "to", + "source", + "proportionBps" ], - "description": "The proportion of the trade to be filled by the `source`" - } - }, - "required": [ - "from", - "to", - "source", - "proportionBps" - ], - "additionalProperties": false - }, - "description": "Details of each segment that 0x routes the swap through" - }, - "tokens": { - "type": "array", - "items": { - "type": "object", - "properties": { - "address": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The token address. This is the unique identifier of the token" + "additionalProperties": false }, - "symbol": { - "type": "string", - "description": "The token symbol. This is not guaranteed to be unique, as multiple tokens can have the same symbol" - } + "description": "Details of each segment that 0x routes the swap through" }, - "required": ["address", "symbol"], - "additionalProperties": false, - "description": "Properties of the tokens involved in the swap" + "tokens": { + "type": "array", + "items": { + "type": "object", + "properties": { + "address": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The token address. This is the unique identifier of the token" + }, + "symbol": { + "type": "string", + "description": "The token symbol. This is not guaranteed to be unique, as multiple tokens can have the same symbol" + } + }, + "required": ["address", "symbol"], + "additionalProperties": false, + "description": "Properties of the tokens involved in the swap" + }, + "description": "Properties of the tokens involved in the swap" + } }, - "description": "Properties of the tokens involved in the swap" - } - }, - "required": ["fills", "tokens"], - "additionalProperties": false, - "description": "The path of liquidity sources to be used in executing this swap" - }, - "sellAmount": { - "allOf": [ - {}, - { + "required": ["fills", "tokens"], + "additionalProperties": false, + "description": "The path of liquidity sources to be used in executing this swap" + }, + "sellAmount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of `sellToken` (in `sellToken` units) that will be sold in this swap" + }, + "sellToken": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" - } - ], - "description": "The amount of `sellToken` (in `sellToken` units) that will be sold in this swap" - }, - "sellToken": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The contract address of the token to sell in the swap" - }, - "tokenMetadata": { - "type": "object", - "properties": { - "buyToken": { + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the token to sell in the swap" + }, + "tokenMetadata": { "type": "object", "properties": { - "buyTaxBps": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" - } - ], - "nullable": true, - "description": "The buy tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" - }, - "sellTaxBps": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "buyToken": { + "type": "object", + "properties": { + "buyTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The buy tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "sellTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The sell tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "transferTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The transfer tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" } + }, + "required": [ + "buyTaxBps", + "sellTaxBps", + "transferTaxBps" ], - "nullable": true, - "description": "The sell tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + "additionalProperties": false, + "description": "Swap-related metadata for the buy token" }, - "transferTaxBps": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "sellToken": { + "type": "object", + "properties": { + "buyTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The buy tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "sellTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The sell tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "transferTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The transfer tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" } + }, + "required": [ + "buyTaxBps", + "sellTaxBps", + "transferTaxBps" ], - "nullable": true, - "description": "The transfer tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + "additionalProperties": false, + "description": "Swap-related metadata for the sell token" + } + }, + "required": ["buyToken", "sellToken"], + "additionalProperties": false, + "description": "Swap-related metadata for the buy and sell token in the swap" + }, + "totalNetworkFee": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" } - }, - "required": [ - "buyTaxBps", - "sellTaxBps", - "transferTaxBps" ], - "additionalProperties": false, - "description": "Swap-related metadata for the buy token" + "nullable": true, + "description": "The estimated total network cost of the swap. On chains where there is no L1 data cost, it is calculated as `gas` * `gasPrice`. On chains where there is an L1 data cost, it is calculated as `gas` * `gasPrice` + L1 data cost." }, - "sellToken": { + "zid": { + "type": "string", + "description": "The unique ZeroEx identifier of the request" + }, + "transaction": { "type": "object", "properties": { - "buyTaxBps": { + "to": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the target contract to send call `data` to. Do NOT use this field when setting token allowances — doing so can result in lost funds. Always use `issues.allowance.spender` or `allowanceTarget` for setting allowances." + }, + "data": { + "type": "string", + "description": "The calldata containing transaction execution details to be sent to the `to` address" + }, + "gas": { "allOf": [ {}, { @@ -1405,9 +2098,9 @@ } ], "nullable": true, - "description": "The buy tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + "description": "The estimated gas limit that should be used to send the transaction to guarantee settlement" }, - "sellTaxBps": { + "gasPrice": { "allOf": [ {}, { @@ -1415,10 +2108,9 @@ "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" } ], - "nullable": true, - "description": "The sell tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + "description": "The gas price (in wei) that should be used to send the transaction" }, - "transferTaxBps": { + "value": { "allOf": [ {}, { @@ -1426,47 +2118,75 @@ "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" } ], - "nullable": true, - "description": "The transfer tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + "description": "The amount of ether (in wei) that should be sent with the transaction" } }, "required": [ - "buyTaxBps", - "sellTaxBps", - "transferTaxBps" + "to", + "data", + "gas", + "gasPrice", + "value" ], "additionalProperties": false, - "description": "Swap-related metadata for the sell token" + "description": "This object contains the details required to submit the transaction" } }, - "required": ["buyToken", "sellToken"], - "additionalProperties": false, - "description": "Swap-related metadata for the buy and sell token in the swap" - }, - "totalNetworkFee": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" - } + "required": [ + "allowanceTarget", + "blockNumber", + "buyAmount", + "buyToken", + "fees", + "issues", + "liquidityAvailable", + "minBuyAmount", + "mode", + "route", + "sellAmount", + "sellToken", + "tokenMetadata", + "totalNetworkFee", + "zid", + "transaction" ], - "nullable": true, - "description": "The estimated total network cost of the swap. On chains where there is no L1 data cost, it is calculated as `gas` * `gasPrice`. On chains where there is an L1 data cost, it is calculated as `gas` * `gasPrice` + L1 data cost." + "additionalProperties": false }, - "transaction": { + { "type": "object", "properties": { - "to": { + "allowanceTarget": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The address of the target contract to send call `data` to. Do NOT use this field when setting token allowances — doing so can result in lost funds. Always use `issues.allowance.spender` or `allowanceTarget` for setting allowances." + "nullable": true, + "description": "The target contract address for which the `taker` needs to have an allowance in order to be able to complete the swap." + }, + "blockNumber": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The block number at which the liquidity sources were sampled to generate the quote. This indicates the freshness of the quote" + }, + "buyAmount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The exact amount of `buyToken` (in `buyToken` units) requested for the swap" }, - "data": { + "buyToken": { "type": "string", - "description": "The calldata containing transaction execution details to be sent to the `to` address" + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the token to buy in the swap" }, - "gas": { + "estimatedNetSellAmount": { "allOf": [ {}, { @@ -1474,10 +2194,370 @@ "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" } ], - "nullable": true, - "description": "The estimated gas limit that should be used to send the transaction to guarantee settlement" + "description": "The estimated net amount of `sellToken` spent after any exact-out refund route executes" }, - "gasPrice": { + "fees": { + "type": "object", + "properties": { + "integratorFee": { + "type": "object", + "properties": { + "amount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of token charged as the integrator fee" + }, + "token": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the token charged as the integrator fee" + }, + "type": { + "type": "string", + "enum": ["volume"] + } + }, + "required": ["amount", "token", "type"], + "additionalProperties": false, + "nullable": true, + "description": "The specified fee to charge and deliver to the `swapFeeRecipient`." + }, + "integratorFees": { + "type": "array", + "items": { + "type": "object", + "properties": { + "amount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of token charged as the integrator fee" + }, + "token": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the token charged as the integrator fee" + }, + "type": { + "type": "string", + "enum": ["volume"] + } + }, + "required": ["amount", "token", "type"], + "additionalProperties": false + }, + "nullable": true, + "description": "The specified fees to charge and deliver to the `swapFeesRecipient`." + }, + "zeroExFee": { + "type": "object", + "properties": { + "amount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of token charged as the 0x fee" + }, + "token": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the token charged as the 0x fee" + }, + "type": { + "type": "string", + "enum": ["volume"] + } + }, + "required": ["amount", "token", "type"], + "additionalProperties": false, + "nullable": true, + "description": "The fee charged by 0x for the trade." + }, + "gasFee": { + "type": "object", + "properties": { + "amount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of token charged as the gas fee" + }, + "token": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the token charged as the gas fee" + }, + "type": { + "type": "string", + "enum": ["gas"] + } + }, + "required": ["amount", "token", "type"], + "additionalProperties": false, + "nullable": true, + "description": "The gas fee to be used in submitting the transaction." + } + }, + "required": [ + "integratorFee", + "integratorFees", + "zeroExFee", + "gasFee" + ], + "additionalProperties": false, + "description": "Fees to be deducted in this transaction. Exact-out v1 does not support fees." + }, + "issues": { + "type": "object", + "properties": { + "allowance": { + "type": "object", + "properties": { + "actual": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The `taker`'s current allowance of the `spender`" + }, + "spender": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address to set the allowance on" + } + }, + "required": ["actual", "spender"], + "additionalProperties": false, + "description": "Details of allowances that the `taker` must set for in order to execute the swap successfully. Null if no allowance is required", + "nullable": true + }, + "balance": { + "type": "object", + "properties": { + "token": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the `sellToken`" + }, + "actual": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The current balance of the `sellToken` in the `taker` address" + }, + "expected": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The balance of the `sellToken` required for the swap to execute successfully" + } + }, + "required": ["token", "actual", "expected"], + "additionalProperties": false, + "description": "Details of balance of the `sellToken` that the `taker` must hold. Null if the `taker` has sufficient balance", + "nullable": true + }, + "simulationIncomplete": { + "type": "boolean", + "description": "This is 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": { + "type": "array", + "items": { "type": "string" }, + "description": "A list of invalid sources present in `excludedSources` request. See `https://api.0x.org/sources?chainId=` with the desired chain's ID for the list of valid sources" + } + }, + "required": [ + "allowance", + "balance", + "simulationIncomplete", + "invalidSourcesPassed" + ], + "additionalProperties": false, + "description": "An object containing potential issues discovered during 0x validation that can prevent the swap from being executed successfully by the `taker`" + }, + "liquidityAvailable": { + "type": "boolean", + "enum": [true], + "description": "This validates the availability of liquidity for the quote requested. The rest of the fields will only be returned if `true`" + }, + "mode": { "type": "string", "enum": ["exact-out"] }, + "routes": { + "type": "object", + "properties": { + "forward": { + "type": "object", + "properties": { + "fills": { + "type": "array", + "items": { + "type": "object", + "properties": { + "from": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the input token" + }, + "to": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the output token" + }, + "source": { + "type": "string", + "description": "The liquidity source used in the route" + }, + "proportionBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The proportion of the trade to be filled by the `source`" + } + }, + "required": [ + "from", + "to", + "source", + "proportionBps" + ], + "additionalProperties": false + }, + "description": "Details of each segment that 0x routes the swap through" + }, + "tokens": { + "type": "array", + "items": { + "type": "object", + "properties": { + "address": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The token address. This is the unique identifier of the token" + }, + "symbol": { + "type": "string", + "description": "The token symbol. This is not guaranteed to be unique, as multiple tokens can have the same symbol" + } + }, + "required": ["address", "symbol"], + "additionalProperties": false, + "description": "Properties of the tokens involved in the swap" + }, + "description": "Properties of the tokens involved in the swap" + } + }, + "required": ["fills", "tokens"], + "additionalProperties": false, + "description": "The forward route used to acquire at least the requested buy amount" + }, + "refund": { + "type": "object", + "properties": { + "fills": { + "type": "array", + "items": { + "type": "object", + "properties": { + "from": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the input token" + }, + "to": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the output token" + }, + "source": { + "type": "string", + "description": "The liquidity source used in the route" + }, + "proportionBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The proportion of the trade to be filled by the `source`" + } + }, + "required": [ + "from", + "to", + "source", + "proportionBps" + ], + "additionalProperties": false + }, + "description": "Details of each segment that 0x routes the swap through" + }, + "tokens": { + "type": "array", + "items": { + "type": "object", + "properties": { + "address": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The token address. This is the unique identifier of the token" + }, + "symbol": { + "type": "string", + "description": "The token symbol. This is not guaranteed to be unique, as multiple tokens can have the same symbol" + } + }, + "required": ["address", "symbol"], + "additionalProperties": false, + "description": "Properties of the tokens involved in the swap" + }, + "description": "Properties of the tokens involved in the swap" + } + }, + "required": ["fills", "tokens"], + "additionalProperties": false, + "nullable": true, + "description": "The optional refund route used to convert buy-token surplus back to the sell token" + } + }, + "required": ["forward", "refund"], + "additionalProperties": false, + "description": "The exact-out forward and refund routes" + }, + "maxSellAmount": { "allOf": [ {}, { @@ -1485,9 +2565,112 @@ "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" } ], - "description": "The gas price (in wei) that should be used to send the transaction" + "description": "The maximum amount of `sellToken` that may be spent by the exact-out swap" + }, + "sellToken": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the token to sell in the swap" + }, + "tokenMetadata": { + "type": "object", + "properties": { + "buyToken": { + "type": "object", + "properties": { + "buyTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The buy tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "sellTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The sell tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "transferTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The transfer tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + } + }, + "required": [ + "buyTaxBps", + "sellTaxBps", + "transferTaxBps" + ], + "additionalProperties": false, + "description": "Swap-related metadata for the buy token" + }, + "sellToken": { + "type": "object", + "properties": { + "buyTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The buy tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "sellTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The sell tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "transferTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The transfer tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + } + }, + "required": [ + "buyTaxBps", + "sellTaxBps", + "transferTaxBps" + ], + "additionalProperties": false, + "description": "Swap-related metadata for the sell token" + } + }, + "required": ["buyToken", "sellToken"], + "additionalProperties": false, + "description": "Swap-related metadata for the buy and sell token in the swap" }, - "value": { + "totalNetworkFee": { "allOf": [ {}, { @@ -1495,42 +2678,89 @@ "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" } ], - "description": "The amount of ether (in wei) that should be sent with the transaction" + "nullable": true, + "description": "The estimated total network cost of the swap. On chains where there is no L1 data cost, it is calculated as `gas` * `gasPrice`. On chains where there is an L1 data cost, it is calculated as `gas` * `gasPrice` + L1 data cost." + }, + "zid": { + "type": "string", + "description": "The unique ZeroEx identifier of the request" + }, + "transaction": { + "type": "object", + "properties": { + "to": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the target contract to send call `data` to. Do NOT use this field when setting token allowances — doing so can result in lost funds. Always use `issues.allowance.spender` or `allowanceTarget` for setting allowances." + }, + "data": { + "type": "string", + "description": "The calldata containing transaction execution details to be sent to the `to` address" + }, + "gas": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The estimated gas limit that should be used to send the transaction to guarantee settlement" + }, + "gasPrice": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The gas price (in wei) that should be used to send the transaction" + }, + "value": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of ether (in wei) that should be sent with the transaction" + } + }, + "required": [ + "to", + "data", + "gas", + "gasPrice", + "value" + ], + "additionalProperties": false, + "description": "This object contains the details required to submit the transaction" } }, - "required": [ - "to", - "data", - "gas", - "gasPrice", - "value" - ], - "additionalProperties": false, - "description": "This object contains the details required to submit the transaction" - }, - "zid": { - "type": "string", - "description": "The unique ZeroEx identifier of the request" - } - }, - "required": [ - "allowanceTarget", - "blockNumber", - "buyAmount", - "buyToken", - "fees", - "issues", - "liquidityAvailable", - "minBuyAmount", - "route", - "sellAmount", - "sellToken", - "tokenMetadata", - "totalNetworkFee", - "transaction", - "zid" - ], - "additionalProperties": false + "required": [ + "allowanceTarget", + "blockNumber", + "buyAmount", + "buyToken", + "estimatedNetSellAmount", + "fees", + "issues", + "liquidityAvailable", + "mode", + "routes", + "maxSellAmount", + "sellToken", + "tokenMetadata", + "totalNetworkFee", + "zid", + "transaction" + ], + "additionalProperties": false + } + ] }, { "type": "object", @@ -1574,6 +2804,7 @@ "invalidSourcesPassed": [] }, "liquidityAvailable": true, + "mode": "exact-in", "minBuyAmount": "99037162", "route": { "fills": [ @@ -1739,11 +2970,18 @@ { "name": "sellAmount", "in": "query", - "required": true, + "required": false, "schema": { "type": "string" }, "description": "The amount of `sellToken` in `sellToken` base units to sell", "example": "100000000" }, + { + "name": "buyAmount", + "in": "query", + "required": false, + "schema": { "type": "string" }, + "description": "The exact amount of `buyToken` in `buyToken` base units to buy" + }, { "name": "taker", "in": "query", @@ -1870,491 +3108,1082 @@ "schema": { "anyOf": [ { - "type": "object", - "properties": { - "allowanceTarget": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "nullable": true, - "description": "The target contract address for which the `taker` needs to have an allowance in order to be able to complete the swap. For swaps with the native asset (ie \"ETH\" or \"BNB\") as the `sellToken`, wrapping the native asset (i.e. \"ETH\" to \"WETH\") or unwrapping, no allowance is needed" - }, - "blockNumber": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" - } - ], - "description": "The block number at which the liquidity sources were sampled to generate the quote. This indicates the freshness of the quote" - }, - "buyAmount": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" - } - ], - "description": "The amount of `buyToken` (in `buyToken` units) that will be bought in the swap" - }, - "buyToken": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The contract address of the token to buy in the swap" - }, - "fees": { + "anyOf": [ + { "type": "object", "properties": { - "integratorFee": { + "allowanceTarget": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "nullable": true, + "description": "The target contract address for which the `taker` needs to have an allowance in order to be able to complete the swap. For swaps with the native asset (ie \"ETH\" or \"BNB\") as the `sellToken`, wrapping the native asset (i.e. \"ETH\" to \"WETH\") or unwrapping, no allowance is needed" + }, + "blockNumber": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The block number at which the liquidity sources were sampled to generate the quote. This indicates the freshness of the quote" + }, + "buyAmount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of `buyToken` (in `buyToken` units) that will be bought in the swap" + }, + "buyToken": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the token to buy in the swap" + }, + "fees": { "type": "object", "properties": { - "amount": { - "allOf": [ - {}, - { + "integratorFee": { + "type": "object", + "properties": { + "amount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of token charged as the integrator fee" + }, + "token": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the token charged as the integrator fee" + }, + "type": { + "type": "string", + "enum": ["volume"] } - ], - "description": "The amount of token charged as the integrator fee" - }, - "token": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The address of the token charged as the integrator fee" + }, + "required": ["amount", "token", "type"], + "additionalProperties": false, + "nullable": true, + "description": "The specified fee to charge and deliver to the `swapFeeRecipient`." }, - "type": { "type": "string", "enum": ["volume"] } - }, - "required": ["amount", "token", "type"], - "additionalProperties": false, - "nullable": true, - "description": "The specified fee to charge and deliver to the `swapFeeRecipient`." - }, - "integratorFees": { - "type": "array", - "items": { - "type": "object", - "properties": { - "amount": { - "allOf": [ - {}, - { + "integratorFees": { + "type": "array", + "items": { + "type": "object", + "properties": { + "amount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of token charged as the integrator fee" + }, + "token": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the token charged as the integrator fee" + }, + "type": { + "type": "string", + "enum": ["volume"] } - ], - "description": "The amount of token charged as the integrator fee" - }, - "token": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The address of the token charged as the integrator fee" + }, + "required": ["amount", "token", "type"], + "additionalProperties": false }, - "type": { - "type": "string", - "enum": ["volume"] - } + "nullable": true, + "description": "The specified fees to charge and deliver to the `swapFeesRecipient`." }, - "required": ["amount", "token", "type"], - "additionalProperties": false - }, - "nullable": true, - "description": "The specified fees to charge and deliver to the `swapFeesRecipient`." - }, - "zeroExFee": { - "type": "object", - "properties": { - "amount": { - "allOf": [ - {}, - { + "zeroExFee": { + "type": "object", + "properties": { + "amount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of token charged as the 0x fee" + }, + "token": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the token charged as the 0x fee" + }, + "type": { + "type": "string", + "enum": ["volume"] } - ], - "description": "The amount of token charged as the 0x fee" - }, - "token": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The address of the token charged as the 0x fee" + }, + "required": ["amount", "token", "type"], + "additionalProperties": false, + "nullable": true, + "description": "The fee charged by 0x for the trade." }, - "type": { "type": "string", "enum": ["volume"] } + "gasFee": { + "type": "object", + "properties": { + "amount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of token charged as the gas fee" + }, + "token": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the token charged as the gas fee" + }, + "type": { + "type": "string", + "enum": ["gas"] + } + }, + "required": ["amount", "token", "type"], + "additionalProperties": false, + "nullable": true, + "description": "The gas fee to be used in submitting the transaction." + } }, - "required": ["amount", "token", "type"], + "required": [ + "integratorFee", + "integratorFees", + "zeroExFee", + "gasFee" + ], "additionalProperties": false, - "nullable": true, - "description": "The fee charged by 0x for the trade." + "description": "Fees to be deducted in this transaction. It contains the `integratorFee`, `zeroExFee` and `gasFee`" }, - "gasFee": { + "issues": { "type": "object", "properties": { - "amount": { - "allOf": [ - {}, - { + "allowance": { + "type": "object", + "properties": { + "actual": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The `taker`'s current allowance of the `spender`" + }, + "spender": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address to set the allowance on" } - ], - "description": "The amount of token charged as the gas fee" + }, + "required": ["actual", "spender"], + "additionalProperties": false, + "description": "Details of allowances that the `taker` must set for in order to execute the swap successfully. Null if no allowance is required", + "nullable": true }, - "token": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The address of the token charged as the gas fee" + "balance": { + "type": "object", + "properties": { + "token": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the `sellToken`" + }, + "actual": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The current balance of the `sellToken` in the `taker` address" + }, + "expected": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The balance of the `sellToken` required for the swap to execute successfully" + } + }, + "required": ["token", "actual", "expected"], + "additionalProperties": false, + "description": "Details of balance of the `sellToken` that the `taker` must hold. Null if the `taker` has sufficient balance", + "nullable": true }, - "type": { "type": "string", "enum": ["gas"] } + "simulationIncomplete": { + "type": "boolean", + "description": "This is 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": { + "type": "array", + "items": { "type": "string" }, + "description": "A list of invalid sources present in `excludedSources` request. See `https://api.0x.org/sources?chainId=` with the desired chain's ID for the list of valid sources" + } }, - "required": ["amount", "token", "type"], + "required": [ + "allowance", + "balance", + "simulationIncomplete", + "invalidSourcesPassed" + ], "additionalProperties": false, - "nullable": true, - "description": "The gas fee to be used in submitting the transaction." - } - }, - "required": [ - "integratorFee", - "integratorFees", - "zeroExFee", - "gasFee" - ], - "additionalProperties": false, - "description": "Fees to be deducted in this transaction. It contains the `integratorFee`, `zeroExFee` and `gasFee`" - }, - "gas": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" - } - ], - "nullable": true, - "description": "The estimated gas limit that should be used to send the transaction to guarantee settlement" - }, - "gasPrice": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" - } - ], - "description": "The gas price (in wei) that should be used to send the transaction. The transaction needs to be sent with this `gasPrice` for the transaction to be successful" - }, - "issues": { - "type": "object", - "properties": { - "allowance": { + "description": "An object containing potential issues discovered during 0x validation that can prevent the swap from being executed successfully by the `taker`" + }, + "liquidityAvailable": { + "type": "boolean", + "enum": [true], + "description": "This validates the availability of liquidity for the quote requested. The rest of the fields will only be returned if `true`" + }, + "minBuyAmount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The price which must be met or else the entire transaction will revert. This price is influenced by the `slippageBps` parameter. On-chain sources may encounter price movements from quote to settlement" + }, + "mode": { "type": "string", "enum": ["exact-in"] }, + "route": { "type": "object", "properties": { - "actual": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" - } - ], - "description": "The `taker`'s current allowance of the `spender`" + "fills": { + "type": "array", + "items": { + "type": "object", + "properties": { + "from": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the input token" + }, + "to": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the output token" + }, + "source": { + "type": "string", + "description": "The liquidity source used in the route" + }, + "proportionBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The proportion of the trade to be filled by the `source`" + } + }, + "required": [ + "from", + "to", + "source", + "proportionBps" + ], + "additionalProperties": false + }, + "description": "Details of each segment that 0x routes the swap through" }, - "spender": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The address to set the allowance on" + "tokens": { + "type": "array", + "items": { + "type": "object", + "properties": { + "address": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The token address. This is the unique identifier of the token" + }, + "symbol": { + "type": "string", + "description": "The token symbol. This is not guaranteed to be unique, as multiple tokens can have the same symbol" + } + }, + "required": ["address", "symbol"], + "additionalProperties": false, + "description": "Properties of the tokens involved in the swap" + }, + "description": "Properties of the tokens involved in the swap" } }, - "required": ["actual", "spender"], + "required": ["fills", "tokens"], "additionalProperties": false, - "description": "Details of allowances that the `taker` must set for in order to execute the swap successfully. Null if no allowance is required", - "nullable": true + "description": "The path of liquidity sources to be used in executing this swap" }, - "balance": { + "sellAmount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of `sellToken` (in `sellToken` units) that will be sold in this swap" + }, + "sellToken": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the token to sell in the swap" + }, + "tokenMetadata": { "type": "object", "properties": { - "token": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The contract address of the `sellToken`" - }, - "actual": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "buyToken": { + "type": "object", + "properties": { + "buyTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The buy tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "sellTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The sell tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "transferTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The transfer tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" } + }, + "required": [ + "buyTaxBps", + "sellTaxBps", + "transferTaxBps" ], - "description": "The current balance of the `sellToken` in the `taker` address" + "additionalProperties": false, + "description": "Swap-related metadata for the buy token" }, - "expected": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "sellToken": { + "type": "object", + "properties": { + "buyTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The buy tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "sellTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The sell tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "transferTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The transfer tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" } + }, + "required": [ + "buyTaxBps", + "sellTaxBps", + "transferTaxBps" ], - "description": "The balance of the `sellToken` required for the swap to execute successfully" + "additionalProperties": false, + "description": "Swap-related metadata for the sell token" } }, - "required": ["token", "actual", "expected"], + "required": ["buyToken", "sellToken"], "additionalProperties": false, - "description": "Details of balance of the `sellToken` that the `taker` must hold. Null if the `taker` has sufficient balance", - "nullable": true + "description": "Swap-related metadata for the buy and sell token in the swap" }, - "simulationIncomplete": { - "type": "boolean", - "description": "This is 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" + "totalNetworkFee": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The estimated total network cost of the swap. On chains where there is no L1 data cost, it is calculated as `gas` * `gasPrice`. On chains where there is an L1 data cost, it is calculated as `gas` * `gasPrice` + L1 data cost." }, - "invalidSourcesPassed": { - "type": "array", - "items": { "type": "string" }, - "description": "A list of invalid sources present in `excludedSources` request. See `https://api.0x.org/sources?chainId=` with the desired chain's ID for the list of valid sources" - } - }, - "required": [ - "allowance", - "balance", - "simulationIncomplete", - "invalidSourcesPassed" - ], - "additionalProperties": false, - "description": "An object containing potential issues discovered during 0x validation that can prevent the swap from being executed successfully by the `taker`" - }, - "liquidityAvailable": { - "type": "boolean", - "enum": [true], - "description": "This validates the availability of liquidity for the quote requested. The rest of the fields will only be returned if `true`" - }, - "minBuyAmount": { - "allOf": [ - {}, - { + "zid": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" - } - ], - "description": "The price which must be met or else the entire transaction will revert. This price is influenced by the `slippageBps` parameter. On-chain sources may encounter price movements from quote to settlement" - }, - "route": { - "type": "object", - "properties": { - "fills": { - "type": "array", - "items": { - "type": "object", - "properties": { - "from": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The contract address of the input token" - }, - "to": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The contract address of the output token" - }, - "source": { - "type": "string", - "description": "The liquidity source used in the route" - }, - "proportionBps": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" - } - ], - "description": "The proportion of the trade to be filled by the `source`" - } - }, - "required": [ - "from", - "to", - "source", - "proportionBps" - ], - "additionalProperties": false - }, - "description": "Details of each segment that 0x routes the swap through" + "description": "The unique ZeroEx identifier of the request" }, - "tokens": { - "type": "array", - "items": { - "type": "object", - "properties": { - "address": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The token address. This is the unique identifier of the token" - }, - "symbol": { - "type": "string", - "description": "The token symbol. This is not guaranteed to be unique, as multiple tokens can have the same symbol" - } - }, - "required": ["address", "symbol"], - "additionalProperties": false, - "description": "Properties of the tokens involved in the swap" - }, - "description": "Properties of the tokens involved in the swap" + "gas": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The estimated gas limit that should be used to send the transaction to guarantee settlement" + }, + "gasPrice": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The gas price (in wei) that should be used to send the transaction. The transaction needs to be sent with this `gasPrice` for the transaction to be successful" } }, - "required": ["fills", "tokens"], - "additionalProperties": false, - "description": "The path of liquidity sources to be used in executing this swap" - }, - "sellAmount": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" - } + "required": [ + "allowanceTarget", + "blockNumber", + "buyAmount", + "buyToken", + "fees", + "issues", + "liquidityAvailable", + "minBuyAmount", + "mode", + "route", + "sellAmount", + "sellToken", + "tokenMetadata", + "totalNetworkFee", + "zid", + "gas", + "gasPrice" ], - "description": "The amount of `sellToken` (in `sellToken` units) that will be sold in this swap" - }, - "sellToken": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The contract address of the token to sell in the swap" + "additionalProperties": false }, - "tokenMetadata": { + { "type": "object", "properties": { + "allowanceTarget": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "nullable": true, + "description": "The target contract address for which the `taker` needs to have an allowance in order to be able to complete the swap." + }, + "blockNumber": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The block number at which the liquidity sources were sampled to generate the quote. This indicates the freshness of the quote" + }, + "buyAmount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The exact amount of `buyToken` (in `buyToken` units) requested for the swap" + }, "buyToken": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the token to buy in the swap" + }, + "estimatedNetSellAmount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The estimated net amount of `sellToken` spent after any exact-out refund route executes" + }, + "fees": { "type": "object", "properties": { - "buyTaxBps": { - "allOf": [ - {}, - { + "integratorFee": { + "type": "object", + "properties": { + "amount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of token charged as the integrator fee" + }, + "token": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the token charged as the integrator fee" + }, + "type": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "enum": ["volume"] } - ], + }, + "required": ["amount", "token", "type"], + "additionalProperties": false, "nullable": true, - "description": "The buy tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + "description": "The specified fee to charge and deliver to the `swapFeeRecipient`." }, - "sellTaxBps": { - "allOf": [ - {}, - { + "integratorFees": { + "type": "array", + "items": { + "type": "object", + "properties": { + "amount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of token charged as the integrator fee" + }, + "token": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the token charged as the integrator fee" + }, + "type": { + "type": "string", + "enum": ["volume"] + } + }, + "required": ["amount", "token", "type"], + "additionalProperties": false + }, + "nullable": true, + "description": "The specified fees to charge and deliver to the `swapFeesRecipient`." + }, + "zeroExFee": { + "type": "object", + "properties": { + "amount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of token charged as the 0x fee" + }, + "token": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the token charged as the 0x fee" + }, + "type": { + "type": "string", + "enum": ["volume"] } - ], + }, + "required": ["amount", "token", "type"], + "additionalProperties": false, "nullable": true, - "description": "The sell tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + "description": "The fee charged by 0x for the trade." }, - "transferTaxBps": { - "allOf": [ - {}, - { + "gasFee": { + "type": "object", + "properties": { + "amount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of token charged as the gas fee" + }, + "token": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the token charged as the gas fee" + }, + "type": { + "type": "string", + "enum": ["gas"] } - ], + }, + "required": ["amount", "token", "type"], + "additionalProperties": false, "nullable": true, - "description": "The transfer tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + "description": "The gas fee to be used in submitting the transaction." } }, "required": [ - "buyTaxBps", - "sellTaxBps", - "transferTaxBps" + "integratorFee", + "integratorFees", + "zeroExFee", + "gasFee" ], "additionalProperties": false, - "description": "Swap-related metadata for the buy token" + "description": "Fees to be deducted in this transaction. Exact-out v1 does not support fees." }, - "sellToken": { + "issues": { "type": "object", "properties": { - "buyTaxBps": { - "allOf": [ - {}, - { + "allowance": { + "type": "object", + "properties": { + "actual": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The `taker`'s current allowance of the `spender`" + }, + "spender": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address to set the allowance on" } - ], - "nullable": true, - "description": "The buy tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "required": ["actual", "spender"], + "additionalProperties": false, + "description": "Details of allowances that the `taker` must set for in order to execute the swap successfully. Null if no allowance is required", + "nullable": true }, - "sellTaxBps": { - "allOf": [ - {}, - { + "balance": { + "type": "object", + "properties": { + "token": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the `sellToken`" + }, + "actual": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The current balance of the `sellToken` in the `taker` address" + }, + "expected": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The balance of the `sellToken` required for the swap to execute successfully" } - ], - "nullable": true, - "description": "The sell tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "required": ["token", "actual", "expected"], + "additionalProperties": false, + "description": "Details of balance of the `sellToken` that the `taker` must hold. Null if the `taker` has sufficient balance", + "nullable": true }, - "transferTaxBps": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "simulationIncomplete": { + "type": "boolean", + "description": "This is 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": { + "type": "array", + "items": { "type": "string" }, + "description": "A list of invalid sources present in `excludedSources` request. See `https://api.0x.org/sources?chainId=` with the desired chain's ID for the list of valid sources" + } + }, + "required": [ + "allowance", + "balance", + "simulationIncomplete", + "invalidSourcesPassed" + ], + "additionalProperties": false, + "description": "An object containing potential issues discovered during 0x validation that can prevent the swap from being executed successfully by the `taker`" + }, + "liquidityAvailable": { + "type": "boolean", + "enum": [true], + "description": "This validates the availability of liquidity for the quote requested. The rest of the fields will only be returned if `true`" + }, + "mode": { "type": "string", "enum": ["exact-out"] }, + "routes": { + "type": "object", + "properties": { + "forward": { + "type": "object", + "properties": { + "fills": { + "type": "array", + "items": { + "type": "object", + "properties": { + "from": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the input token" + }, + "to": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the output token" + }, + "source": { + "type": "string", + "description": "The liquidity source used in the route" + }, + "proportionBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The proportion of the trade to be filled by the `source`" + } + }, + "required": [ + "from", + "to", + "source", + "proportionBps" + ], + "additionalProperties": false + }, + "description": "Details of each segment that 0x routes the swap through" + }, + "tokens": { + "type": "array", + "items": { + "type": "object", + "properties": { + "address": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The token address. This is the unique identifier of the token" + }, + "symbol": { + "type": "string", + "description": "The token symbol. This is not guaranteed to be unique, as multiple tokens can have the same symbol" + } + }, + "required": ["address", "symbol"], + "additionalProperties": false, + "description": "Properties of the tokens involved in the swap" + }, + "description": "Properties of the tokens involved in the swap" } - ], + }, + "required": ["fills", "tokens"], + "additionalProperties": false, + "description": "The forward route used to acquire at least the requested buy amount" + }, + "refund": { + "type": "object", + "properties": { + "fills": { + "type": "array", + "items": { + "type": "object", + "properties": { + "from": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the input token" + }, + "to": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the output token" + }, + "source": { + "type": "string", + "description": "The liquidity source used in the route" + }, + "proportionBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The proportion of the trade to be filled by the `source`" + } + }, + "required": [ + "from", + "to", + "source", + "proportionBps" + ], + "additionalProperties": false + }, + "description": "Details of each segment that 0x routes the swap through" + }, + "tokens": { + "type": "array", + "items": { + "type": "object", + "properties": { + "address": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The token address. This is the unique identifier of the token" + }, + "symbol": { + "type": "string", + "description": "The token symbol. This is not guaranteed to be unique, as multiple tokens can have the same symbol" + } + }, + "required": ["address", "symbol"], + "additionalProperties": false, + "description": "Properties of the tokens involved in the swap" + }, + "description": "Properties of the tokens involved in the swap" + } + }, + "required": ["fills", "tokens"], + "additionalProperties": false, "nullable": true, - "description": "The transfer tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + "description": "The optional refund route used to convert buy-token surplus back to the sell token" } }, - "required": [ - "buyTaxBps", - "sellTaxBps", - "transferTaxBps" + "required": ["forward", "refund"], + "additionalProperties": false, + "description": "The exact-out forward and refund routes" + }, + "maxSellAmount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } ], + "description": "The maximum amount of `sellToken` that may be spent by the exact-out swap" + }, + "sellToken": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the token to sell in the swap" + }, + "tokenMetadata": { + "type": "object", + "properties": { + "buyToken": { + "type": "object", + "properties": { + "buyTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The buy tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "sellTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The sell tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "transferTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The transfer tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + } + }, + "required": [ + "buyTaxBps", + "sellTaxBps", + "transferTaxBps" + ], + "additionalProperties": false, + "description": "Swap-related metadata for the buy token" + }, + "sellToken": { + "type": "object", + "properties": { + "buyTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The buy tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "sellTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The sell tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "transferTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The transfer tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + } + }, + "required": [ + "buyTaxBps", + "sellTaxBps", + "transferTaxBps" + ], + "additionalProperties": false, + "description": "Swap-related metadata for the sell token" + } + }, + "required": ["buyToken", "sellToken"], "additionalProperties": false, - "description": "Swap-related metadata for the sell token" - } - }, - "required": ["buyToken", "sellToken"], - "additionalProperties": false, - "description": "Swap-related metadata for the buy and sell token in the swap" - }, - "totalNetworkFee": { - "allOf": [ - {}, - { + "description": "Swap-related metadata for the buy and sell token in the swap" + }, + "totalNetworkFee": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The estimated total network cost of the swap. On chains where there is no L1 data cost, it is calculated as `gas` * `gasPrice`. On chains where there is an L1 data cost, it is calculated as `gas` * `gasPrice` + L1 data cost." + }, + "zid": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "description": "The unique ZeroEx identifier of the request" + }, + "gas": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The estimated gas limit that should be used to send the transaction to guarantee settlement" + }, + "gasPrice": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The gas price (in wei) that should be used to send the transaction. The transaction needs to be sent with this `gasPrice` for the transaction to be successful" } + }, + "required": [ + "allowanceTarget", + "blockNumber", + "buyAmount", + "buyToken", + "estimatedNetSellAmount", + "fees", + "issues", + "liquidityAvailable", + "mode", + "routes", + "maxSellAmount", + "sellToken", + "tokenMetadata", + "totalNetworkFee", + "zid", + "gas", + "gasPrice" ], - "nullable": true, - "description": "The estimated total network cost of the swap. On chains where there is no L1 data cost, it is calculated as `gas` * `gasPrice`. On chains where there is an L1 data cost, it is calculated as `gas` * `gasPrice` + L1 data cost." - }, - "zid": { - "type": "string", - "description": "The unique ZeroEx identifier of the request" + "additionalProperties": false } - }, - "required": [ - "allowanceTarget", - "blockNumber", - "buyAmount", - "buyToken", - "fees", - "gas", - "gasPrice", - "issues", - "liquidityAvailable", - "minBuyAmount", - "route", - "sellAmount", - "sellToken", - "tokenMetadata", - "totalNetworkFee", - "zid" - ], - "additionalProperties": false + ] }, { "type": "object", @@ -2400,6 +4229,7 @@ "invalidSourcesPassed": [] }, "liquidityAvailable": true, + "mode": "exact-in", "minBuyAmount": "99032421", "route": { "fills": [ @@ -2558,11 +4388,18 @@ { "name": "sellAmount", "in": "query", - "required": true, + "required": false, "schema": { "type": "string" }, "description": "The amount of `sellToken` in `sellToken` base units to sell", "example": "100000000" }, + { + "name": "buyAmount", + "in": "query", + "required": false, + "schema": { "type": "string" }, + "description": "The exact amount of `buyToken` in `buyToken` base units to buy" + }, { "name": "taker", "in": "query", @@ -2686,196 +4523,562 @@ "description": "Successful response", "content": { "application/json": { - "schema": { - "anyOf": [ - { - "type": "object", - "properties": { - "allowanceTarget": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "nullable": true, - "description": "The target contract address for which the `taker` needs to have an allowance in order to be able to complete the swap. For swaps with the native asset (ie \"ETH\" or \"BNB\") as the `sellToken`, wrapping the native asset (i.e. \"ETH\" to \"WETH\") or unwrapping, no allowance is needed" - }, - "blockNumber": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" - } - ], - "description": "The block number at which the liquidity sources were sampled to generate the quote. This indicates the freshness of the quote" - }, - "buyAmount": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" - } - ], - "description": "The amount of `buyToken` (in `buyToken` units) that will be bought in the swap" - }, - "buyToken": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The contract address of the token to buy in the swap" - }, - "fees": { + "schema": { + "anyOf": [ + { + "anyOf": [ + { "type": "object", "properties": { - "integratorFee": { + "allowanceTarget": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "nullable": true, + "description": "The target contract address for which the `taker` needs to have an allowance in order to be able to complete the swap. For swaps with the native asset (ie \"ETH\" or \"BNB\") as the `sellToken`, wrapping the native asset (i.e. \"ETH\" to \"WETH\") or unwrapping, no allowance is needed" + }, + "blockNumber": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The block number at which the liquidity sources were sampled to generate the quote. This indicates the freshness of the quote" + }, + "buyAmount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of `buyToken` (in `buyToken` units) that will be bought in the swap" + }, + "buyToken": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the token to buy in the swap" + }, + "fees": { "type": "object", "properties": { - "amount": { - "allOf": [ - {}, - { + "integratorFee": { + "type": "object", + "properties": { + "amount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of token charged as the integrator fee" + }, + "token": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the token charged as the integrator fee" + }, + "type": { + "type": "string", + "enum": ["volume"] } - ], - "description": "The amount of token charged as the integrator fee" - }, - "token": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The address of the token charged as the integrator fee" + }, + "required": ["amount", "token", "type"], + "additionalProperties": false, + "nullable": true, + "description": "The specified fee to charge and deliver to the `swapFeeRecipient`." }, - "type": { "type": "string", "enum": ["volume"] } - }, - "required": ["amount", "token", "type"], - "additionalProperties": false, - "nullable": true, - "description": "The specified fee to charge and deliver to the `swapFeeRecipient`." - }, - "integratorFees": { - "type": "array", - "items": { - "type": "object", - "properties": { - "amount": { - "allOf": [ - {}, - { + "integratorFees": { + "type": "array", + "items": { + "type": "object", + "properties": { + "amount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of token charged as the integrator fee" + }, + "token": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the token charged as the integrator fee" + }, + "type": { + "type": "string", + "enum": ["volume"] } - ], - "description": "The amount of token charged as the integrator fee" + }, + "required": ["amount", "token", "type"], + "additionalProperties": false }, - "token": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The address of the token charged as the integrator fee" + "nullable": true, + "description": "The specified fees to charge and deliver to the `swapFeesRecipient`." + }, + "zeroExFee": { + "type": "object", + "properties": { + "amount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of token charged as the 0x fee" + }, + "token": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the token charged as the 0x fee" + }, + "type": { + "type": "string", + "enum": ["volume"] + } }, - "type": { - "type": "string", - "enum": ["volume"] - } + "required": ["amount", "token", "type"], + "additionalProperties": false, + "nullable": true, + "description": "The fee charged by 0x for the trade." }, - "required": ["amount", "token", "type"], - "additionalProperties": false + "gasFee": { + "type": "object", + "properties": { + "amount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of token charged as the gas fee" + }, + "token": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the token charged as the gas fee" + }, + "type": { + "type": "string", + "enum": ["gas"] + } + }, + "required": ["amount", "token", "type"], + "additionalProperties": false, + "nullable": true, + "description": "The gas fee to be used in submitting the transaction." + } }, - "nullable": true, - "description": "The specified fees to charge and deliver to the `swapFeesRecipient`." + "required": [ + "integratorFee", + "integratorFees", + "zeroExFee", + "gasFee" + ], + "additionalProperties": false, + "description": "Fees to be deducted in this transaction. It contains the `integratorFee`, `zeroExFee` and `gasFee`" }, - "zeroExFee": { + "issues": { "type": "object", "properties": { - "amount": { - "allOf": [ - {}, - { + "allowance": { + "type": "object", + "properties": { + "actual": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The `taker`'s current allowance of the `spender`" + }, + "spender": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address to set the allowance on" } - ], - "description": "The amount of token charged as the 0x fee" + }, + "required": ["actual", "spender"], + "additionalProperties": false, + "description": "Details of allowances that the `taker` must set for in order to execute the swap successfully. Null if no allowance is required", + "nullable": true }, - "token": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The address of the token charged as the 0x fee" + "balance": { + "type": "object", + "properties": { + "token": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the `sellToken`" + }, + "actual": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The current balance of the `sellToken` in the `taker` address" + }, + "expected": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The balance of the `sellToken` required for the swap to execute successfully" + } + }, + "required": ["token", "actual", "expected"], + "additionalProperties": false, + "description": "Details of balance of the `sellToken` that the `taker` must hold. Null if the `taker` has sufficient balance", + "nullable": true }, - "type": { "type": "string", "enum": ["volume"] } + "simulationIncomplete": { + "type": "boolean", + "description": "This is 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": { + "type": "array", + "items": { "type": "string" }, + "description": "A list of invalid sources present in `excludedSources` request. See `https://api.0x.org/sources?chainId=` with the desired chain's ID for the list of valid sources" + } }, - "required": ["amount", "token", "type"], + "required": [ + "allowance", + "balance", + "simulationIncomplete", + "invalidSourcesPassed" + ], "additionalProperties": false, - "nullable": true, - "description": "The fee charged by 0x for the trade." + "description": "An object containing potential issues discovered during 0x validation that can prevent the swap from being executed successfully by the `taker`" }, - "gasFee": { + "liquidityAvailable": { + "type": "boolean", + "enum": [true], + "description": "This validates the availability of liquidity for the quote requested. The rest of the fields will only be returned if `true`" + }, + "minBuyAmount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The price which must be met or else the entire transaction will revert. This price is influenced by the `slippageBps` parameter. On-chain sources may encounter price movements from quote to settlement" + }, + "mode": { "type": "string", "enum": ["exact-in"] }, + "route": { "type": "object", "properties": { - "amount": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" - } - ], - "description": "The amount of token charged as the gas fee" - }, - "token": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The address of the token charged as the gas fee" + "fills": { + "type": "array", + "items": { + "type": "object", + "properties": { + "from": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the input token" + }, + "to": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the output token" + }, + "source": { + "type": "string", + "description": "The liquidity source used in the route" + }, + "proportionBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The proportion of the trade to be filled by the `source`" + } + }, + "required": [ + "from", + "to", + "source", + "proportionBps" + ], + "additionalProperties": false + }, + "description": "Details of each segment that 0x routes the swap through" }, - "type": { "type": "string", "enum": ["gas"] } + "tokens": { + "type": "array", + "items": { + "type": "object", + "properties": { + "address": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The token address. This is the unique identifier of the token" + }, + "symbol": { + "type": "string", + "description": "The token symbol. This is not guaranteed to be unique, as multiple tokens can have the same symbol" + } + }, + "required": ["address", "symbol"], + "additionalProperties": false, + "description": "Properties of the tokens involved in the swap" + }, + "description": "Properties of the tokens involved in the swap" + } }, - "required": ["amount", "token", "type"], + "required": ["fills", "tokens"], "additionalProperties": false, - "nullable": true, - "description": "The gas fee to be used in submitting the transaction." - } - }, - "required": [ - "integratorFee", - "integratorFees", - "zeroExFee", - "gasFee" - ], - "additionalProperties": false - }, - "issues": { - "type": "object", - "properties": { - "allowance": { + "description": "The path of liquidity sources to be used in executing this swap" + }, + "sellAmount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of `sellToken` (in `sellToken` units) that will be sold in this swap" + }, + "sellToken": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the token to sell in the swap" + }, + "tokenMetadata": { "type": "object", "properties": { - "actual": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "buyToken": { + "type": "object", + "properties": { + "buyTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The buy tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "sellTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The sell tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "transferTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The transfer tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" } + }, + "required": [ + "buyTaxBps", + "sellTaxBps", + "transferTaxBps" ], - "description": "The `taker`'s current allowance of the `spender`" + "additionalProperties": false, + "description": "Swap-related metadata for the buy token" + }, + "sellToken": { + "type": "object", + "properties": { + "buyTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The buy tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "sellTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The sell tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "transferTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The transfer tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + } + }, + "required": [ + "buyTaxBps", + "sellTaxBps", + "transferTaxBps" + ], + "additionalProperties": false, + "description": "Swap-related metadata for the sell token" + } + }, + "required": ["buyToken", "sellToken"], + "additionalProperties": false, + "description": "Swap-related metadata for the buy and sell token in the swap" + }, + "totalNetworkFee": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The estimated total network cost of the swap. On chains where there is no L1 data cost, it is calculated as `gas` * `gasPrice`. On chains where there is an L1 data cost, it is calculated as `gas` * `gasPrice` + L1 data cost." + }, + "zid": { + "type": "string", + "description": "The unique ZeroEx identifier of the request" + }, + "permit2": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["Permit2"], + "description": "`Permit2`" }, - "spender": { + "hash": { "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The address to set the allowance on" + "description": "The hash for the approval according to [EIP-712](https://eips.ethereum.org/EIPS/eip-712). If you compute the hash from eip712 field, it should match the value of this field" + }, + "eip712": { + "type": "object", + "properties": { + "types": { + "type": "object", + "additionalProperties": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { "type": "string" }, + "type": { "type": "string" } + }, + "required": ["name", "type"], + "additionalProperties": false + } + } + }, + "domain": { + "type": "object", + "properties": { + "name": { "type": "string" }, + "version": { "type": "string" }, + "chainId": { "type": "number" }, + "verifyingContract": { + "type": "string" + }, + "salt": { "type": "string" } + }, + "additionalProperties": false + }, + "message": { + "type": "object", + "additionalProperties": { + "anyOf": [ + { "type": "string" }, + { + "type": "array", + "items": { "type": "string" } + }, + { "type": "number" }, + { + "type": "array", + "items": { "type": "number" } + }, + { "type": "boolean" }, + { + "type": "array", + "items": { "type": "boolean" } + }, + {}, + { "type": "array", "items": {} } + ] + } + }, + "primaryType": { "type": "string" } + }, + "required": [ + "types", + "domain", + "message", + "primaryType" + ], + "additionalProperties": false, + "description": "Necessary data for [EIP-712](https://eips.ethereum.org/EIPS/eip-712)" } }, - "required": ["actual", "spender"], + "required": ["type", "hash", "eip712"], "additionalProperties": false, - "description": "Details of allowances that the `taker` must set for in order to execute the swap successfully. Null if no allowance is required", + "description": "This is the approval object which contains the necessary fields to submit an approval for this transaction. Null if sell token is the native token or the transaction is a native token wrap / unwrap", "nullable": true }, - "balance": { + "transaction": { "type": "object", "properties": { - "token": { + "to": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The contract address of the `sellToken`" + "description": "The address of the target contract to send call `data` to. Do NOT use this field when setting token allowances — doing so can result in lost funds. Always use `issues.allowance.spender` or `allowanceTarget` for setting allowances." }, - "actual": { + "data": { + "type": "string", + "description": "The calldata containing transaction execution details to be sent to the `to` address" + }, + "gas": { "allOf": [ {}, { @@ -2883,9 +5086,10 @@ "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" } ], - "description": "The current balance of the `sellToken` in the `taker` address" + "nullable": true, + "description": "The estimated gas limit that should be used to send the transaction to guarantee settlement" }, - "expected": { + "gasPrice": { "allOf": [ {}, { @@ -2893,266 +5097,681 @@ "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" } ], - "description": "The balance of the `sellToken` required for the swap to execute successfully" + "description": "The gas price (in wei) that should be used to send the transaction" + }, + "value": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of ether (in wei) that should be sent with the transaction" } }, - "required": ["token", "actual", "expected"], + "required": [ + "to", + "data", + "gas", + "gasPrice", + "value" + ], "additionalProperties": false, - "description": "Details of balance of the `sellToken` that the `taker` must hold. Null if the `taker` has sufficient balance", - "nullable": true - }, - "simulationIncomplete": { - "type": "boolean", - "description": "This is 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": { - "type": "array", - "items": { "type": "string" }, - "description": "A list of invalid sources present in `excludedSources` request. See `https://api.0x.org/sources?chainId=` with the desired chain's ID for the list of valid sources" + "description": "This object contains the details required to submit the transaction" } }, "required": [ - "allowance", - "balance", - "simulationIncomplete", - "invalidSourcesPassed" - ], - "additionalProperties": false, - "description": "An object containing potential issues discovered during 0x validation that can prevent the swap from being executed successfully by the `taker`" - }, - "liquidityAvailable": { - "type": "boolean", - "enum": [true], - "description": "This validates the availability of liquidity for the quote requested. The rest of the fields will only be returned if `true`" - }, - "minBuyAmount": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" - } + "allowanceTarget", + "blockNumber", + "buyAmount", + "buyToken", + "fees", + "issues", + "liquidityAvailable", + "minBuyAmount", + "mode", + "route", + "sellAmount", + "sellToken", + "tokenMetadata", + "totalNetworkFee", + "zid", + "permit2", + "transaction" ], - "description": "The price which must be met or else the transaction will revert. This price is influenced by the `slippageBps` parameter. On-chain sources may encounter price movements from quote to settlement" + "additionalProperties": false }, - "permit2": { + { "type": "object", "properties": { - "type": { + "allowanceTarget": { "type": "string", - "enum": ["Permit2"], - "description": "`Permit2`" + "pattern": "^0x[a-fA-F0-9]{40}$", + "nullable": true, + "description": "The target contract address for which the `taker` needs to have an allowance in order to be able to complete the swap." }, - "hash": { + "blockNumber": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The block number at which the liquidity sources were sampled to generate the quote. This indicates the freshness of the quote" + }, + "buyAmount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The exact amount of `buyToken` (in `buyToken` units) requested for the swap" + }, + "buyToken": { "type": "string", - "description": "The hash for the approval according to [EIP-712](https://eips.ethereum.org/EIPS/eip-712). If you compute the hash from eip712 field, it should match the value of this field" + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the token to buy in the swap" }, - "eip712": { + "estimatedNetSellAmount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The estimated net amount of `sellToken` spent after any exact-out refund route executes" + }, + "fees": { "type": "object", "properties": { - "types": { + "integratorFee": { "type": "object", - "additionalProperties": { - "type": "array", - "items": { - "type": "object", - "properties": { - "name": { "type": "string" }, - "type": { "type": "string" } - }, - "required": ["name", "type"], - "additionalProperties": false + "properties": { + "amount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of token charged as the integrator fee" + }, + "token": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the token charged as the integrator fee" + }, + "type": { + "type": "string", + "enum": ["volume"] } - } + }, + "required": ["amount", "token", "type"], + "additionalProperties": false, + "nullable": true, + "description": "The specified fee to charge and deliver to the `swapFeeRecipient`." }, - "domain": { + "integratorFees": { + "type": "array", + "items": { + "type": "object", + "properties": { + "amount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of token charged as the integrator fee" + }, + "token": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the token charged as the integrator fee" + }, + "type": { + "type": "string", + "enum": ["volume"] + } + }, + "required": ["amount", "token", "type"], + "additionalProperties": false + }, + "nullable": true, + "description": "The specified fees to charge and deliver to the `swapFeesRecipient`." + }, + "zeroExFee": { "type": "object", "properties": { - "name": { "type": "string" }, - "version": { "type": "string" }, - "chainId": { "type": "number" }, - "verifyingContract": { "type": "string" }, - "salt": { "type": "string" } + "amount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of token charged as the 0x fee" + }, + "token": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the token charged as the 0x fee" + }, + "type": { + "type": "string", + "enum": ["volume"] + } }, - "additionalProperties": false + "required": ["amount", "token", "type"], + "additionalProperties": false, + "nullable": true, + "description": "The fee charged by 0x for the trade." }, - "message": { + "gasFee": { "type": "object", - "additionalProperties": { - "anyOf": [ - { "type": "string" }, - { - "type": "array", - "items": { "type": "string" } - }, - { "type": "number" }, - { - "type": "array", - "items": { "type": "number" } - }, - { "type": "boolean" }, - { - "type": "array", - "items": { "type": "boolean" } - }, - {}, - { "type": "array", "items": {} } - ] - } - }, - "primaryType": { "type": "string" } + "properties": { + "amount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The amount of token charged as the gas fee" + }, + "token": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the token charged as the gas fee" + }, + "type": { + "type": "string", + "enum": ["gas"] + } + }, + "required": ["amount", "token", "type"], + "additionalProperties": false, + "nullable": true, + "description": "The gas fee to be used in submitting the transaction." + } }, "required": [ - "types", - "domain", - "message", - "primaryType" + "integratorFee", + "integratorFees", + "zeroExFee", + "gasFee" ], "additionalProperties": false, - "description": "Necessary data for [EIP-712](https://eips.ethereum.org/EIPS/eip-712)" - } - }, - "required": ["type", "hash", "eip712"], - "additionalProperties": false, - "description": "This is the approval object which contains the necessary fields to submit an approval for this transaction. Null if sell token is the native token or the transaction is a native token wrap / unwrap", - "nullable": true - }, - "route": { - "type": "object", - "properties": { - "fills": { - "type": "array", - "items": { - "type": "object", - "properties": { - "from": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The contract address of the input token" - }, - "to": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The contract address of the output token" - }, - "source": { - "type": "string", - "description": "The liquidity source used in the route" + "description": "Fees to be deducted in this transaction. Exact-out v1 does not support fees." + }, + "issues": { + "type": "object", + "properties": { + "allowance": { + "type": "object", + "properties": { + "actual": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The `taker`'s current allowance of the `spender`" + }, + "spender": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address to set the allowance on" + } }, - "proportionBps": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" - } - ], - "description": "The proportion of the trade to be filled by the `source`" - } + "required": ["actual", "spender"], + "additionalProperties": false, + "description": "Details of allowances that the `taker` must set for in order to execute the swap successfully. Null if no allowance is required", + "nullable": true }, - "required": [ - "from", - "to", - "source", - "proportionBps" - ], - "additionalProperties": false + "balance": { + "type": "object", + "properties": { + "token": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the `sellToken`" + }, + "actual": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The current balance of the `sellToken` in the `taker` address" + }, + "expected": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The balance of the `sellToken` required for the swap to execute successfully" + } + }, + "required": ["token", "actual", "expected"], + "additionalProperties": false, + "description": "Details of balance of the `sellToken` that the `taker` must hold. Null if the `taker` has sufficient balance", + "nullable": true + }, + "simulationIncomplete": { + "type": "boolean", + "description": "This is 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": { + "type": "array", + "items": { "type": "string" }, + "description": "A list of invalid sources present in `excludedSources` request. See `https://api.0x.org/sources?chainId=` with the desired chain's ID for the list of valid sources" + } }, - "description": "Details of each segment that 0x routes the swap through" + "required": [ + "allowance", + "balance", + "simulationIncomplete", + "invalidSourcesPassed" + ], + "additionalProperties": false, + "description": "An object containing potential issues discovered during 0x validation that can prevent the swap from being executed successfully by the `taker`" }, - "tokens": { - "type": "array", - "items": { - "type": "object", - "properties": { - "address": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The token address. This is the unique identifier of the token" + "liquidityAvailable": { + "type": "boolean", + "enum": [true], + "description": "This validates the availability of liquidity for the quote requested. The rest of the fields will only be returned if `true`" + }, + "mode": { "type": "string", "enum": ["exact-out"] }, + "routes": { + "type": "object", + "properties": { + "forward": { + "type": "object", + "properties": { + "fills": { + "type": "array", + "items": { + "type": "object", + "properties": { + "from": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the input token" + }, + "to": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the output token" + }, + "source": { + "type": "string", + "description": "The liquidity source used in the route" + }, + "proportionBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The proportion of the trade to be filled by the `source`" + } + }, + "required": [ + "from", + "to", + "source", + "proportionBps" + ], + "additionalProperties": false + }, + "description": "Details of each segment that 0x routes the swap through" + }, + "tokens": { + "type": "array", + "items": { + "type": "object", + "properties": { + "address": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The token address. This is the unique identifier of the token" + }, + "symbol": { + "type": "string", + "description": "The token symbol. This is not guaranteed to be unique, as multiple tokens can have the same symbol" + } + }, + "required": ["address", "symbol"], + "additionalProperties": false, + "description": "Properties of the tokens involved in the swap" + }, + "description": "Properties of the tokens involved in the swap" + } }, - "symbol": { - "type": "string", - "description": "The token symbol. This is not guaranteed to be unique, as multiple tokens can have the same symbol" - } + "required": ["fills", "tokens"], + "additionalProperties": false, + "description": "The forward route used to acquire at least the requested buy amount" }, - "required": ["address", "symbol"], - "additionalProperties": false, - "description": "Properties of the tokens involved in the swap" + "refund": { + "type": "object", + "properties": { + "fills": { + "type": "array", + "items": { + "type": "object", + "properties": { + "from": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the input token" + }, + "to": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the output token" + }, + "source": { + "type": "string", + "description": "The liquidity source used in the route" + }, + "proportionBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The proportion of the trade to be filled by the `source`" + } + }, + "required": [ + "from", + "to", + "source", + "proportionBps" + ], + "additionalProperties": false + }, + "description": "Details of each segment that 0x routes the swap through" + }, + "tokens": { + "type": "array", + "items": { + "type": "object", + "properties": { + "address": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The token address. This is the unique identifier of the token" + }, + "symbol": { + "type": "string", + "description": "The token symbol. This is not guaranteed to be unique, as multiple tokens can have the same symbol" + } + }, + "required": ["address", "symbol"], + "additionalProperties": false, + "description": "Properties of the tokens involved in the swap" + }, + "description": "Properties of the tokens involved in the swap" + } + }, + "required": ["fills", "tokens"], + "additionalProperties": false, + "nullable": true, + "description": "The optional refund route used to convert buy-token surplus back to the sell token" + } }, - "description": "Properties of the tokens involved in the swap" - } - }, - "required": ["fills", "tokens"], - "additionalProperties": false, - "description": "The path of liquidity sources to be used in executing this swap" - }, - "sellAmount": { - "allOf": [ - {}, - { + "required": ["forward", "refund"], + "additionalProperties": false, + "description": "The exact-out forward and refund routes" + }, + "maxSellAmount": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "description": "The maximum amount of `sellToken` that may be spent by the exact-out swap" + }, + "sellToken": { "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" - } - ], - "description": "The amount of `sellToken` (in `sellToken` units) that will be sold in this swap" - }, - "sellToken": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The contract address of the token to sell in the swap" - }, - "tokenMetadata": { - "type": "object", - "properties": { - "buyToken": { + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The contract address of the token to sell in the swap" + }, + "tokenMetadata": { "type": "object", "properties": { - "buyTaxBps": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "buyToken": { + "type": "object", + "properties": { + "buyTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The buy tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "sellTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The sell tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "transferTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The transfer tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" } + }, + "required": [ + "buyTaxBps", + "sellTaxBps", + "transferTaxBps" ], - "nullable": true, - "description": "The buy tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + "additionalProperties": false, + "description": "Swap-related metadata for the buy token" }, - "sellTaxBps": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + "sellToken": { + "type": "object", + "properties": { + "buyTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The buy tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "sellTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The sell tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + }, + "transferTaxBps": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The transfer tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" } + }, + "required": [ + "buyTaxBps", + "sellTaxBps", + "transferTaxBps" ], - "nullable": true, - "description": "The sell tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + "additionalProperties": false, + "description": "Swap-related metadata for the sell token" + } + }, + "required": ["buyToken", "sellToken"], + "additionalProperties": false, + "description": "Swap-related metadata for the buy and sell token in the swap" + }, + "totalNetworkFee": { + "allOf": [ + {}, + { + "type": "string", + "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" + } + ], + "nullable": true, + "description": "The estimated total network cost of the swap. On chains where there is no L1 data cost, it is calculated as `gas` * `gasPrice`. On chains where there is an L1 data cost, it is calculated as `gas` * `gasPrice` + L1 data cost." + }, + "zid": { + "type": "string", + "description": "The unique ZeroEx identifier of the request" + }, + "permit2": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["Permit2"], + "description": "`Permit2`" }, - "transferTaxBps": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" - } + "hash": { + "type": "string", + "description": "The hash for the approval according to [EIP-712](https://eips.ethereum.org/EIPS/eip-712). If you compute the hash from eip712 field, it should match the value of this field" + }, + "eip712": { + "type": "object", + "properties": { + "types": { + "type": "object", + "additionalProperties": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { "type": "string" }, + "type": { "type": "string" } + }, + "required": ["name", "type"], + "additionalProperties": false + } + } + }, + "domain": { + "type": "object", + "properties": { + "name": { "type": "string" }, + "version": { "type": "string" }, + "chainId": { "type": "number" }, + "verifyingContract": { + "type": "string" + }, + "salt": { "type": "string" } + }, + "additionalProperties": false + }, + "message": { + "type": "object", + "additionalProperties": { + "anyOf": [ + { "type": "string" }, + { + "type": "array", + "items": { "type": "string" } + }, + { "type": "number" }, + { + "type": "array", + "items": { "type": "number" } + }, + { "type": "boolean" }, + { + "type": "array", + "items": { "type": "boolean" } + }, + {}, + { "type": "array", "items": {} } + ] + } + }, + "primaryType": { "type": "string" } + }, + "required": [ + "types", + "domain", + "message", + "primaryType" ], - "nullable": true, - "description": "The transfer tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + "additionalProperties": false, + "description": "Necessary data for [EIP-712](https://eips.ethereum.org/EIPS/eip-712)" } }, - "required": [ - "buyTaxBps", - "sellTaxBps", - "transferTaxBps" - ], + "required": ["type", "hash", "eip712"], "additionalProperties": false, - "description": "Swap-related metadata for the buy token" + "description": "This is the approval object which contains the necessary fields to submit an approval for this transaction. Null if sell token is the native token or the transaction is a native token wrap / unwrap", + "nullable": true }, - "sellToken": { + "transaction": { "type": "object", "properties": { - "buyTaxBps": { + "to": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The address of the target contract to send call `data` to. Do NOT use this field when setting token allowances — doing so can result in lost funds. Always use `issues.allowance.spender` or `allowanceTarget` for setting allowances." + }, + "data": { + "type": "string", + "description": "The calldata containing transaction execution details to be sent to the `to` address" + }, + "gas": { "allOf": [ {}, { @@ -3161,9 +5780,9 @@ } ], "nullable": true, - "description": "The buy tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + "description": "The estimated gas limit that should be used to send the transaction to guarantee settlement" }, - "sellTaxBps": { + "gasPrice": { "allOf": [ {}, { @@ -3171,10 +5790,9 @@ "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" } ], - "nullable": true, - "description": "The sell tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + "description": "The gas price (in wei) that should be used to send the transaction" }, - "transferTaxBps": { + "value": { "allOf": [ {}, { @@ -3182,112 +5800,42 @@ "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" } ], - "nullable": true, - "description": "The transfer tax in bps of the token. Since each token could have arbitrary implementation, this field is best effort, meaning it would be set to `null` if the system is not able to determine the tax" + "description": "The amount of ether (in wei) that should be sent with the transaction" } }, "required": [ - "buyTaxBps", - "sellTaxBps", - "transferTaxBps" + "to", + "data", + "gas", + "gasPrice", + "value" ], "additionalProperties": false, - "description": "Swap-related metadata for the sell token" - } - }, - "required": ["buyToken", "sellToken"], - "additionalProperties": false, - "description": "Swap-related metadata for the buy and sell token in the swap" - }, - "totalNetworkFee": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" - } - ], - "nullable": true, - "description": "The estimated total network cost of the swap. On chains where there is no L1 data cost, it is calculated as `gas` * `gasPrice. On chains where there is an L1 data cost, it is calculated as `gas` * `gasPrice + L1 data" - }, - "transaction": { - "type": "object", - "properties": { - "to": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The address of the target contract to send call `data` to. Do NOT use this field when setting token allowances — doing so can result in lost funds. Always use `issues.allowance.spender` or `allowanceTarget` for setting allowances." - }, - "data": { - "type": "string", - "description": "The calldata containing transaction execution details to be sent to the `to` address" - }, - "gas": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" - } - ], - "nullable": true, - "description": "The estimated gas limit that should be used to send the transaction to guarantee settlement" - }, - "gasPrice": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" - } - ], - "description": "The gas price (in wei) that should be used to send the transaction" - }, - "value": { - "allOf": [ - {}, - { - "type": "string", - "pattern": "^[-+]?(0|[1-9]\\d*)(\\.\\d+)?$" - } - ], - "description": "The amount of ether (in wei) that should be sent with the transaction" + "description": "This object contains the details required to submit the transaction" } }, "required": [ - "to", - "data", - "gas", - "gasPrice", - "value" + "allowanceTarget", + "blockNumber", + "buyAmount", + "buyToken", + "estimatedNetSellAmount", + "fees", + "issues", + "liquidityAvailable", + "mode", + "routes", + "maxSellAmount", + "sellToken", + "tokenMetadata", + "totalNetworkFee", + "zid", + "permit2", + "transaction" ], - "additionalProperties": false, - "description": "This object contains the details required to submit the transaction" - }, - "zid": { - "type": "string", - "description": "The unique ZeroEx identifier of the request" + "additionalProperties": false } - }, - "required": [ - "allowanceTarget", - "blockNumber", - "buyAmount", - "buyToken", - "fees", - "issues", - "liquidityAvailable", - "minBuyAmount", - "permit2", - "route", - "sellAmount", - "sellToken", - "tokenMetadata", - "totalNetworkFee", - "transaction", - "zid" - ], - "additionalProperties": false + ] }, { "type": "object", @@ -3331,6 +5879,7 @@ "invalidSourcesPassed": [] }, "liquidityAvailable": true, + "mode": "exact-in", "minBuyAmount": "99037162", "permit2": { "type": "Permit2",