Bluefin7k Aggregator TypeScript SDK

Installation

npm i @bluefin-exchange/bluefin7k-aggregator-sdk

This package requires @pythnetwork/pyth-sui-js as a peer dependency. If your project does not have it, you need to install it.

npm i @pythnetwork/pyth-sui-js

Usage

You can import the entire SDK as a module:

import SevenK from "@bluefin-exchange/bluefin7k-aggregator-sdk";

or import specific functions as needed:

import { getQuote, buildTx } from "@bluefin-exchange/bluefin7k-aggregator-sdk";

Config

Configuration is optional, but if provided, it must be set before invoking any SDK functions.

Set API Key

You can use our SDK with a default rate limit of 5 requests per second without needing an API key.

• For frontend (in-browser) usage, no API key is required, and the rate limit cannot be increased.

• For backend (server-side) usage, the API key is optional for default usage. However, to request a higher rate limit, you must provide both an API key and partner information.

To request a rate limit increase, please submit your request at our Discord. Create a ticket to request an API key for Bluefin7k Aggregator.

import { Config } from "@bluefin-exchange/bluefin7k-aggregator-sdk";

Config.setApiKey("YOUR_API_KEY");
console.log("API key", Config.getApiKey());

Set BluefinX API key

Setting a BluefinX API key is optional. However, if you'd like to use one — for example, to avoid rate limits when routing through BluefinX — you'll need to request an API key directly from Bluefin.

import { Config } from "@bluefin-exchange/bluefin7k-aggregator-sdk";

Config.setBluefinXApiKey("YOUR_BLUEFINX_API_KEY");
console.log("BluefinX API key", Config.getBluefinXApiKey());

Set Sui Client

The SDK uses a single primary Sui client that accepts any ClientWithCoreApi implementation (gRPC, JSON-RPC, or GraphQL). Set via setSuiClient. Defaults to gRPC for best performance. This client is used for transaction execution, simulation, coin fetching, and Pyth price feed operations (as of @pythnetwork/pyth-sui-js v4, Pyth reads transport-agnostically through the unified .core API).

Using gRPC (Recommended)

import { SuiGrpcClient } from "@mysten/sui/grpc";
import { Config } from "@bluefin-exchange/bluefin7k-aggregator-sdk";

const network = "mainnet";

// Primary client for transaction execution, simulation, and coin fetching
const suiClient = new SuiGrpcClient({
  baseUrl: "https://fullnode.mainnet.sui.io:443",
  network,
});
Config.setSuiClient(suiClient);

Note: this package only supports mainnet.

Enable Pyth-priced sources

A few liquidity sources price their swaps from a Pyth oracle, and buildTx has to attach a signed Pyth price update for a route that uses one:

• steamm_oracle_quoter
• steamm_oracle_quoter_v2
• obric — not usable at present, see below
• haedal_pmm — not usable at present, see below
• sevenk_v1 — not usable at present, see below

obric, haedal_pmm and sevenk_v1 cannot be enabled by any client configuration today. Their on-chain packages still target the pre-upgrade Pyth deployment, so they reject the price objects this SDK produces, and the pre-upgrade price feeds they would otherwise read stopped updating at the 26 August 2026 Pyth Core cutover. They need a new on-chain release from each protocol; supplying a Pyth key does not help. The rest of this section applies to the two steamm_oracle_quoter sources.

These sources are off by default. Since the Pyth Core upgrade on 26 August 2026, every Hermes caller needs an API key, so the SDK cannot fetch a price update on its own. Quotes and swaps work fine without any Pyth setup — the aggregator routes around these sources, and in current mainnet liquidity that costs well under 0.01% on major pairs.

The SDK targets the upgraded Pyth Core deployment: https://pyth.dourolabs.app/hermes with the upgraded Sui state objects. Get a key from Pyth Terminal (a free trial is included), then:

import { Config } from "@bluefin-exchange/bluefin7k-aggregator-sdk";

// Server side, holding a Pyth Pro access token directly:
Config.usePythPro({ accessToken: process.env.PYTH_ACCESS_TOKEN! });

// Browser side, where a token cannot be shipped to the client — name your own
// endpoint that holds the token on the page's behalf:
Config.usePythPro({
  updateDataUrl: "https://your.api.example/price-update-data",
});

The updateDataUrl endpoint must answer GET <url>?ids=<comma-separated feed ids> with { "updateData": ["<base64 price update>", ...] }.

Call this once, before any getQuote, alongside your other Config setup.

Already run your own Pyth plumbing? Config.setPythConnection() also enables these sources. If you take that route you must also call Config.setPythClient() with state ids from the same Pyth deployment your connection fetches from: setPythConnection moves the price fetch and setPythClient moves the on-chain state, and a mismatch between them fails inside Wormhole's VAA verification with an error that never mentions Pyth. usePythPro exists to move both together, so prefer it unless you need your own connection object.

setPythClient() on its own does not enable these sources — it moves the on-chain state ids, not the price fetch.

When a source is dropped because no Pyth endpoint is configured, the SDK logs a one-time warning naming the sources and the setup call.

Set Endpoint Provider (API Version)

You can toggle between different API versions:

• "Bluefin7k" (default) - Uses v2/quote endpoint
• "Bluefin7kV2" - Uses v3/quote endpoint with RFQ support

import { Config } from "@bluefin-exchange/bluefin7k-aggregator-sdk";

// Use v2 API (default)
Config.setEndpointProvider("Bluefin7k");

// Use v3 API with RFQ support
Config.setEndpointProvider("Bluefin7kV2");

Swap

See Swap.

BluefinX

See BluefinX.

Limit Orders

See Limit Orders.

DCA Orders

See DCA Orders.

Prices

import { getTokenPrice, getTokenPrices, getSuiPrice } from "@bluefin-exchange/bluefin7k-aggregator-sdk";

const tokenPrice = await getTokenPrice(
  "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
);

const tokenPrices = await getTokenPrices([
  "0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI",
  "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
]);

const suiPrice = await getSuiPrice();

Miscellaneous

If you encounter issues when importing functions from this SDK in a Node.js environment, refer to src/examples/nodejs/ for guidance.

License

Bluefin7k Aggregator TypeScript SDK released under the MIT license. See the LICENSE file for details.