Encifher ZEC to USDC SDK

A minimal TypeScript SDK for converting ZEC (Zcash) to USDC on Solana using the Near Intent API via ChainDefuser.

Features

• 🚀 Simple Integration: Easy-to-use API for ZEC to USDC conversions
• 💰 Quote Generation: Get real-time quotes for your ZEC to USDC swaps
• 📊 Status Tracking: Monitor the progress of your transfers
• 🔒 Type Safe: Full TypeScript support with comprehensive type definitions
• ⚡ Lightweight: Minimal dependencies and fast execution

Installation

npm install encifher-zec-usdc-sdk

Quick Start

import { EncifherZecUsdcSdk } from 'encifher-zec-sdk';

// Initialize the SDK
const sdk = new EncifherZecUsdcSdk({
  apiKey: 'your-chaindefuser-api-key'
});

// Get a quote for converting ZEC to USDC
const quote = await sdk.getQuote({
  amount: '1000000', // 1 ZEC in smallest unit (satoshis)
  recipient: '13QkxhNMrTPxoCkRdYdJ65tFuwXPhL5gLS2Z5Nr6gjRK', // Solana wallet address
  slippageTolerance: 100, // 1% slippage
  refundTo: 't1TL6sJHu9jrAa9vJ3syEcCCsF5mZazCDSp' // refund address in case bridge fails
});

console.log('Quote:', quote);

API Reference

Constructor

new EncifherZecUsdcSdk(config: SdkConfig)

Parameters

• config.apiKey (string): Your ChainDefuser API key
• config.baseUrl (string, optional): Custom API base URL (defaults to ChainDefuser API)

Methods

getQuote(request: ZecToUsdcQuoteRequest): Promise<CompatibleQuoteType>

Get a quote for converting ZEC to USDC.

Parameters

• request.amount (string): Amount of ZEC to convert (in smallest unit)
• request.recipient (string): Solana wallet address to receive USDC
• request.slippageTolerance (number, optional): Slippage tolerance in basis points (default: 100 = 1%)
• request.refundTo (string, optional): Optional refund address

Returns

{
  inputMint: string;           // ZEC asset identifier
  outputMint: string;          // USDC asset identifier
  inAmount: string;            // Input amount in smallest unit
  outAmount: string;           // Output amount in smallest unit
  slippageBps: number;         // Slippage in basis points
  router: string;              // Router identifier
  prioritizationFeeLamports: number; // Priority fee
  inUsdValue: number;          // Input value in USD
  outUsdValue: number;         // Output value in USD
  depositAddress: string;      // Deposit address for the transaction
}

getStatus(depositAddress: string): Promise<StatusResponse>

Get the status of a transfer using the deposit address from a quote.

Parameters

• depositAddress (string): The deposit address from the quote response

Returns

{
  quoteResponse?: ChainDefuserQuoteResponse; // Original quote response
  status: 'PENDING' | 'KNOWN_DEPOSIT_TX' | 'COMPLETED' | 'FAILED' | 'REFUNDED';
  updatedAt: string; // Last update timestamp
  swapDetails?: {
    intentHashes?: string[];
    nearTxHashes?: string[];
    amountIn: string;
    amountInFormatted: string;
    amountInUsd: string;
    amountOut: string;
    amountOutFormatted: string;
    amountOutUsd: string;
    slippage: number;
    originChainTxHashes?: Array<{
      hash: string;
      explorerUrl: string;
    }>;
    destinationChainTxHashes?: Array<{
      hash: string;
      explorerUrl: string;
    }>;
    refundedAmount?: string;
    refundedAmountFormatted?: string;
    refundedAmountUsd?: string;
  };
}

Utility Methods

EncifherZecUsdcSdk.validateAmount(amount: string): boolean

Validate if a ZEC amount string is valid.

EncifherZecUsdcSdk.validateSolanaAddress(address: string): boolean

Validate if a Solana wallet address is properly formatted.

Usage Examples

Basic Quote Request

import { EncifherZecUsdcSdk } from 'encifher-zec-usdc-sdk';

const sdk = new EncifherZecUsdcSdk({
  apiKey: process.env.CHAINDEFUSER_API_KEY!
});

try {
  const quote = await sdk.getQuote({
    amount: '1000000', // 1 ZEC
    recipient: '13QkxhNMrTPxoCkRdYdJ65tFuwXPhL5gLS2Z5Nr6gjRK'
  });

  console.log(`Convert ${quote.inAmount} ZEC to ${quote.outAmount} USDC`);
  console.log(`Deposit to: ${quote.depositAddress}`);
  console.log(`Estimated USD value: $${quote.outUsdValue}`);
} catch (error) {
  console.error('Failed to get quote:', error);
}

Status Monitoring

async function monitorTransfer(depositAddress: string) {
  const sdk = new EncifherZecUsdcSdk({
    apiKey: process.env.CHAINDEFUSER_API_KEY!
  });

  let status = await sdk.getStatus(depositAddress);
  
  while (status.status !== 'COMPLETED' && status.status !== 'FAILED') {
    console.log(`Transfer status: ${status.status}`);
    
    if (status.swapDetails) {
      console.log(`Amount in: ${status.swapDetails.amountInFormatted} ZEC`);
      console.log(`Amount out: ${status.swapDetails.amountOutFormatted} USDC`);
    }
    
    // Wait 30 seconds before checking again
    await new Promise(resolve => setTimeout(resolve, 30000));
    status = await sdk.getStatus(depositAddress);
  }
  
  if (status.status === 'COMPLETED') {
    console.log('Transfer completed successfully!');
    if (status.swapDetails?.destinationChainTxHashes) {
      console.log('Transaction hash:', status.swapDetails.destinationChainTxHashes[0].hash);
    }
  } else {
    console.log('Transfer failed or was refunded');
  }
}

Input Validation

import { EncifherZecUsdcSdk } from 'encifher-zec-usdc-sdk';

function validateQuoteRequest(amount: string, recipient: string): boolean {
  if (!EncifherZecUsdcSdk.validateAmount(amount)) {
    console.error('Invalid ZEC amount');
    return false;
  }
  
  if (!EncifherZecUsdcSdk.validateSolanaAddress(recipient)) {
    console.error('Invalid Solana address');
    return false;
  }
  
  return true;
}

// Usage
if (validateQuoteRequest('1000000', '13QkxhNMrTPxoCkRdYdJ65tFuwXPhL5gLS2Z5Nr6gjRK')) {
  const quote = await sdk.getQuote({
    amount: '1000000',
    recipient: '13QkxhNMrTPxoCkRdYdJ65tFuwXPhL5gLS2Z5Nr6gjRK'
  });
}

Error Handling

The SDK throws SdkError objects with the following properties:

• message: Human-readable error message
• status: HTTP status code (if applicable)
• code: Error code identifier

try {
  const quote = await sdk.getQuote(request);
} catch (error) {
  if (error.status === 401) {
    console.error('Invalid API key');
  } else if (error.status === 400) {
    console.error('Invalid request parameters');
  } else {
    console.error('Unexpected error:', error.message);
  }
}

Development

Building

npm run build

Testing

npm test

Linting

npm run lint

License

MIT

Support

For issues and questions, please check the documentation or contact support.