@tuwaio/quasar-sdk

@tuwaio/quasar-sdk is the Layer 5 (L5) package of the TUWA SDK: the client of the API of Quasar, the TUWA backend that tracks the transactions of your app on the server and keeps their history. It works with Quasar Cloud (https://api.tuwa.io) and with a self-hosted Quasar server. It has three parts: the Quasar client for your server, a check for the browser (@tuwaio/quasar-sdk/react), and the quasar-sdk CLI that relays webhooks to localhost.

🏛️ Core Capabilities

• Transaction sync: quasar.pulsar.syncCreate sends a transaction created by Pulsar to Quasar, which tracks it until it reaches a final status (so the status survives a closed tab) and sends your webhooks.
• History: quasar.pulsar.getHistory returns the transactions of your app, newest first, filtered by wallet address, chain, status, transaction key or application name.
• Errors: every failed request throws a QuasarSDKError with the HTTP status.
• Pre-flight check: preFlightTxCheck from @tuwaio/quasar-sdk/react stops a Pulsar transaction in the browser when the user is not signed in with SIWX or the Quasar API does not respond.
• Webhook relay: npx @tuwaio/quasar-sdk listen receives the deliveries of a webhook endpoint with a localhost URL and posts them to your local app, without a tunnel.

💾 Installation

pnpm add @tuwaio/quasar-sdk @tuwaio/pulsar-core

The root entry point imports neither React nor SIWX packages, so it runs in Node.js, Next.js Server Actions and route handlers, and Edge runtimes. Its HTTP client, ofetch, is a dependency.

🚀 Usage

Create the client on the server with the secret key of your Quasar app (sk_live_... or sk_test_..., from the dashboard). Never create it in the browser: the key authorizes writes to your app.

'use server';
 
import { Quasar, type Transaction } from '@tuwaio/quasar-sdk';
 
const quasar = new Quasar({ secretKey: process.env.QUASAR_SECRET_KEY ?? '' });
 
export async function syncTransaction(tx: Transaction) {
  const { txKey } = await quasar.pulsar.syncCreate(tx, 'my-app');
  return txKey;
}
 
export async function getHistory(walletAddress: string, page = 1) {
  return quasar.pulsar.getHistory({ walletAddress, page, limit: 10, appName: 'my-app' });
}

Before calling Quasar for a user, check on the server that the user owns the wallet (for example with getSiwxServerSession and isSessionMatchingTarget from @tuwaio/siwx-server), so nobody can sync or read the transactions of another address. The complete flow — SIWX sessions, the Pulsar callbacks onRemoteCreate and beforeTxProcess, the history in Nova Transactions — is the Quasar transaction sync guide ; Quasar itself (apps and keys, quotas, webhooks, self-hosting) is described in the Quasar docs .

Webhook relay

Add a webhook endpoint with a localhost URL in the Quasar dashboard, put its signing secret in .env.local and start the relay next to your dev server:

# .env.local: QUASAR_WEBHOOK_SECRET=whsec_...
npx @tuwaio/quasar-sdk listen --forward-to http://localhost:3000/api/webhooks/quasar

The relay posts each delivery with the x-quasar-signature, x-quasar-event and x-quasar-delivery-id headers and the same body as a direct delivery, so your endpoint verifies the signature the same way. It reconnects with a backoff of up to 15 seconds and stops on a 401 (wrong secret) or 404 (no endpoint with that secret).

🗄️ Browser Storage

Nothing is written. preFlightTxCheck reads the SIWX session from the store of @tuwaio/siwx-react, which keeps it in localStorage under siwx-react:session.

🌐 External Services

The transactions you sync, with their payload, are stored by Quasar.

📚 API Reference

Every export, with signatures and types generated from the source, is documented at sdk.docs.tuwa.io/packages/quasar-sdk . The HTTP API is described in the Quasar API reference .

📄 License

Licensed under the Apache-2.0 License. See the LICENSE  file for details.

Modules

• server
• react