0x Trade Analytics API
Read-only API for retrieving the integrator's Swap and Gasless trade history with surplus, fees, taker, route, and per-trade settlement detail — used for monetisation reporting, accounting reconciliation, and dashboarding.
OpenAPI Specification
openapi: 3.0.3
info:
title: 0x API
description: This is the official API reference for the latest 0x API (v2).
version: v2
x-source-url: https://github.com/0xProject/0x-docs/blob/main/fern/openapi.json
x-last-validated: '2026-05-28'
servers:
- url: https://api.0x.org
paths:
/swap/allowance-holder/price:
get:
operationId: swap::allowanceHolder::getPrice
summary: Get Price (Allowance Holder)
description: Get the indicative price for a swap using Allowance Holder to set allowances
tags:
- Swap
parameters:
- description: Visit dashboard.0x.org to get your API Key
in: header
name: 0x-api-key
required: true
schema:
type: string
- description: API version
in: header
name: 0x-version
required: true
schema:
type: string
example: v2
- name: chainId
in: query
required: true
schema:
type: integer
exclusiveMinimum: true
minimum: 0
description: Chain ID. See [here](https://docs.0x.org/docs/introduction/supported-chains) for the list of supported
chains
example: 1
- name: buyToken
in: query
required: true
schema:
type: string
pattern: ^0x(?!0{40})[a-fA-F0-9]{40}$
description: The contract address of the token to buy
example: '0xdac17f958d2ee523a2206206994597c13d831ec7'
- name: sellToken
in: query
required: true
schema:
type: string
pattern: ^0x(?!0{40})[a-fA-F0-9]{40}$
description: The contract address of the token to sell
example: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
- name: sellAmount
in: query
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
required: false
schema:
type: string
pattern: ^0x[a-fA-F0-9]{40}$
description: The address which holds the `sellToken` balance and has the allowance set for the swap
example: '0x70a9f34f9b34c64957b9c401a97bfed35b95049e'
- name: txOrigin
in: query
required: false
schema:
type: string
pattern: ^0x[a-fA-F0-9]{40}$
description: The address of the external account that started the transaction. This is only needed if `taker` is a
smart contract.
- name: recipient
in: query
required: false
schema:
type: string
pattern: ^0x[a-fA-F0-9]{40}$
description: The address to receive the `buyToken`. If not provided, defaults to the taker address. Not supported
for wrap/unwrap operations.
- name: swapFeeRecipient
in: query
required: false
schema:
type: string
pattern: ^\s*0x[a-fA-F0-9]{40}(\s*,\s*0x[a-fA-F0-9]{40})*\s*$
description: The wallet address to receive the specified trading fees (supports single or multiple comma-separated
values). You must also specify the `swapFeeBps` in the request to use this feature. When multiple values are provided,
must match length of `swapFeeBps`.
- name: swapFeeBps
in: query
required: false
schema:
type: string
pattern: ^\s*\d+(\s*,\s*\d+)*\s*$
description: The amount in Bps of the `swapFeeToken` to charge and deliver to the `swapFeeRecipient` (supports single
or multiple comma-separated values). You must also specify the `swapFeeRecipient` in the request to use this feature.
For security, this field has a default limit of 1000 Bps. If your application requires a higher value, please reach
out to us.
- name: swapFeeToken
in: query
required: false
schema:
type: string
pattern: ^\s*0x(?!0{40})[a-fA-F0-9]{40}(\s*,\s*0x(?!0{40})[a-fA-F0-9]{40})*\s*$
description: The contract address of the token to receive trading fees in (supports single or multiple comma-separated
values). Each token must be set to the value of either the `buyToken` or the `sellToken`. If omitted, the fee token
will be determined by 0x with preference to stablecoins and highly liquid assets. You must also specify the `swapFeeRecipient`
and `swapFeeBps` to charge integrator fees. When multiple values are provided, must match length of `swapFeeBps`.
- name: tradeSurplusRecipient
in: query
required: false
schema:
type: string
pattern: ^0x[a-fA-F0-9]{40}$
description: The address to receive any trade surplus. If specified, this address will receive trade surplus when
applicable. Otherwise, the taker will receive the surplus. This feature is only available to selected integrators
on a custom pricing plan. In other cases, the surplus will be collected by 0x. For assistance with a custom plan,
please contact support.
- name: tradeSurplusMaxBps
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 10000
description: The maximum trade surplus (positive slippage) that can be collected in Bps of the buy amount. If not
provided, defaults to 10000 (100%). Must be used together with `tradeSurplusRecipient`.
- name: gasPrice
in: query
required: false
schema:
type: string
description: The target gas price (in wei) for the swap transaction. If not provided, the default value is based on
the 0x gas price oracle
- name: slippageBps
in: query
required: false
schema:
type: integer
minimum: 0
maximum: 10000
description: The maximum acceptable slippage of the `buyToken` in Bps. If this parameter is set to 0, no slippage
will be tolerated. If not provided, the default slippage tolerance is 100Bps
- name: slippagePpm
in: query
required: false
schema:
type: integer
minimum: 0
maximum: 1000000
description: The maximum acceptable slippage of the `buyToken` in parts-per-million (PPM). Mutually exclusive with
`slippageBps`. e.g. 3000 PPM = 30 BPS = 0.30%.
- name: excludedSources
in: query
required: false
schema:
type: string
description: Liquidity sources e.g. Uniswap_V3, SushiSwap, 0x_RFQ to exclude from the provided quote. See https://api.0x.org/sources?chainId=<chain_id>
with the desired chain's ID for a full list of sources. Separate multiple sources with a comma
- name: sellEntireBalance
in: query
required: false
schema:
type: string
enum:
- 'true'
- 'false'
default: 'false'
description: If set to `true`, the taker's entire `sellToken` balance will be sold during trade execution. The `sellAmount`
should be the maximum estimated value, as close as possible to the actual taker's balance to ensure the best routing.
Selling more than the `sellAmount` may cause the trade to revert. This feature is designed for cases where the precise
sell amount is determined during execution. Learn more [here](https://docs.0x.org/docs/0x-swap-api/additional-topics/sell-entire-balance).
- name: wrapUnwrapMode
in: query
required: false
schema:
anyOf:
- not: {}
- type: string
enum:
- direct
- settler
description: Controls how native wrap/unwrap trades are executed. `direct` calls the wrapped-native token contract
directly. `settler` routes wrap/unwrap through Settler or Allowance Holder for compatibility. Ignored for non-wrap/unwrap
swaps. If omitted, `direct` mode is used.
responses:
'200':
description: Successful response
content:
application/json:
schema:
anyOf:
- 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:
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. It contains the `integratorFee`, `zeroExFee`
and `gasFee`
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`
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: ^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 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
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
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
- fees
- issues
- liquidityAvailable
- minBuyAmount
- mode
- route
- sellAmount
- sellToken
- tokenMetadata
- totalNetworkFee
- zid
- gas
- gasPrice
additionalProperties: false
- 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:
integratorFee:
type: object
properties:
amount:
allOf:
- {}
- type: string
# --- truncated at 32 KB (421 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/0x/refs/heads/main/openapi/0x-api.yaml