# Velocity SDK

> Canonical: https://docs.velocity.exchange/developers/velocity-sdk

`@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](/developers/concepts.md).

## Where to start

Read [Setup](/developers/velocity-sdk/setup.md) and [Precision and Types](/developers/velocity-sdk/precision-and-types.md) 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](/developers/velocity-sdk/deposits-withdrawals.md) and [Orders](/developers/velocity-sdk/orders.md) 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

## 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.

```js
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();
}
```

> **Info:**
>
> 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](/developers/velocity-sdk/sdk-internals.md#error-handling) for how to decode program errors and retry safely.