npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@sperax/tool-alchemy

v0.2.2

Published

Alchemy enhanced APIs — a wallet's full historical transfer log across Ethereum, Arbitrum, Base, Polygon and Optimism, plus ERC-20 balances and token metadata. — an agent tool for SperaxOS.

Readme

@sperax/tool-alchemy

Alchemy enhanced APIs — a wallet's full historical transfer log across Ethereum, Arbitrum, Base, Polygon and Optimism, plus ERC-20 balances and token metadata.

Alchemy 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-alchemy

Usage

Call it directly

import { alchemyExecutor } from '@sperax/tool-alchemy';

const result = await alchemyExecutor.invoke('getAssetTransfers', {"address":"<address>","categories":"<categories>"}, {
  messageId: 'msg-1',
});

console.log(result.content); // prose summary written for the model to read
console.log(result.state);   // typed data payload for your own UI

Give it to a model

import Anthropic from '@anthropic-ai/sdk';
import { AlchemyManifest, alchemyExecutor } from '@sperax/tool-alchemy';

const client = new Anthropic();

const response = await client.messages.create({
  model: 'claude-opus-4-8',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Ask something this tool can answer' }],
  tools: AlchemyManifest.api.map((api) => ({
    name: api.name,
    description: api.description,
    input_schema: api.parameters,
  })),
});

for (const block of response.content) {
  if (block.type !== 'tool_use') continue;
  const result = await alchemyExecutor.invoke(block.name, block.input, { messageId: response.id });
  console.log(result.content);
}

AlchemyManifest.api is already in JSON-Schema form, so it maps onto any tool-calling API — Anthropic, OpenAI, the Vercel AI SDK, or an MCP server — without translation.

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 { alchemyExecutor } = await import('@sperax/tool-alchemy');

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-alchemy

API reference

getAssetTransfers

Get a wallet's historical asset transfers — native, ERC-20, ERC-721, ERC-1155 and internal — newest first, filterable by direction and category. This answers "what has this wallet done", which plain RPC cannot. Results are capped at 100 per call; when nextPageKey is returned, more history exists and the result must not be described as complete.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | address | string | yes | Wallet address to fetch transfers for (0x + 40 hex). | | categories | array | no | Transfer categories to include: external, internal, erc20, erc721, erc1155. Defaults to ["external","erc20"]. Request erc721/erc1155 explicitly for NFT activity. Note that "internal" is not indexed on Base or Optimism and is dropped there. | | chain | string | no | Chain to query: ethereum, arbitrum, base, polygon or optimism. Defaults to ethereum. | | direction | string | no | Which transfers to fetch: "out" (sent by the wallet), "in" (received), or "both". Use a single direction when you intend to page through history — "both" has no continuation cursor. | | limit | number | no | Maximum transfers to return (1–100). | | pageKey | string | no | Cursor from a previous call's nextPageKey, to fetch the next page of history. |

getTokenBalances

Get a wallet's non-zero ERC-20 token balances on one chain, with symbol, name and decimals resolved per contract. Returns raw balances with NO USD pricing — use the Moralis tool for priced holdings. Metadata is resolved for at most 25 balances; when metadataTruncated is true the list is partial.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | address | string | yes | Wallet address (0x + 40 hex). | | chain | string | no | Chain to query: ethereum, arbitrum, base, polygon or optimism. Defaults to ethereum. |

getTokenMetadata

Get name, symbol, decimals and logo for an ERC-20 token contract. Use this to identify an unfamiliar contract address before interpreting balances or transfers involving it.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | address | string | yes | ERC-20 token contract address (0x + 40 hex). | | chain | string | no | Chain to query: ethereum, arbitrum, base, polygon or optimism. Defaults to ethereum. |

Types

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

Related

License

Apache-2.0