Skip to main content

API References

Introduction​

The 0x Orderbook API is deployed on the following chains:

NetworkEndpoint
Ethereum (mainnet)https://api.0x.org/
Polygonhttps://polygon.api.0x.org/
Binance Smart Chainhttps://bsc.api.0x.org/

Versioning​

Each 0x HTTP API path is versioned independently using URI versioning. The format is: https://api.0x.org/<path>/<version>/<endpoint>.

For example, you can request https://api.0x.org/swap/v1/quote which represents v1 of the quote endpoint in the swap path. URLs not adhering to this format are not supported.

A major version bump occurs whenever a backwards incompatible change occurs to an endpoint, in which case every endpoint in that path will be on the next version. Old versions of the API will be deprecated and new features will be rolled out to them on a best-effort basis.

Pagination​

Requests that return potentially large collections are paginated and respond to the page and perPage parameters.

Any endpoint that follows this convention will display the following:

This endpoint is paginated.

And will only document the objects in the records field.\

By default, a request returns page 1 with 20 orders. It is possible to change which page and how many records are returned per page via the query parameters. For example, to fetch page 3 with 50 records per page:

https://api.0x.org/orderbook/v1/orders?page=3&perPage=20

Request​

Query ParamDescription
page(Optional, defaults to "1") The page index (1-indexed) requested in the collection.
perPage(Optional, defaults to "20") The amount of records to return per page. The maximum is "1000".

Response​

FieldDescription
pageThe page index (1-indexed) of returned in the response (same as request if provided).
perPageThe amount of records requested in the pagination, but not necessarily returned.
totalThe total amount of records in the collection (across all pages).
recordsThe actual records returned for this page of the collection.

If a query provides an unreasonable (ie. too high) perPage value, the response can return a validation error as specified in the errors section. If the query specifies a page that does not exist (ie. there are not enough records), the response will return an empty records array.

Allowance Targets​

Some interactions with 0x require or are improved by setting token allowances, or in other words, giving 0x's smart contracts permission to move certain tokens on your behalf. Some examples include -

  • Submitting a 0x API quote selling ERC20 tokens, you will need to give an allowance to the contract address. This address can be found either as the value of allowanceTarget returned in the quote response or in the ExchangeProxy Address column in the "Addresses by Network" table below.
  • Trading ERC20 tokens using the Exchange contract, you will have to give an allowance to the ERC20Proxy contract.
  • Note: For swaps with "ETH" as sellToken, wrapping "ETH" to "WETH" or unwrapping "WETH" to "ETH" no allowance is needed, a null address of 0x0000000000000000000000000000000000000000 is then returned instead.

Addresses by Network​

The following table includes commonly used contract addresses. For a full list of our smart contract deployments address, see the0x-cheat-sheet.md .

NetworkExchangeProxy AddressERC20Proxy AddressStakingProxy Address
Ethereum (mainnet)0xdef1c0ded9bec7f1a1670819833240f027b25eff0x95e6f48254609a6ee006f7d493c8e5fb97094cef0xa26e80e7dea86279c6d778d702cc413e6cffa777
Polygon0xdef1c0ded9bec7f1a1670819833240f027b25eff0x00000000000000000000000000000000000000000x0000000000000000000000000000000000000000
Binance Smart Chain0xdef1c0ded9bec7f1a1670819833240f027b25eff0x00000000000000000000000000000000000000000x0000000000000000000000000000000000000000
Optimism0xdef1abe32c034e558cdd535791643c58a13acc100x00000000000000000000000000000000000000000x0000000000000000000000000000000000000000
Fantom0xdef189deaef76e379df891899eb5a00a94cbc2500x00000000000000000000000000000000000000000x0000000000000000000000000000000000000000
Celo0xdef1c0ded9bec7f1a1670819833240f027b25eff0x00000000000000000000000000000000000000000x0000000000000000000000000000000000000000
Avalanche0xdef1c0ded9bec7f1a1670819833240f027b25eff0x00000000000000000000000000000000000000000x0000000000000000000000000000000000000000

Errors​

Unless the spec defines otherwise, errors to bad requests should respond with HTTP 4xx or status codes.

Common Error Codes​

CodeReason
400Bad Request – Invalid request format
404Not found
429Too many requests - Rate limit exceeded
500Internal Server Error
501Not Implemented
503Server Error - Too many open connections

Error reporting format​

For all 400 responses, see the error response schema.

{
    "code": 101,
    "reason": "Validation failed",
    "validationErrors": [
        {
            "field": "maker",
            "code": 1002,
            "reason": "Invalid address"
        }
    ]
}

General error codes​

CodeReason
100Validation Failed
101Malformed JSON
102Order submission disabled
103Throttled
104Not Implemented
105Transaction Invalid

Validation error codes​

CodeReason
1000Required field
1001Incorrect format
1002Invalid address
1003Address not supported
1004Value out of range
1005Invalid signature or hash
1006Unsupported option
1007Invalid 0x order
1008Internal error
1009Token is not supported
1010Field is invalid

Common Objects​

This section outlines API JSON objects that are common to many endpoints.

Signed Order​

A 0x Limit Order with additional fields and ready to be consumed by our tooling and sent to the 0x exchange proxy contract.

FieldDescription
makerThe address of the party that creates the order. The maker is also one of the two parties that will be involved in the trade if the order gets filled.
takerThe address of the party that is allowed to fill the order. If set to a specific party, the order cannot be filled by anyone else. If left unspecified, anyone can fill the order.
makerTokenThe address of the ERC20 token the maker is selling to the taker.
takerTokenThe address of the ERC20 token the taker is selling to the maker.
makerAmountThe amount of makerToken being sold by the maker
takerAmountThe amount of takerToken being sold by the taker
expiryTimestamp in seconds of when the order expires. Expired orders cannot be filled.
saltA value that can be used to guarantee order uniqueness. Typically it is set to a random number.
feeRecipientThe address of the entity that will receive any fees stipulated by the order. This is typically used to incentivize off-chain order relay.
poolThe staking pool to attribute the 0x protocol fee from this order. Set to zero to attribute to the default pool, not owned by anyone.
takerTokenFeeAmountAmount of takerToken paid by the taker to the feeRecipient.
senderAn advanced field that doesn't need to be set. It allows the maker to enforce that the order flow through some additional logic before it can be filled (e.g., a KYC whitelist) -- more on the ability to extend 0x later.
verifyingContractAddress of the contract where the transaction should be sent, usually this is the 0x exchange proxy contract.
chainIdThe ID of the Ethereum chain where the verifyingContract is located.
signatureA JSON object with the signature of the fields above using the private key of maker. The fields of the signature object are documented in the table below.

Signature​

A structured object containing the signature data for the order. For more info see How to sign.

FieldDescription
signatureTypeA number representing the signature method used for signing the order, EIP712 (2) and EthSign (3) are supported.
rA hexadecimal string with signature data.
sA hexadecimal string with signature data.
vAn integer number with signature data.

Misc.​

  • All requests and responses should be of "application/json" content type.
  • All token amounts are sent in amounts of the smallest level of precision (base units). (e.g if a token has 18 decimal places, selling 1 unit of the token would show up as selling 1000000000000000000 base units by this API).
  • All addresses are sent as lower-case (non-checksummed) Ethereum addresses with the 0x prefix.
  • All parameters should use lowerCamelCase.