Liberty Swap API old

The official integration API for LibertySwap V3. 🚀

Overview

LibertySwap provides an off-chain quoting system that generates executable calldata for supported cross-chain swaps. DApps and integration partners use the API to resolve the source transaction target, calculate fees, and build the transaction that the user signs from their own wallet.

Key Concepts:

• Non-Custodial API: The API never takes custody of user funds or signs on the user's behalf. It only generates transaction payloads for LibertySwap or Circle contracts.

• Cross-Chain Payload Generation: The quote response contains the source transaction target, approval payload when required, calldata, and native value.

• Direct and CCTP Routing: LibertySwap V3 combines Liberty liquidity pools with Circle CCTP V2 Fast Transfer.

• Privacy Swaps: Railgun shielding is integrated into /quote; the API encrypts the raw Railgun recipient and returns ready-to-sign Liberty pool calldata. See Privacy Swaps.

Base URL: https://apis.libertyswap.finance/v3/swap

Quote endpoint: GET /quote

Router registry: GET https://apis.libertyswap.finance/v3/app/routers

Supported Pairs

1. Standard Swaps (Public)

Asset	Inbound: Public Networks → PulseChain	Outbound: PulseChain → Public Networks
USDC	Direct: Ethereum, Base, BSC. CCTP: Avalanche, Arbitrum, Optimism, Polygon, UniChain, Linea, World Chain, Plume, Morph, Ink, Monad, Sonic, Sei, HyperEVM, Pharos, Cronos → USDC	USDC → Direct: Ethereum, Base, BSC. CCTP: Avalanche, Arbitrum, Optimism, Polygon, UniChain, Linea, World Chain, Plume, Morph, Ink, Monad, Sonic, Sei, HyperEVM, Pharos, Cronos
ETH / WETH	Ethereum, Base, Robinhood Chain native ETH → PulseChain WETH	PulseChain WETH → Ethereum, Base, Robinhood Chain native ETH
USDT / DAI	Ethereum USDT/DAI, BSC USDT → PulseChain USDC	(Inbound only)
USD1	BSC USD1 → PulseChain USDC	(Inbound only)

The following source pairs return route.type = CCTP_INBOUND:

Source	Destination
Avalanche USDC	PulseChain USDC
Arbitrum USDC	PulseChain USDC
Optimism USDC	PulseChain USDC
Polygon USDC	PulseChain USDC
UniChain USDC	PulseChain USDC
Linea USDC	PulseChain USDC
World Chain USDC	PulseChain USDC
Plume USDC	PulseChain USDC
Morph USDC	PulseChain USDC
Ink USDC	PulseChain USDC
Monad USDC	PulseChain USDC
Sonic USDC	PulseChain USDC
Sei USDC	PulseChain USDC
HyperEVM USDC	PulseChain USDC
Pharos USDC	PulseChain USDC
Cronos USDC	PulseChain USDC

The CCTP outbound destination list is the same as the CCTP inbound EVM source list above. All other currently supported source transactions target a Liberty pool and return route.type = DIRECT. This includes CCTP outbound: the user first calls the PulseChain pool, and the backend performs the later CCTP leg.

2. Privacy Swaps

LibertySwap's Railgun integration supports shielding and unshielding to reduce transfer linkability.

Asset	Shielding (Public → Railgun)	Unshielding (Railgun → Public)
USDC	PulseChain, Ethereum, Base, BSC → USDC (Railgun Ethereum / BSC)	USDC (Railgun Ethereum / BSC) → PulseChain, Ethereum, Base, BSC
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

Railgun destinations use virtual routing IDs in dstChain; they are not RPC network chain IDs. For shielding, pass the raw 0zk... Railgun address as recipient and 2 as recipientType. Railgun shielding returns route.type = DIRECT because the source transaction targets a Liberty pool.

Shielding quote example:

curl "https://apis.libertyswap.finance/v3/swap/quote?srcToken=USDC&dstToken=USDC&amount=1000000000&srcChain=369&dstChain=69696969&recipient=0zk...&recipientType=2"

Fees

