plugin-algovault

AlgoVault composite trade-call verdicts for ElizaOS agents — keyless free tier, served over the AlgoVault MCP server.

plugin-algovault gives any Eliza agent native access to AlgoVault's signal-interpretation tools. It is a thin wrapper over the AlgoVault MCP surface (api.algovault.com/mcp): each action delegates to the Model Context Protocol client and returns the server's verdict — the scoring engine stays server-side and always current.

Actions

Action	Tool	Tier	What it returns
ALGOVAULT_GET_TRADE_CALL	get_trade_call	Free	Composite LONG / SHORT / HOLD verdict for a crypto asset, with a confidence score, market regime, and reasoning.
ALGOVAULT_GET_TRADE_SIGNAL	get_trade_signal	Free	Alias of the trade call (kept for "give me a signal" phrasing).
ALGOVAULT_GET_MARKET_REGIME	get_market_regime	Free*	Market-regime classification (trending / ranging) + cross-venue funding context.
ALGOVAULT_SCAN_FUNDING_ARB	scan_funding_arb	Free*	Cross-venue funding-rate arbitrage opportunities, ranked by spread (free tier returns the top 5).

_{*Available keyless on the free tier; an ALGOVAULT_API_KEY raises request limits.}

The composite verdict aggregates indicators across exchanges. AlgoVault's PFE (peak-favourable-excursion) win-rate track record is published live via the signal-performance MCP resource and at algovault.com.

Installation

npm install plugin-algovault
# or: bun add plugin-algovault

Configuration

Keyless (free tier) — zero config. Just add the plugin to your character:

{
  "name": "My Trading Agent",
  "plugins": ["plugin-algovault"]
}

All four actions work keyless on the free tier (100 calls/month; scan_funding_arb returns the top 5).

Optional — raise request limits / unlock paid tiers by providing an API key. Set it as a secret/env var:

{
  "name": "My Trading Agent",
  "plugins": ["plugin-algovault"],
  "settings": {
    "secrets": {
      "ALGOVAULT_API_KEY": "your-algovault-api-key"
    }
  }
}

Setting	Required	Description
ALGOVAULT_API_KEY	No	Unlocks paid tools. Omit for the keyless free tier.
ALGOVAULT_MCP_URL	No	Override the MCP endpoint. Defaults to https://api.algovault.com/mcp.

Usage

Once installed, the agent calls AlgoVault automatically when the conversation calls for it:

User:  AlgoVault trade call for BTC
Agent: BTC — HOLD (confidence 62/100) · regime: ranging.
       Indicators are mixed; no clear edge right now.

User:  should I long ETH on the 4h?
Agent: ETH — LONG (confidence 71/100) @ $3,420 · regime: trending_up.

User:  scan funding arb opportunities
Agent: Found 5 funding-arbitrage opportunities, ranked by spread.

The coin (and optional timeframe / exchange) are read from the message; sensible defaults match the live tool schemas (15m / BINANCE for trade calls, 4h / HL for regime).

How it works

Eliza agent ──▶ plugin-algovault action ──▶ @modelcontextprotocol/sdk
                                              (Streamable HTTP)
                                                    │
                                                    ▼
                                       api.algovault.com/mcp  ──▶ verdict

The plugin holds no scoring logic. Each action extracts the tool arguments, calls the named MCP tool, and formats the response. Structured AlgoVault errors (e.g. a paid tool called keyless) surface their suggested_* guidance so the agent can self-correct. An optional API key is sent as an Authorization: Bearer header.

Development

bun install
bun test        # unit tests (extraction, formatting, config, plugin shape)
bun run build   # → dist/

Tests

The pure logic (argument extraction, verdict formatting, error mapping, config resolution, plugin shape) is unit-tested with bun test; the live MCP round-trip is verified against api.algovault.com/mcp keyless. See examples/keyless-demo.ts for a runnable end-to-end demo.

License

MIT

---

Built by AlgoVault Labs — composable, API-first signal-interpretation tools for AI agents.