# Liberty Swap API

### Overview <a href="#overview" id="overview"></a>

LibertySwap provides an offchain quoting system that generates secure calldata for cross-chain swaps. By using this API, DApps and integration partners can easily fetch the optimal route, calculate fees, and generate the transaction payload needed to interact with the LibertySwap contracts.

**Key Concepts:**

* **Non-Custodial**: LibertySwap never holds user funds. The API simply generates the payload for the user to sign and execute the transaction from their own wallet.
* **Cross-Chain Payload Generation**: Automatically encodes the required transaction data for your cross-chain transfer.
* **Privacy By Default**: Native support for shielding and unshielding via Railgun, directly integrated into the quoting API.

Base URL: `https://api.libertyswap.finance` Current API Version: `v1`

### Supported Pairs <a href="#supported-pairs" id="supported-pairs"></a>

LibertySwap supports direct pool-to-pool cross-chain swaps optimized for high liquidity and privacy.

#### 1. Standard Swaps (Public) <a href="#standard-swaps-public" id="standard-swaps-public"></a>

| Asset              | Inbound: Public Networks → PulseChain             | Outbound: PulseChain → Public Networks  |
| ------------------ | ------------------------------------------------- | --------------------------------------- |
| **USDC**           | Ethereum, Base, BSC, Arbitrum, Polygon → **USDC** | **USDC** → Ethereum, Base, BSC, Polygon |
| **ETH** / **WETH** | Ethereum (Native ETH) → **WETH**                  | **WETH** → Ethereum (Native ETH)        |
| **USDT** / **DAI** | Ethereum, BSC → **USDC**                          | *(Inbound Only)*                        |
| **USD1**           | BSC → **USDC**                                    | *(Inbound Only)*                        |

#### 2. Privacy Swaps (Railgun) <a href="#privacy-swaps-railgun" id="privacy-swaps-railgun"></a>

Shield and unshield assets to break the linkability of your transfers.

| Asset              | Shielding (Public → Railgun)                                                 | Unshielding (Railgun → Public)                                               |
| ------------------ | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| **USDC**           | PulseChain, Ethereum, Base, BSC, Arb, Polygon → **USDC (Railgun Eth / BSC)** | **USDC (Railgun Ethereum / BSC)** → PulseChain, Ethereum, Base, BSC, Polygon |
| **USDT** / **DAI** | Ethereum, BSC → **USDC (Railgun Ethereum / BSC)**                            | *(Inbound Only)*                                                             |
| **USD1**           | BSC → **USDC (Railgun Ethereum / BSC)**                                      | *(Inbound Only)*                                                             |
| **ETH** / **WETH** | Ethereum, PulseChain → **WETH (Railgun Ethereum / BSC)**                     | **WETH (Railgun Ethereum / BSC)** → PulseChain, Ethereum                     |

### Fees <a href="#fees" id="fees"></a>

The API automatically calculates fees based on the bridge direction and privacy settings: \* **PulseChain → EVM Chains**: **0.5%** \* **EVM Chains → PulseChain**: **0.3%** \* **Privacy Swaps (Railgun)**: **0.5%** (Applies to all shielding & unshielding transfers)

### Amount Limits <a href="#amount-limits" id="amount-limits"></a>

The API enforces strict per-transaction volume limits to ensure liquidity stability. If the requested amount violates these constraints, the API returns an error.

* **Stablecoins (USDC/USDT/DAI/USD1):** Min `10 USDC`, Max `25,000 USDC` equivalent
* **ETH / WETH:** Min `0.01 ETH`, Max `20 ETH`

### Chain IDs Reference <a href="#chain-ids-reference" id="chain-ids-reference"></a>

Developers must pass numeric `srcChain` and `dstChain` IDs representing the networks:

| Network              | Chain ID   |
| -------------------- | ---------- |
| **Ethereum**         | `1`        |
| **PulseChain**       | `369`      |
| **Base**             | `8453`     |
| **BSC**              | `56`       |
| **Polygon**          | `137`      |
| **Arbitrum**         | `42161`    |
| **Railgun Ethereum** | `69696969` |
| **Railgun BSC**      | `96969696` |

### API Documentation <a href="#api-documentation" id="api-documentation"></a>

#### Get Quote <a href="#get-quote" id="get-quote"></a>

