Vistadex TypeScript SDK

A Node.js TypeScript SDK for trading with the Vistadex RFQ server. It handles RFQ creation, WebSocket updates, transaction signing, and waiting for filler acceptance.

Install

npm install vistadex

Requirements

• Node.js 18+
• An API key for the Vistadex client API
• Optional: VISTADEX_RPC_URL (for custom/private Solana RPC)
• Optional: VISTADEX_POSITIONS_API_URL (for position values API base URL)

Main Flow (Recommended)

import { VistadexClient, keypairFromSecretKey, USDC_MINT } from 'vistadex';
import { readFileSync } from 'node:fs';

const client = new VistadexClient({
  apiKey: process.env.VISTADEX_CLIENT_API_KEY as string,
  rpcUrl: process.env.VISTADEX_RPC_URL,
  positionsBaseUrl: process.env.VISTADEX_POSITIONS_API_URL
});

const wallet = keypairFromSecretKey(readFileSync('keypair.json', 'utf8'));
const walletAddress = wallet.publicKey.toBase58();

const rfq = await client.createRfq({
  walletAddress,
  conditionId: '7e81bc03589aa7980fdcef0be7661930f696034faab9d881bf1ab7726d015eb3',
  collateralMint: USDC_MINT,
  outcomeIndex: 0,
  side: 'buy',
  quoteBasis: 'usd',
  usdAmount: 10,
  orderType: 'market'
});

const result = await client.submitTrade({
  rfqId: rfq.rfqId,
  wallet
});

console.log('Trade complete:', result.transactionSignature);

submitTrade(...) handles waiting for the quote, signing, submitting, and waiting for filler acceptance.

Quick Start (One-Call Wrapper)

import { VistadexClient, createWallet, USDC_MINT } from 'vistadex';

const client = new VistadexClient({
  apiKey: process.env.VISTADEX_CLIENT_API_KEY as string
});

const wallet = createWallet();

const result = await client.buy({
  wallet,
  conditionId: '0x1234...abcd',
  collateralMint: USDC_MINT,
  outcomeIndex: 0,
  usdAmount: 25
});

console.log('Trade complete:', result.transactionSignature);

Core Methods

• createRfq(...)
• submitTrade(...)
• getEvent(slug, options?)
• getPositions(...)
• getUSDCBalance(...)

Get Event

const event = await client.getEvent('will-trump-win-2024');

console.log('Event title:', event.event.title);
console.log('Market count:', event.markets.length);

getEvent(...) calls GET /v1/events/:slug and, if the server returns 202 while the event is being created in the background, it polls until the full event payload is ready or the wait timeout is exceeded.

Get USDC Balance

const usdc = await client.getUSDCBalance({
  walletAddress: wallet.publicKey.toBase58()
});

console.log('USDC balance:', usdc.balance);
console.log('USDC raw:', usdc.balanceRaw);

Get Positions

const firstPage = await client.getPositions({
  walletAddress: wallet.publicKey.toBase58(),
  limit: 100
});

console.log('Total positions:', firstPage.total);
console.log('Has more:', firstPage.hasMore);
console.log('Next cursor:', firstPage.nextCursor);
console.log('First item:', firstPage.positions[0]);

if (firstPage.hasMore && firstPage.nextCursor) {
  const secondPage = await client.getPositions({
    walletAddress: wallet.publicKey.toBase58(),
    cursor: firstPage.nextCursor,
    limit: 100
  });
  console.log('Second page count:', secondPage.positions.length);
}

limit defaults to 100 (max 200). Use nextCursor to request the next page.

Each item includes readable fields like:

• positionMint
• balanceRaw (base units)
• balance (decimal string)
• full upstream fields: position_mint, condition_id, outcome_index, collateral_mint, status, price, payout, metadata

getPositions(...) always calls the position endpoint with include_metadata: true.

Configuration

const client = new VistadexClient({
  apiKey: 'vdx_...client_key',
  timeoutMs: 10000,
  rpcUrl: 'https://api.mainnet-beta.solana.com',
  positionsBaseUrl: 'https://markets.vistadex.com'
});

• programId defaults to VisTAPABATtyG5FGQ3twF7Hk6xAi6qBPS5BLuGoSQ3i
• rpcUrl defaults to https://api.mainnet-beta.solana.com
• positionsBaseUrl defaults to https://markets.vistadex.com

Wallet Helpers

import { createWallet, keypairToSecretKeyBase64, keypairFromSecretKey } from 'vistadex';

const wallet = createWallet();
const secret = keypairToSecretKeyBase64(wallet);
const restored = keypairFromSecretKey(secret);

Full Example: Manual Trade Flow

Complete example file: examples/full-trading-flow.ts

import {
  VistadexClient,
  keypairFromSecretKey,
  USDC_MINT
} from 'vistadex';
import { readFileSync } from 'node:fs';

const client = new VistadexClient({ apiKey: process.env.VISTADEX_CLIENT_API_KEY as string });
const wallet = keypairFromSecretKey(readFileSync('keypair.json', 'utf8'));
const walletAddress = wallet.publicKey.toBase58();

const rfq = await client.createRfq({
  walletAddress,
  conditionId: '7e81bc03589aa7980fdcef0be7661930f696034faab9d881bf1ab7726d015eb3',
  collateralMint: USDC_MINT,
  outcomeIndex: 0,
  side: 'buy',
  quoteBasis: 'usd',
  usdAmount: 10,
  orderType: 'market'
});

const submitResult = await client.submitTrade({
  rfqId: rfq.rfqId,
  wallet
});

console.log('Trade confirmed:', submitResult.transactionSignature);

The high-level buy(), sell(), and trade() methods wrap this same flow into one call.

USDC_MINT is exported by the SDK for convenience.

Notes

• conditionId must be a 32-byte hex string (64 characters). 0x prefix is allowed.
• API keys must be kept server-side. Do not expose them in browser code.