> For the complete documentation index, see [llms.txt](https://docs.unizen.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.unizen.io/permit2/usage-in-our-api.md).

# 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`](https://www.npmjs.com/package/@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**:

```json
{
  "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**:

```json
{
  "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>.