# 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>.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.unizen.io/permit2/usage-in-our-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.