Compass SDK

Compass SDK is a powerful cross-chain transaction SDK that provides a unified liquidity layer by aggregating multiple liquidity sources across blockchain networks. It seamlessly integrates DEXs (Decentralized Exchanges), Cross-chain Bridges, RFQ (Request for Quote) systems, and Intent Protocols into a single, reliable interface. This enables developers to easily implement cross-chain token swaps, transfers, and complex DeFi operations across EVM chains, Solana, and Cosmos ecosystems.

The SDK automatically optimizes routes for the best rates and lowest fees by splitting transactions across multiple liquidity sources, handling complex cross-chain operations, and managing transaction sequences. It provides real-time price quotes, gas estimations, and transaction status tracking while abstracting away the complexity of cross-chain interactions.

Features

- Cross-chain token swaps and transfers with optimal routing
- Unified access to multiple liquidity sources:
- DEXs (Uniswap, PancakeSwap, etc.)
- Cross-chain bridges (Wormhole, LayerZero, etc.)
- RFQ systems for better pricing on large trades
- Intent Protocols for complex DeFi operations
- Support for multiple blockchain networks:
- EVM chains (Ethereum, BSC, Polygon, etc.)
- Solana
- Cosmos ecosystem
- Real-time transaction status tracking and notifications
- Comprehensive token and chain information with metadata
- Advanced gas fee estimation and optimization
- Built-in caching system for improved performance
- Flexible configuration options for different environments
- Robust error handling and transaction recovery

Installation

``bash npm install @blockend/compass-sdk

`or`


yarn add @blockend/compass-sdk


Quick Start

`typescript import { initializeSDK, getQuotes, executeTransaction, createTransaction, getNextTxn, checkStatus, } from "@blockend/compass-sdk";

// Initialize the SDK with your API key initializeSDK({ apiKey: "YOUR_API_KEY", integratorId: "YOUR_INTEGRATOR_ID", });

// Get quotes for a token swap const quotes = await getQuotes({ fromChainId: "ethereum", fromAssetAddress: "0x...", toChainId: "solana", toAssetAddress: "...", inputAmount: "1000000000000000000", // Amount in wei inputAmountDisplay: "1.0", // Human readable amount userWalletAddress: "0x...", recipient: "0x...", });

// Execute the transaction with the best quote const result = await executeTransaction({ quote: quotes.data.quotes[0], provider: ethersProvider, // For EVM chains walletAdapter: solanaWallet, // For Solana cosmosClient: cosmosClient, // For Cosmos onStatusUpdate: (status, data) => { console.log(Transaction status: ${status}, data); }, });

// Check transaction status, poll the status until the status is "success" or "failed" or "partial-success". "in-progress" means the transaction is still being processed. See example implementation below. const status = await checkStatus({ routeId: transaction.routeId, stepId: transaction.steps[0].id, txnHash: result.hash, });`

`API Reference`

`$3`

#### initializeSDK(config)

Initialize the SDK with your credentials and configuration.

`typescript initializeSDK({ apiKey: string; integratorId: string; baseURL?: string; enableCache?: boolean; cacheTimeout:number; });`

To get config, use the getConfig() method.

`typescript const config = getConfig();`

To update config, use the updateConfig() method. You can update one or more parameters mentioned in the Configuration Parameters section.

`typescript updateConfig({ apiKey: "YOUR_API_KEY", });`

`$3`

#### apiKey (required)

- Your unique API key for authentication with the Blockend API - Must be obtained through the Blockend platform - Used to track API usage and enforce rate limits

#### integratorId (required)

- A unique identifier for your integration/application - Used for analytics, tracking, and support purposes - Helps identify your specific implementation when interacting with Blockend services

#### errorHandler (optional)

- A callback function to handle SDK errors globally - Receives aBlockendErrorobject with properties: -message: Description of the error -code: Error code (e.g., "CONFIGURATION_ERROR", "NETWORK_ERROR", "VALIDATION_ERROR") -data: Additional error context (if available) - Useful for centralized error handling, logging, and error reporting - Example usage:

