Velocity Protocol

@velocity-exchange/sdk is the TypeScript client for the Velocity program: it derives the accounts, builds the instructions, signs and sends the transactions, and keeps a live cache of the onchain state the caller reads between calls. These pages are written for someone integrating against it, whether that is a trading bot, a keeper, a front end, or a backend service. Everything here assumes the SDK; for the onchain layouts underneath it, see Concepts.

Where to start

Read Setup and Precision and Types before anything else. Setup covers constructing and subscribing a client; precision explains why every amount is a BN at a fixed exponent, which is the single mistake most likely to move real funds the wrong way. From there, Deposits & Withdrawals and Orders cover the two paths almost every integration needs.

The rest is reference. Read a page when the thing it covers comes up.

In this section

Setup

Program IDs, the quote mint per environment, loading a wallet, and constructing and subscribing a VelocityClient.

Precision and Types

The precision constants, BigNum, token math helpers, and why a slot count is not a fixed amount of time.

Deposits & Withdrawals

Moving tokens between a wallet token account and a subaccount's spot balance, plus the borrow and lend rates.

Transfers

Moving deposits, borrows, and perp positions between subaccounts under one authority, including delegate transfers.

Users

Subaccounts, the active subaccount, delegates, margin settings, and reading orders and positions off a User.

Markets, Oracles, and Positions

Reading perp and spot market accounts, oracle prices, market tier numbers, and the global state account.

Orders

Order types and post-only modes, placement and cancels, scale-order ladders, and the raw instruction builders.

PnL & Risk

Health, total and free collateral, margin requirement, leverage, unrealized PnL, and settling perp PnL.

Events

The full event catalog and how EventSubscriber filters, buffers, and replays program events.

DLOB

Building a local order book out of user accounts, then querying L2 depth and best bid/ask.

Swaps

Routing a collateral swap through Jupiter or Titan so tokens move through the account's Velocity spot balances.

Swift

Signing an order offchain and submitting it for keepers and market makers to land onchain.

Builder Codes

Attaching a builder fee to an order, the fill-time escrow requirement, and collecting accrued revenue share.

Transactions

The four tx senders, blockhash caching, compute-unit sizing, and the priority-fee subscribers.

SDK Internals

Account subscription strategies, the subscriber and map catalog, caching behavior, and error handling.

End-to-end example

Connect, deposit collateral, place a market order, and read back the position. Each step is covered in depth on its own page.

import { Connection } from "@solana/web3.js";
import {
  PositionDirection,
  VelocityClient,
  Wallet,
  getMarketOrderParams,
  loadKeypair,
} from "@velocity-exchange/sdk";

// 1. Connect and subscribe (see Setup)
const connection = new Connection("<RPC_URL>", "confirmed");
const wallet = new Wallet(loadKeypair("<KEYPAIR_PATH>"));
const velocityClient = new VelocityClient({ connection, wallet, env: "mainnet-beta" });
await velocityClient.subscribe();

try {
  // 2. Deposit 100 quote-asset units as collateral (see Deposits & Withdrawals)
  const quoteMarketIndex = 0; // spot market 0 is the quote asset
  const amount = velocityClient.convertToSpotPrecision(quoteMarketIndex, 100);
  const associatedTokenAccount =
    await velocityClient.getAssociatedTokenAccount(quoteMarketIndex);
  await velocityClient.deposit(amount, quoteMarketIndex, associatedTokenAccount);

  // 3. Place a market order: long 1 SOL-PERP (see Orders)
  const txSig = await velocityClient.placePerpOrder(
    getMarketOrderParams({
      marketIndex: 0, // perp market 0 is SOL-PERP
      direction: PositionDirection.LONG,
      baseAssetAmount: velocityClient.convertToPerpPrecision(1),
    })
  );
  console.log("order placed:", txSig);

  // 4. Read back account state (see PnL & Risk)
  const user = velocityClient.getUser();
  console.log("health:", user.getHealth());
} finally {
  await velocityClient.unsubscribe();
}

Every SDK call that sends a transaction can fail: insufficient collateral, a stale oracle, an RPC error. Wrap calls in try/catch and inspect the program error code. See Error handling for how to decode program errors and retry safely.

Velocity SDK