The Aggregator package has been developed to facilitate interaction with multiple decentralised protocols. It provides a unified interface for developers, with the objective of offering end users the best of each protocol in the most straightforward manner.

Supported protocols

The current supported protocols are:

• Thorchain
• Maya Protocol
• Chainflip
• OneClick (NEAR Intents)

Installation

yarn add @xchainjs/xchain-aggregator

or

npm install @xchainjs/xchain-aggregator

Initialization

Aggregator can be easily initialise providing the Wallet with the XChainJs Clients you are working with. If no protocol is provided, the Aggregator will work with all the supported protocols.

import { Aggregator } from '@xchainjs/xchain-aggregator';

const aggregator = new Aggregator({
  wallet: new Wallet({
    // Your XChainJS clients
  }),
  protocols: [
    // The protocols you want to work with
  ],
  affiliate: {
    // Affiliate config
  }
})

Features

Swaps

• Estimate the most efficient swap among protocols
• Do swaps
• Get swap history through different protocols

Chainflip deposit channels

Chainflip estimateSwap is quote-only — it does not open a deposit channel. Wallets that refresh quotes must not call channel creation on every refresh (channels expire; late deposits may not swap or refund).

Recommended flow:

1. aggregator.estimateSwap(...) — price discovery / refresh (toAddress empty for Chainflip; canSwap means a usable quote exists)
2. At confirm, immediately before broadcast: aggregator.requestChainflipDepositAddress(...) — returns depositAddress, depositChannelId, and expiresAt
3. Transfer to that deposit address (or use doSwap, which opens a channel then sends)

Do not cache deposit addresses across expiresAt. EVM Chainflip deposit addresses can be reused across channels; always bind signing to a live depositChannelId + expiry.

Important: Chainflip must observe the deposit before channel expiry. Broadcasting before expiresAt is not enough if the source chain (especially EVM) confirms after expiry — funds may not create a swap and may not FoK-refund. Prefer requestChainflipDepositAddress over doSwap when you need to track expiresAt / depositChannelId around slow Ledger signing or post-broadcast monitoring (doSwap does not return channel metadata).

OneClick deposit addresses

OneClick estimateSwap is quote-only (dry: true). It prices the route and does not create an executable order. Dry responses often have no deposit address. canSwap means amountOut is present.

Recommended flow:

1. aggregator.estimateSwap(...) — price discovery / refresh (toAddress is empty; canSwap means a priced quote exists)
2. At confirm, immediately before broadcast: aggregator.requestOneClickDepositAddress(...) — wet quote, returns depositAddress and expectedAmount
3. Transfer to that deposit address with your own signer, then aggregator.submitOneClickDeposit(txHash, depositAddress). doSwap does the wet quote, the transfer, and submitDeposit together. If registration fails after the transfer, retry submitOneClickDeposit with the same hash and deposit address. Do not transfer again.

Quote amounts are integer base-unit strings, so 24-decimal NEAR amounts are not sent in scientific notation. Set oneClickReferral on the Aggregator config (for example 'asgardex') to stamp that referral on every 1Click quote. Preview quotes without wallet addresses send a placeholder refundTo / recipient, because 1Click rejects empty addresses even when dry is true.

Examples

You can find examples using the Aggregator package in the aggregator examples folder.

Documentation

More information about how to use the Aggregator package can be found on documentation