Repository navigation
Releases
v0.4.0
Overview
New SDK surface:
quoteTimeoutonquotes.get()QUOTE_TIMEOUTerror code, reported inquote.warnings
SDK 0.4.0 requires Pegaroute v0.9.3 for quoteTimeout.
npm install @pegaroute/sdk@0.4.00.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
-1returns 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
Overview
New SDK surface:
userIponquotes.get()andswaps.create()destinationMemoonquotes.get()andswaps.create()QuoteRoute.destinationMemoLabelDESTINATION_MEMO_UNSUPPORTEDproviderStatusonTransactionWebhookData.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.00.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:
- Send the same
userIpto bothquotes.get()andswaps.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,
});- To send a destination memo, tag, or payment ID, pass
destinationMemoto 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.
- 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.
}
}
}- Read provider status evidence from webhooks when present.
if (event.data.input.providerStatus?.actionRequired) {
showAction(event.data.input.providerStatus.message);
}v0.2.0
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.0Breaking 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/sdkand@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
First public release of the TypeScript SDK for the Pegaroute cross-chain swap API.
npm install @pegaroute/sdkWhat's included
- Typed client for every API-key endpoint:
quotes.get,swaps.create/get/events/submitTxHash,transactions.list(paginated),chains,tokens,providers,healthandping. - Status polling:
swaps.waitForCompletionwaits until a swap reaches a final status. - Webhook verification:
verifyWebhookchecks theX-Pegasus-SignatureHMAC and returns a typed event. - Typed errors: a
PegarouteErrorsubclass per HTTP status, includingProviderChangedError, which carries the refreshed quote. GET requests are retried on network failures and retryable errors. - Browser-safe types:
@pegaroute/sdk/typesexports the types and type guards your frontend needs to readexecutionand sign, without the client or the API key.
Requirements
- Node.js 22.12+, Bun or Deno. ESM only:
importit, orrequire()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.