Usage in our api

Using permitData to Enhance Permit2 in the Trading API

This document explains how to leverage the permitData field with the Permit2 mechanism in the trading API for efficient and secure token approvals. The endpoint in focus is:

Endpoint: GET /single-chain/swap

---

What is permitData?

permitData is an advanced feature provided by the API to facilitate gas-efficient and user-friendly token approvals. By utilizing Permit2, permitData enables off-chain signatures for token allowances, which can be submitted on-chain without requiring the user to send a separate approval transaction.

This eliminates the need for traditional ERC-20 approve calls, streamlining the trading experience while saving gas costs and improving security.

---

How permitData Works

1. Off-Chain Signature: The user signs a permit message off-chain authorizing the trading contract to spend their tokens.

2. On-Chain Execution: The signed permitData is sent along with the swap request to the /single-chain/swap endpoint.

3. Token Allowance: The contract uses Permit2 to verify the signature and execute the swap, avoiding a separate on-chain approval step.

---

Workflow to Use permitData

1. Retrieve permitData Structure

To generate the permitData that the user needs to sign, follow these steps:

1. Prepare the Request Payload:

   • Prepare the data required for Permit2 signed typed data, including token, amount, spender, nonce, and deadline. Generate the typed data for signing using either @uniswap/permit2-sdk or any method of your choice.

   • Ensure the token being approved supports Permit2.

   • Ensure that you sent version=v2 on the quote request endpoint, as this feature it's only available in v2 version of our smart contract.

2. User Signs the Data:

   • Obtain the user’s signature on the permitData using a wallet (e.g., MetaMask or hardware wallet). (for example: https://viem.sh/docs/actions/wallet/signTypedData.html)

   • with the signature after sign, this is the permitData format:

   "permitData": {
       "user": "0x2472d3EF4bF71af00c3dE490a5a53A99CbAC0791", // user address
       "amount": "8018856", // amount to trade
       "deadline": 1734451256, // deadline for the permit2 signature
       "nonce": 3791859555499801, // random nonce https://github.com/shonentropy3/cdeer/blob/15faa9d33e6ded2cececf3ecf3e1c07b99b58943/front/pages/order.js#L134
       "sign": "0xbdd2d80ced…7a1c" // result of signTypedData
   }

---

2. Call the Swap Endpoint with permitData

Send the signed permitData to the /single-chain/swap endpoint along with the other required parameters:

Request Example:

{
  "transactionData": {},
  "nativeValue": "0",
  "amount": "1000000000000000000", // Amount in smallest units (e.g., wei)
  "account":  "0xF0Fbf42C54Ac40dA016003baD35E5AefaC6E1CE1",
  "receiver":  "0xF0Fbf42C54Ac40dA016003baD35E5AefaC6E1CE1",
  "tradeType" : "0",
  "permitData": {
    "user": "0x2472d3EF4bF71af00c3dE490a5a53A99CbAC0791",
    "amount": "8018856",
    "deadline": 1734451256,
    "nonce": 3791859555499801,
    "sign": "0xbdd2d80ced…7a1c
  }
}

Response Example:

{
  "data": {},
  "contractVersion": "v1",
  "estimateGas": "11231133211313",
  "estimateGasError": "Execution reverted",
  "nativeValue": "0",
  "allowance": "56442235035",
  "insufficientFunds": false,
  "insufficientAllowance": false,
  "insufficientGas": false,
  "maxFeePerGas": "20748300881",
  "maxPriorityFeePerGas": "maxPriorityFeePerGas",
  "gasPrice": "56442235035",
  "estimateGasRawError": "Error: invalid BigNumber string (argument=\"value\", value=\"\", code=INVALID_ARGUMENT, version=bignumber/5.7.0)"
}

---

Benefits of Using permitData

1. Gas Savings:

   • Eliminates the need for a separate approval transaction, reducing gas costs.

2. Enhanced Security:

   • Users can provide time-limited and amount-specific allowances, minimizing exposure to potential exploits.

3. Streamlined UX:

   • Allows users to sign once off-chain and execute swaps seamlessly without additional approval steps.

4. Batch Approvals:

   • Permit2 enables batch approvals and allowances for multiple tokens, optimizing multi-token swaps.

---

Best Practices

1. Validate permitData Before Execution:

   • Ensure the permitData signature is valid and corresponds to the intended swap parameters.

2. Handle Expiry Gracefully:

   • Monitor the deadline field in the permitData to ensure it hasn’t expired before sending the transaction.

3. Test with Supported Tokens:

   • Verify that the tokens involved in the swap support Permit2. Tokens without Permit2 support will require traditional approvals.

---

Key Notes

• Permit2 is only supported on compatible tokens and networks.

• Ensure that the spender address matches the contract that will execute the swap.

• Keep the signed permitData secure and ensure it is only used for the intended transaction.

By incorporating permitData and Permit2 into your trading workflow, you can enhance user experience, save gas, and improve transaction efficiency. For additional details, refer to the full API documentation at https://api.zcx.com/trade/docs#/Single%20chain%20methods/SwapSingleController_getSingleSwap.