`typescript initializeSDK({ apiKey: "YOUR_API_KEY", integratorId: "YOUR_INTEGRATOR_ID", errorHandler: (error) => { console.error([Compass SDK Error] ${error.code}: ${error.message}, error.data ); // Custom error handling logic (e.g., reporting to monitoring service) }, });`

#### baseURL (optional)

- The base URL endpoint for the Blockend API - Defaults tohttps://api2.blockend.com/v1- Can be modified for different environments (staging, testing, etc.) - Should include the version prefix (/v1)

#### enableCache (optional)

- Boolean flag to enable/disable SDK's built-in caching mechanism - When enabled, caches API responses to reduce network requests - Particularly useful for frequently accessed data like token lists and chain information - Defaults tofalse if not specified

#### cacheTimeout (optional)

- Duration in milliseconds for how long cached items should remain valid - Only applies whenenableCache is true- Defaults to 1 hour (3600000 milliseconds) - Can be adjusted based on your application's needs and data freshness requirements

`$3`

#### getQuotes

Gets quotes for cross-chain token swaps or transfers by aggregating liquidity from multiple sources including DEXs, Bridges, RFQs, and Intent Protocols.

`typescript interface QuoteParams { // Chain ID of the source blockchain (e.g., "ethereum", "solana", "bsc") fromChainId: string;

// Token contract address on source chain (use native token address for chain's native currency) fromAssetAddress: string;

// Chain ID of the destination blockchain toChainId: string;

// Token contract address on destination chain toAssetAddress: string;

// Amount in smallest unit (wei, lamports, etc.) inputAmount: string;

// Human readable amount (e.g., "1.0" ETH) inputAmountDisplay: string;

// Source wallet address that will initiate the transaction userWalletAddress: string;

// Optional: Destination wallet address (defaults to userWalletAddress if not specified) recipient?: string;

// Optional: Solana priority fee in lamports or predefined level ("LOW" | "MEDIUM" | "HIGH") solanaPriorityFee?: number | PriorityLevel;

// Optional: Solana Jito MEV tip in lamports or predefined level solanaJitoTip?: number | PriorityLevel;

// Optional: EVM priority fee in gwei or predefined level evmPriorityFee?: number | PriorityLevel;

// Optional: Maximum allowed slippage percentage (default: 1.0) slippage?: number;

// Optional: Skip certain validation checks for faster response skipChecks?: boolean;

// Optional: Comma-separated list of preferred liquidity sources include?: string;

// Optional: Comma-separated list of liquidity sources to exclude exclude?: string;

// Optional: Use recommended liquidity provider recommendedProvider?: boolean; }

//Example implementation const quotes = await getQuotes({ fromChainId: "evm", fromAssetAddress: "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", toChainId: "evm", toAssetAddress: "0xc2132d05d31c914a87c6611c10748aeb04b58e8f.", inputAmountDisplay: "1.0", userWalletAddress: "0x...", recipient: "0x...", });

// Example Response (shortened) { "status": "success", "data": { "quotes": [{ "routeId": "01J2WB1NY6MD3F25CJTTB01D8F", "from": { "chainId": "1", "symbol": "ETH", // ... other token details }, "to": { "chainId": "sol", "symbol": "USDC", // ... other token details }, "outputAmountDisplay": "1459.244847", "estimatedTimeInSeconds": 900 }] } }`

View full quotes response example

#### createTransaction(params)

Creates a transaction from a selected quote, preparing all necessary steps for the cross-chain transfer.

`typescript interface CreateTransactionParams { // Route ID obtained from getQuotes response routeId: string; }

//Example implementation const transaction = await createTransaction({ routeId: quotes.data.quotes[0].routeId, });

// Example Response (shortened) { "status": "success", "data": { "routeId": "01J2WB1NY6MD3F25CJTTB01D8F", "steps": [{ "stepId": "01J2WB1NY64MKVCM8FM994WMZV", "stepType": "bridge", "chainId": "1" }] } }`

View full createTransaction response example

#### getNextTxn(params)

Retrieves the raw transaction data for the next pending step in the transaction sequence. The response format varies based on the blockchain network:

