@deserialize/swap-sdk

deserialize-swap-sdk

Swap SDK

The Swap SDK is a TypeScript library that simplifies interacting with a Deserialize swap endpoint. It abstracts away the low-level details of converting between SVM types (e.g., PublicKey, Keypair) and the API’s JSON formats. Use it to easily construct swap transactions or retrieve underlying instructions for advanced scenarios.

Features

• Simple API:
  Accepts SVM PublicKey objects and numerical amounts while handling all necessary conversions.
• Transaction Deserialization & Signing:
  Automatically converts a base64-encoded transaction from the API into a VersionedTransaction and applies signatures.
• Flexible Usage:
  Choose between getting a fully constructed transaction (using swapTx) or the raw instructions (using swapIx) for manual transaction assembly.
• Custom Routing Options:
  Pass options (e.g., limiting swap hops) to tailor the swap behavior to your needs.

Installation

Install the package via npm (or yarn):

npm install @deserialize/swap-sdk
# or
yarn add @deserialize/swap-sdk

Usage

Below is a simple example of how to use the SDK in your project:

// index.ts
import { SwapSDK } from "@deserialize/swap-sdk";
import { Buffer } from "buffer";
(async () => {
  const deserialize = new SwapSDK();

  const privKey = "PRIVATE_KEY";

  const privateKeyArray = deserialize.base58.decode(privKey);
  const userKeyPair = deserialize.web3.Keypair.fromSecretKey(privateKeyArray);

  const params = {
    tokenB: new deserialize.web3.PublicKey(
      "BeRUj3h7BqkbdfFU7FBNYbodgf8GCHodzKvF9aVjNNfL"
    ),
    tokenA: new deserialize.web3.PublicKey(
      "GU7NS9xCwgNPiAdJ69iusFrRfawjDDPjeMBovhV1d4kn"
    ),
    publicKey: new deserialize.web3.PublicKey(
      "8PE7zNHVmn1zmFqNxPHpgjriDd8MNfTHWadPKenYDQX2"
    ),
    amountIn: 0.0028,
    dexId: "INVARIANT",
    options: {
      reduceToTwoHops: false, //set to true if you always want two hops
    },
  };
  const response = await deserialize.swapTx(params);

  console.log("Instructions:", response);
  //sign and simulate the transaction

  const connection = new deserialize.web3.Connection(
    "https:///eclipse.lgns.net",
    "confirmed"
  );
  const tx = response.transaction;

  const serializedTx = Buffer.from(tx.serialize()).toString("base64");
  console.log("serializedTx: ", serializedTx);

  const { value } = await connection.simulateTransaction(tx);
  console.log("value: ", value);

  tx.sign([userKeyPair]);
  const sign = await connection.sendTransaction(tx, { skipPreflight: false });
  console.log("sign: ", sign);
})();

API Reference

SwapSDK

Constructor

new SwapSDK(baseUrl?: string)

Methods

• swapTx(params: SwapRequestParams): Promise<SwapTxResult>
  Sends a swap request and returns a fully constructed, unsigned VersionedTransaction along with:

  • amountOut: Raw output amount.
  • amountOutUi: Human-readable output amount.
  • routePlan: An array of route steps (with tokens as PublicKey).
  • lookupAccounts: Lookup accounts as PublicKey objects.
  • signers: Signers as Keypair objects.

• swapIx(params: SwapRequestParams): Promise<SwapIxResult>
  Sends a swap request and returns the underlying instruction groups and additional swap details:

  • instructionGroups: Groups of main and cleanup instructions (as TransactionInstruction objects).
  • amountOut: Raw output amount.
  • amountOutUi: Human-readable output amount.
  • routePlan: An array of route steps (with tokens as PublicKey).
  • lookupAccounts: Lookup accounts as PublicKey objects.
  • signers: Top-level signers as base64-encoded strings.

Interfaces

SwapRequestParams

• publicKey: User's public key (PublicKey).
• tokenA: Token A's address (PublicKey).
• tokenB: Token B's address (PublicKey).
• amountIn: Amount of token A to swap (number, in human-readable units).
• dexId: "INVARIANT" (string literal).
• options?: Optional routing options (RouteOptions).

RouteOptions

• reduceToTwoHops: boolean — if set to true, limits the swap to two hops to avoid errors like TooManyAccountLocks.

SwapTxResult & SwapIxResult

Both results include the output amounts, route plan, and lookup accounts; the key difference is that SwapTxResult returns a full transaction (as a VersionedTransaction), whereas SwapIxResult returns raw instruction groups.

License

This project is licensed under the MIT License.

Happy swapping!

---