Get started with Gasless API

Learn how to send your first Gasless API request.

About Gasless API

Gasless API allows developers to create the smoothest trading experience in DeFi by abstracting away the complexities related to approvals, allowances, and swaps for their users.

Enabling Gasless API in your app allows you to:

• build more intuitive user interfaces and user flows in your applications
• improve your conversion funnel drop-offs due to insufficient gas, and
• set yourself up to easily onboard the next wave of users into Web3.

Make sure to read Understanding Gasless API for an in-depth understanding of how it works, key terms, and technical flow charts for how to implement in-app.

This guide will walk you through the scenario of using Gasless API when a user is:

• selling USDC, a non-native, ERC-20 token on Polygon that supports Permit (EIP-2612),
• no prior token allowance has been set and approval is required,
• the token is on the gasless approvals token list, so we can perform gasless approvals

See other user flows here.

0. Before you begin

Get a 0x API key

Every call to a 0x API must include a 0x API secret key. Get one from the 0x Dashboard.

Enable Gasless API from your dashboard

If you have been granted access to Gasless API, you will be able to enable Gasless API in your app from "App Settings" in your 0x dashboard. You can enable it for any active apps you have (see screenshot).

1. Get an indicative price

Use /tx-relay/v1/swap/price to get the indicative price. This is used when the user is just browsing for the price they could receive on the specified asset pair, but they are not ready to submit the quote yet.

This endpoint responds with pricing information, but the response does not contain a full 0x order, so it does not constitute a full transaction that can be submitted to the Ethereum network (you must use /quote for this). Think of /price as the the "read-only" version of /quote.

Example request

Here is an example indicative price request to sell 100 USDC (supports Permit) for WETH (does not support Permit) using /price on Polygon (137):

https://api.0x.org/tx-relay/v1/swap/price              // Request an indicative price
?sellToken=0x2791Bca1f2de4661ED88A30C99A7a9449Aa8417   // Sell USDC
&sellAmount=100000000                                  // Sell amount 100 USDC (6 decimals)
&buyToken=0x0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270   // Buy WMATIC
&takerAddress=$USER_TAKER_ADDRESS                      // Address that will make the trade
--header '0x-api-key: [API_KEY]'                       // Replace with your own API key
--header '0x-chain-id: 137'                            // Supports Ethereum (1), Polygon (137), `42161` (Arbitrum), `8453` (Base) and `10` (Optimism)

Sample cURL request

curl 'https://api.0x.org/tx-relay/v1/swap/price?buyToken=0x0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270&sellAmount=100000000&sellToken=0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174&takerAddress=<TAKER_ADDRESS>&priceImpactProtectionPercentage=0.95&feeType=volume&feeSellTokenPercentage=0.01&feeRecipient=<FEE_RECIPIENT_ADDRESS>' \
--header '0x-api-key: <API_KEY>' \
--header '0x-chain-id: 137'

Example response

{
  "liquidityAvailable": true,
  "buyAmount": "99887369",
  "buyTokenAddress": "0xc2132d05d31c914a87c6611c10748aeb04b58e8f",
  "estimatedPriceImpact": "0",
  "price": "0.998873",
  "sellAmount": "100000000",
  "sellTokenAddress": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
  "grossBuyAmount": "100005950",
  "grossSellAmount": "100000000",
  "grossPrice": "1.000059",
  "grossEstimatedPriceImpact": "0",
  "sources": [
    {
      "name": "DODO",
      "proportion": "1"
    }
  ],
  "fees": {
    "zeroExFee": {
      "feeType": "volume",
      "feeToken": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
      "feeAmount": "100000",
      "billingType": "on-chain"
    },
    "gasFee": {
      "feeType": "gas",
      "feeToken": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
      "feeAmount": "18574",
      "billingType": "on-chain"
    }
  },
  "allowanceTarget": "0xdef1c0ded9bec7f1a1670819833240f027b25eff"
}

2. Get a firm quote

When the user has found a price they are happy with and are ready to fill a quote, they should request a firm quote from Gasless API using the /tx-relay/v1/swap/quote endpoint. At this point, the taker is making a soft commitment to fill the suggested orders, and understands they may be penalized by the Market Maker if they do not.

tip

Quote expire in ~ 30s in order to ensure freshness.Make sure to take this into account when building your app with a timer and/or automatic refresh.

Example request

Here is an example to fetch a firm quote to sell 100 USDC (supports Permit) for WETH (does not support Permit) using /quote on Polygon (137):

