Node.js SDK Integration

Integrating the Quasar Cloud into your backend is straightforward using the official @tuwaio/quasar-sdk. The SDK acts as the primary bridge for indexing transactions (via Pulsar), validating signatures, and syncing state.

Installation

Install the SDK alongside its required fetch transport:


pnpm add @tuwaio/quasar-sdk ofetch

Initialization

The Quasar class requires a secretKey. This key authenticates your requests to the High-Performance Engine API (api.tuwa.io).

[!WARNING] Server-Side Only: Never expose the Quasar client or your secretKey to the frontend. The secretKey has full administrative power over your Quasar App’s resources.


import { Quasar } from '@tuwaio/quasar-sdk';
 
// Initialize the client in your backend
export const quasar = new Quasar({ 
  secretKey: process.env.QUASAR_SECRET_KEY, 
  baseUrl: 'https://api.tuwa.io' // Optional, defaults to production
});

Basic Usage

Once initialized, the client provides access to various domain services. The most prominent is the Pulsar service for transaction tracking.


import { ChainType } from '@tuwaio/pulsar-core';
 
// 1. Sync a new pending transaction to Quasar
const { txKey } = await quasar.pulsar.syncCreate({
  txKey: 'tx_local_18f2...',          // Unique transaction key
  chainId: 1,                          // Ethereum Mainnet
  from: '0xabc...',                    // Sender address
  type: 'TRANSFER',                    // Transaction type
  connectorType: 'evm:metamask',       // Connector type
  adapter: 'evm',                      // Adapter ('evm', 'solana', 'starknet')
  tracker: 'ethereum',                 // Tracker ('ethereum', 'solana', 'safe', 'gelato')
  pending: true,
  localTimestamp: Date.now(),
  hash: '0xabc...',                    // Optional transaction hash
}, 'My Custom Application');
 
// 2. Query transaction history
const history = await quasar.pulsar.getHistory({
  chainId: 1,
  limit: 10
});

Error Handling

All SDK methods throw typed QuasarSDKError instances when API calls fail. You can catch and inspect the HTTP status code and messages returned by the Engine.


import { QuasarSDKError } from '@tuwaio/quasar-sdk';
 
try {
  await quasar.pulsar.syncCreate(txData);
} catch (error) {
  if (error instanceof QuasarSDKError) {
    console.error(`Engine returned ${error.status}: ${error.message}`);
  }
}

Next, see the Full TUWA Stack to learn how to integrate Quasar into a modern React application alongside EVM and Solana providers.