hak-saucerswap-plugin 1.0.1 → 2.1.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Juanma Gomez
+Copyright (c) 2026 Juan Manuel Gómez López
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -15,6 +15,14 @@ lets AI agents:
 - Add/remove liquidity via router transactions
 - Discover farming opportunities
 
+## Documentation
+
+- **[Configuration](./docs/CONFIGURATION.md)** — full settings table, env vs. plugin-config
+  precedence, and pointers to the official SaucerSwap contract deployment list.
+- **[Tools](./docs/TOOLS.md)** — per-tool reference (parameters, return shape, example prompts,
+  error behavior) for all six tools registered by the plugin.
+- **[Examples](./docs/EXAMPLES.md)** — dry-run swap, CLI wrapper, and integration smoke test.
+
 ## Installation
 
 ```bash
@@ -24,108 +32,48 @@ npm install hak-saucerswap-plugin
 ## Quick Start
 
 ```ts
-import { saucerswapPlugin } from "hak-saucerswap-plugin";
+import { saucerswapPlugin, SAUCERSWAP_MAINNET } from "hak-saucerswap-plugin";
 
-const agent = new HederaAgent({
-  plugins: [saucerswapPlugin]
-});
-```
-
-## Configuration
-
-Provide router contract IDs and (optionally) token aliases via environment or plugin config.
-
-```bash
-export SAUCERSWAP_ROUTER_CONTRACT_ID=0.0.123456
-export SAUCERSWAP_ROUTER_V2_CONTRACT_ID=0.0.654321
-export SAUCERSWAP_WRAPPED_HBAR_TOKEN_ID=0.0.987654
-```
-
-```ts
 const agent = new HederaAgent({
   plugins: [saucerswapPlugin],
   config: {
     saucerswap: {
-      routerContractId: "0.0.123456",
-      routerV2ContractId: "0.0.654321",
-      wrappedHbarTokenId: "0.0.987654",
-      tokenAliases: { HBAR: "0.0.987654" },
-      defaultPoolVersion: "v2"
-    }
-  }
+      ...SAUCERSWAP_MAINNET,
+      apiKey: process.env.SAUCERSWAP_API_KEY,
+    },
+  },
 });
 ```
 
-## Tools
-
-- `saucerswap_get_swap_quote` - Fetches swap quotes from SaucerSwap API.
-- `saucerswap_swap_tokens` - Builds/executes swap transactions with slippage protection.
-- `saucerswap_get_pools` - Lists pools or finds a pool by token pair.
-- `saucerswap_add_liquidity` - Builds/executes add-liquidity transactions.
-- `saucerswap_remove_liquidity` - Builds/executes remove-liquidity transactions.
-- `saucerswap_get_farms` - Lists farming opportunities.
-
-## Dry-Run Swap Example
-
-Build a swap transaction without executing it by setting `mode` to `returnBytes`.
+Or use the `network` shorthand and set `SAUCERSWAP_NETWORK=mainnet` in your environment — no
+contract addresses needed:
 
 ```ts
-import { Client } from "@hashgraph/sdk";
-import { saucerswapPlugin } from "@your-org/hak-saucerswap-plugin";
-
-const client = Client.forTestnet();
-client.setOperator(process.env.HEDERA_ACCOUNT_ID!, process.env.HEDERA_PRIVATE_KEY!);
-
-const context = { mode: "returnBytes" };
-const tools = saucerswapPlugin.tools(context);
-const swapTool = tools.find((tool) => tool.method === "saucerswap_swap_tokens");
-
-if (!swapTool) {
-  throw new Error("Swap tool not registered.");
-}
-
-const result = await swapTool.execute(client, context, {
-  fromToken: "0.0.123456",
-  toToken: "0.0.654321",
-  amount: "1.5",
-  slippageTolerance: 0.5
+const agent = new HederaAgent({
+  plugins: [saucerswapPlugin],
+  config: {
+    saucerswap: { network: "mainnet", apiKey: process.env.SAUCERSWAP_API_KEY },
+  },
 });
-
-console.log(result);
 ```
 
-Or run the built-in CLI wrapper after building:
+The SaucerSwap API requires an `x-api-key` header. Get a key from
+[saucerswap.finance](https://www.saucerswap.finance) and supply it via either
+`SAUCERSWAP_API_KEY` in the environment or `config.saucerswap.apiKey`. See
+[`.env.example`](./.env.example) for a copy-paste template of all supported environment variables.
 
-```bash
-npm run build
+## Network Defaults
 
-export HEDERA_NETWORK=testnet
-export HEDERA_ACCOUNT_ID=0.0.1234
-export HEDERA_PRIVATE_KEY=302e020100300506032b657004220420...
-export SAUCERSWAP_ROUTER_CONTRACT_ID=0.0.123456
-export SAUCERSWAP_SWAP_FROM=0.0.111111
-export SAUCERSWAP_SWAP_TO=0.0.222222
-export SAUCERSWAP_SWAP_AMOUNT=1.5
+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.
 
-npm run dry-run:swap
-```
+| 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`       |
 
-## Integration Smoke Test
-
-Hit the SaucerSwap API and print basic counts.
-
-```bash
-npm run test:integration
-```
-
-Optional environment overrides:
-
-```bash
-export SAUCERSWAP_BASE_URL=https://api.saucerswap.finance
-export SAUCERSWAP_TEST_FROM_TOKEN=0.0.123456
-export SAUCERSWAP_TEST_TO_TOKEN=0.0.654321
-export SAUCERSWAP_TEST_AMOUNT=1
-```
+Both constants also include `tokenAliases` for `SAUCE` and `XSAUCE`. Contract addresses sourced
+from the [official SaucerSwap deployment docs](https://docs.saucerswap.finance/developerx/contract-deployments).
 
 ## Development