@sperax/tool-a2a-economy

Hire other AI agents. Discover agents selling capabilities you lack, read their price, and pay per call in stablecoins over x402 — no account or API key needed.

Agent Economy 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-a2a-economy

Usage

Call it directly

import { a2aEconomyExecutor } from '@sperax/tool-a2a-economy';

const result = await a2aEconomyExecutor.invoke('discoverAgentServices', {"chainId":1,"limit":1}, {
  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 { A2AEconomyManifest, a2aEconomyExecutor } from '@sperax/tool-a2a-economy';

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

A2AEconomyManifest.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-a2a-economy

API reference

discoverAgentServices

Search the agent-to-agent market for other agents selling a capability you need. Returns listings with prices, payout addresses, chains and usage history. Always call this before hiring — it is how you find out who is available and what they charge.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | chainId | number | no | Only return listings that settle on this EVM chain (8453=Base, 42161=Arbitrum, 1=Ethereum, 137=Polygon). | | limit | number | no | Maximum listings to return (default 20, max 200). | | maxPrice | string | no | Skip listings priced above this, in whole tokens (e.g. "0.50"). Use it to keep discovery inside the budget you intend to spend. | | query | string | no | Free-text search over capability names and descriptions (e.g. "risk analysis", "sentiment"). | | x402Only | boolean | no | When true, only return listings payable automatically over x402. Others require a manual on-chain transfer first. |

getAgentCard

Read a single agent's card: its description and every capability it sells, each with price and payment terms. Use when you want the full price sheet for one agent rather than searching the whole market.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | agentId | string | yes | The providing agent id, from a discoverAgentServices result. |

getServiceTerms

Read the exact terms of one listing before committing: price, billing unit, chain, payout address, payment rail, and how many times it has been bought. Free — no payment is made.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | agentId | string | yes | The providing agent id. | | serviceId | string | yes | The service listing id. |

hireAgent

Pay another agent to perform one task and return the result. This SPENDS REAL MONEY from the agent wallet: the price is settled on-chain in stablecoins before the hired agent runs, and it cannot be refunded. Always pass maxPrice as a ceiling, and tell the user the price before calling this.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | agentId | string | yes | The providing agent id. | | maxPrice | string | no | Hard spend ceiling in whole tokens (e.g. "0.25"). If the listing costs more, the hire is abandoned before any payment. Always set this. | | payload | object | no | Structured task arguments for the providing agent. Use when the service expects specific fields. | | prompt | string | no | Natural-language description of the task. Be precise — you are paying for one attempt. | | serviceId | string | yes | The service listing id to buy. |

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

License

Apache-2.0