Liberty Swap API

The official API for Liberty Swap! 🚀

Overview

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

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

1. Standard Swaps (Public)

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)

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

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

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

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

Get Quote

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

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)

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

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

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.