https://api.0x.org/tx-relay/v1/swap/quote              // Request a firm quote
?sellToken=0x2791Bca1f2de4661ED88A30C99A7a9449Aa8417   // Sell USDC
&sellAmount=100000000                                  // Sell amount 100 USDC (6 decimals)
&buyToken=0x0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270   // Buy WMATIC
&checkApproval=true                                    // If true, check for approval and uses gasless approval feature
&takerAddress=$USER_TAKER_ADDRESS                      // Address that will make the trade
--header '0x-api-key: [API_KEY]'                       // Replace with your own API key
--header '0x-chain-id: 137'                            // Supports Ethereum (1), Polygon (137), `42161` (Arbitrum), `8453` (Base) and `10` (Optimism)

Sample cURL request

curl 'https://api.0x.org/tx-relay/v1/swap/quote?buyToken=0x0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270&sellAmount=100000000&sellToken=0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174&takerAddress=<TAKER_ADDRESS>&priceImpactProtectionPercentage=0.95&feeType=volume&feeSellTokenPercentage=0.01&feeRecipient=<FEE_RECIPIENT_ADDRESS>' \
--header '0x-api-key: <API_KEY>' \
--header '0x-chain-id: 137'

checkApproval parameter

The request parameters for /quote are the same as /price except with an extra field checkApproval.

This optional boolean checks for approval and potentially utilizes gasless approval feature. Its allowed values are true or false, the default to false if not provided.

/tx-relay/v1/swap/quote responds with a full 0x order, which can be submitted to an Ethereum node by the client. Therefore it is expected that the maker has reserved the maker assets required to settle the trade, leaving the order unlikely to revert.

Example responses

If liquidity is available, 2 objects may be returned:

• trade: this object will contains the necessary information to process a trade, for example, which of the 2 possible types this trade is (metatransaction_v2 or otc). Read more here.

• approval: if checkApproval=true was passed to /quote, this object will be returned. If we are able to initiate a gasless approval for the sell token, this object will contain the necessary information to process a gasless approval. Read more here.

See here for examples of possible responses:

• Liquidity Unavalable Responses
• Example Meta-Transaction V2 Response
• Example OTC Response

3. Submit transaction

When user accepts the quote and wants to submit the trade, use /tx-relay/v1/swap/submit to send both signatures back along with the payload from /quote.

In order to submit the trade, we must complete the following:

• Sign the gasless approval (if applicable)
• Sign the trade object
• Split signatures for both signed objects
• Package both signed objects in a format that is acceptable to POST to /submit
• Optional, compute trade hash

Example request

curl -X POST '<https://api.0x.org/tx-relay/v1/swap/submit>' --header '0x-api-key: <API_KEY>' --header '0x-chain-id: 137' --data '{
 "trade": {
   "type": "metatransaction_v2", // this is trade.type from the /quote endpoint
   "eip712": { /* this is trade.eip712 from the /quote endpoint */ },
   "signature": {
     "v": 27,
     "r": "0xeaac9ddbbf9b251a384eb4a545a2800a6d7aca4ceb5e5a3154ddd0d2923533d2",
     "s": "0x601deadfd33bd8b0ad35468613eabcac0a250a7a32035e261a13e2dcbc462e49",
     "signatureType": 2
    }
  },
 "approval":{
     "type": "permit", // this is approval.type from the /quote endpoint
     "eip712": {/* this is approval.eip712 from the /quote endpoint */},
     "signature": {
       "v": 28,
       "r": "0x55c26901285d5cb4d9d1ebb2828122fd6c334b343901944d34a810b3d2d79773",
       "s": "0x20854d829e3118c3f780228ca83fac6154060328a90d2a21267c9f7d1ae9e53b",
       "signatureType": 2
    }
  }
}'

Example response

{
  "type": "metatransaction_v2",
  "tradeHash": "0xde5a11983edd012047dd3107532f007a73ae488bfb354f35b8a40580e2a775a1"
}

More information on signing 0x orders is available here.

4. Check trade status

Once the user has signed and submitted both signatures (gasless approval and meta-transaction), and a tradeHash is returned from /quote, you can poll /tx-relay/v1/swap/status/:trade-hash to check the status of the trade.

Example request

curl '<https://api.0x.org/tx-relay/v1/swap/status/0xd114c77249bb3a137634afeba1ea1c8d6080c687c1a00cc4137fd9cb905a5fb6>' \\
--header '0x-api-key: <API_KEY>' --header '0x-chain-id: 137'

Example response

// confirmed
{
    "status": 'confirmed',
    "transactions": [{
        "hash": "0x...",
        "timestamp": 1624290253193
    }]
}

// failed due to transaction reverted
{
    "status": "failed",
    "transactions": [{
        "hash": "0x...",
        "timestamp": 1624290253193
    }],
    "reason": "transaction_reverted"
}

See here for:

• Shape of Response
• Possible Reasons for Failure
• Status Codes

Once the trade is successful, you can display the transaction confirmation to your user.

Learn more

To see an example of how to integrate Gasless API, checkout this guide along with the code for the Demo App (Next.js).

Also read,

• Understanding Gasless API
• Gasless FAQ