@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.
Maintainers
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-alchemyUsage
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 UIGive 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.comor 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
@sperax/agent-tools-core— the tool contract- All SperaxOS agent tools — tool-alchemy is one of many
- SperaxOS — the agent workspace these tools were built for
License
Apache-2.0
