SDK API

The SDK is the TypeScript boundary for apps, bots, and backend services that need to build Collateral Rail calls without hand-copying ABIs or recreating hookData wiring.

Package

Package: @steerprotocol/collateral-rail-sdk

npm install @steerprotocol/collateral-rail-sdk

Peer runtime stack:

viem for public and wallet clients.
wagmi when you want generated React-facing contract actions.
a quote server response when the path needs signed settlement material.

Build A Signed Swap Call

Use this when you already have hookData from the quote server and need a router call descriptor for SignedCollateralSwapRouter.

import {
  buildExactInputSignedQuoteCallDescriptor,
  defaultSwapDeadline,
} from "@steerprotocol/collateral-rail-sdk";

const call = buildExactInputSignedQuoteCallDescriptor({
  executorAddress: manifest.router,
  poolKey: manifest.poolKey,
  amountIn: 1_000_000n,
  amountOutMin: 990_000n,
  zeroForOne: true,
  receiver: account.address,
  deadline: defaultSwapDeadline(),
  hookData: quote.hookData,
});

await walletClient.writeContract({
  address: call.to,
  abi: call.abi,
  functionName: call.functionName,
  args: call.args,
  account,
});

Turn A Product Quote Into A Swap

Use this for protected native-stablecoin product quotes. The helper rejects expired or nearly stale quotes, calculates the output floor, and returns the raw router call.

import {
  buildProductSwapExecutionDescriptor,
  parseNativeStablecoinQuoteResponse,
} from "@steerprotocol/collateral-rail-sdk";

const nativeQuote = parseNativeStablecoinQuoteResponse(await response.json());

const descriptor = buildProductSwapExecutionDescriptor({
  draft: {
    direction: "open",
    instanceKind: "protected-cdp",
    quoteProvider: "nrtusd-native",
    collateralToken: manifest.collateralToken,
    stablecoin: manifest.stablecoin,
    amountIn: "1000000",
    quoteExpiresAt: nativeQuote.quoteExpiresAt,
    nativeQuote,
  },
  manifest,
  receiver: account.address,
  executorAddress: manifest.router,
  deadline: BigInt(nativeQuote.quoteExpiresAt),
  slippageBps: 50,
});

await walletClient.writeContract({
  address: descriptor.raw.to,
  abi: descriptor.raw.abi,
  functionName: descriptor.raw.functionName,
  args: descriptor.raw.args,
  account,
});

Parse Quote Server Responses

Use the parsers at the network boundary. They validate response shape before app code depends on hookData, expiry, route preview, or registered-issuer material.

import {
  parseM1DepositQuoteResponse,
  parseNativeStablecoinQuoteResponse,
  parseRegisteredIssuerQuoteResponse,
} from "@steerprotocol/collateral-rail-sdk";

const registeredIssuerQuote = parseRegisteredIssuerQuoteResponse(rawJson);
const m1DepositQuote = parseM1DepositQuoteResponse(rawJson);
const nativeQuote = parseNativeStablecoinQuoteResponse(rawJson);

When To Reach For Lower-Level Surfaces

Most integrations should start with the call builders and quote parsers above. Reach lower only when you have a specific job:

Need	Use
Raw contract clients or simulations	named ABIs, `generated`, `createProtocolPublicClient`
Manual signed quote encoding	`signedQuote` helpers
Liquidation bots	`liquidation` and `liquidationHookData` helpers
Deployment source of truth	`manifest` helpers
User-facing errors and logs	`errors`, `swapErrors`, and `events`
Runtime health cards	`readiness` helpers

Source Files

sdk/src/index.ts
sdk/src/swap.ts
sdk/src/productSwapExecution.ts
sdk/src/quotePayload.ts