The API calculates the Liberty protocol fee based on bridge direction:

• Public chain → PulseChain: 0.3%

• PulseChain → public chain: 0.5%

• Privacy swaps: 0.5%

For CCTP inbound, the API sets maxFee to Circle's estimated Fast Transfer fee plus a 20% safety margin. This margin applies only to the estimated Circle fee, not to the transferred amount. Liberty absorbs the executed Circle fee, so destAmount reflects the Liberty protocol fee without subtracting the Circle fee a second time.

Amount Limits

The API enforces per-transaction limits. A request outside the configured range returns 400 Bad Request.

• Stablecoins (USDC/USDT/DAI/USD1): minimum 10, maximum 25,000 token units

• ETH / WETH: minimum 0.01, maximum 20 token units

Chain IDs Reference

Pass numeric srcChain and dstChain values:

Network	Chain ID
Ethereum	1
Optimism	10
Cronos	25
BSC	56
UniChain	130
Polygon	137
Monad	143
Sonic	146
PulseChain	369
World Chain	480
HyperEVM	999
Sei	1329
Pharos	1672
Morph	2818
Robinhood Chain	4663
Base	8453
Arbitrum	42161
Avalanche	43114
Ink	57073
Linea	59144
Plume	98866

Railgun uses separate virtual routing IDs. These values are passed as srcChain or dstChain for Railgun flows, but they must not be used as RPC network chain IDs:

Railgun route	Virtual chain ID	Underlying network
Railgun Ethereum	69696969	Ethereum (1)
Railgun BSC	96969696	BSC (56)

API Documentation

Get Quote

GET /quote

Fetches the estimated destination amount and executable source transaction payload.

General Conventions:

• amount is a base-10 integer string in the source token's smallest unit.

• recipient is required. Use a non-zero EVM address for standard swaps or a raw 0zk... address for Railgun shielding.

• methodParameters.value and methodParameters.calldata are hex strings.

• The endpoint currently generates EVM transactions. Solana CCTP instructions require a separate SVM transaction builder.

Example Request:

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

Query Parameters

Parameter	Type	Required	Description
srcToken	string	Yes	Supported source token symbol or address.
dstToken	string	Yes	Supported destination token symbol or address.
amount	string	Yes	Source amount in the token's smallest unit. For example, 1000000 is 1 USDC on a 6-decimal chain.
srcChain	string	Yes	Source network chain ID.
dstChain	string	Yes	Destination network chain ID.
recipient	string	Yes	Receiver address. Use a non-zero EVM address for standard swaps. For Railgun shielding, pass the raw 0zk... address; /quote encrypts and encodes it internally.
recipientType	integer	No	Recipient format: 0 for a standard EVM recipient; 2 for Railgun/CUSTOM. Defaults to 0; a raw 0zk... recipient is automatically encoded as type 2.

Response Schema

Field	Type	Description
to	string	Contract address to receive the source transaction: a Liberty pool for DIRECT, or Circle TokenMessenger V2 for CCTP_INBOUND.
srcToken	object	Resolved source token address, symbol, decimals, and chain ID.
destToken	object	Resolved destination token address, symbol, decimals, and chain ID.
srcAmount	string	Requested source amount in source-token smallest units.
destAmount	string	Estimated amount after the Liberty protocol fee, in destination-token smallest units.
fee.percentage	number	Liberty protocol fee percentage, such as 0.3 or 0.5.
fee.amount	string	Liberty fee in destination-token smallest units.
fee.token	string	Always destination.
approval	object, optional	ERC-20 approval payload. Omitted for a native source token.
approval.token	string	ERC-20 contract that receives the approval transaction.
approval.spender	string	Contract authorized to spend the source token.
approval.amount	string	Required allowance in source-token smallest units.
approval.calldata	string	Encoded ERC-20 approve(spender, amount) calldata.
methodParameters.calldata	string	Encoded main source transaction calldata.
methodParameters.value	string	Native value to send with the main transaction; 0x0 for ERC-20 sources.
route.type	string	DIRECT or CCTP_INBOUND.

