Quick Start

This guide creates the SDK clients, reads exchange data, submits a signed order, and subscribes to live updates.

1. Install the SDK

npm install @gammaswap/v2-exchange-sdk ethers

2. Configure the environment

EXCHANGE_API_URL=https://exchange-api.gammaswap.com/api
MARKET_WS_URL=wss://exchange-api.gammaswap.com/ws/
ORACLE_WS_URL=wss://exchange-api.gammaswap.com/oracle-ws/

CHAIN_ID=84532
RPC_URL=https://your-rpc-provider.example
PRIVATE_KEY=0x...

Keep private keys in a server-side secret manager. Do not include them in frontend bundles or commit them to source control.

3. Read asset metadata

Read-only methods use InfoClient and do not require a wallet.

import { createInfoClient } from "@gammaswap/v2-exchange-sdk";

const info = createInfoClient({
  apiUrl: process.env.EXCHANGE_API_URL!,
});

const assetId =
  "261336857817713630688382311349658711122006440411137";

const asset = await info.getAsset(assetId);

console.log(asset);

Example response:

{
  "assetId": "261336857817713630688382311349658711122006440411137",
  "epoch": "12",
  "registered": true,
  "expiration": "1730000000",
  "assetType": "2",
  "strikePrice": "999000",
  "ledger": "0x1111111111111111111111111111111111111111"
}

4. Load an order-book snapshot

const epoch = "12";

const book = await info.getOrderBook({
  assetId,
  epoch,
});

console.log(book.bids);
console.log(book.asks);

Example response:

{
  "assetId": "261336857817713630688382311349658711122006440411137",
  "epoch": "12",
  "ts": 1730000000,
  "seqId": 123,
  "bids": [],
  "asks": []
}

5. Create a signed exchange client

import { createExchangeClient } from "@gammaswap/v2-exchange-sdk";
import { Wallet } from "ethers";

const wallet = new Wallet(process.env.PRIVATE_KEY!);

const exchange = createExchangeClient({
  apiUrl: process.env.EXCHANGE_API_URL!,
  wallet,
  chainId: process.env.CHAIN_ID!,
});

6. Place an order

const order = await exchange.placeOrder({
  assetId,
  epoch,
  side: false,
  price: "99.9",
  size: "10.25",
});

console.log(order);

Order input conventions:

Field	Meaning
side: false	Buy
side: true	Sell
price	Human decimal string with up to one decimal place
size	Human decimal string with up to two decimal places
timeInForce	Optional; defaults to GTC
nonce	Optional; generated by the SDK

Example response:

{
  "orderId": "0x1111111111111111111111111111111111111111111111111111111111111111",
  "filled": "0",
  "remaining": "1025",
  "cancelled": "0",
  "status": "ACCEPTED",
  "reason": ""
}

7. Subscribe to market updates

Load the REST order-book snapshot before applying live updates.

import {
  createExchangeWebSocketClient,
} from "@gammaswap/v2-exchange-sdk";

const marketStream = createExchangeWebSocketClient({
  websocketUrl: process.env.MARKET_WS_URL!,
  onError: (error) => console.error("Market stream error", error),
});

const unsubscribeBook = await marketStream.subscribeOrderBook(assetId, {
  onUpdate: (update) => {
    console.log("Market update", update);
  },
  onOrder: (update) => {
    console.log("Order update", update);
  },
  onTrade: (update) => {
    console.log("Trade update", update);
  },
  onCancel: (update) => {
    console.log("Cancel update", update);
  },
  onResolution: (update) => {
    console.log("Resolution update", update);
  },
  onResyncRequired: async (resyncAssetId) => {
    const freshBook = await info.getOrderBook({
      assetId: resyncAssetId,
      epoch,
    });

    console.log("Reloaded order book", freshBook);
  },
});

When the subscription is no longer needed:

await unsubscribeBook();
marketStream.close();

8. Subscribe to oracle prices

import {
  createOracleWebSocketClient,
} from "@gammaswap/v2-exchange-sdk";

const oracleStream = createOracleWebSocketClient({
  websocketUrl: process.env.ORACLE_WS_URL!,
  stalePriceTimeoutMs: 30_000,
  onError: (error) => console.error("Oracle stream error", error),
});

const unsubscribePrice = await oracleStream.subscribePrice("1", {
  onPrice: (update) => {
    console.log(
      "Oracle price",
      update.symbolId,
      update.price,
      update.ts,
    );
  },
  onStale: (symbolId) => {
    console.warn("Oracle price is stale", symbolId);
  },
});

When the subscription is no longer needed:

await unsubscribePrice();
oracleStream.close();

9. Create a deposit client

Deposits communicate directly with onchain contracts.

import { createDepositClient } from "@gammaswap/v2-exchange-sdk";

const deposit = createDepositClient({
  rpcUrl: process.env.RPC_URL!,
  wallet,
  chainId: process.env.CHAIN_ID!,
});

Check the connected wallet’s settlement-token balance:

const balance = await deposit.getSettlementTokenBalance();

console.log(balance);

Before submitting a deposit, approve the required spender using the relevant deposit-ledger or Permit2 approval method.

Next steps

• Use InfoClient to read balances, positions, books, and resolutions.

• Use ExchangeClient to place orders, cancel orders, claim, and withdraw.

• Use an agent wallet to separate automated signing from the master wallet.

• Use DepositClient for token approvals and deposits.

• Use the WebSocket clients for real-time market and oracle updates.