Developer overview - Vistadex Docs

The vistadex TypeScript package provides RFQ creation, WebSocket updates, transaction validation and signing, market data, balances, and positions for approved server-side integrations.

Product context

The Vistadex app starts with Discover, People, and Ideas. Those surfaces connect captured predictions to track records. Long/Short adds account-authorized automated execution for eligible future trades, while users can still submit individual market orders. This SDK guide covers funded market execution and wallet data. Its getPositions method reads wallet holdings; it is not a query for someone’s paper portfolio. The SDK contract documented here does not provide person enrollment, tracking billing, private claims, or Long/Short subscription management. Public person links use https://www.vistadex.com/people/username; a web route is not an SDK endpoint or an authorization mechanism.

Keep Vistadex API keys and wallet secret keys on a trusted server. Do not embed them in browser code or commit them to source control.

Requirements

Node.js >=18
A Vistadex client API key
A Solana keypair for trading methods
USDC on Solana for buys, or Vistadex position tokens for sells

Install

pnpm add vistadex

Create a client

import { VistadexClient } from 'vistadex';

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

Configuration defaults

Field	Required	Default
`apiKey`	Yes	None
`baseUrl`	No	`https://server.vistadex.com`
`wsUrl`	No	`wss://server.vistadex.com`
`positionsBaseUrl`	No	`https://markets.vistadex.com`
`timeoutMs`	No	`10,000` ms
`rpcUrl`	No	`https://api.mainnet-beta.solana.com`
`programId`	No	Built-in Vistadex mainnet program ID: `VisTAPABATtyG5FGQ3twF7Hk6xAi6qBPS5BLuGoSQ3i`
`expectedFeeCollectorWallet`	No	Unset; set it to pin an expected collector before signing

You can also supply custom fetch and WebSocketImpl implementations.

Execute a trade

The recommended two-step flow creates an RFQ and then lets submitTrade wait for the quote, validate and sign the transaction, submit the user signature, and wait for the filler result.

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 rfq = await client.createRfq({
  walletAddress: wallet.publicKey.toBase58(),
  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(result.transactionSignature);

The buy, sell, and trade methods wrap the same lifecycle. The lower-level quote, awaitAuctionResult, signAndSubmitRfq, submitUserSignature, and awaitFillerAction methods are available when an integration needs explicit control.

Wallet helpers

The package exports createWallet, keypairFromSecretKey, keypairToSecretKeyBase64, derivePositionMintPda, and signTransactionBase64. Keep generated or imported secret-key material on a trusted server. Use the lower-level PDA and signing helpers only when you also preserve the SDK’s transaction-validation context.

RFQ parameters

Field	Contract
`walletAddress`	Valid Solana address
`conditionId`	64 hexadecimal characters; the SDK accepts and strips an optional `0x` prefix
`collateralMint`	Valid Solana mint address
`outcomeIndex`	`0 \| 1`
`side`	`buy \| sell`
`quoteBasis`	`usd \| shares`
`usdAmount`	Positive and required when `quoteBasis` is `usd`
`shareAmount`	Positive and required when `quoteBasis` is `shares`
`orderType`	`market \| limit`; defaults to `market`
`limitPrice`	Required for `limit`; greater than `0` and at most `1`
`timestamp`	Optional Unix timestamp in seconds; defaults to the current time

Amounts settle with 6 decimal places. An amount must round to at least one settlement unit and remain within the maximum safely encodable 6-decimal amount. The current signing flow supports USD-denominated buys and share-denominated sells.

The direct POST /rfqs server endpoint requires condition_id without 0x. The SDK normalizes the prefix for you.

Market data and portfolio methods

Method	Behavior and limits
`getEvent(slug, options?)`	Loads `GET /v1/events/:slug`; polls every `1,000` ms for up to `60,000` ms by default when creation returns `202`. `options.platform` accepts `polymarket \| kalshi`; it is sent as the `platform` query parameter and restricts lookup to that provider’s native slug or ticker
`getMarketPrices(conditionIds)`	Loads bulk market snapshots for at most `500` condition IDs and removes duplicates
`getPositions({ walletAddress, cursor, limit })`	Reads token balances through the configured Solana `rpcUrl`, then loads position metadata; `limit` defaults to `100` and cannot exceed `200`
`getUSDCBalance({ walletAddress })`	Reads the wallet through the configured Solana `rpcUrl` and returns readable and raw USDC balances

Use nextCursor while hasMore is true to paginate positions. Position balances are returned both as raw base units and decimal strings.

WebSocket subscriptions

subscribeRfq({ walletAddress, ...callbacks }) opens the user RFQ stream and returns an object with unsubscribe(). It can report subscribed, rfq_created, auction_ended, filler_action, user_signed, error, and close events through the corresponding callbacks. Automatic reconnection defaults to true. The first reconnect delay defaults to 1,000 ms, doubles after each failed attempt, and is capped at 30,000 ms. Reconnect attempts are unlimited by default. Override those values with autoReconnect, reconnectDelayMs, maxReconnectDelayMs, and maxReconnectAttempts.

Timeouts and response values

General HTTP requests use the configured timeoutMs, which defaults to 10,000 ms.
Event creation polling defaults to 1,000 ms between attempts and a 60,000 ms maximum wait.
The high-level quote, buy, sell, and trade methods wait until auctionEndTime plus 5,000 ms for a quote, with a minimum wait of 5,000 ms, unless quoteTimeoutMs is supplied.
submitTrade uses a 60,000 ms quote fallback only when it must fetch a missing auction result. awaitAuctionResult, awaitFillerAction, and the submitTrade filler phase also default to 60,000 ms unless their method-specific timeout is supplied.
Before submitting the user signature, submitTrade waits for its RFQ WebSocket subscription to become ready. The readiness timeout is fillerTimeoutMs clamped to a minimum of 1,000 ms and a maximum of 10,000 ms; the wait ends as soon as the subscription is confirmed.
RFQ responses include auctionDurationMs and auctionEndTime. Use those response fields instead of assuming the server’s configured auction duration.
Fee fields, when present, are RFQ-specific. Do not infer the charged platform fee from the SDK’s independent signing-safety ceiling.

Signing safety

The standard SDK flow validates server-supplied Solana transactions before signing. It binds the transaction to the requested wallet, market, side, amounts, winning filler, programs, accounts, and any returned fee context. If you sign a transaction obtained outside the standard flow, provide an explicit signingContext. Context-free signing is rejected because the SDK cannot safely determine what the transaction is intended to do.

Errors

SDK failures throw VistadexError. Treat validation failures as non-retryable until the input changes. Network timeouts, temporary 202 event creation responses, and unavailable quotes may be retryable according to your application’s policy.

​Product context

​Requirements

​Install

​Create a client

​Configuration defaults

​Execute a trade

​Wallet helpers

​RFQ parameters

​Market data and portfolio methods

​WebSocket subscriptions

​Timeouts and response values

​Signing safety

​Errors

Product context

Requirements

Install

Create a client

Configuration defaults

Execute a trade

Wallet helpers

RFQ parameters

Market data and portfolio methods

WebSocket subscriptions

Timeouts and response values

Signing safety

Errors