CCTP Inbound Response Example

{
  "to": "0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d",
  "srcToken": {
    "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
    "symbol": "USDC",
    "decimals": 6,
    "chainId": 42161
  },
  "destToken": {
    "address": "0x15D38573d2feeb82e7ad5187aB8c1D52810B1f07",
    "symbol": "USDC",
    "decimals": 6,
    "chainId": 369
  },
  "srcAmount": "1000000000",
  "destAmount": "997000000",
  "fee": {
    "percentage": 0.3,
    "amount": "3000000",
    "token": "destination"
  },
  "approval": {
    "token": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
    "spender": "0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d",
    "amount": "1000000000",
    "calldata": "0x..."
  },
  "methodParameters": {
    "calldata": "0x...",
    "value": "0x0"
  },
  "route": {
    "type": "CCTP_INBOUND"
  }
}

CCTP Inbound

For a supported EVM CCTP source USDC → PulseChain USDC request, the API returns Circle TokenMessenger V2 and encodes:

depositForBurnWithHook(
  amount,
  6,                  // Base CCTP domain
  baseHubBytes32,     // mintRecipient
  sourceUsdc,
  baseHubBytes32,     // destinationCaller
  maxFee,
  1000,               // Fast Transfer finality
  hookData
)

The packed hookData layout is:

version(1)
| destChainId(32)
| targetToken(20)
| integratorId(32)
| recipientType(1)
| recipientLength(1)
| recipient(N)

Circle attests the complete burn message, including hookData. The Base Hub reads the destination chain, target token, integrator, recipient type, and recipient from that attested data. Altering these bytes invalidates the attestation, so the relayer cannot redirect the swap.

For ERC-20 sources, first send approval.calldata to approval.token when the existing allowance is below approval.amount. Then send methodParameters.calldata to to with methodParameters.value.

Security Best Practices

IMPORTANT: Verify quote.to before asking the user to sign or broadcasting the transaction.

Official Router Deployments

Current Liberty V3 router deployments are published dynamically by:

GET https://api.libertyswap.finance/v3/app/routers

Do not hardcode a global whitelist copied from this README. Match quote.to against the exact (srcChain, srcToken) deployment. Legacy routers can remain online for historical operations and must not be accepted merely because they appear in an older release.

Recommended Integration Logic

const CCTP_TOKEN_MESSENGER_V2 =
  '0x28b5a0e9C621a5BadaA536219b3a228C8168cf5d';

const quoteResponse = await fetch(quoteUrl);
if (!quoteResponse.ok) {
  throw new Error(`Quote failed with HTTP ${quoteResponse.status}`);
}
const quote = await quoteResponse.json();

if (quote.route.type === 'CCTP_INBOUND') {
  if (quote.to.toLowerCase() !== CCTP_TOKEN_MESSENGER_V2.toLowerCase()) {
    throw new Error('Unexpected Circle TokenMessenger');
  }
} else {
  const routerResponse = await fetch(
    'https://api.libertyswap.finance/v3/app/routers'
  );
  const { data: routers } = await routerResponse.json();

  const expected = routers.find(
    router =>
      router.chainId === Number(srcChain) &&
      router.symbol.toUpperCase() === quote.srcToken.symbol.toUpperCase()
  );

  if (!expected || expected.router.toLowerCase() !== quote.to.toLowerCase()) {
    throw new Error('Unexpected LibertySwap source router');
  }
}

const signer = await provider.getSigner();

if (quote.approval) {
  const approvalTx = await signer.sendTransaction({
    to: quote.approval.token,
    data: quote.approval.calldata,
    value: 0
  });
  await approvalTx.wait();
}

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

const receipt = await sourceTx.wait();
console.log('Source transaction confirmed:', receipt.hash);

The router registry check catches accidental deployment drift. Because the quote API and registry are both LibertySwap infrastructure, integrations requiring an independent trust anchor should pin reviewed deployments in their own configuration.

API Rate Limiting

• Limit: 30 requests per minute per source IP

• Error: Exceeding the limit returns 429 Too Many Requests