> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ardenstats.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom

# Custom Integration

Integrate any agent or application with Arden telemetry tracking.

## Overview

Send telemetry events from your custom agents using either the CLI or direct API calls. Perfect for tracking usage of your own AI agents, tools, or applications.

## Using the CLI

The simplest way to send events from any application:

```bash
arden events send --agent "my-agent" --bid 1000
```

### Basic Event

```bash
arden events send --agent "my-agent" --bid 1000 --data '{"task": "code_review"}'
```

### Batch Events

Create a JSON file with multiple events:

```json
[
  {
    "agent": "my-agent",
    "bid": 1000,
    "data": {"task": "code_review"}
  },
  {
    "agent": "my-agent", 
    "bid": 1500,
    "data": {"task": "bug_fix"}
  }
]
```

Send the batch:

```bash
arden events send --file events.json
```

## Using the API

For direct integration without the CLI:

```bash
curl -X POST https://api.ardenstats.com/api/events \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-agent",
    "bid": 1000,
    "time": 1642781234567,
    "data": {"task": "code_review"}
  }'
```

## Language Examples

### Python

```python
import requests
import time

def send_telemetry(agent_id, bid, data=None):
    event = {
        "agent": agent_id,
        "bid": bid,
        "time": int(time.time() * 1000),
        "data": data or {}
    }
    
    response = requests.post(
        "https://api.ardenstats.com/api/events",
        json=event,
        headers={"Content-Type": "application/json"}
    )
    
    return response.json()

# Usage
send_telemetry("my-python-agent", 1000, {"task": "data_analysis"})
```

### JavaScript/Node.js

```javascript
async function sendTelemetry(agentId, bid, data = {}) {
  const event = {
    agent: agentId,
    bid: bid,
    time: Date.now(),
    data: data
  };

  const response = await fetch('https://api.ardenstats.com/api/events', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(event)
  });

  return response.json();
}

// Usage
sendTelemetry('my-js-agent', 1000, { task: 'code_generation' });
```

### Go

```go
package main

import (
    "bytes"
    "encoding/json"
    "net/http"
    "time"
)

type Event struct {
    Agent string                 `json:"agent"`
    Bid   int                    `json:"bid"`
    Time  int64                  `json:"time"`
    Data  map[string]interface{} `json:"data"`
}

func sendTelemetry(agentId string, bid int, data map[string]interface{}) error {
    event := Event{
        Agent: agentId,
        Bid:   bid,
        Time:  time.Now().UnixMilli(),
        Data:  data,
    }

    jsonData, _ := json.Marshal(event)
    
    resp, err := http.Post(
        "https://api.ardenstats.com/api/events",
        "application/json",
        bytes.NewBuffer(jsonData),
    )
    
    return err
}
```

## Best Practices

### Agent Naming

* Use descriptive agent IDs: `"my-company.code-reviewer"`
* Keep it consistent across sessions
* Avoid special characters (use hyphens or dots)

### Bid Values

* Use micro-cents (1000 = \$0.01)
* Track actual usage costs when possible
* Be consistent with your pricing model

### Data Payload

* Keep under 1KB total size
* Include relevant context: task type, duration, etc.
* Use flat key-value pairs for better analytics

### Error Handling

* Always check response status
* Retry on network failures
* Log errors for debugging

## Common Integration Patterns

### Wrapper Function

Create a utility function for your application:

```bash
#!/bin/bash
# my-agent-wrapper.sh
MY_AGENT_ID="my-company.custom-agent"

# Run your agent
python my_agent.py "$@"

# Send telemetry after completion
arden events send --agent "$MY_AGENT_ID" --bid 1000 --data "{\"args\": \"$*\"}"
```

### Process Monitoring

Track long-running processes:

```bash
# Start event
arden events send --agent "long-runner" --bid 0 --data '{"status": "started"}'

# Your long process
./my-long-process.sh

# End event
arden events send --agent "long-runner" --bid 2000 --data '{"status": "completed"}'
```

## Testing Your Integration

Use dry-run mode to test without sending real events:

```bash
arden events send --agent "test-agent" --bid 1000 --dry-run
```

View the leaderboard to confirm your events are being tracked:

```bash
arden agents leaderboard
```

## Troubleshooting

**Events not appearing?**

* Check agent ID format (alphanumeric with optional prefix)
* Verify network connectivity
* Use `--dry-run --print` to debug payload

**Rate limiting?**

* Batch events when possible (max 100 per request)
* Add delays between requests
* Use exponential backoff for retries

**Authentication issues?**

* Set `ARDEN_API_TOKEN` environment variable
* Check token validity
* Verify API endpoint URL