Skip to content

Releases

v0.4.0

Choose a tag to compare

@dillu24 dillu24 released this 16 Nov 11:05

Overview

New SDK surface:

  • quoteTimeout on quotes.get()
  • QUOTE_TIMEOUT error code, reported in quote.warnings

SDK 0.4.0 requires Pegaroute v0.9.3 for quoteTimeout.

npm install @pegaroute/sdk@0.4.0

0.4.0 is additive over 0.3.0. Existing calls remain valid.

Upgrading

quoteTimeout controls how long Pegaroute collects provider quotes:

  • omitted or 0: wait for every provider (the current behaviour)
  • positive: a collection window in seconds. The full window is used, then pending providers are ignored if at least one quote arrived
  • negative: return once that many valid quotes arrived, so -1 returns the first quote
const quote = await pr.quotes.get({ ...params, quoteTimeout: 5 });

for (const warning of quote.warnings) {
  if (warning.code === "QUOTE_TIMEOUT") {
    // This provider was still pending when collection stopped.
  }
}

This is separate from the client's HTTP timeoutMs, which bounds the whole request, so keep timeoutMs above the quote window.

Full changelog: v0.3.0...v0.4.0

v0.3.0

Choose a tag to compare

@atharen atharen released this 11 Nov 09:55
285c7ea

Overview

New SDK surface:

  • userIp on quotes.get() and swaps.create()
  • destinationMemo on quotes.get() and swaps.create()
  • QuoteRoute.destinationMemoLabel
  • DESTINATION_MEMO_UNSUPPORTED
  • providerStatus on TransactionWebhookData.input

SDK 0.3.0 requires Pegaroute v0.9.0 for destination memo and webhook provider-status fields.

Upgrade guide: 0.2.0 → 0.3.0

Install the new SDK:

npm install @pegaroute/sdk@0.3.0

0.3.0 is additive over 0.2.0. Existing quote and swap calls remain valid. No catalog-specific SDK changes are required: chain and token IDs are already typed as strings.

To enable SwapSpace routes:

  1. Send the same userIp to both quotes.get() and swaps.create().
const quote = await pr.quotes.get({
  fromChain: "ETH",
  fromToken: "ETH",
  toChain: "CANTON",
  toToken: "CC",
  amount: "1",
  userIp: "203.0.113.7",
});

const route = quote.routes.find((candidate) => candidate.provider === "swapspace") ?? quote.routes[0];

const swap = await pr.swaps.create({
  fromChain: "ETH",
  fromToken: "ETH",
  toChain: "CANTON",
  toToken: "CC",
  amount: "1",
  senderAddress: "0x1111111111111111111111111111111111111111",
  destinationAddress: "canton-address",
  userIp: "203.0.113.7",
  quoteId: quote.quoteId,
  routeProvider: route?.provider,
});
  1. To send a destination memo, tag, or payment ID, pass destinationMemo to both calls.
const destinationMemo = "payment-id-1";

const quote = await pr.quotes.get({
  fromChain: "ETH",
  fromToken: "ETH",
  toChain: "CANTON",
  toToken: "CC",
  amount: "1",
  userIp: "203.0.113.7",
  destinationMemo,
});

const destinationMemoLabel = quote.routes[0]?.destinationMemoLabel;

const swap = await pr.swaps.create({
  fromChain: "ETH",
  fromToken: "ETH",
  toChain: "CANTON",
  toToken: "CC",
  amount: "1",
  senderAddress: "0x1111111111111111111111111111111111111111",
  destinationAddress: "canton-address",
  userIp: "203.0.113.7",
  destinationMemo,
  quoteId: quote.quoteId,
  routeProvider: quote.routes[0]?.provider,
});

Use destinationMemoLabel for the field label. It is the live provider label, such as Memo, Tag, or Payment ID. Do not add destinationMemo to execution.memo; it is not a source-chain signing memo.

  1. Handle the new errors.
import { PegarouteError } from "@pegaroute/sdk";

try {
  const quote = await pr.quotes.get(params);
} catch (error) {
  if (error instanceof PegarouteError) {
    if (error.code === "USER_IP_REQUIRED") {
      // Collect a valid end-user IP and retry the quote.
    }
    if (error.code === "DESTINATION_MEMO_UNSUPPORTED") {
      // Remove destinationMemo or choose a route that supports it.
    }
  }
}
  1. Read provider status evidence from webhooks when present.
if (event.data.input.providerStatus?.actionRequired) {
  showAction(event.data.input.providerStatus.message);
}

v0.2.0

Choose a tag to compare

@dillu24 dillu24 released this 14 Oct 14:12
c6adbd5

Quote routes now have one standard fee measure, priced at reference prices, instead of the per-provider fee fields. This follows Pegaroute's new fee API and is a breaking change.

npm install @pegaroute/sdk@0.2.0

Breaking changes

Before Now
QuoteRoute.fees: QuoteFees QuoteRouteFees | NoQuoteRouteFees: total in USD and bps, split into affiliate, route and gas. {} means no fee data, not a zero fee
QuoteRoute.resolvedFee removed
(none) QuoteRoute.additionalFee: AdditionalFee | null: a fee the wallet pays on top, in the source chain's native coin
RouteInfo.fees, GetSwapResponse.fees, Transaction.fees, TransactionWebhookData.fees removed
QuoteFees type removed; new QuoteRouteFees, NoQuoteRouteFees, FeeAmount, AdditionalFee

Routes are now ranked by expectedOutput minus additionalFee, then by speed.

Added

  • hasQuoteRouteFees(fees) tells full fees from {}. It's exported from @pegaroute/sdk and @pegaroute/sdk/types.

Upgrading

if (hasQuoteRouteFees(route.fees)) show(`$${route.fees.totalUsd} (${route.fees.totalBps} bps)`);
if (route.additionalFee) show(`+ ${route.additionalFee.amount} ${route.additionalFee.token}`);

fees.totalUsd is never negative, so compare routes by expectedOutput. See the README.

Full changelog: v0.1.0...v0.2.0

v0.1.0

Choose a tag to compare

@dillu24 dillu24 released this 12 Oct 14:01

First public release of the TypeScript SDK for the Pegaroute cross-chain swap API.

npm install @pegaroute/sdk

What's included

  • Typed client for every API-key endpoint: quotes.get, swaps.create / get / events / submitTxHash, transactions.list (paginated), chains, tokens, providers, health and ping.
  • Status polling: swaps.waitForCompletion waits until a swap reaches a final status.
  • Webhook verification: verifyWebhook checks the X-Pegasus-Signature HMAC and returns a typed event.
  • Typed errors: a PegarouteError subclass per HTTP status, including ProviderChangedError, which carries the refreshed quote. GET requests are retried on network failures and retryable errors.
  • Browser-safe types: @pegaroute/sdk/types exports the types and type guards your frontend needs to read execution and sign, without the client or the API key.

Requirements

  • Node.js 22.12+, Bun or Deno. ESM only: import it, or require() it from CommonJS on Node 22.12+.
  • Use the client on your backend only: it holds your API key.

See the README for usage, and examples/ for a backend (Hono) and EVM signing (viem) example.

Before 1.0, a minor release may include breaking changes.