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.