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