@sperax/tool-safe-multisig

Gnosis Safe multi-sig treasury management: view balances, propose transactions, track signatures, and execute collected transactions.

Safe Multisig 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-safe-multisig

Usage

Call it directly

import { safeMultisigExecutor } from '@sperax/tool-safe-multisig';

const result = await safeMultisigExecutor.invoke('getSafeInfo', {"chainId":1,"safeAddress":"<safeAddress>"}, {
  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 { SafeMultisigManifest, safeMultisigExecutor } from '@sperax/tool-safe-multisig';

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

SafeMultisigManifest.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-safe-multisig

API reference

getSafeInfo

Get detailed information about a Gnosis Safe: owners list, signing threshold, current nonce, ETH and top ERC-20 token balances with USD values, and count of pending transactions. Use this first to orient the user around their Safe.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | chainId | number | no | Chain ID: 1=Ethereum, 10=Optimism, 100=Gnosis, 137=Polygon, 8453=Base, 42161=Arbitrum. Default: 1. | | safeAddress | string | yes | The Safe contract address (0x...). |

getPendingTransactions

Get all pending (unexecuted) transactions for a Safe. Returns each transaction with: destination address, ETH value, calldata (decoded if possible), how many owners have signed, who still needs to sign, and a link to the Safe UI to complete signing.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | chainId | number | no | Chain ID. Default: 1 (Ethereum). | | safeAddress | string | yes | The Safe contract address (0x...). |

proposeTransaction

Propose a new transaction to a Gnosis Safe. Computes the Safe transaction hash and submits it to the Safe Transaction Service. Returns the safeTxHash and a link to the Safe UI where owners can sign it. ALWAYS confirm destination, value, and calldata with the user before calling this.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | chainId | number | no | Chain ID. Default: 1 (Ethereum). | | data | string | no | Hex-encoded calldata (optional, defaults to "0x"). | | safeAddress | string | yes | The Safe contract address (0x...). | | senderAddress | string | yes | The wallet address proposing the transaction (0x...). | | to | string | yes | Destination address for the transaction (0x...). | | value | string | yes | ETH value to send (human-readable, e.g. "0.5" for 0.5 ETH). |

getSafeTransactionHistory

Get the transaction history of a Safe — recently executed multisig transactions with timestamps, values, and decoded calldata descriptions.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | chainId | number | no | Chain ID. Default: 1 (Ethereum). | | limit | number | no | Number of transactions to return. Default: 20. Max: 50. | | safeAddress | string | yes | The Safe contract address (0x...). |

estimateSafeGas

Estimate the gas required for a proposed Safe transaction before submitting it. Useful for cost estimation before calling proposeTransaction.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | chainId | number | no | Chain ID. Default: 1 (Ethereum). | | data | string | no | Hex calldata (optional). | | safeAddress | string | yes | The Safe contract address (0x...). | | to | string | yes | Destination address (0x...). | | value | string | yes | ETH value in human-readable format (e.g. "0"). |

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

License

Apache-2.0