`GET /v1/quote`

Fetches the optimal route, estimated fees, and calldata for the transaction.

**General Conventions:**

* Requested `amount` should be a decimal string representing the smallest unit (wei).
* Response `methodParameters.value` and `calldata` are formatted in hex (`0x...`).

**Example Request:**

```
curl "https://apis.libertyswap.finance/swap/v1/quote?srcToken=USDC&dstToken=USDC&amount=1000000000&srcChain=8453&dstChain=369&recipient=0x18d618759B8F22CB9935D9e4d4c91751a890fae5"
```

**Query Parameters**

| Parameter       | Type    | Required | Description                                                                                |
| --------------- | ------- | -------- | ------------------------------------------------------------------------------------------ |
| `srcToken`      | string  | Yes      | The source token address or symbol (e.g., `ETH` or `USDC`).                                |
| `dstToken`      | string  | Yes      | The destination token address or symbol.                                                   |
| `amount`        | string  | Yes      | Amount in wei/smallest unit as a decimal string (e.g. `1000000` for 1 USDC).               |
| `srcChain`      | string  | Yes      | Source network chain ID (e.g. `1`, `8453`).                                                |
| `dstChain`      | string  | Yes      | Destination network chain ID.                                                              |
| `recipient`     | string  | No       | Receiver address. If not provided, it defaults to the zero address.                        |
| `recipientType` | integer | No       | Recipient format constraint. `0`: Standard EVM, `2`: Railgun destination. Defaults to `0`. |

**Response Schema**

| Field                       | Type   | Description                                                                                                                                     |
| --------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `to`                        | string | The Smart Contract Router Address you must send the transaction to.                                                                             |
| `srcToken`                  | object | Details about the source token (address, symbol, decimals, chainId).                                                                            |
| `destToken`                 | object | Details about the destination token.                                                                                                            |
| `srcAmount`                 | string | Source amount specified in the request (decimal string).                                                                                        |
| `destAmount`                | string | Target amount the user will receive *after fees have been deducted* (decimal string).                                                           |
| `fee.percentage`            | number | Bridge fee percentage (e.g., 0.3 or 0.5).                                                                                                       |
| `fee.amount`                | string | Absolute fee amount in the source token’s smallest unit (decimal string).                                                                       |
| `methodParameters.calldata` | string | The raw encoded byte-payload you must pass into the `data` field of your Ethereum transaction.                                                  |
| `methodParameters.value`    | string | The amount of native gas token (in hex format) to pass into the `value` field of your Ethereum transaction. Will be `0x0` for ERC-20 transfers. |

**Response Example:**

```
{
    "to": "0xefB11856C4bE75C276A5C9E286F8032D3E16Ced2",
    "srcToken": {
        "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "symbol": "USDC",
        "decimals": 6,
        "chainId": 8453
    },
    "destToken": {
        "address": "0x15D38573d2feeb82e7ad5187aB8c1D52810B1f07",
        "symbol": "USDC",
        "decimals": 6,
        "chainId": 369
    },
    "srcAmount": "1000000000",
    "destAmount": "997000000",
    "fee": {
        "percentage": 0.3,
        "amount": "3000000"
  },
    "methodParameters": {
        "calldata": "0xed81cfdf0000000000000000000000000000000000000000000000000000000000000171000000000000000000000000000000000000000000000000000000003b9aca0000000000000000000000000000000000000000000000000000000000000000a0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000015d38573d2feeb82e7ad5187ab8c1d52810b1f07000000000000000000000000000000000000000000000000000000000000001418d618759b8f22cb9935d9e4d4c91751a890fae5000000000000000000000000",
        "value": "0x0"
  },
    "route": {
        "paths": [],
        "swaps": [
            {
                "pool": "Direct",
                "in": "USDC",
                "out": "USDC"
            }
        ]
    }
}
```

***

### Security Best Practices <a href="#security-best-practices" id="security-best-practices"></a>

> IMPORTANT: To prevent “Man-in-the-Middle” or DNS/Server compromise attacks, we strongly recommend that integration partners implement a **Contract Whitelist**.

While the API securely computes the most optimal `to` (Router) address for your swap, you should verify this address against our official list of deployments before asking your end-user to sign any transaction.

