@sperax/tool-dust-sweeper

Scan wallets for small token balances across chains and consolidate them into DeFi yield. Recover trapped value from gas-prohibitive dust tokens.

Dust Sweeper is an agent tool from SperaxOS, packaged headless so you can call it from any agent framework. It ships two things: the manifest — a JSON-Schema function definition a model can call — and the executor that runs the call against the real API.

There is no UI layer and no framework lock-in. It works anywhere TypeScript runs.

Install

npm install @sperax/tool-dust-sweeper

Usage

import { Manifest } from '@sperax/tool-dust-sweeper';

// Manifest.api is a JSON-Schema tool definition, ready to hand to any model.

Every executor returns a BuiltinToolResult — { success, content, state }. content is prose written for the model to read; state is the typed data payload for your own code. Executors never throw: a failed call comes back as { success: false, content: '<reason>' }, so a network blip degrades the answer instead of crashing the agent loop.

Configuration — required

This tool needs a backend you control. It will not work on a bare npm install alone.

The upstream API requires a secret key. That key is deliberately not bundled here — shipping it in an npm package would leak it to every consumer. Instead the executor calls a SperaxOS /webapi/* route, which holds the key server-side and injects it. That route is session-authenticated, so the public deployment at https://chat.sperax.io (the default origin) answers 401 to anonymous callers.

To use this tool you need one of:

• a SperaxOS deployment of your own, or
• any HTTP endpoint that implements the same request shape and supplies the key.

Point the package at it before importing the tool — the URL is resolved once, when the module first loads:

SPERAX_API_BASE_URL=https://my-speraxos.example.com

or in code:

import { configureSperaxApi } from '@sperax/agent-tools-core';

configureSperaxApi({ baseUrl: 'https://my-speraxos.example.com' });

// import the tool only after configuring, so the path resolves against your origin
const { Manifest } = await import('@sperax/tool-dust-sweeper');

Inside a browser that already serves those routes at its own origin, requests stay same-origin and no configuration is needed.

If you want a tool that runs with zero setup, use one of the standalone tools — those call public APIs directly and need no key, no origin, and no backend.

Tool identifier

sperax-dust-sweeper

API reference

scanForDust

Scan a wallet for dust tokens (small balances) across all supported chains.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | address | string | yes | Wallet address (0x…) | | minValueUsd | number | no | Minimum USD value to consider as dust (default: 10) |

getSweepStrategy

Calculate optimal sweep strategy: which tokens to consolidate and where to deposit for yield.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | address | string | yes | Wallet address (0x…) | | targetYield | usds | aave | lido | yearn | auto | no | Yield destination: usds (default, Sperax USDs ~12% APY), aave, lido, yearn, or auto (best APY) |

estimateSweepValue

Quick estimate of total recoverable dust value after gas costs.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | address | string | yes | Wallet address (0x…) |

executeSweep

Execute the sweep strategy (consolidate dust and deposit for yield). Requires user approval.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | address | string | yes | Wallet address (0x…) | | strategy | object | yes | Sweep strategy from getSweepStrategy |

getSweepHistory

View past sweep operations and yield earned.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | address | string | yes | Wallet address (0x…) |

Types

Shared types come from @sperax/agent-tools-core: BuiltinToolManifest, BuiltinToolResult, BuiltinToolContext, and the BaseExecutor class every tool executor extends.

Related

• @sperax/agent-tools-core — the tool contract
• All SperaxOS agent tools — tool-dust-sweeper is one of many
• SperaxOS — the agent workspace these tools were built for

License

Apache-2.0