Get Quote API
Get real-time pricing and routing information for cross-chain payments. This API provides accurate quotes with transparent fee breakdown and optimal routing paths.
Endpoint
POST /v1/quote/getAuthentication
This endpoint requires API key authentication:
Authorization: Bearer YOUR_API_KEYRequest Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
checkoutId | string | ✅ | Checkout session identifier |
paymentToken | TokenInfo | ✅ | Token user wants to pay with |
settlementToken | TokenInfo | ✅ | Token merchant wants to receive |
amount | string | ✅ | Payment amount |
amountType | string | ✅ | Amount type: exactInput or exactOutput |
slippageTolerance | number | ❌ | Maximum acceptable slippage (default: 0.5%) |
userAddress | string | ❌ | User's wallet address for balance checks |
routePreference | string | ❌ | Route optimization: fastest, cheapest, or balanced |
TokenInfo Object
interface TokenInfo {
address: string; // Token contract address
decimals: number; // Token decimals
symbol: string; // Token symbol (e.g., "USDC", "ETH")
name?: string; // Token full name
chainId: number; // Blockchain network ID
}Example Request
{
"checkoutId": "checkout_1759231185333_abc123",
"paymentToken": {
"address": "0x7F5c764cBc14f9669B88837ca1490cCa17c31607",
"decimals": 6,
"symbol": "USDC.e",
"name": "USD Coin (Bridged)",
"chainId": 10
},
"settlementToken": {
"address": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
"decimals": 6,
"symbol": "USDC",
"name": "USD Coin",
"chainId": 137
},
"amount": "100.00",
"amountType": "exactOutput",
"slippageTolerance": 0.5,
"userAddress": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8e8",
"routePreference": "balanced"
}Response Format
Success Response
{
"success": true,
"data": {
"quoteId": "quote_1759231185333_abc123",
"checkoutId": "checkout_1759231185333_def456",
"status": "valid",
"paymentAmount": "100.50",
"settlementAmount": "100.00",
"minimumReceived": "99.50",
"exchangeRate": "0.9950",
"estimatedTime": 420,
"checks": {
"allowance": {
"token": "0x7F5c764cBc14f9669B88837ca1490cCa17c31607",
"spender": "0x89415a82d909a7238d69094C3Dd1dCC1aCbDa85C",
"actual": "115792089237316195423570985008687907853269984665640564039457584007913127120885",
"expected": "1012743"
},
"balance": {
"token": "0x7F5c764cBc14f9669B88837ca1490cCa17c31607",
"actual": "9454481",
"expected": "1012743"
}
},
"steps": {
"originSwap": {
"tokenIn": {
"decimals": 6,
"symbol": "USDC.e",
"address": "0x7F5c764cBc14f9669B88837ca1490cCa17c31607",
"name": "USD Coin (bridged)",
"chainId": 10
},
"tokenOut": {
"address": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
"decimals": 6,
"symbol": "USDC",
"chainId": 10
},
"inputAmount": "1012743",
"outputAmount": "1010025",
"minOutputAmount": "1010025",
"maxInputAmount": "1012743",
"swapProvider": {
"name": "lifi",
"sources": ["sushiswap"]
}
},
"bridge": {
"inputAmount": "1005000",
"outputAmount": "1003162",
"tokenIn": {
"address": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
"decimals": 6,
"symbol": "USDC",
"chainId": 10
},
"tokenOut": {
"decimals": 6,
"symbol": "USDC",
"address": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
"name": "USD Coin",
"chainId": 137
},
"fees": {
"totalRelay": {
"pct": "1831028712150619",
"total": "1838"
},
"relayerCapital": {
"pct": "100000000000000",
"total": "100"
},
"relayerGas": {
"pct": "1671641791044776",
"total": "1679"
},
"lp": {
"pct": "59386921105843",
"total": "59"
}
}
}
},
"fees": {
"total": {
"amount": "12845",
"amountUsd": "0.012841189842999978",
"pct": "12683405866169017",
"token": {
"decimals": 6,
"symbol": "USDC.e",
"address": "0x7F5c764cBc14f9669B88837ca1490cCa17c31607",
"name": "USD Coin (bridged)",
"chainId": 10
}
},
"originGas": {
"amount": "650223906530",
"amountUsd": "0.002700132798734608",
"token": {
"chainId": 10,
"address": "0x0000000000000000000000000000000000000000",
"decimals": 18,
"symbol": "ETH"
}
},
"destinationGas": {
"amount": "7506235586405534",
"amountUsd": "0.001678326721",
"pct": "1657704561550702",
"token": {
"chainId": 137,
"address": "0x0000000000000000000000000000000000000000",
"decimals": 18,
"symbol": "MATIC"
}
},
"relayerCapital": {
"amount": "100",
"amountUsd": "0.0000999599",
"pct": "98731659413383",
"token": {
"address": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
"decimals": 6,
"symbol": "USDC",
"chainId": 10
}
},
"lpFee": {
"amount": "59",
"amountUsd": "0.000058976341",
"pct": "58251679053896",
"token": {
"address": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
"decimals": 6,
"symbol": "USDC",
"chainId": 10
}
},
"relayerTotal": {
"amount": "1838",
"amountUsd": "0.001837262962",
"pct": "1814687900017981",
"token": {
"address": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
"decimals": 6,
"symbol": "USDC",
"chainId": 10
}
},
"app": {
"amount": "0",
"amountUsd": "0.0",
"pct": "0",
"token": {
"decimals": 6,
"symbol": "USDC",
"address": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
"name": "USD Coin",
"chainId": 137
}
}
},
"swapTx": {
"simulationSuccess": true,
"chainId": 10,
"to": "0x89415a82d909a7238d69094C3Dd1dCC1aCbDa85C",
"data": "0x...",
"gas": "649910",
"maxFeePerGas": "1000483",
"maxPriorityFeePerGas": "1000000"
},
"inputToken": {
"decimals": 6,
"symbol": "USDC.e",
"address": "0x7F5c764cBc14f9669B88837ca1490cCa17c31607",
"name": "USD Coin (bridged)",
"chainId": 10
},
"outputToken": {
"decimals": 6,
"symbol": "USDC",
"address": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
"name": "USD Coin",
"chainId": 137
},
"refundToken": {
"address": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
"decimals": 6,
"symbol": "USDC",
"chainId": 10
}
},
"timestamp": "2024-01-01T00:00:00Z"
}Response Fields
Core Fields
| Field | Type | Description |
|---|---|---|
quoteId | string | Unique quote identifier for tracking |
checkoutId | string | Associated checkout session ID |
status | string | Quote status (valid, expired, processing) |
paymentAmount | string | Amount user needs to pay |
settlementAmount | string | Amount merchant will receive |
minimumReceived | string | Minimum guaranteed output amount |
exchangeRate | string | Current exchange rate |
estimatedTime | number | Estimated completion time in seconds |
Pre-execution Checks
Before payment execution, the system validates:
- allowance: Token spending approval status
- balance: User account balance verification
Payment Steps
Source Chain Operations
Token operations on the payment network:
| Field | Description |
|---|---|
tokenIn | Input token information |
tokenOut | Output token information |
inputAmount | Input token amount |
outputAmount | Output token amount |
swapProvider | DEX provider information |
Cross-Chain Bridge
Bridge operations between networks:
| Field | Description |
|---|---|
tokenIn | Bridge input token |
tokenOut | Bridge output token |
inputAmount | Bridge input amount |
outputAmount | Bridge output amount |
fees | Bridge fee breakdown |
Fee Structure
Fee Types
| Fee Type | Description |
|---|---|
total | Total fees |
originGas | Source chain gas fees |
destinationGas | Destination chain gas fees |
relayerCapital | Relayer capital fees |
lpFee | Liquidity provider fees |
relayerTotal | Total relayer fees |
app | Application fees |
Fee Object Structure
interface FeeInfo {
amount: string; // Fee amount
amountUsd: string; // USD value
pct: string; // Percentage (based on input amount)
token: TokenInfo; // Fee token information
}Transaction Information
| Field | Description |
|---|---|
simulationSuccess | Whether transaction simulation succeeded |
chainId | Blockchain network ID |
to | Target contract address |
data | Transaction data |
gas | Gas limit |
maxFeePerGas | Maximum gas fee |
maxPriorityFeePerGas | Maximum priority fee |
Payment Route Types
Any to Bridgeable
Convert any token to a bridgeable token:
- Swap input token to bridgeable token on source chain
- Bridge token to destination chain
Bridgeable to Any
Convert bridgeable token to any token:
- Bridge token from source chain to destination chain
- 在目标链上将可桥接代币交换为目标代币
错误处理
常见错误
| 错误码 | 描述 | 解决方案 |
|---|---|---|
INSUFFICIENT_BALANCE | 余额不足 | 检查账户余额 |
INSUFFICIENT_ALLOWANCE | 授权额度不足 | 增加代币授权 |
UNSUPPORTED_TOKEN | 不支持的代币 | 使用支持的代币列表 |
SLIPPAGE_TOO_HIGH | 滑点过高 | 调整滑点设置或稍后重试 |
ROUTE_NOT_FOUND | 找不到交换路径 | 尝试其他代币对或调整金额 |
错误响应示例
{
"success": false,
"data": null,
"error": {
"code": "INSUFFICIENT_BALANCE",
"message": "Insufficient balance for swap",
"details": {
"required": "1012743",
"available": "500000",
"token": "0x7F5c764cBc14f9669B88837ca1490cCa17c31607"
}
},
"timestamp": "2024-01-01T00:00:00Z"
}代码示例
JavaScript/TypeScript
import { CyberPaySDK } from '@cyberpay/sdk';
const sdk = new CyberPaySDK({
apiKey: 'YOUR_API_KEY',
environment: 'production' // or 'testnet'
});
async function getSwapQuote() {
try {
const quote = await sdk.swap.getQuote({
crossSwapType: 'anyToBridgeable',
amountType: 'exactOutput',
inputToken: {
address: '0x7F5c764cBc14f9669B88837ca1490cCa17c31607',
decimals: 6,
symbol: 'USDC.e',
chainId: 10
},
outputToken: {
address: '0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359',
decimals: 6,
symbol: 'USDC',
chainId: 137
},
expectedOutputAmount: '1000000'
});
console.log('Swap quote:', quote);
return quote;
} catch (error) {
console.error('Error getting quote:', error);
}
}最佳实践
1. 预检查
在发起交换前，始终检查：
- 账户余额是否充足
- 代币授权是否足够
- 网络状态是否正常
2. 滑点管理
- 对于稳定币交换，建议滑点设置为 0.1-0.5%
- 对于波动性较大的代币，建议滑点设置为 1-3%
- 在网络拥堵时，适当提高滑点容忍度
3. 费用优化
- 在 Gas 费用较低时执行交换
- 考虑批量操作以分摊固定费用
- 监控不同路径的费用差异
4. 错误重试
- 实现指数退避重试机制
- 对临时性错误进行重试
- 记录和监控错误模式
支持的链和代币
支持的区块链网络
| 网络 | Chain ID | 状态 |
|---|---|---|
| Ethereum | 1 | ✅ 支持 |
| Polygon | 137 | ✅ 支持 |
| Optimism | 10 | ✅ 支持 |
| Arbitrum | 42161 | ✅ 支持 |
| Base | 8453 | ✅ 支持 |
| BSC | 56 | 🚧 即将支持 |
主要支持代币
- 稳定币: USDC, USDT, DAI, FRAX
- 主流代币: ETH, WETH, WBTC, MATIC
- DeFi 代币: UNI, AAVE, COMP, SUSHI
更多支持的代币请查看 代币列表 API。
相关链接
- Token Prices API - 代币价格查询
- Transaction API - 交易状态查询