API Reference

Token Trading Workflow

❗️

Deprecated Documentation

These documents are no longer maintained. Please visit hub.uniswap.org/docs for the latest documentation.

High Level Message Flow

The diagram below is an a illustration of the token swap flow where steps in gray are taken through the Uniswap Labs API and steps in red are written to the blockchain by the customer.

A high level decision tree diagram showing the progression of API calls required to complete a swap with the help of Uniswap Labs APIs.
  1. The customer checks if they have given the necessary approval to the Permit2 contract to spend the token they intended to swap through a /check_approvalrequest.
    1. If the approval is not yet in place, a fully-formed transaction is returned to the customer to sign.
  2. The customer makes a request for quote for their desired swap using a /quote request.
    1. Quotes are requested whether the customer is seeking to perform a token for token swap, a cross-chain bridge, or a token wrap/unwrap.
    2. Customer specifies their desired execution paths (v2, v3, or v4 protocol pools, or UniswapX) through the protocols array (see more below).
    3. Customer receives back the best available quote and a fully-formed transaction for signature to approve the the swap.
  3. Depending upon the desired outcome and selected protocols, the customer makes either an /order or /swapAPI request
    1. /order requests are submitted when the swap will be filled by a UniswapX RFQ market maker. In this case the order is "gasless" because the market maker will write the transaction to chain to fill the swap.
    2. /swap requests are submitted when the swap will be filled by a "classic" v2, v3, or v4 Uniswap protocol pool, or in the event that the swap is a bridge or a token wrap/unwrap. This is a "gasful" transaction because the customer will write the transaction to the chain to fill the swap.

📘

Protocol Naming Convention

UniswapX, UniswapX_V2, and UniswapX_V3 are alternately referred to as DutchQuote, DutchQuoteV2, and DutchQuoteV3 (respectively) in the API documentation. Additionally, Uniswap_V2 can be referred to as a PriorityQuote (when a UniswapX_V2 request is made on Base or Unichain chains).

Classic is a collective term for the V2, V3, and V4 Uniswap Protocols

Swap Routing

In order to get the appropriate swap routing, it is important to closely consider the values submitted through the /quote protocols and routingPreference fields. We recommend specifying the desired swap routing by specifying all protocols which you feel comfortable using and leaving the routingPreference field blank.

  • The protocols field is used to specify the protocols from which pricing will be considered and through which your swap may eventually be executed. The possible values for the field are V2, V3, V4, UNISWAPX, UNISWAPX_V2, and UNISWAPX_V3
  • The routingPreference field is used to specify the preferred matching strategy. The possible values for the field are BEST_PRICE and FASTEST

🚧

RoutingPreference Deprecation

The routingPreference field previously supported additional values. These additional values are now deprecated (but remain available for legacy integrations). For more information, see the migration section below.

For complete information on the available values and combinations for the protocols and routingPreference fields, see the field descriptions in the /quote page. A summary is provided below:

  • To perform a swap using only Uniswap protocol liquidity pools, specify protocols as V2, V3, and/or V4.
  • To perform a swap using only UniswapX protocol liquidity, specify protocols as UNISWAPX, UNISWAPX_V2, or UNISWAPX_V3. Note that multiple UniswapX protocols may not be specified in the same request.
  • To perform a wrap/unwrap or bridge action, do not specify values for protocols or routingPreference. Note that wrapping/unwrapping is not supported through UniswapX protocols at all and a request to wrap/unwrap when protocols is set to any UniswapX protocol will fail.
  • To obtain the best possible pricing from all protocols or the limited set of protocols specified, set routingPreference to BEST_PRICE
  • To obtain the fastest possible quote from all protocols or the limited set of protocols specified, set routingPreference to FASTEST. (Note that this will not consider private liquidity available via the UniswapX protocols.)

🚧

UniswapX Deprecation

The UNISWAPX value in the protocols field is deprecated (but remains available for legacy integrations). It is recommended that you specify UNISWAPX_V2 or UNISWAPX_V3 if you want to specify the use of a UniswapX protocol. Note that these newer UniswapX protocols provide superior price and fill performance. For more deatils, see https://docs.uniswap.org/contracts/uniswapx/v1vsv2

