@sperax/tool-polymarket
v0.2.1
Published
Read and trade on Polymarket prediction markets. — an agent tool for SperaxOS.
Maintainers
Readme
@sperax/tool-polymarket
Read and trade on Polymarket prediction markets.
Polymarket 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-polymarketUsage
Call it directly
import { polymarketExecutor } from '@sperax/tool-polymarket';
const result = await polymarketExecutor.invoke('listMarkets', {"active":"<active>","category":"<category>"}, {
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 { PolymarketManifest, polymarketExecutor } from '@sperax/tool-polymarket';
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: PolymarketManifest.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 polymarketExecutor.invoke(block.name, block.input, { messageId: response.id });
console.log(result.content);
}PolymarketManifest.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-polymarket
API reference
listMarkets
List active Polymarket prediction markets. Use q to search by question text and category/tag to filter.
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| active | boolean | no | Only return active markets. Default true. |
| category | string | no | Filter by Gamma category (e.g. "Politics", "Sports"). |
| limit | number | no | Max markets to return (default 20, max 100). |
| q | string | no | Free-text search across market questions. |
| tag | string | no | Filter by tag slug (e.g. "trump", "elections-2024"). |
getMarket
Fetch a single Polymarket market by id (the Gamma numeric id or slug).
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| marketId | string | yes | Gamma market id or slug. |
getOrderbook
Fetch the CLOB orderbook + midpoint for a market outcome token.
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| conditionId | string | yes | Condition id of the market (matches Gamma conditionId). |
| tokenId | string | yes | ERC1155 outcome token id (one of clobTokenIds). |
getLastTrades
Fetch the most recent fills on a market.
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| limit | number | no | Max trades (default 25, max 100). |
| market | string | yes | Polymarket conditionId. |
getUserPositions
Fetch a user's open positions on Polymarket.
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| user | string | yes | Polygon address (proxy wallet). |
getUserActivity
Fetch a user's recent on-chain activity (trades, conversions, deposits).
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| limit | number | no | Default 25, max 100. |
| type | string | no | Filter by activity type (trade | conversion | deposit | withdrawal | reward). |
| user | string | yes | Polygon address. |
getLeaderboard
Fetch the Polymarket leaderboard.
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| interval | string | no | Time window: 1d | 7d | 30d | all. Default 7d. |
| limit | number | no | Default 20, max 100. |
| sort | string | no | Sort by volume (default) or pnl. |
placeOrder
Place a signed limit order on Polymarket. The order must be EIP-712 signed before being passed here. Requires explicit user confirmation.
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| expiration | string | no | ISO timestamp; omit for GTC. |
| orderType | string | no | GTC (default), FOK, or GTD. |
| price | number | yes | Limit price 0..1. |
| side | string | yes | BUY or SELL. |
| signature | string | yes | EIP-712 signature produced by the user's wallet. |
| size | number | yes | Outcome shares. |
| tokenId | string | yes | ERC1155 outcome token id. |
cancelOrder
Cancel a live order.
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| orderId | string | yes | CLOB order id. |
getOrderStatus
Fetch the current status of an order.
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| orderId | string | yes | CLOB order id. |
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-polymarket is one of many
- SperaxOS — the agent workspace these tools were built for
License
Apache-2.0
