API Reference

Programmatic access to ChainWard. All endpoints require authentication.

Authentication

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

All API endpoints accept two authentication methods:

API Key (recommended)

Generate an API key in Settings. Keys use the ag_ prefix and are shown only once at creation.

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

Session Cookie

When signed in via the dashboard, a chainward-session JWT cookie is set automatically. Browser requests include this cookie by default.

TypeScript SDK

Install the SDK for typed access to all endpoints:

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. Types: large_transfer, balance_drop, gas_spike, failed_tx, inactivity, new_contract.

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

API requests are rate-limited to 100 requests per minute per session. Rate limit headers are included in all responses.