Docs/Analytics

Agent Analytics

Automatic event tracking, engagement scoring, and reputation analysis for your AI agents.

Automatic Tracking

Analytics are tracked automatically when agents use their Agent Passport. No manual tracking required - everything happens under the hood.

Events

Auth, payments, and agent lifecycle

Scores

Engagement, reputation, and risk

Segments

Champions, loyal, at risk, dormant

Event Types

Authentication Events

auth.success

Agent successfully authenticated with signature

auth.failed

Authentication attempt failed (invalid signature, expired nonce, etc.)

Payment Events

payment.success

Payment completed successfully

payment.failed

Payment failed during verification or settlement

Agent Lifecycle

agent.created

New agent passport created

agent.key_recovered

Agent recovered their private key via mnemonic

Session Events

session.created

Short-lived session token issued

session.expired

Session token expired or revoked

Engagement Scoring

Each agent receives a 0-100 engagement score based on three factors (RFM analysis):

Recency (40%)

How recently the agent was active. Decays over 30 days of inactivity.

Frequency (35%)

How often the agent interacts. Based on total events over time.

Monetary (25%)

Total payment value processed. Higher volume = higher score.

Score Calculation Formula

engagement_score =
    (recency_score × 0.4) +
    (frequency_score × 0.35) +
    (monetary_score × 0.25)

// Each component is 0-100
// Final score is 0-100

Agent Segments

Agents are automatically categorized into segments based on their behavior:

Champions

High engagement, high reputation, active users

Engagement > 80, active in last 7 days

Loyal

Consistent activity, good reputation

Engagement 50-80, regular transactions

At Risk

Previously active but declining engagement

Engagement dropped, 14+ days since last activity

Dormant

No recent activity, may need re-engagement

30+ days since last activity

New

Recently created agents, building reputation

Created within last 7 days

API Endpoints

GET/v1/analytics/agents/:did/overview

Get a comprehensive analytics overview for an agent.

Response

{
  "agent_did": "did:nervepay:agent:7xKp...",
  "engagement": {
    "engagement_score": 85.5,
    "recency_score": 95.0,
    "frequency_score": 80.0,
    "monetary_score": 75.0
  },
  "reputation": {
    "total_events": 142,
    "total_payments": 28,
    "success_rate": 0.96
  },
  "segment": "champion",
  "risk_score": 0.15
}

GET/v1/analytics/agents/:did/events

Get recent events for an agent (paginated).

Query Parameters

limit - Number of events (default: 50, max: 100)
offset - Pagination offset
event_name - Filter by event type

GET/v1/analytics/agents/:did/metrics

Get daily metrics for charting (time series data).

Query Parameters

days - Number of days to fetch (default: 30, max: 90)

GET/v1/analytics/dashboard/summary

Get aggregated analytics across all your agents.

Response

{
  "total_agents": 25,
  "total_events_24h": 1420,
  "total_payments_24h": 87,
  "segment_distribution": {
    "champions": 5,
    "loyal": 12,
    "at_risk": 3,
    "dormant": 2,
    "new": 3
  }
}

How It Works

Agent Uses Passport

Agent authenticates with their Ed25519 signature. No extra tracking code needed.

Events Captured Automatically

Auth attempts, payments, and lifecycle events are logged to the events table.

Scores Update in Real-Time

Database triggers recalculate engagement, reputation, and risk scores on every event.

View in Dashboard

Access analytics via API or the dashboard UI. No setup required.

Get Started

Create your first agent and start tracking analytics

API Reference

Full documentation for all analytics endpoints