@sperax/tool-zealy

Zealy community engagement — quests, leaderboards, sprints & XP

Zealy 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-zealy

Usage

Call it directly

import { zealyExecutor } from '@sperax/tool-zealy';

const result = await zealyExecutor.invoke('getCommunityInfo', {"subdomain":"<subdomain>"}, {
  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 { ZealyManifest, zealyExecutor } from '@sperax/tool-zealy';

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: ZealyManifest.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 zealyExecutor.invoke(block.name, block.input, { messageId: response.id });
  console.log(result.content);
}

ZealyManifest.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

None. This tool calls a public API directly and needs no key or origin configuration.

Tool identifier

sperax-zealy

API reference

getCommunityInfo

Get basic information about a Zealy community — name, description, member count, and image.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | subdomain | string | no | The community subdomain (last part of the Zealy URL, e.g. "speraxos" from zealy.io/cw/speraxos). Defaults to "speraxos". |

getUser

Look up a Zealy community member by user ID, wallet address, Discord handle, Twitter username, or email. Returns XP, rank, level, and connected accounts.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | blockchainAddress | string | no | Blockchain wallet address to look up the user by. Use with blockchainNetwork for multi-chain. | | blockchainNetwork | string | no | Blockchain network for the address lookup (e.g. "eth-mainnet", "arb-mainnet", "sol-mainnet"). | | discordHandle | string | no | Discord handle to look up the user by. | | discordId | string | no | Discord ID (snowflake) to look up the user by. | | email | string | no | Email address to look up the user by. | | ethAddress | string | no | Ethereum wallet address to look up the user by. | | subdomain | string | no | Community subdomain. Defaults to "speraxos". | | twitterId | string | no | Twitter/X numeric ID to look up the user by. | | twitterUsername | string | no | Twitter/X username to look up the user by. | | userId | string | no | Zealy user ID (UUID) for direct lookup. |

getLeaderboard

Retrieve the community leaderboard showing top members ranked by XP. Supports all-time and sprint-specific leaderboards with pagination.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | limit | number | no | Number of records per page (default: 50, max: 1000). | | page | number | no | Page number for pagination (starts at 1). | | sprintId | string | no | Sprint ID to get sprint-specific leaderboard. Omit for all-time leaderboard. | | subdomain | string | no | Community subdomain. Defaults to "speraxos". |

listQuests

List all quests in a Zealy community with their rewards, recurrence settings, and validation status. Requires admin access.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | subdomain | string | no | Community subdomain. Defaults to "speraxos". |

listSprints

List sprints (time-limited competitions) in a Zealy community. Includes active and past sprints with start/end dates and reward zones.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | onlyCurrent | boolean | no | If true, returns only the currently active sprint. | | subdomain | string | no | Community subdomain. Defaults to "speraxos". |

reviewSubmission

Review quest submissions — approve, reject, or set pending. Can optionally add a comment and bonus XP. Requires admin API key.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | claimedQuestIds | array | yes | Array of claimed quest IDs to review. | | comment | string | no | Optional comment for the review. | | status | success | fail | pending | yes | Review decision: "success" (approve), "fail" (reject), or "pending". | | subdomain | string | no | Community subdomain. Defaults to "speraxos". |

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-zealy is one of many
• SperaxOS — the agent workspace these tools were built for

License

Apache-2.0