Velocity SDK
The TypeScript SDK (@velocity-exchange/sdk) is the primary way to build on Velocity: placing and canceling orders, managing accounts and positions, subscribing to onchain updates, and integrating protocol logic in your backend or client app.
Suggested reading path
The pages in this section build on each other. If you’re new, read them in this order:
- Get set up — Setup (program addresses, wallet,
VelocityClient), then Precision & Types (everything isBNs at fixed precision — read this before touching funds). - Move funds — Deposits & Withdrawals and Transfers.
- Trade — Users, Markets, Orders, and P&L / Risk.
- Go deeper — Events, DLOB, Swaps, Swift, Builder Codes, and SDK Internals (including error handling).
If you haven’t yet, skim the Concepts section first — the account model explains the onchain state the SDK wraps.
End-to-end example
A minimal flow — connect, deposit USDT, 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 {
VelocityClient, Wallet, loadKeypair,
getMarketOrderParams, PositionDirection, BASE_PRECISION, BN,
} 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 USDT as collateral (see Deposits & Withdrawals)
const marketIndex = 0; // quote asset spot market
const amount = velocityClient.convertToSpotPrecision(marketIndex, 100);
const associatedTokenAccount = await velocityClient.getAssociatedTokenAccount(marketIndex);
await velocityClient.deposit(amount, marketIndex, associatedTokenAccount);
// 3. Place a market order: long 1 SOL-PERP (see Orders)
const txSig = await velocityClient.placePerpOrder(
getMarketOrderParams({
marketIndex: 0,
direction: PositionDirection.LONG,
baseAssetAmount: new BN(1).mul(BASE_PRECISION),
})
);
console.log("order placed:", txSig);
// 4. Read back account state (see P&L / 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, stale oracle, RPC errors) — wrap calls in try/catch and inspect the program error code. See Error handling in SDK Internals for how to decode program errors and retry safely.