@pegaroute/sdk 0.0.0-stage → 0.1.0

package/dist/index-CeY_5Z4u.d.ts

@@ -0,0 +1,1070 @@
+//#region src/types/discovery.d.ts
+/** A chain Pegaroute can route to or from. */
+interface Chain {
+  /** Chain ID to use in quote and swap requests, e.g. `"ETH"`. */
+  id: string;
+  /** Display name, e.g. `"Ethereum"`. */
+  name: string;
+  /** EVM chain ID, or `null` for non-EVM chains. */
+  chainId: number | null;
+}
+/** Response of `chains.list()`. */
+interface ChainsResponse {
+  /** Every chain Pegaroute can route to or from. */
+  chains: Chain[];
+}
+/** A token Pegaroute recognises on a chain. Decimals are not included: use the swap's `TokenAmount` values instead. */
+interface Token {
+  /** Token ID to use in quote and swap requests, e.g. `"SOL"` or `"USDC-0xA0b8…"`. */
+  id: string;
+  /** Display symbol, e.g. `"USDC"`. */
+  symbol: string;
+}
+/** Response of `tokens.list(chain)`. */
+interface TokensResponse {
+  /** Canonical ID of the requested chain (the lookup ignores case). */
+  chain: string;
+  /** Tokens Pegaroute recognises on that chain. */
+  tokens: Token[];
+}
+/** Provider integration types Pegaroute is known to use. */
+type KnownProviderType = "cross-chain-amm" | "cross-chain-aggregator" | "dex-aggregator" | "api-provider";
+/** Any provider integration type, including ones added after this SDK version. */
+type ProviderType = KnownProviderType | (string & {});
+/**
+ * A provider's documented affiliate (referrer) fee range.
+ * Each value is given both in basis points and as a percent.
+ */
+interface ProviderAffiliateFeeStructure {
+  /** Minimum fee in basis points, when the provider documents one. */
+  minBps?: number;
+  /** Minimum fee as a percent, when the provider documents one. */
+  minPercent?: number;
+  /** Minimum non-zero fee in basis points; zero (no fee) stays valid. */
+  minBpsWhenSet?: number;
+  /** Minimum non-zero fee as a percent; zero (no fee) stays valid. */
+  minPercentWhenSet?: number;
+  /** Maximum fee in basis points. */
+  maxBps: number;
+  /** Maximum fee as a percent. */
+  maxPercent: number;
+  /** Fee the provider applies when none is requested, in basis points. */
+  defaultBps?: number;
+  /** Fee the provider applies when none is requested, as a percent. */
+  defaultPercent?: number;
+}
+/** The provider's cut of the affiliate fee (a share of the fee, not of the swap amount). */
+interface ProviderTakeStructure {
+  /** Provider's cut in basis points of the affiliate fee. */
+  bpsOfAffiliateFee: number;
+  /** Provider's cut as a percent of the affiliate fee. */
+  percentOfAffiliateFee: number;
+}
+/** A provider's documented affiliate fee range and its cut of that fee. */
+interface ProviderFeeStructure {
+  /** The affiliate fee range the provider accepts. */
+  affiliateFee: ProviderAffiliateFeeStructure;
+  /** Provider's cut of the affiliate fee, or `null` when it takes none. */
+  providerTake: ProviderTakeStructure | null;
+}
+/** A provider's live status, as returned by `health()`. */
+interface ProviderHealth {
+  /** Provider name, e.g. `"thorchain"`. */
+  name: string;
+  /** Provider integration type. */
+  type: ProviderType;
+  /** Whether the provider's last health check succeeded. */
+  available: boolean;
+  /** Whether the provider is switched on for new quotes. */
+  routingEnabled: boolean;
+  /** Pegaroute's circuit breaker for this provider: `open` means requests to it are currently paused. */
+  circuitState: "closed" | "open" | "half-open";
+  /** Latency of the last health check, in milliseconds. */
+  latencyMs: number;
+  /** Chains the provider has halted. */
+  haltedChains: string[];
+  /** When the provider was last checked (ISO 8601). */
+  lastChecked: string;
+  /** Pegaroute's maximum affiliate fee for this provider in basis points, or `null` when none is configured. */
+  maxAffiliateBps: number | null;
+  /** The provider's documented fee range, or `null` when unknown. */
+  feeStructure: ProviderFeeStructure | null;
+}
+/** A provider, as returned by `providers.list()`. */
+interface ProviderInfo extends ProviderHealth {
+  /**
+   * Chain IDs the provider can route in principle. A quote is still the source of truth for current availability.
+   */
+  supportedChains: string[];
+  /** Only returned to Pegaroute operators; always `null` for API keys. */
+  configuredReferral: null;
+}
+/** Options for `providers.list()`. */
+interface ListProvidersParams {
+  /** Also return providers that are switched off (`routingEnabled: false`). Default `false`. */
+  includeDisabled?: boolean;
+}
+/** Response of `providers.list()`. */
+interface ProvidersResponse {
+  /**
+   * The providers that are switched on, with their live status. Providers that are switched off
+   * (`routingEnabled: false`) are also listed when you call `providers.list({ includeDisabled: true })`.
+   */
+  providers: ProviderInfo[];
+}
+/** Response of `health()`. */
+interface HealthResponse {
+  /** `degraded` when the database is down or an enabled provider is unavailable. */
+  status: "ok" | "degraded";
+  /** Server time (ISO 8601). */
+  timestamp: string;
+  /** Database connectivity. Reports `connected: false` when Pegaroute runs without a database. */
+  db: {
+    /** Whether the database answered. */
+    connected: boolean;
+    /** Latency of the database check, in milliseconds. */
+    latencyMs: number;
+  };
+  /** Write-ahead log backlog. `pendingEntries` is `-1` when it can't be read. */
+  wal: {
+    /** Writes buffered while the database was unavailable and not yet replayed, or `-1` when unknown. */
+    pendingEntries: number;
+  };
+  /** Status of every provider, including disabled ones. */
+  providers: ProviderHealth[];
+}
+/** Response of `ping()`. */
+interface PingResponse {
+  /** Always `"pong"`. */
+  response: "pong";
+  /** Server time (ISO 8601). */
+  timestamp: string;
+  /** Service name, `"pegaroute"`. */
+  service: string;
+}
+//#endregion
+//#region src/types/common.d.ts
+/** Providers Pegaroute is known to route through. Other names may appear as providers are added. */
+type KnownProvider = "thorchain" | "maya" | "openocean" | "instaswap" | "squid";
+/** Any provider name, including ones added after this SDK version. */
+type Provider = KnownProvider | (string & {});
+/**
+ * Confidential execution mode for a swap.
+ *
+ * - `false` (or omitted): public execution.
+ * - `true`: confidential execution, falling back to zkproof.
+ * - `"zk"`: zkproof execution only.
+ *
+ * Other strings are reserved for provider modes added in the future.
+ */
+type PrivateSwapMode = boolean | "zk" | (string & {});
+/**
+ * An exact on-chain amount, in two forms.
+ *
+ * @example
+ * { display: "1000", baseUnits: "1000000000" } // 1000 USDC (6 decimals)
+ */
+interface TokenAmount {
+  /** Human-readable rendering of `baseUnits` for UI. Never rebuild `baseUnits` from it. */
+  display: string;
+  /** Exact integer in the token's smallest unit. Pass it unchanged to transfers, approvals and allowance checks. */
+  baseUnits: string;
+}
+/**
+ * Fees for a route, as human-readable decimal strings.
+ *
+ * Amounts are in destination-asset units (THORChain/Maya), or in USD when `unit` is `"USD"` (Instaswap/Squid).
+ * Read `total` for the full fee the user pays.
+ */
+interface QuoteFees {
+  /** Pegaroute's affiliate fee. For Instaswap and Squid this excludes the integrator's share (see `subAffiliate`). */
+  affiliate: string;
+  /** Liquidity and other route fees. On Squid this includes Squid's own platform share. */
+  liquidity: string;
+  /** Outbound gas fee on the destination chain (`"0"` when not applicable). */
+  outbound: string;
+  /** Sum of `affiliate`, `liquidity`, `outbound` and `subAffiliate` (when present). */
+  total: string;
+  /** Present when all fee amounts are in USD instead of asset units. */
+  unit?: "USD";
+  /** The integrator's USD share, excluded from `affiliate` (Instaswap/Squid only). */
+  subAffiliate?: string;
+  /** Total provider-facing fee in basis points, when the provider reports it. */
+  totalBps?: number;
+  /** Slippage in basis points, when the provider reports it. */
+  slippageBps?: number;
+}
+/** How the affiliate fee on a swap was split between Pegaroute and the integrator, in basis points. */
+interface AffiliateFeeBreakdown {
+  /** Pegaroute's configured share, before the provider cap is applied. */
+  configuredPegasusShareBps: number;
+  /** The integrator's configured share, before the provider cap is applied. */
+  configuredIntegratorFeeBps: number;
+  /** The provider's maximum affiliate/referrer fee. */
+  providerAffiliateCapBps: number;
+  /** The affiliate fee actually sent to the provider, after the cap. */
+  effectiveAffiliateFeeBps: number;
+  /** Pegaroute's share after the cap. */
+  realizedPegasusFeeBps: number;
+  /** The integrator's share after the cap. */
+  realizedIntegratorFeeBps: number;
+  /** Which provider fee config was used for this route. */
+  feeSource: string;
+  /** Pegaroute's real net revenue, after any provider revenue share. */
+  pegasusNetBps?: number;
+  /** Pegaroute's net revenue in USD, when the provider reports it (Instaswap). */
+  pegasusNetUsd?: string;
+}
+/** The OpenOcean meta-aggregator (Jupiter, Titan, Cetus, …) behind a Solana or Sui route. */
+interface OpenOceanRouteMeta {
+  /** Index of the winning aggregator, e.g. Solana `10` = Titan, `6` = Jupiter. */
+  dexId?: number;
+  /** Name of the winning aggregator, e.g. `"Titan"`. */
+  dexCode?: string;
+  /** Every aggregator OpenOcean considered for the quote. */
+  dexes?: Array<{
+    /** Index of the aggregator. */
+    dexId?: number;
+    /** Name of the aggregator. */
+    dexCode?: string;
+  }>;
+}
+/** The route a swap was executed on. Returned by `swaps.create`, `swaps.get` and `transactions.list`. */
+interface RouteInfo {
+  /** The provider executing the swap. */
+  provider: Provider;
+  /** Route chosen inside the provider (e.g. `"Chainflip"`), when the provider exposes one. */
+  subprovider?: string;
+  /** Confidential execution mode of the swap. */
+  private?: PrivateSwapMode;
+  /** Expected output amount in the destination token, as a human-readable decimal. */
+  expectedOutput: string;
+  /** Fees for this route. */
+  fees: QuoteFees;
+  /** Estimated time to complete, in seconds. */
+  estimatedTimeSeconds: number;
+  /** OpenOcean aggregator behind the route (Solana/Sui only). */
+  openOceanRoute?: OpenOceanRouteMeta;
+}
+/**
+ * A refund observed for a failed swap.
+ *
+ * `status` here is the refund's own lifecycle, separate from the swap's status: a swap can already be
+ * `refunded` (internal) / `fail` (external) while the refund is still `pending` or `broadcasting`.
+ */
+interface RefundInfo {
+  /** Refund lifecycle state. */
+  status: "pending" | "broadcasting" | "completed";
+  /** Refund transaction hash, once known. */
+  txHash?: string;
+  /** Chain the refund is sent on. */
+  chain: string;
+  /** Amount refunded, as a human-readable decimal. */
+  amount: string;
+  /** The original source amount of the swap. */
+  originalAmount: string;
+  /** Amount deducted from the refund (e.g. network fees). */
+  feeDeducted: string;
+  /** What the deducted amount was for. */
+  feeDescription: string;
+  /** Address the refund was actually sent to. May differ from the refund address requested on the swap. */
+  refundAddress: string;
+  /** When the refund completed (ISO 8601), once known. */
+  completedAt?: string;
+}
+/** Progress of a streaming swap, which executes as several smaller sub-swaps. */
+interface StreamingProgress {
+  /** Sub-swaps finished so far. */
+  completedSubSwaps: number;
+  /** Total sub-swaps planned. */
+  totalSubSwaps: number;
+  /** When the last sub-swap happened (ISO 8601). */
+  lastSubSwapTimestamp?: string;
+  /** Output received so far, as a human-readable decimal. */
+  partialOutput?: string;
+  /** Amount refunded so far, when some sub-swaps could not execute. */
+  partialRefund?: {
+    /** Amount refunded, in the same format as `partialOutput`. */
+    amount: string;
+    /** Chain the refund was sent on. */
+    chain: string;
+    /** Token refunded. */
+    token: string;
+  };
+}
+//#endregion
+//#region src/types/errors.d.ts
+/** Error codes Pegaroute is known to return. Other strings may appear as the API evolves. */
+type KnownErrorCode = "VALIDATION_ERROR" | "UNAUTHORIZED" | "NOT_FOUND" | "UNSUPPORTED_PAIR" | "AMOUNT_TOO_LOW" | "INVALID_ADDRESS" | "INVALID_AMOUNT" | "QUOTE_MISMATCH" | "QUOTE_EXPIRED" | "PROVIDER_REJECTED" | "PROVIDER_CHANGED" | "PROVIDER_UNAVAILABLE" | "PROVIDER_TIMEOUT" | "MEMO_TOO_LONG" | "SLIPPAGE_EXCEEDED" | "RATE_LIMITED" | "CHAIN_HALTED" | "CHAIN_DISABLED" | "MISSING_QUOTE_DATA" | "BROADCAST_FAILED" | "INTERNAL_ERROR" | "CONNECTION_ERROR" | "TIMEOUT" | "INVALID_RESPONSE" | "WAIT_TIMEOUT" | "UNKNOWN_ERROR";
+/** Any error code, including unknown ones returned by the API as it evolves. */
+type ErrorCode = KnownErrorCode | (string & {});
+//#endregion
+//#region src/types/quotes.d.ts
+/**
+ * What to quote. Chain and token IDs come from `chains.list()` and `tokens.list(chain)`; case is ignored.
+ *
+ * @example
+ * { fromChain: "ETH", fromToken: "ETH", toChain: "BTC", toToken: "BTC", amount: "0.5" }
+ */
+interface GetQuoteParams {
+  /** Source chain ID, e.g. `"ETH"`. */
+  fromChain: string;
+  /** Source token ID, e.g. `"ETH"` or `"USDC-0xA0b8…"`. */
+  fromToken: string;
+  /** Destination chain ID, e.g. `"BTC"`. */
+  toChain: string;
+  /** Destination token ID, e.g. `"BTC"`. */
+  toToken: string;
+  /** Amount of the source token, as a human-readable decimal, e.g. `"0.5"`. */
+  amount: string;
+  /** Confidential execution mode. Routes from providers that don't support it are left out. */
+  private?: PrivateSwapMode;
+  /** Real recipient address, for providers that need one to quote. A placeholder is used when omitted. */
+  destinationAddress?: string;
+  /** Address sending the funds. Required when `refundAddress` is set; the quote is bound to it. */
+  senderAddress?: string;
+  /**
+   * Where refunds should go, if not the sender. Providers that can't refund to a different address
+   * are left out of `routes` and listed in `warnings`.
+   */
+  refundAddress?: string;
+}
+/**
+ * One way to execute the swap, from one provider.
+ *
+ * `memo`, `inboundAddress`, `router` and `gasRate` are a preview only. `swaps.create` rebuilds them (the memo gets
+ * the real destination address, the vault address is refreshed), so sign with the `execution` it returns,
+ * e.g. `execution.memo`, never with these fields.
+ */
+interface QuoteRoute {
+  /** Provider offering this route. Pass it as `routeProvider` to `swaps.create` to choose this route. */
+  provider: Provider;
+  /** Route chosen inside the provider (e.g. `"Chainflip"`), when the provider exposes one. */
+  subprovider?: string;
+  /** Confidential execution mode of this route. */
+  private?: PrivateSwapMode;
+  /** The provider's integration type. */
+  providerType: ProviderType;
+  /** Expected output in the destination token, as a human-readable decimal, after fees. */
+  expectedOutput: string;
+  /** Estimated time to complete, in seconds. */
+  estimatedTimeSeconds: number;
+  /** Fees for this route. */
+  fees: QuoteFees;
+  /** The provider's own quote expiry (ISO 8601 or Unix seconds), if it has one. Use the quote's `expiresAt` instead. */
+  expiry: string | null;
+  /** Transaction memo (THORChain/Maya), if any. */
+  memo: string | null;
+  /** Vault address funds are sent to, if any. */
+  inboundAddress: string | null;
+  /** Router contract address (EVM), when the provider exposes one. */
+  router: string | null;
+  /** Recommended fee rate for UTXO transactions, if any. */
+  gasRate: string | null;
+  /** Minimum swap amount in the source token, as a human-readable decimal, if the provider has one. */
+  minAmount: string | null;
+  /** The fee applied to this route after provider caps. */
+  resolvedFee: {
+    /** Effective fee in basis points. */
+    feeBps: number;
+  };
+  /** OpenOcean aggregator behind the route (Solana/Sui only). */
+  openOceanRoute?: OpenOceanRouteMeta;
+}
+/** Why a provider didn't return a route. */
+interface RouteWarning {
+  /** The provider that failed. Rarely empty, e.g. when no provider is enabled. */
+  provider: string;
+  /** Same codes as API errors, e.g. `PROVIDER_TIMEOUT` or `UNSUPPORTED_PAIR`. */
+  code: ErrorCode;
+  /** Technical message for logs. */
+  message: string;
+  /** Message that is safe to show to end users. */
+  userMessage: string;
+}
+/**
+ * Response of `quotes.get()`.
+ *
+ * A 200 response can have no routes: check `warnings` to see why each provider was left out.
+ */
+interface QuoteResponse {
+  /** Pass to `swaps.create` to execute on these terms. */
+  quoteId: string;
+  /** When the quote expires (ISO 8601). After that, `swaps.create` throws `QuoteExpiredError`. */
+  expiresAt: string;
+  /** Available routes, best first: highest output, then fastest, then lowest slippage. */
+  routes: QuoteRoute[];
+  /** One entry per provider that was tried but didn't return a route. */
+  warnings: RouteWarning[];
+}
+//#endregion
+//#region src/types/execution.d.ts
+/** An ERC-20 approval that must be sent before an EVM `contract-call`. */
+interface EvmApproval {
+  /** Address to approve (router or spender contract). */
+  spender: string;
+  /** ERC-20 token contract address. */
+  tokenAddress: string;
+  /** Exact amount to approve. */
+  amount: TokenAmount;
+}
+/**
+ * Sign and send an EVM transaction.
+ *
+ * - `contract-call`: send `to` / `data` / `value`, after the `approval` if there is one.
+ * - `native-transfer`: send `value` of the native gas token to `to`.
+ * - `erc20-transfer`: send `transferAmount` of the source token to `to`.
+ */
+interface EvmSwapExecution {
+  /** Execution family: an EVM chain. */
+  family: "evm";
+  /** How to send it: call a contract, send the native gas token, or send an ERC-20 token. */
+  mode: "contract-call" | "native-transfer" | "erc20-transfer";
+  /** When present, sign `message` with EIP-191 `personal_sign` first and submit the signature with the tx hash. */
+  signature?: {
+    method: "personal_sign";
+    message: string;
+  };
+  /** EVM chain ID the transaction must be sent on. */
+  chainId: number;
+  /** Recipient: a contract for `contract-call`, otherwise the deposit address. */
+  to: string;
+  /** Calldata for `contract-call`; `null` otherwise. */
+  data: string | null;
+  /** Native gas token amount to send with the transaction, if any. */
+  value: TokenAmount | null;
+  /** Suggested gas limit, if the provider supplies one. */
+  gasLimit: string | null;
+  /** Opaque memo or deposit instructions, if any. */
+  memo: string | null;
+  /** ERC-20 approval required before a `contract-call`; `null` otherwise. */
+  approval: EvmApproval | null;
+  /** Exact ERC-20 amount for `erc20-transfer`; `null` otherwise. */
+  transferAmount: TokenAmount | null;
+}
+/** Send `amount` to `to` with `memo` as an OP_RETURN output. Used for BTC, LTC, BCH, DOGE, DASH and ZEC. */
+interface UtxoSwapExecution {
+  /** Execution family: a Bitcoin-like chain. */
+  family: "utxo";
+  /** Send a payment with an OP_RETURN memo. */
+  mode: "payment-with-memo";
+  /** Deposit address. */
+  to: string;
+  /** Exact amount to send. */
+  amount: TokenAmount;
+  /** Memo to include as OP_RETURN, if any. */
+  memo: string | null;
+  /** Advisory fee-rate hint (THORChain/Maya). The wallet chooses the actual fee. */
+  gasRate: string | null;
+}
+/** Send a standard Cosmos `MsgSend` to the provider's inbound address. */
+interface CosmosBankSendSwapExecution {
+  /** Execution family: a Cosmos chain. */
+  family: "cosmos";
+  /** Send a `MsgSend`. */
+  mode: "bank-send";
+  /** Inbound address. */
+  to: string;
+  /** Exact amount to send. */
+  amount: TokenAmount;
+  /** Transaction memo, if any. */
+  memo: string | null;
+}
+/** Send a native `MsgDeposit` on THORChain or Maya. */
+interface CosmosMsgDepositSwapExecution {
+  /** Execution family: THORChain and Maya are Cosmos chains. */
+  family: "cosmos";
+  /** Send a `MsgDeposit`. */
+  mode: "msg-deposit";
+  /** Inbound address. */
+  to: string;
+  /** Protocol asset for the deposit coin, e.g. `"THOR.RUNE"`. */
+  asset: string;
+  /** Decimals to write into the deposit coin. */
+  assetDecimals: number;
+  /** Exact amount to deposit. */
+  amount: TokenAmount;
+  /** Transaction memo, if any. */
+  memo: string | null;
+}
+/** Sign and broadcast a provider-built Cosmos message (IBC transfer or CosmWasm execute) unchanged. */
+interface CosmosMsgExecuteSwapExecution {
+  /** Execution family: a Cosmos chain. */
+  family: "cosmos";
+  /** Broadcast `messageJson` unchanged. */
+  mode: "msg-execute";
+  /** JSON-encoded `{ typeUrl, value }` message. Pass it through as-is; never rebuild it. */
+  messageJson: string;
+  /** Transaction memo, if any. */
+  memo: string | null;
+  /** Advisory gas price, e.g. `"0.025uosmo"`. The wallet chooses the actual fee. */
+  gasPrice: string | null;
+  /** Advisory gas simulation multiplier, if the provider supplies one. */
+  gasMultiplier: number | null;
+}
+/** Sign a fully built transaction: Solana base64, Sui transaction, Bitcoin hex PSBT or Stellar XDR. */
+interface SerializedSwapExecution {
+  /** Execution family: says how `serializedTransaction` is encoded. */
+  family: "solana" | "sui" | "utxo" | "stellar";
+  /** Sign `serializedTransaction`. */
+  mode: "serialized-tx";
+  /** The encoded transaction to sign. */
+  serializedTransaction: string;
+  /** Minimum swap output encoded in the transaction (not the input amount), if known. */
+  minOut: TokenAmount | null;
+}
+/** Sign a JSON-described XRPL or Stellar payment. */
+interface JsonSwapExecution {
+  /** Execution family: XRPL or Stellar. */
+  family: "xrp" | "stellar";
+  /** Sign the payment in `transactionJson`. */
+  mode: "transaction-json";
+  /** Destination address. */
+  to: string;
+  /** JSON-encoded payment fields. Keep every memo field. */
+  transactionJson: string;
+}
+/** Send `amount` to a deposit address on a chain with its own execution family. */
+interface NamedDepositSwapExecution {
+  /** Execution family of the chain to deposit on. */
+  family: "solana" | "sui" | "xrp" | "tron" | "near" | "hypercore" | "cardano";
+  /** Send `amount` to the deposit address `to`. */
+  mode: "deposit-transfer";
+  /** Deposit address. */
+  to: string;
+  /** Exact amount to send. */
+  amount: TokenAmount;
+  /** Memo to attach, if any. */
+  memo: string | null;
+}
+/** Send `amount` to a deposit address on a chain without a dedicated execution family (see `chain`). */
+interface OtherDepositSwapExecution {
+  /** No dedicated execution family: `chain` says which chain. */
+  family: "other";
+  /** Send `amount` to the deposit address `to`. */
+  mode: "deposit-transfer";
+  /** Pegaroute chain ID, e.g. `"APTOS"`. */
+  chain: string;
+  /** Deposit address. */
+  to: string;
+  /** Exact amount to send. */
+  amount: TokenAmount;
+  /** Memo to attach, if any. */
+  memo: string | null;
+}
+/**
+ * What the user's wallet must sign to fund a swap. Switch on `family` and `mode`, never on the provider name.
+ *
+ * @example
+ * if (isExecutionFamily(execution, "evm")) {
+ *   // execution is EvmSwapExecution
+ * } else if (isExecutionFamily(execution, "utxo")) {
+ *   // execution.mode is "payment-with-memo" | "serialized-tx"
+ * }
+ */
+type SwapExecution = EvmSwapExecution | UtxoSwapExecution | CosmosBankSendSwapExecution | CosmosMsgDepositSwapExecution | CosmosMsgExecuteSwapExecution | SerializedSwapExecution | JsonSwapExecution | NamedDepositSwapExecution | OtherDepositSwapExecution;
+/** Every execution family, e.g. `"evm"` or `"utxo"`. */
+type ExecutionFamily = SwapExecution["family"];
+/**
+ * The execution variants of one family, with `family` narrowed to it.
+ *
+ * `Extract` can't be used here: variants shared by several families (e.g. `SerializedSwapExecution`)
+ * would be dropped. The intersection keeps them and removes variants of other families.
+ *
+ * @example
+ * ExecutionOfFamily<"utxo"> // UtxoSwapExecution | (SerializedSwapExecution & { family: "utxo" })
+ */
+type ExecutionOfFamily<F extends ExecutionFamily> = SwapExecution & {
+  family: F;
+};
+/** Every execution mode, e.g. `"contract-call"` or `"deposit-transfer"`. */
+type ExecutionMode = SwapExecution["mode"];
+/**
+ * The execution variants of one mode, across all families, with `mode` narrowed to it.
+ *
+ * Uses an intersection for the same reason as {@link ExecutionOfFamily}: `EvmSwapExecution` covers three modes.
+ *
+ * @example
+ * ExecutionOfMode<"deposit-transfer"> // NamedDepositSwapExecution | OtherDepositSwapExecution
+ */
+type ExecutionOfMode<M extends ExecutionMode> = SwapExecution & {
+  mode: M;
+};
+/**
+ * Narrows an execution to the variants of one mode, whatever the family.
+ * Within a single family, a `switch` on `mode` is usually clearer.
+ *
+ * @example
+ * if (isExecutionMode(execution, "deposit-transfer")) {
+ *   showDepositAddress(execution.to, execution.amount.display, execution.memo); // any chain
+ * }
+ */
+declare function isExecutionMode<M extends ExecutionMode>(execution: SwapExecution, mode: M): execution is ExecutionOfMode<M>;
+/**
+ * Narrows an execution to the variants of one family.
+ *
+ * @example
+ * if (isExecutionFamily(execution, "evm")) {
+ *   // execution.mode is "contract-call" | "native-transfer" | "erc20-transfer"
+ * }
+ */
+declare function isExecutionFamily<F extends ExecutionFamily>(execution: SwapExecution, family: F): execution is ExecutionOfFamily<F>;
+//#endregion
+//#region src/types/status.d.ts
+/**
+ * The public swap status. Use this one for business logic.
+ *
+ * Returned as `status` by `swaps.get`, `transactions.list` and webhooks.
+ */
+type SwapStatus = "pending" | "executing" | "success" | "fail";
+/**
+ * Pegaroute's detailed internal status, meant for debugging. Steps can be skipped (e.g. `pending` → `completed`).
+ *
+ * Returned as `internalStatus` by `swaps.get`, `transactions.list` and webhooks, as `status` by
+ * `swaps.submitTxHash` (`"submitted"`) and in `swaps.events`. The `transactions.list({ status })` filter takes these values.
+ */
+type InternalSwapStatus = "pending" | "submitted" | "executing" | "confirming" | "completed" | "failed" | "refunded";
+/**
+ * Converts an internal status to the public one.
+ *
+ * @example
+ * toExternalStatus("submitted"); // "executing"
+ * toExternalStatus("refunded"); // "fail" — check the swap's `refund` for details
+ */
+declare function toExternalStatus(status: InternalSwapStatus): SwapStatus;
+/**
+ * Whether a swap in this status is finished and will not change status again. Accepts either status set.
+ *
+ * A `refunded` swap's `refund` object may still progress (e.g. `pending` → `completed`) after this returns `true`.
+ */
+declare function isTerminalStatus(status: SwapStatus | InternalSwapStatus): boolean;
+//#endregion
+//#region src/types/swaps.d.ts
+/**
+ * What to swap. Pass the `quoteId` and chosen route's `provider` from `quotes.get()` to execute on the quoted terms.
+ * Without a `quoteId`, Pegaroute quotes again and picks the best route itself.
+ *
+ * @example
+ * {
+ *   fromChain: "ETH", fromToken: "ETH", toChain: "BTC", toToken: "BTC", amount: "0.5",
+ *   senderAddress: "0xabc…", destinationAddress: "bc1q…",
+ *   quoteId: quote.quoteId, routeProvider: quote.routes[0].provider,
+ * }
+ */
+interface CreateSwapParams {
+  /** Source chain ID, e.g. `"ETH"`. Must match the quote. */
+  fromChain: string;
+  /** Source token ID, e.g. `"ETH"`. Must match the quote. */
+  fromToken: string;
+  /** Destination chain ID, e.g. `"BTC"`. Must match the quote. */
+  toChain: string;
+  /** Destination token ID, e.g. `"BTC"`. Must match the quote. */
+  toToken: string;
+  /** Amount of the source token, as a human-readable decimal, e.g. `"0.5"`. Must match the quote. */
+  amount: string;
+  /** Address that receives the swapped funds. */
+  destinationAddress: string;
+  /** Address sending the funds. Must match the quote's `senderAddress`, if it had one. */
+  senderAddress: string;
+  /** Where refunds should go, if not the sender. Must match the quote's `refundAddress`, if it had one. */
+  refundAddress?: string;
+  /** Maximum slippage as a fraction between 0 and 1, e.g. `0.01` for 1%. Uses the provider's default when omitted. */
+  slippageTolerance?: number;
+  /** Execute as a streaming swap (several smaller sub-swaps), where the provider supports it. */
+  streaming?: boolean;
+  /** The `quoteId` from `quotes.get()`. Throws `QuoteExpiredError` if it expired and no route is still valid. */
+  quoteId?: string;
+  /** The chosen route's `provider` from the quote. Without it, the best route is used. */
+  routeProvider?: Provider;
+  /** Confidential execution mode. Must match the quote. */
+  private?: PrivateSwapMode;
+}
+/** The provider executing a swap, with its own reference for the swap. */
+interface SwapProviderInfo {
+  /** Provider name, e.g. `"thorchain"`. */
+  name: Provider;
+  /** The provider's own ID for the swap (e.g. an Instaswap txid or Squid quote ID), if it has one. */
+  referenceId: string | null;
+  /** Extra provider metadata for UI and debugging (e.g. OpenOcean route, warnings). Never needed to sign. */
+  details: Record<string, unknown> | null;
+}
+/**
+ * Response of `swaps.create()`.
+ *
+ * Send `execution` to the frontend for signing, then report the tx hash with `swaps.submitTxHash()`.
+ */
+interface CreateSwapResponse {
+  /** Swap ID. Use it with `swaps.get`, `swaps.events` and `swaps.submitTxHash`. */
+  transactionId: string;
+  /** External status of the new swap. `"pending"` today. */
+  status: SwapStatus;
+  /** The integration type of the selected provider. */
+  providerType: ProviderType;
+  /** The route the swap will execute on. */
+  route: RouteInfo;
+  /** What the user must sign. Switch on `family` and `mode`, never on the provider name. */
+  execution: SwapExecution;
+  /** The provider executing the swap. */
+  provider: SwapProviderInfo;
+}
+/** The provider's own status for a swap, when it reports one. */
+interface ProviderStatusInfo {
+  /** The provider's native status value. */
+  status: string;
+  /** Whether the user must act (e.g. top up a deposit) before the swap can continue. */
+  actionRequired: boolean;
+  /** Short explanation of the status. */
+  message: string;
+  /** Provider or chain explorer link, when available. */
+  explorerUrl?: string;
+}
+/** One fee line in an Instaswap deposit quote. */
+interface InstaswapFeeLine {
+  /** Fee kind as Instaswap names it, e.g. `"subAffiliate"`. */
+  type?: string;
+  /** Display label for the fee. */
+  name?: string;
+  /** Fee in USD. A JavaScript number as Pegaroute sends it: for display only, may be imprecise. */
+  amountUsd?: number;
+  /** Asset the fee is charged in. */
+  asset?: string;
+  /** Fee in `asset`. A JavaScript number as Pegaroute sends it: for display only, may be imprecise. */
+  amount?: number;
+}
+/** Instaswap's deposit details for a swap, kept so a deposit UI can be shown again after a reload. */
+interface InstaswapSwapLiteSnapshot {
+  /** Instaswap's swap ID. */
+  txid: string;
+  /** Estimated output amount. */
+  estimatedOut?: number;
+  /** Estimated output value in USD. */
+  estimatedOutUsd?: number;
+  /** Amount to deposit. For display only: sign with the amounts in `execution`. */
+  depositAmount?: number;
+  /** Exact amount to deposit, as a human-readable decimal. For display only: sign with the amounts in `execution`. */
+  depositAmountExact?: string;
+  /** Deposit value in USD. */
+  depositAmountUsd?: number;
+  /** Fee lines. */
+  feeBreakdown?: InstaswapFeeLine[];
+  /** Estimated time to complete, in seconds. */
+  etaSeconds?: number;
+  /** Address to deposit to. */
+  depositAddress: string;
+  /** Symbol of the token to deposit, e.g. `"BTC"`. */
+  depositTokenSymbol?: string;
+  /** When the deposit window closes (ISO 8601), if it does. */
+  expiresAt?: string | null;
+  /** Deposit instructions to show the user. */
+  instructions?: string;
+}
+/** The source side of a swap. */
+interface SwapInput {
+  /** Source chain ID. */
+  chain: string;
+  /** Source token ID. */
+  token: string;
+  /** Amount sent, as a human-readable decimal. */
+  amount: string;
+  /** Address sending the funds. */
+  address?: string;
+  /** Where refunds go. Falls back to `address` for older swaps. */
+  refundAddress?: string;
+  /** Source transaction hash, once reported with `swaps.submitTxHash()` or detected. */
+  txHash?: string;
+  /** The provider's own ID for the swap, if it has one. */
+  providerReferenceId?: string;
+  /** The provider's latest status for the swap, when it reports one. */
+  providerStatus?: ProviderStatusInfo;
+  /** Instaswap deposit details (Instaswap swaps only). */
+  instaswapSwapLite?: InstaswapSwapLiteSnapshot;
+}
+/** The destination side of a swap. */
+interface SwapOutput {
+  /** Destination chain ID. */
+  chain: string;
+  /** Destination token ID. */
+  token: string;
+  /** Address receiving the funds. */
+  address: string;
+  /** Amount received, as a human-readable decimal, once known. */
+  amount?: string;
+  /** Destination transaction hash, once known. */
+  txHash?: string;
+}
+/** When a swap reached each stage (ISO 8601). Stages can be skipped. */
+interface SwapTimestamps {
+  /** When the swap was created. */
+  created: string;
+  /** When the source tx hash was reported. */
+  submitted?: string;
+  /** When the source transaction was confirmed. */
+  confirmed?: string;
+  /** When the swap finished, whatever the outcome. */
+  completed?: string;
+}
+/** Why a swap failed. */
+interface SwapFailure {
+  /** Same codes as API errors, e.g. `SLIPPAGE_EXCEEDED`. */
+  code: ErrorCode;
+  /** Technical message for logs. */
+  message: string;
+  /** Message that is safe to show to end users. */
+  userMessage: string;
+  /** Provider that caused the failure, when it is provider-specific. */
+  provider?: string;
+}
+/** Response of `swaps.get()`: the swap's current state. */
+interface GetSwapResponse {
+  /** Swap ID. */
+  transactionId: string;
+  /** External status. Use this one for business logic. */
+  status: SwapStatus;
+  /** Internal status, for debugging. */
+  internalStatus: InternalSwapStatus;
+  /** The route the swap executes on. */
+  route: RouteInfo;
+  /** The source side of the swap. */
+  input: SwapInput;
+  /** The destination side of the swap. */
+  output: SwapOutput;
+  /** Fees for the swap. */
+  fees: QuoteFees;
+  /** How the affiliate fee was split, when recorded. */
+  affiliateFeeBreakdown?: AffiliateFeeBreakdown;
+  /** When the swap reached each stage. */
+  timestamps: SwapTimestamps;
+  /** Why the swap failed, or `null`. */
+  error: SwapFailure | null;
+  /** The refund for a failed swap, or `null`. */
+  refund: RefundInfo | null;
+  /** Progress of a streaming swap, or `null` for a regular swap. */
+  streamingProgress: StreamingProgress | null;
+  /** What the user must sign, when it can be rebuilt (e.g. an Instaswap deposit). Same shape as `swaps.create()`. */
+  execution?: SwapExecution;
+  /** The provider executing the swap. Present together with `execution`. */
+  provider?: SwapProviderInfo;
+}
+/** One entry in a swap's audit log. */
+interface SwapEvent {
+  /** Event ID. */
+  id: string;
+  /** Internal status before the event; `"none"` for the swap's creation. */
+  fromStatus: InternalSwapStatus | "none";
+  /** Internal status after the event. Equal to `fromStatus` for audit entries that don't change status. */
+  toStatus: InternalSwapStatus;
+  /** When the event happened (ISO 8601). */
+  timestamp: string;
+  /** Extra context recorded with the event, e.g. `{ txHash }`, or `null`. */
+  metadata: Record<string, unknown> | null;
+}
+/** Response of `swaps.events()`. */
+interface SwapEventsResponse {
+  /** Swap ID. */
+  transactionId: string;
+  /** Events, oldest first. */
+  events: SwapEvent[];
+}
+/** The source transaction to report for a swap. */
+interface SubmitTxHashParams {
+  /** Hash of the signed and broadcast source transaction. */
+  txHash: string;
+  /**
+   * The EIP-191 `personal_sign` signature (`0x` + 130 hex chars), required when the swap's
+   * `execution.signature` asked for one. Leave it out otherwise.
+   */
+  signature?: string;
+}
+/** Response of `swaps.submitTxHash()`. */
+interface SubmitTxHashResponse {
+  /** Swap ID. */
+  transactionId: string;
+  /** Internal status after reporting the hash. `"submitted"` today (external `"executing"`). */
+  status: InternalSwapStatus;
+  /** The reported hash. */
+  txHash: string;
+}
+//#endregion
+//#region src/types/transactions.d.ts
+/**
+ * Filters for `transactions.list()`. All are optional.
+ *
+ * @example
+ * { status: "failed", provider: "thorchain", startTime: "2026-09-01T00:00:00Z", count: 100 }
+ */
+interface ListTransactionsParams {
+  /** Only swaps in this **internal** status, e.g. `"failed"` (not the external `"fail"`). */
+  status?: InternalSwapStatus;
+  /** Only swaps executed by this provider; case is ignored. */
+  provider?: Provider;
+  /** Only swaps created at or after this time (ISO 8601). */
+  startTime?: string;
+  /** Only swaps created at or before this time (ISO 8601). */
+  endTime?: string;
+  /** Page size, from 1 to 200. Default 50. */
+  count?: number;
+  /** Start after this cursor (a previous page's `pagination.nextCursor`). Not needed when iterating with `for await`. */
+  cursor?: string;
+}
+/**
+ * A swap as listed by `transactions.list()`: the same data as `swaps.get()` under different field names,
+ * plus Pegaroute's affiliate-fee verification data.
+ */
+interface Transaction {
+  /** Swap ID (`transactionId` elsewhere). */
+  id: string;
+  /** The integration the swap belongs to (the one your API key is scoped to). */
+  integrationId: string;
+  /** External status. Use this one for business logic. */
+  status: SwapStatus;
+  /** Internal status, for debugging. */
+  internalStatus: InternalSwapStatus;
+  /** The source side of the swap (`input` in `swaps.get()`). */
+  source: SwapInput;
+  /** The destination side of the swap (`output` in `swaps.get()`). */
+  destination: SwapOutput;
+  /** The route the swap executes on. */
+  route: RouteInfo;
+  /** Fees for the swap. */
+  fees: QuoteFees;
+  /** How the affiliate fee was split, when recorded. */
+  affiliateFeeBreakdown?: AffiliateFeeBreakdown;
+  /** Why the swap failed, if it did. */
+  error?: SwapFailure;
+  /** The refund for a failed swap, if there is one. */
+  refund?: RefundInfo;
+  /** When the swap reached each stage. */
+  timestamps: SwapTimestamps;
+  /** The exact THORChain/Maya memo built for the swap, when the route uses one. */
+  expectedMemo?: string;
+  /** Affiliates parsed from `expectedMemo`; empty when there is none. */
+  expectedAffiliateEntries: ExpectedAffiliateEntry[];
+  /** Referrer address the provider is expected to credit (e.g. OpenOcean), when set. */
+  expectedReferrerAddress?: string;
+  /** ID of the affiliate configuration used for the swap (THORChain/Maya only). */
+  selectedProviderAffiliateCompositionId?: string;
+  /** When the on-chain memo was last checked against `expectedMemo` (ISO 8601). */
+  memoVerifiedAt?: string;
+}
+/** One affiliate in a swap's memo, as Pegaroute expects the provider to pay it. */
+interface ExpectedAffiliateEntry {
+  /** Position in the memo's affiliate list, starting at 0. */
+  position: number;
+  /** Affiliate name as written in the memo. */
+  name: string;
+  /** Fee in basis points, or `null` when unknown. */
+  bps: number | null;
+  /** Whether `bps` was written in the memo (`"explicit"`) or is the affiliate name's default (`"name_default"`). */
+  bpsSource: "explicit" | "name_default";
+  /** Pegaroute's ID for the affiliate, when it is one of the configured ones. */
+  affiliateId?: string;
+  /** Whose affiliate it is: Pegaroute's (`"operator"`) or the integrator's (`"client"`). */
+  scope?: "operator" | "client";
+}
+/** Where a page sits in a cursor-paginated list. */
+interface CursorPagination {
+  /** Pass as `cursor` to get the next page; `null` on the last page. */
+  nextCursor: string | null;
+  /** Whether more pages follow. */
+  hasMore: boolean;
+}
+/** One page of `transactions.list()`, newest swaps first. */
+interface TransactionsResponse {
+  /** The swaps on this page. */
+  transactions: Transaction[];
+  /** Whether more pages follow, and the cursor to fetch the next one. */
+  pagination: CursorPagination;
+}
+//#endregion
+//#region src/types/webhooks.d.ts
+/**
+ * Events Pegaroute sends when a swap changes. Every one carries the same {@link TransactionWebhookData}.
+ *
+ * - `transaction.status_changed`: any other status change (e.g. `pending` → `submitted`).
+ * - `transaction.completed`: the swap succeeded.
+ * - `transaction.partially_completed`: a streaming swap completed with part of the amount refunded.
+ * - `transaction.failed`: the swap failed.
+ * - `transaction.refunded`: the swap failed and its funds were refunded.
+ * - `transaction.refund_initiated`: a refund started; the swap's status may not be terminal yet.
+ */
+type TransactionWebhookEventType = "transaction.status_changed" | "transaction.completed" | "transaction.partially_completed" | "transaction.failed" | "transaction.refunded" | "transaction.refund_initiated";
+/** Streaming progress as webhooks send it: the usual progress plus which sub-swap failed. */
+interface WebhookStreamingProgress extends StreamingProgress {
+  /**
+   * Which sub-swap failed, for failed, refunded or partially refunded streaming swaps:
+   * `"first"` (nothing executed, full refund) or `"subsequent"` (partial output plus partial refund).
+   * `null` when nothing failed.
+   */
+  failureContext: "first" | "subsequent" | null;
+}
+/** The swap carried by every `transaction.*` webhook: its state after the change, plus the status it changed from. */
+interface TransactionWebhookData {
+  /** Swap ID. */
+  transactionId: string;
+  /** External status after the change. Use this one for business logic. */
+  status: SwapStatus;
+  /** Internal status after the change, for debugging. */
+  internalStatus: InternalSwapStatus;
+  /** External status before the change. */
+  previousStatus: SwapStatus;
+  /** Internal status before the change, for debugging. */
+  internalPreviousStatus: InternalSwapStatus;
+  /** The route the swap executes on (fewer fields than `swaps.get()`). */
+  route: Pick<RouteInfo, "provider" | "subprovider" | "private">;
+  /** The source side of the swap (fewer fields than `swaps.get()`). */
+  input: Pick<SwapInput, "chain" | "token" | "amount" | "address" | "refundAddress" | "txHash">;
+  /** The destination side of the swap. */
+  output: SwapOutput;
+  /** Fees for the swap. */
+  fees: QuoteFees;
+  /** When the swap reached each stage. */
+  timestamps: SwapTimestamps;
+  /** Why the swap failed, or `null`. */
+  error: SwapFailure | null;
+  /** The refund for a failed swap, or `null`. */
+  refund: RefundInfo | null;
+  /** Progress of a streaming swap, or `null` for a regular swap. */
+  streamingProgress: WebhookStreamingProgress | null;
+}
+/** A webhook about a swap. Narrow on `event` to react to a specific change. */
+interface TransactionWebhookEvent {
+  /** What happened. */
+  event: TransactionWebhookEventType;
+  /** When Pegaroute created the event (ISO 8601). Retries resend the same value. */
+  timestamp: string;
+  /** The swap after the change. */
+  data: TransactionWebhookData;
+}
+/** A test webhook, sent from the Pegaroute UI to check your endpoint. */
+interface TestWebhookEvent {
+  /** What happened. */
+  event: "webhook.test";
+  /** When Pegaroute created the event (ISO 8601). */
+  timestamp: string;
+  /** Who sent the test, and for which integration. */
+  data: {
+    /** Your integration's ID. */
+    integrationId: string;
+    /** Always `"Pegaroute test webhook"` today. */
+    message: string;
+    /** Who sent the test: the operator's email, or `"operator_pat"`. */
+    generatedBy: string;
+  };
+}
+/**
+ * Any webhook Pegaroute sends, as returned by `verifyWebhook`. Narrow on `event`.
+ *
+ * Delivery is at-least-once: the same event can arrive more than once, so make handlers idempotent.
+ *
+ * @example
+ * switch (event.event) {
+ *   case "transaction.completed":
+ *     markPaid(event.data.transactionId);
+ *     break;
+ *   case "webhook.test":
+ *     break;
+ * }
+ */
+type WebhookEvent = TransactionWebhookEvent | TestWebhookEvent;
+//#endregion
+export { KnownErrorCode as $, toExternalStatus as A, JsonSwapExecution as B, SwapInput as C, Token as Ct, InternalSwapStatus as D, SwapTimestamps as E, EvmSwapExecution as F, UtxoSwapExecution as G, OtherDepositSwapExecution as H, ExecutionFamily as I, GetQuoteParams as J, isExecutionFamily as K, ExecutionMode as L, CosmosMsgDepositSwapExecution as M, CosmosMsgExecuteSwapExecution as N, SwapStatus as O, EvmApproval as P, ErrorCode as Q, ExecutionOfFamily as R, SwapFailure as S, ProvidersResponse as St, SwapProviderInfo as T, SerializedSwapExecution as U, NamedDepositSwapExecution as V, SwapExecution as W, QuoteRoute as X, QuoteResponse as Y, RouteWarning as Z, ProviderStatusInfo as _, ProviderFeeStructure as _t, WebhookEvent as a, QuoteFees as at, SwapEvent as b, ProviderTakeStructure as bt, ExpectedAffiliateEntry as c, StreamingProgress as ct, TransactionsResponse as d, ChainsResponse as dt, AffiliateFeeBreakdown as et, CreateSwapParams as f, HealthResponse as ft, InstaswapSwapLiteSnapshot as g, ProviderAffiliateFeeStructure as gt, InstaswapFeeLine as h, PingResponse as ht, TransactionWebhookEventType as i, Provider as it, CosmosBankSendSwapExecution as j, isTerminalStatus as k, ListTransactionsParams as l, TokenAmount as lt, GetSwapResponse as m, ListProvidersParams as mt, TransactionWebhookData as n, OpenOceanRouteMeta as nt, WebhookStreamingProgress as o, RefundInfo as ot, CreateSwapResponse as p, KnownProviderType as pt, isExecutionMode as q, TransactionWebhookEvent as r, PrivateSwapMode as rt, CursorPagination as s, RouteInfo as st, TestWebhookEvent as t, KnownProvider as tt, Transaction as u, Chain as ut, SubmitTxHashParams as v, ProviderHealth as vt, SwapOutput as w, TokensResponse as wt, SwapEventsResponse as x, ProviderType as xt, SubmitTxHashResponse as y, ProviderInfo as yt, ExecutionOfMode as z };