Quick Start

Get your agent sending events to VIGIL in under 2 minutes. No SDK required, just one HTTP call.

Create an account

Go to vigil.costrinity.xyz/dashboard and register with your email.

Create an agent

Click "New Agent", give it a name, and copy your API key.

Send your first event

Make a POST request from your agent:

bash

curl -X POST https://vigil.costrinity.xyz/api/ingest \
  -H "Authorization: Bearer vigil_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "hello-world", "data": {"message": "VIGIL connected!"}}'

✓ That's it. Open your dashboard and you'll see the event appear in real-time.

REST API

The VIGIL API is a simple REST API. Every endpoint accepts JSON and returns JSON.

POST /api/ingest

Log a single event from your agent. Core endpoint, call this every time your agent does something.

Headers

Header	Value
Authorization	`Bearer vigil_YOUR_KEY`
Content-Type	`application/json`

javascript

await fetch('https://vigil.costrinity.xyz/api/ingest', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vigil_YOUR_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    action: 'buy',
    data: { token: 'SOL', amount: 0.5, reason: 'momentum signal' },
    cost_sol: 0.001,
    status: 'success'
  })
})

Response

json

{
  "ok": true,
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "storage_mode": "cloud"
}

🔒 Storage Mode

Every event request accepts a storage_mode field. When set to "local", VIGIL validates your API key and enforces rate limits, but never writes to our database. Events are returned to the client and stored in your browser's IndexedDB. Nothing persists on COSTRINITY servers.

☁️ Cloud (default)

Events stored in your isolated VIGIL account. Accessible from any device. 7–90 day history depending on plan.

💾 Local

Events stored in your browser's IndexedDB only. Zero server persistence. Data never leaves your machine.

javascript

// Cloud mode, stored in your VIGIL account
body: JSON.stringify({ action: 'buy', storage_mode: 'cloud' })

// Local mode, VIGIL never touches our DB
body: JSON.stringify({ action: 'buy', storage_mode: 'local' })
// → Server returns enriched event with ID + compliance tags
// → Your dashboard stores it in IndexedDB automatically

POST /api/ingest (batch)

Log multiple events in a single call. Up to 100 events per request.

javascript

await fetch('https://vigil.costrinity.xyz/api/ingest', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vigil_YOUR_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    events: [
      { action: 'scan', data: { tokens: 847 } },
      { action: 'filter', data: { passed: 12 } },
      { action: 'buy', data: { token: 'BONK' }, cost_sol: 0.1 }
    ]
  })
})

GET /api/graph

Returns the activity graph for an agent, nodes are actions (or individual events), edges are causal links inferred from parent_id / trace_id / run_id / temporal proximity. Used by the dashboard’s Activity Graph and the vigil_get_agent_pnl MCP tool.

agent_id*	UUID	Required.
owner_id*	UUID	Required. Must own the agent.
group	"action"\|"event"	Default 'action'. 'event' returns one node per event (raw timeline).
limit	int 1–5000	Default 2000. Caps the number of events scanned.
include_noise	0\|1	Default 0. When 0, baseline events (heartbeat, ping, health-check, -heartbeat, idle_) are filtered server-side BEFORE the temporal-proximity edge calculation. The dashboard passes 1 to keep the count badge live; CLI consumers usually want the default.
include_system	0\|1	Default 0. When 1, VIGIL-internal cron events (heartbeat_missed, budget_warning, key_rotated, …) are included.

bash

# Default, actions only, clean edges
curl "https://vigil.costrinity.xyz/api/graph?agent_id=...&owner_id=..."

# Include baseline noise (what the dashboard does)
curl "https://vigil.costrinity.xyz/api/graph?agent_id=...&owner_id=...&include_noise=1"

json

{
  "nodes": [
    { "id": "buy", "label": "buy", "count": 47, "color": "#4ade80", "size": 7, ... }
  ],
  "edges": [
    { "from": "scan", "to": "buy", "weight": 12, "kind": "trace" }
  ],
  "stats": {
    "event_count": 1284,
    "action_count": 6,
    "edge_count": 14,
    "window_hours": 24.0,
    "noise_event_count": 847,    // events filtered out as baseline noise
    "noise_action_count": 1      // distinct noise action types (e.g. "griid-heartbeat")
  },
  "agent": { "id": "...", "name": "trading-bot-alpha" }
}

TypeScript SDK

Optional typed wrapper around the REST API. Adds retry logic, batching, and type safety.

bash

npm install @costrinity/vigil

typescript

import { Vigil } from '@costrinity/vigil'

const vigil = new Vigil({
  apiKey: process.env.VIGIL_API_KEY!,
  // Optional: set a default agent name
  // agent: 'my-trading-bot',
})

// Single event
await vigil.log({
  action: 'buy',
  data: { token: 'SOL', amount: 0.5 },
  cost_sol: 0.001,
  status: 'success',
})