Migrating from RoutingPreference to Protocols

If you are currently specifying a value for the routingPreference field which is not BEST_PRICE or FASTEST, you are using a deprecated method of specifying your swap routing. We recommend migrating to specifying the protocols you have whitelisted in the protocols field. A mapping of deprecated routingPreference values to new protocols fields are presented in the following table, assuming you permit all protocols values today:

routingPreference Legacy ValueEquivalent protocols Value
CLASSICV2, V3, V4
UNISWAPXUNISWAPX
UNISWAPX_V2UNISWAPX_V2
BEST_PRICEV2, V3, V4, UNISWAPX_V2
BEST_PRICE_V2V2, V3, V4, UNISWAPX_V2
V2_ONLYV2
V3_ONLYV3
FASTESTV2, V3, V4

Bolded routingPreference values are still permitted and will request the listed equivalent protocols fields unless the protocols field contains values which constrain the protocols considered in routing.

The following are some examples of both the legacy and new approaches, as well as some edge cases to consider.

Legacy use of routingPreference

protocols: undefined  
routingPreference: 'BEST_PRICE'  
// protocols considered => ['V2', 'V3', 'V4', 'UNISWAPX']

protocols: undefined  
routingPreference: 'V3_ONLY'  
// protocols considered => ['V3']

New use of protocols and routingPreference

protocols: ['V2', 'V3']  
routingPreference: 'BEST_PRICE'  
// protocols considered => ['V2', 'V3']

protocols: ['V2']  
routingPreference: 'BEST_PRICE'  
// protocols considered => ['V2']

protocols: ['V2', 'V3', 'UNISWAPX', 'UNISWAPX_V2']  
routingPreference: undefined  
// request validation error, you cannot specify UNISWAPX and UNISWAPX_V2 at the same time

protocols: ['V2', 'V3', 'UNISWAPX_V2']  
routingPreference: undefined  
// protocols considered => ['V2', 'V3', 'UNISWAPX_V2']

New use of protocols and routingPreference edge cases

protocols: ['V2', 'V3']  
routingPreference: 'CLASSIC'  
// request validation error, you can only use 'BEST_PRICE' when 'protocols' is defined

Detailed Message Flow

The following diagram provides a more detailed explanation of the API endpoint call flow. In the diagram, the API user (e.g. you) are represented by the "Customer". Additionally note:

  • Every arrow represents a message exchanged between the two indicated parties.
  • Bolded values are API calls or specific fields or values within an API request or response.
  • The import important details of the request or response are called out with helper text, but complete details of every request and response field can be found within the Token Trading endpoints found further on in this documentation.
  • Note that customers must take different actions depending on the result of their /quote request. The /quote request may result in a proposed swap against Uniswap or other public protocols, causing the following API request from the customer to be a /swap. Alternatively, the /quote request may result in a proposed swap with a private liquidity filler, causing the following API request from the customer to be an /order.
Detailed API flow diagram showing an API customer's interaction with Uniswap Labs and with the blockchain.

Additional API Functionality

IndicativeQuote

The /indicative_quote endpoint allows a customer to get the swap rate of one token to another token based on the fastest quote available from liquidity in V2, V3, and V4 Uniswap Protocols.

🚧

IndicativeQuote Deprecation

The /indicative_quote endpoint is planned for deprecation and not recommended for use by new integrators. The endpoint is replaced by performing a /quote request where routingPreference is specified as FASTEST.

Send

The /send endpoint allows a customer to generate an unsigned transaction for sending a single token from one address to another address. The resulting transaction includes a gas fee estimation.

SwapableTokens

The /swppable_tokens endpoint takes a chain and token and returns the list of chains to which that token can be bridged. To clarify, this endpoint is only for use to determine bridging options and is not indicative of which tokens are swapable within a single chain via V2, V3, V4, or UniswapX protocols.