Hedera Agent Kit - SaucerSwap Plugin

A plugin for Hedera Agent Kit that integrates with SaucerSwap to enable token swaps, liquidity management, and farm insights on Hedera.

Overview

SaucerSwap is Hedera's leading DEX with deep liquidity and active DeFi opportunities. This plugin lets AI agents:

• Execute swaps with slippage protection
• Fetch swap quotes and price impact estimates
• Query pool reserves and token metadata
• Add/remove liquidity via router transactions
• Discover farming opportunities

Documentation

• Configuration — full settings table, env vs. plugin-config precedence, and pointers to the official SaucerSwap contract deployment list.
• Tools — per-tool reference (parameters, return shape, example prompts, error behavior) for all six tools registered by the plugin.
• Examples — dry-run swap, CLI wrapper, and integration smoke test.

Installation

npm install hak-saucerswap-plugin

Quick Start

import { saucerswapPlugin, SAUCERSWAP_MAINNET } from "hak-saucerswap-plugin";

const agent = new HederaAgent({
  plugins: [saucerswapPlugin],
  config: {
    saucerswap: {
      ...SAUCERSWAP_MAINNET,
      apiKey: process.env.SAUCERSWAP_API_KEY,
    },
  },
});

Or use the network shorthand and set SAUCERSWAP_NETWORK=mainnet in your environment — no contract addresses needed:

const agent = new HederaAgent({
  plugins: [saucerswapPlugin],
  config: {
    saucerswap: { network: "mainnet", apiKey: process.env.SAUCERSWAP_API_KEY },
  },
});

The SaucerSwap API requires an x-api-key header. Get a key from saucerswap.finance and supply it via either SAUCERSWAP_API_KEY in the environment or config.saucerswap.apiKey. See .env.example for a copy-paste template of all supported environment variables.

Network Defaults

The plugin ships with official contract addresses for both networks. Import the constants directly or use the network shorthand — individual fields always take precedence if set.

| Export | Network | routerContractId | routerV2ContractId | wrappedHbarTokenId | |----------------------|---------|------------------|--------------------|-------------------| | SAUCERSWAP_MAINNET | mainnet | 0.0.3045981 | 0.0.3949434 | 0.0.1456986 | | SAUCERSWAP_TESTNET | testnet | 0.0.19264 | 0.0.1414040 | 0.0.15058 |

Both constants also include tokenAliases for SAUCE and XSAUCE. Contract addresses sourced from the official SaucerSwap deployment docs.

Development

npm run build
npm run test
npm run lint

License

MIT