// Log an error
await vigil.log({
  action: 'error',
  data: { message: 'Slippage too high', code: 'ERR_SLIPPAGE' },
  status: 'error',
})

// Batch log, efficient for high-frequency agents
await vigil.logBatch([
  { action: 'scan',   data: { tokens: 847 } },
  { action: 'filter', data: { passed: 12 } },
  { action: 'buy',    data: { token: 'BONK' }, cost_sol: 0.1 },
])

// Transfer event with built-in SOL tracking
await vigil.transfer({
  from: '7xKp...1aB2',
  to:   '9mRn...3nR2',
  amount_sol: 1.2,
  memo: 'profit withdrawal',
})

ElizaOS Plugin

Zero-config plugin for ElizaOS agents. Automatically logs every action your agent takes.

bash

npm install @costrinity/vigil-eliza-plugin

typescript

import vigilPlugin from '@costrinity/vigil-eliza-plugin';

export const character = {
  name: 'TradingBot',
  plugins: [
    vigilPlugin({
      apiKey: process.env.VIGIL_API_KEY,
      // Optional: custom agent name (defaults to character.name)
      agentName: 'my-elizaos-bot',
    }),
  ],
  // All agent actions are automatically captured:
  // - Tool calls and responses
  // - Decision reasoning
  // - Memory reads/writes
  // - Errors and retries
};

💡 The ElizaOS plugin hooks into the agent runtime automatically. You don't need to add any vigil.log() calls manually.

MCP Proxy

For agents that use the Model Context Protocol (MCP). The proxy sidecars any MCP server, captures every tool call, resource read, prompt fetch, and notification as a VIGIL event. Zero changes to your agent code.

bash

npm install -g @costrinity/vigil-mcp

Add it to your MCP client config (Claude Desktop, Claude Code, Cursor, etc.):

json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "@costrinity/vigil-mcp", "--",
        "npx", "@modelcontextprotocol/server-filesystem", "/path/to/files"
      ],
      "env": {
        "VIGIL_API_KEY":  "vigil_...",
        "VIGIL_AGENT_ID": "claude-desktop-filesystem"
      }
    }
  }
}

💡 Captured events appear as mcp.tools.call, mcp.resources.read, etc. with request params, response result, and duration on the same event. The proxy is fire-and-forget: VIGIL outages never block the MCP flow.

Event Schema

Full schema of all fields accepted by the ingest endpoint.

Field	Type	Description
action*	string	What the agent did. Free-form string: 'buy', 'error', 'decision', 'transfer', etc.
data	object	Any additional context. JSON object, up to 64KB. Fully searchable in dashboard.
cost_sol	number	SOL spent on this action (for P&L tracking). Supports up to 9 decimal places.
status	string	'success' \| 'error' \| 'info' \| 'warning'. Defaults to 'info'.
id	uuid	Auto-generated UUID for the event. Returned in response.
agent_id	uuid	Resolved from your API key. You don't need to pass this.
timestamp	timestamptz	Auto-set to current UTC time. Cannot be overridden.

Alerts

Smart alerts watch your agents for you. Configure them from the dashboard, no code needed.

Silence DetectionMost Popular

Trigger when an agent hasn't sent an event in N minutes. Catches stuck, crashed, or looping agents.

Error Rate

Alert when error events exceed X% of total events in a rolling window.

SOL Spend ThresholdCritical

Alert when cost_sol total exceeds your limit in 1 hour. Protects against runaway spending.

Custom Action Match

Alert when a specific action appears, e.g. fire immediately if action === 'emergency-stop'.

Delivery channels

✓ Email (all plans)
✓ Webhook POST (Pro+)
✓ Slack webhook (Team+)

Webhooks

VIGIL can POST to your endpoint when an alert fires. Available on Pro and above.

json

// Example webhook payload
{
  "event": "alert.fired",
  "alert_type": "silence",
  "agent_id": "agt_abc123",
  "agent_name": "sniper-v5",
  "message": "Agent has been silent for 10 minutes",
  "fired_at": "2026-03-24T18:00:00Z",
  "dashboard_url": "https://vigil.costrinity.xyz/dashboard/agt_abc123"
}

Webhook requests include a X-VIGIL-Signature header (HMAC-SHA256) so you can verify authenticity. Configure your endpoint URL in the Dashboard → Alerts → Settings.

Rate Limits

Rate limits are per API key. Exceeded requests return 429.

Plan	Rate Limit	Events / Month	History
Free	100 req/min	10k/month	7 days
Pro	1,000 req/min	1M/month	90 days
Team	5,000 req/min	5M/month	1 year
Enterprise	Unlimited	Unlimited	Custom

💡 Batch requests via the events[] array count as 1 request regardless of event count. Use batching to maximize throughput on high-frequency agents.