`typescript interface TransactionDataParams { routeId: string; // Route ID from createTransaction stepId: string; // Step ID from the transaction steps array }

//Example implementation const nextTxn = await getNextTxn({ routeId: transaction.routeId, stepId: transaction.steps[0].id, });

// Example Response (shortened) { "status": "success", "data": { "routeId": "01J2WB1NY6MD3F25CJTTB01D8F", "stepId": "01J2WB1NY64MKVCM8FM994WMZV", "networkType": "evm", "txnData": { "txnEvm": { "to": "0x...", "value": "420000000000000000", // ... other transaction details } } } };`

#### Transaction Data Response Examples

#### EVM Chain Response

`typescript { "status": "success", "data": { "routeId": "01J2WB1NY6MD3F25CJTTB01D8F", "stepId": "01J2WB1NY64MKVCM8FM994WMZV", "networkType": "evm", "txnData": { "txnEvm": { "from": "0x17e7c3DD600529F34eFA1310f00996709FfA8d5c", "to": "0x1234567890abcdef1234567890abcdef12345678", "value": "420000000000000000", "data": "0x095ea7b3...", "gasPrice": "30000000000", "gasLimit": "250000" } } } }`

#### Solana Chain Response

`typescript { "status": "success", "data": { "routeId": "01J2WB1NY6MD3F25CJTTB01D8F", "stepId": "01J2WB1NY64MKVCM8FM994WMZV", "networkType": "sol", "txnData": { "txnSol": { "data": "base64EncodedTransactionData...", } } } }`

#### Cosmos Chain Response

`typescript { "status": "success", "data": { "routeId": "01J2WB1NY6MD3F25CJTTB01D8F", "stepId": "01J2WB1NY64MKVCM8FM994WMZV", "networkType": "cosmos", "txnData": { "txnCosmos": { "data": "{"typeUrl":"/ibc.applications.trans"}", "value": "0", "gasLimit": "250000", "gasPrice": "0.025", } } } }`

View full getNextTxn response example

#### checkStatus(params)

Monitors the status of a transaction step, providing detailed information about its progress.

`typescript interface StatusCheckParams { // Route ID of the transaction routeId: string;

// Step ID being checked stepId: string;

// Transaction hash from the blockchain txnHash: string; }

//Example implementation const status = await checkStatus({ routeId: transaction.routeId, stepId: transaction.steps[0].id, txnHash: result.hash, });

// Example Response (shortened) { "status": "success", "data": { "status": "success", "outputAmount": "1459244847", "outputAmountDisplay": "1459.244847" } } type TransactionStatus = "not-started" | "in-progress" | "success" | "failed";`

View full checkStatus response example

Here's a simpler example to poll the transaction status:

`typescript async function pollWithWhileLoop( routeId: string, stepId: string, txnHash: string ) { const POLLING_INTERVAL = 3000; // 3 seconds const MAX_ATTEMPTS = 200; // Maximum number of attempts (10 minutes with 3s interval) let attempts = 0;

while (attempts < MAX_ATTEMPTS) { try { const response = await checkStatus({ routeId, stepId, txnHash }); const status = response.data.status;

console.log(Current status: ${status});

if (["success", "failed", "partial-success"].includes(status)) { return response.data; }

// Wait for the polling interval await new Promise((resolve) => setTimeout(resolve, POLLING_INTERVAL)); attempts++; } catch (error) { console.error("Error checking status:", error); throw error; } }

throw new Error("Polling timeout: Maximum attempts reached"); }

// Usage example: try { const result = await pollWithWhileLoop( "your-route-id", "your-step-id", "your-transaction-hash" ); console.log("Final result:", result); } catch (error) { console.error("Polling failed:", error); }`

#### pollTransactionStatus(params)

Continuously monitors a transaction's status by polling at regular intervals until a final state is reached or timeout occurs. This method provides a convenient way to track cross-chain transactions through their entire lifecycle.

