API Reference

The monitoring API manages the agent wallets you watch from the dashboard. Every endpoint on this page needs your API key or a signed-in session; without one it answers 401. The free public checks are on the Public API page.

Authentication

Base URL: https://api.chainward.ai

Every endpoint accepts either of two credentials:

API key (recommended)

Generate an API key in Settings (sign in with your wallet first). Keys start with ag_ and are shown only once, when you create them. A key with the read scope can make GET requests; POST, PATCH and DELETE need write, or the API answers 403.

curl -H "Authorization: Bearer ag_YOUR_KEY" \
  https://api.chainward.ai/api/agents

Session cookie

When you sign in on the dashboard, a chainward-session cookie is set. Browser requests send it automatically.

TypeScript SDK

Install the SDK for typed access to agents, transactions and alerts:

npm install @chainward/sdk

import { ChainWard } from '@chainward/sdk';

const cw = new ChainWard({ apiKey: 'ag_YOUR_KEY' });

// Register an agent
await cw.agents.register({ chain: 'base', wallet: '0x...' });

// List transactions
const txs = await cw.transactions.list({ limit: 50 });

// Create an alert
await cw.alerts.create({
  wallet: '0x...',
  type: 'large_transfer',
  threshold: 1000,
  channels: ['discord'],
  discordWebhook: 'https://discord.com/api/webhooks/...',
});

Endpoints

Agents

GET/api/agents

List all your monitored agents.

Example

curl -H "Authorization: Bearer ag_YOUR_KEY" \
  https://api.chainward.ai/api/agents

Response

{
  "success": true,
  "data": [
    {
      "id": 1,
      "walletAddress": "0x3cAc...",
      "chain": "base",
      "agentName": "My Trading Bot",
      "agentFramework": "agentkit",
      "createdAt": "2026-03-01T00:00:00Z"
    }
  ]
}

GET/api/agents/:id

Get details for a specific agent.

Example

curl -H "Authorization: Bearer ag_YOUR_KEY" \
  https://api.chainward.ai/api/agents/1

POST/api/agents

Example

curl -X POST \
  -H "Authorization: Bearer ag_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"walletAddress":"0x...","chain":"base","agentName":"My Bot"}' \
  https://api.chainward.ai/api/agents

Response

{
  "success": true,
  "data": {
    "id": 1,
    "walletAddress": "0x...",
    "chain": "base",
    "agentName": "My Bot"
  }
}

PATCH/api/agents/:id

Update agent name, framework, or tags.

Example

curl -X PATCH \
  -H "Authorization: Bearer ag_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agentName":"Renamed Bot","tags":["production"]}' \
  https://api.chainward.ai/api/agents/1

DELETE/api/agents/:id

Remove an agent and stop monitoring its wallet.

Example

curl -X DELETE \
  -H "Authorization: Bearer ag_YOUR_KEY" \
  https://api.chainward.ai/api/agents/1

Transactions

GET/api/transactions

List transactions across your agents. Supports filtering and pagination.

Example

curl -H "Authorization: Bearer ag_YOUR_KEY" \
  "https://api.chainward.ai/api/transactions?wallet=0x...&limit=50&offset=0"

Response

{
  "success": true,
  "data": [...],
  "pagination": { "total": 142, "limit": 50, "offset": 0, "hasMore": true }
}

GET/api/transactions/stats

Transaction volume over time, bucketed by interval.

Example

curl -H "Authorization: Bearer ag_YOUR_KEY" \
  "https://api.chainward.ai/api/transactions/stats?wallet=0x...&bucket=1h"

Alerts

GET/api/alerts

List all alert configurations.

Example

curl -H "Authorization: Bearer ag_YOUR_KEY" \
  https://api.chainward.ai/api/alerts

Response

{
  "success": true,
  "data": [
    {
      "id": 1,
      "walletAddress": "0x...",
      "chain": "base",
      "alertType": "large_transfer",
      "thresholdValue": "1000",
      "thresholdUnit": "usd",
      "channels": ["discord"],
      "enabled": true
    }
  ]
}

POST/api/alerts

Create a new alert. alertType is one of large_transfer, balance_drop, gas_spike, failed_tx, inactivity, new_contract, idle_balance (see Alert Types). thresholdUnit is usd, native or percentage. lookbackWindow (for example "24 hours") sets the window for balance_drop and inactivity, and how long the balance must sit idle for idle_balance. channels takes discord, telegram and webhook, with discordWebhook, telegramChatId and webhookUrl.

Example

curl -X POST \
  -H "Authorization: Bearer ag_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"walletAddress":"0x...","chain":"base","alertType":"large_transfer","thresholdValue":"1000","thresholdUnit":"usd","channels":["discord"],"discordWebhook":"https://discord.com/api/webhooks/..."}' \
  https://api.chainward.ai/api/alerts

PATCH/api/alerts/:id

Update an alert configuration (threshold, channels, enabled state).

Example

curl -X PATCH \
  -H "Authorization: Bearer ag_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"thresholdValue":"500","enabled":false}' \
  https://api.chainward.ai/api/alerts/1

DELETE/api/alerts/:id

Delete an alert configuration.

Example

curl -X DELETE \
  -H "Authorization: Bearer ag_YOUR_KEY" \
  https://api.chainward.ai/api/alerts/1

POST/api/alerts/:id/test

Send a test alert to verify your delivery channels. Rate limited to 5/min.

Example

curl -X POST \
  -H "Authorization: Bearer ag_YOUR_KEY" \
  https://api.chainward.ai/api/alerts/1/test

GET/api/alerts/events

List alert event history with delivery status.

Example

curl -H "Authorization: Bearer ag_YOUR_KEY" \
  "https://api.chainward.ai/api/alerts/events?limit=20&offset=0"

Data

GET/api/stats/overview

Fleet-wide stats: total agents, transactions, gas spend, balance.

Example

curl -H "Authorization: Bearer ag_YOUR_KEY" \
  https://api.chainward.ai/api/stats/overview

GET/api/stats/agents/:id

Per-agent stats: transaction count, gas, balance, last activity.

Example

curl -H "Authorization: Bearer ag_YOUR_KEY" \
  https://api.chainward.ai/api/stats/agents/1

GET/api/balances/latest

Latest balance snapshot for each agent.

Example

curl -H "Authorization: Bearer ag_YOUR_KEY" \
  https://api.chainward.ai/api/balances/latest

GET/api/balances/history

Historical balance data for charting. Params: wallet, from, to, bucket (1h or 1d).

Example

curl -H "Authorization: Bearer ag_YOUR_KEY" \
  "https://api.chainward.ai/api/balances/history?wallet=0x...&bucket=1h"

GET/api/gas/analytics

Gas spend analytics over time. Params: wallet, from, to, bucket.

Example

curl -H "Authorization: Bearer ag_YOUR_KEY" \
  https://api.chainward.ai/api/gas/analytics

Rate limits. 100 requests a minute per IP address. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.