@sperax/tool-limit-orders

Place gasless limit orders via 1inch Protocol — MEV-protected, no gas to place

Limit Orders 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-limit-orders

Usage

Call it directly

import { limitOrdersExecutor } from '@sperax/tool-limit-orders';

const result = await limitOrdersExecutor.invoke('createLimitOrder', {"amountIn":"<amountIn>","chain":"<chain>"}, {
  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 { LimitOrdersManifest, limitOrdersExecutor } from '@sperax/tool-limit-orders';

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

LimitOrdersManifest.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-limit-orders

API reference

createLimitOrder

Create a gasless limit order to buy or sell tokens at a specific price. Uses 1inch Limit Order Protocol with EIP-712 signing (no gas cost to place). Always preview first, then request user confirmation before signing.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | amountIn | string | yes | Amount of source token to sell (human-readable, e.g. "1.5" for 1.5 ETH). | | chain | string | yes | Chain name or ID (e.g. "arbitrum", "1" for Ethereum, "42161" for Arbitrum). Default: "arbitrum". | | expiryHours | number | no | Hours until the order expires. Default: 720 (30 days). Max: 8760 (1 year). | | limitPrice | string | yes | Trigger price quoted as tokenOut per tokenIn (e.g. "2600" means 1 tokenIn = 2600 tokenOut). | | tokenIn | string | yes | Token to sell (symbol, e.g. "ETH", "USDC"). | | tokenOut | string | yes | Token to buy (symbol, e.g. "USDC", "ETH"). | | walletAddress | string | no | User wallet address (0x...). Optional — the connected wallet is injected at signing time. |

listOrders

List the user's limit orders — active, filled, expired, or cancelled. Optionally filter by chain.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | chain | string | no | Filter by chain name or ID. Omit to list orders on Arbitrum (default). | | walletAddress | string | no | User wallet address (0x...). If available, pass it to query orders. Otherwise omit — the user will be prompted to connect their wallet. |

cancelOrder

Cancel an active limit order. Requires the order ID and chain. The user must confirm before cancellation.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | chain | string | yes | Chain the order was placed on (e.g. "arbitrum"). | | orderHash | string | yes | The order hash to cancel (0x + 64 hex characters). Get this from listOrders. | | walletAddress | string | no | User wallet address (0x...). Optional — used for validation only. |

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

License

Apache-2.0