`typescript interface PollTransactionStatusParams { // Route ID of the transaction routeId: string;

// Step ID being monitored stepId: string;

// Transaction hash from the blockchain txnHash: string;

// Optional: Interval between status checks in milliseconds (default: 2000ms) pollingIntervalMs?: number;

// Optional: Maximum time to poll before timing out in milliseconds (default: 600000ms / 10 minutes) timeoutMs?: number;

// Optional: Callback function for real-time status updates onStatusUpdate?: (status: TransactionStatus, data?: ExecuteTransactionResult) => void; }

// Example usage: const result = await pollTransactionStatus({ routeId: "your-route-id", stepId: "your-step-id", txnHash: "your-transaction-hash", pollingIntervalMs: 3000, // Poll every 3 seconds, by default it's 2 seconds timeoutMs: 300000, // Timeout after 5 minutes, by default it's 10 minutes onStatusUpdate: (status, data) => { console.log(Transaction status updated: ${status}); if (data) { console.log("Transaction data:", data); } }, });

// Example Response { "status": "success", "data": { "status": "success", "outputAmount": "1459244847", "outputAmountDisplay": "1459.244847", "srcTxnHash": "0x...", "dstTxnHash": "0x...", "srcTxnUrl": "https://etherscan.io/tx/0x...", "dstTxnUrl": "https://etherscan.io/tx/0x...", "points": 100, "warnings": [], } }`

The method will continue polling until one of these conditions is met:

- Transaction reaches a final status ("success", "failed", or "partial-success") - Polling timeout is reached - An error occurs during status checking

Status Types:

- "not-started": Transaction has not been initiated -"in-progress": Transaction is being processed -"success": Transaction completed successfully -"failed": Transaction failed -"partial-success": Transaction partially succeeded (some steps completed)

Error Handling:

- Throws a timeout error if timeoutMsis exceeded - Throws any errors encountered during status checking - Provides detailed error information through theBlockendError class

Best Practices:

1. Set appropriate pollingIntervalMsbased on chain block times 2. Configure reasonabletimeoutMsfor your use case 3. Implement proper error handling 4. Use theonStatusUpdate callback for real-time UI updates

#### executeTransaction(params)

Execute a transaction with the provided quote and wallet. This method handles the actual execution of the cross-chain transaction using the appropriate wallet/provider based on the chain type.

`typescript interface ExecuteTransactionParams { quote: Quote; // For EVM chains (Ethereum, BSC, Polygon, etc.) provider?: Provider | WalletClient; // Supports ethers.js BrowserProvider or viem WalletClient (including wagmi's getWalletClient) // For Solana chain walletAdapter?: WalletAdapter; // Compatible with @solana/web3.js and @solana/wallet-adapter-base wallets // For Cosmos-based chains cosmosClient?: any; // Compatible with @cosmjs/stargate and @cosmjs/cosmwasm-stargate clients // Optional callback for tracking transaction status onStatusUpdate?: (status: TransactionStatus, data?: any) => void; solanaRpcUrl?: string; }`

Examples for different chains:

