API Documentation
Introduction
Welcome to the Quantum Swaps API documentation. This guide provides comprehensive information about our API endpoints, allowing you to integrate cryptocurrency swap functionality into your applications seamlessly. All API requests use POST methods and return JSON responses.
The Quantum Swaps API follows RESTful principles and is organized around predictable resource-oriented endpoints. Below you'll find information on how to handle errors and integrate with our API.
Quickstart
Get started quickly with the Quantum Swaps API by following this end-to-end example for creating a cryptocurrency swap:
// 1. Check available currency pairs
const pairsResponse = await fetch('https://api.quantumswaps.xyz/v1/currencies/pairs', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-pk-key': 'YOUR_PUBLIC_KEY'
},
body: JSON.stringify({
fromCurrencies: ['BTC'],
fromNetworks: ['BTC'],
toCurrencies: ['ETH'],
toNetworks: ['ETH']
})
});
const pairs = await pairsResponse.json();
console.log('Available pairs:', pairs);
// 2. Get a quote for the swap
const quoteResponse = await fetch('https://api.quantumswaps.xyz/v1/swap/quote', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-pk-key': 'YOUR_PUBLIC_KEY'
},
body: JSON.stringify({
fromCurrencies: ['BTC'],
fromNetworks: ['BTC'],
toCurrencies: ['ETH'],
toNetworks: ['ETH'],
fromAmount: '0.01',
fromWalletAddress: '0x123...'
})
});
const quote = await quoteResponse.json();
console.log('Quote details:', quote);
// 3. Execute the swap with the quote signature
const executeResponse = await fetch('https://api.quantumswaps.xyz/v1/swap/execute', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-pk-key': 'YOUR_PUBLIC_KEY',
'x-sk-key': 'YOUR_SECRET_KEY'
},
body: JSON.stringify({
signature: quote.signature,
toWalletAddress: '0x456...',
refundWalletAddress: '0x123...'
})
});
const transaction = await executeResponse.json();
console.log('Swap transaction:', transaction);Errors
The Quantum Swaps API uses conventional HTTP response codes to indicate the success or failure of an API request.
// HTTP Status Codes 200 - OK // Everything worked as expected 400 - Bad Request // Missing required parameters or validation failed 401 - Unauthorized // Invalid API key 404 - Not Found // The requested resource doesn't exist 429 - Too Many Requests // You've hit rate limits 500 - Server Error // Something went wrong on our end
{
"error": {
"code": "invalid_request",
"message": "The request was invalid",
"details": "Missing required parameter: fromCurrencies"
}
}API Endpoints
Authentication Headers
All API requests require authentication headers. Include the x-pk-key header in all API calls. For swap execution, you must additionally include the x-sk-key header.
// Headers for all API calls
{
'Content-Type': 'application/json',
'x-pk-key': 'YOUR_PUBLIC_KEY'
}
// Additional header for swap execution
{
'x-sk-key': 'YOUR_SECRET_KEY' // Required only for /v1/swap/execute
}Currencies Info
Get detailed information about all available tokens and their supported networks. This endpoint returns a comprehensive list of all cryptocurrencies that can be used with the API.
// Response
[
{
code: string;
name: string;
networks: string[];
isEnabled: boolean;
}
]Currencies Pairs
Get available currency pairs for swapping. You can optionally filter the results by specifying source currencies or networks. If you specify fromNetworks or fromCurrencies, the response will be limited to only include those pairs.
// Request
{
fromCurrencies?: string[]; // Optional: filter by source currencies
toCurrencies?: string[]; // Optional: filter by destination currencies
fromNetworks?: string[]; // Optional: filter by source networks
toNetworks?: string[]; // Optional: filter by destination networks
}
// Response
{
pairs: [
{
fromCurrencies: string[];
fromNetworks: string[];
toCurrencies: string[];
toNetworks: string[];
isEnabled: boolean;
}
]
}Swap Quote
Get a price quote for swapping between currencies. The quote includes exchange rates, fees, and a signature needed for executing the swap. You can specify either floating or fixed rate by using the flow parameter. The result includes a signature that will be required when executing the swap.
// Request
{
fromCurrencies: string[];
fromNetworks?: string[];
toCurrencies: string[];
toNetworks?: string[];
fromAmount?: string; // Either this or toAmount is required
toAmount?: string; // Either this or fromAmount is required
flow?: string; // Optional: "floating" or "fixed" rate
fromWalletAddress: string;
fromWalletAddressExtra?: string;
}
// Response
{
fromAmount: string;
toAmount: string;
networkFee: string;
fromCurrencies: string[];
fromNetworks?: string[];
toCurrencies: string[];
toNetworks?: string[];
expiresIn?: string;
rateId: string;
flow?: string;
fromWalletAddress: string;
fromWalletAddressExtra?: string;
signature: string; // Required for swap execution
}Swap Execute
Execute a swap using the quote signature obtained from the Quote endpoint. This initiates the transaction to fulfill the swap. You must pass the quote signature from the previous step, along with the destination wallet address and a refund address in case the transaction fails.
// Request
{
signature: string; // The signature from the quote response
toWalletAddress: string; // Destination wallet for receiving funds
toWalletAddressExtra?: string;
refundWalletAddress: string; // Address to refund if transaction fails
refundWalletAddressExtra?: string;
}
// Response
{
id: string;
fromCurrency: string;
fromAmount: string;
fromWalletAddress: string;
fromWalletAddressExtra?: string;
toCurrency: string;
toAmount: string;
toWalletAddress: string;
toWalletAddressExtra?: string;
status: TransactionStatus;
completedAt?: string;
}