#### Official Router Addresses (Mainnet) <a href="#official-router-addresses-mainnet" id="official-router-addresses-mainnet"></a>

| Chain          | Asset | Router Address                               |
| -------------- | ----- | -------------------------------------------- |
| **PulseChain** | USDC  | `0xe7EE706a6708b691a232452c9cb267d186942F09` |
| **PulseChain** | WETH  | `0x80C2C603d72ea17A0D85B670D4489eB3012035Cd` |
| **Ethereum**   | USDC  | `0x06291eeE038e94E8DEC2b3bfB6e030c0b5615506` |
| **Ethereum**   | USDT  | `0x12352B55e0b4305Dd83A349A5d7845bE9B5a2Eea` |
| **Ethereum**   | DAI   | `0xAA7a195D69327a894eeb969D3bCb89116FC78A14` |
| **Ethereum**   | ETH   | `0x60FDAf9198eFCD6fAF27D50E955e1A42905f2eeb` |
| **BSC**        | USDC  | `0x43f403972080406e3e6602793A5072DBc4389bAb` |
| **BSC**        | USDT  | `0xc438D51F296fF3e53d061293D2bC4Bb9fb2f7f19` |
| **BSC**        | USD1  | `0x4E839dA8DCd61df10976B926cbF9Ab7D06BfF072` |
| **Base**       | USDC  | `0xefB11856C4bE75C276A5C9E286F8032D3E16Ced2` |
| **Arbitrum**   | USDC  | `0x05216280d45Bb8E8dcb863186E4762090bab7b6F` |
| **Polygon**    | USDC  | `0xcb2b2a70F29a8b7467fA930A09f9271D1eF0E5A9` |

#### Recommended Integration Logic <a href="#recommended-integration-logic" id="recommended-integration-logic"></a>

```
import { ethers } from 'ethers';

// 1. Fetch quote from Liberty API
c>= await fetch(`https://api.libertyswap.finance/v1/quote?srcToken=USDC&...`);
c>= await res.js>;

// 2. SECURITY CHECK: Verify the target router
// Keep this list in sync with the Official Router Addresses table above
c>= new Set([
  "0xe7EE706a6708b691a232452c9cb267d186942F09", // PulseChain  – USDC
  "0x80C2C603d72ea17A0D85B670D4489eB3012035Cd", // PulseChain  – WETH
  "0x06291eeE038e94E8DEC2b3bfB6e030c0b5615506", // Ethereum    – USDC
  "0x12352B55e0b4305Dd83A349A5d7845bE9B5a2Eea", // Ethereum    – USDT
  "0xAA7a195D69327a894eeb969D3bCb89116FC78A14", // Ethereum    – DAI
  "0x60FDAf9198eFCD6fAF27D50E955e1A42905f2eeb", // Ethereum    – ETH
  "0x43f403972080406e3e6602793A5072DBc4389bAb", // BSC         – USDC
  "0xc438D51F296fF3e53d061293D2bC4Bb9fb2f7f19", // BSC         – USDT
  "0x4E839dA8DCd61df10976B926cbF9Ab7D06BfF072", // BSC         – USD1
  "0xefB11856C4bE75C276A5C9E286F8032D3E16Ced2", // Base        – USDC
  "0x05216280d45Bb8E8dcb863186E4762090bab7b6F", // Arbitrum    – USDC
  "0xcb2b2a70F29a8b7467fA930A09f9271D1eF0E5A9", // Polygon     – USDC
].map(addr => addr.toLowerCase()));

if (!OFFICIAL_WHITELIST.has(quote.to.toLowerCase())) {
  throw new Error("Security Alert: Unauthorized Router Address detected!");
}

// 3. Request Signature from User & Broadcast
c>= await provider.getSigner();

c>= await signer.sendTransaction({
  to: quote.to,
  data: quote.methodParameters.calldata,
  value: quote.methodParameters.value
});

c>= await tx.wait();
c>.log('Swap securely executed!', receipt.hash);
```

### API Rate Limiting <a href="#api-rate-limiting" id="api-rate-limiting"></a>

To prevent infrastructure abuse and DDoS attacks, the following rate limits are applied per source IP:

* **Limit:** 30 requests per minute
* **Error:** Exceeding this limit results in a `429 Too Many Requests` status.


---

# 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.libertyswap.finance/resources/liberty-swap-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.