`typescript // 1. EVM Chains Examples // Using ethers.js BrowserProvider import { BrowserProvider } from "ethers"; const provider = new BrowserProvider(window.ethereum); const evmResult = await executeTransaction({ quote: quotes.data.quotes[0], provider: provider, });

// Using viem WalletClient import { createWalletClient, custom } from "viem"; const walletClient = createWalletClient({ transport: custom(window.ethereum), }); const evmViemResult = await executeTransaction({ quote: quotes.data.quotes[0], provider: walletClient, });

// Using wagmi's getWalletClient import { getWalletClient } from "@wagmi/core"; const wagmiClient = await getWalletClient(); const evmWagmiResult = await executeTransaction({ quote: quotes.data.quotes[0], provider: wagmiClient, });

// 2. Solana Examples // Using Phantom Wallet import { PhantomWalletAdapter } from "@solana/wallet-adapter-phantom"; const phantomWallet = new PhantomWalletAdapter(); await phantomWallet.connect(); const solanaResult = await executeTransaction({ quote: quotes.data.quotes[0], walletAdapter: phantomWallet, });

// Using Solana Wallet Adapter import { useWallet } from "@solana/wallet-adapter-react"; const { wallet } = useWallet(); const solanaAdapterResult = await executeTransaction({ quote: quotes.data.quotes[0], walletAdapter: wallet, });

// 3. Cosmos Examples // Using CosmJS with Keplr import { SigningStargateClient } from "@cosmjs/stargate"; import { SigningCosmWasmClient } from "@cosmjs/cosmwasm-stargate";

// For standard Cosmos chains const getStargateClient = async () => { if (!window.keplr) throw new Error("Keplr not installed"); await window.keplr.enable("cosmoshub-4"); // or your chain ID const offlineSigner = window.keplr.getOfflineSigner("cosmoshub-4"); const client = await SigningStargateClient.connectWithSigner( "https://rpc.cosmos.network", // your RPC endpoint offlineSigner ); return client; };

const cosmosResult = await executeTransaction({ quote: quotes.data.quotes[0], cosmosClient: await getStargateClient(), });

// For CosmWasm chains (e.g., Terra, Secret Network) const getCosmWasmClient = async () => { if (!window.keplr) throw new Error("Keplr not installed"); await window.keplr.enable("phoenix-1"); // or your chain ID const offlineSigner = window.keplr.getOfflineSigner("phoenix-1"); const client = await SigningCosmWasmClient.connectWithSigner( "https://terra-rpc.example.com", // your RPC endpoint offlineSigner ); return client; };

const cosmWasmResult = await executeTransaction({ quote: quotes.data.quotes[0], cosmosClient: await getCosmWasmClient(), });`

The provider, walletAdapter, and cosmosClient parameters are mutually exclusive - you should provide the appropriate one based on the chain you're interacting with:

- For EVM chains: provide the providerparameter - For Solana: provide thewalletAdapterparameter - For Cosmos chains: provide thecosmosClient parameter

The onStatusUpdate callback receives real-time updates about the transaction status and optional data payload.

`$3`

#### getTokens(chainId?)

Get a list of supported tokens, optionally filtered by chain ID.

`typescript interface TokensParams { chainId?: string; }

//Example implementation const tokens = await getTokens();// to fetch all tokens from all chains const tokens = await getTokens("1");// to fetch all tokens from chain 1

//Example response { "status": "success", "data":{ "1":[ { "networkType": "evm", "address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", "chainId": "1", "blockchain": "Ethereum", "decimals": 18, "name": "Ethereum", "symbol": "ETH", "image": "https://assets.coingecko.com/coins/images/279/standard/ethereum.png?1595348880", "lastPrice": 2703.62, "isEnabled": true, "isFlagged": false, "isNative": true, "isPopular": true }, //other coins on chain 1 ] } }`

#### getChains()

Get a list of supported blockchain networks.

`typescript interface Chain { id: string; name: string; networkType: "evm" | "sol" | "cosmos"; nativeCurrency: { name: string; symbol: string; decimals: number; }; blockExplorer: string; rpcUrls: string[]; } //Example implementation const chains = await getChains(); // to fetch all chains

//Example response { "status": "success", "data": [ { "chainId": "sol", "symbol": "sol", "name": "Solana", "networkType": "sol", "image": "https://assets.coingecko.com/coins/images/4128/large/solana.png?1696504756", "explorer": { "address": "https://solscan.io/account/{address}", "token": "https://solscan.io/token/{tokenAddress}", "txn": "https://solscan.io/tx/{txnHash}" }, "isPopular": true, "tokenCount": 946, "isEnabled": true }, //other supported chains ] }`

`Error Handling`

The SDK uses a custom BlockendError class for error handling. All errors will be instances of this class and include:

- message: Human-readable error message -code: Error code for programmatic handling -data: Additional error context (if available)

`Best Practices`

1. Always handle transaction status updates using the onStatusUpdatecallback 2. Implement proper error handling for failed transactions 3. Use appropriate slippage tolerance for volatile tokens 4. Cache chain and token information when possible 5. Verify wallet connections before executing transactions

`Network Support`

- EVM Chains (Ethereum, BSC, Polygon, etc.) - Solana - Cosmos-based chains

Compass SDK

Features

Installation

``bash npm install @blockend/compass-sdk

`or`


yarn add @blockend/compass-sdk


Quick Start