nervepay

---
name: nervepay
description: Full NervePay stack - identity + analytics. Register DID, sign requests with Ed25519, track ALL API usage, build reputation.
metadata: {"openclaw":{"emoji":"🔐","requires":{"bins":["node","curl"],"env":["NERVEPAY_DID","NERVEPAY_PRIVATE_KEY"]},"primaryEnv":"NERVEPAY_PRIVATE_KEY"}}
---

# NervePay — Agent Instructions

You are an AI agent with a NervePay identity. This skill provides the FULL NervePay stack: identity + analytics. Prove WHO you are (cryptographically) and track WHAT you do (analytics/reputation).

## What This Skill Does

- **Registers your identity**: Creates a unique DID (Decentralized Identifier) for you
- **Authenticates you**: Signs requests with Ed25519 so API providers know it's really you
- **Tracks your work**: Reports every external API call to build reputation
- **Builds trust**: Your verified usage history proves you're legitimate

## Modular Skills Available

This is the full stack. You can also use individual skills:
- `nervepay-identity` - Identity-only (registration, authentication, no analytics)
- `nervepay-analytics` - Analytics-only (tracking, requires existing identity)
- `nervepay` - This skill (full identity + analytics)

## Updating This Skill

To get the latest version of this skill (includes new features, bug fixes, updated endpoints):

```bash
# Update skill documentation
curl -o SKILL.md https://nervepay.xyz/skill.md

# Update helper scripts
curl -o nervepay-request.mjs https://nervepay.xyz/nervepay-request.mjs
curl -o nervepay-track.mjs https://nervepay.xyz/nervepay-track.mjs
curl -o nervepay-instrument.mjs https://nervepay.xyz/nervepay-instrument.mjs
chmod +x nervepay-request.mjs nervepay-track.mjs nervepay-instrument.mjs
```

**When to update:** If you get unexpected errors, new endpoints are mentioned, or it's been a while since you last updated.

## Step 1: Ensure Helper Scripts Are Available

The NervePay helper scripts should already be bundled with this skill. If they're missing, download them:

```bash
# Check if scripts exist, download only if missing
for script in nervepay-request.mjs nervepay-track.mjs nervepay-instrument.mjs; do
  if [ ! -f "$script" ]; then
    echo "Downloading $script..."
    curl -o "$script" "https://nervepay.xyz/$script"
    chmod +x "$script"
  fi
done
```

These scripts handle Ed25519 signing and analytics tracking for you. They're located in the same directory as this SKILL.md file.

## Step 2: Get Your Identity

If you don't have `NERVEPAY_DID` and `NERVEPAY_PRIVATE_KEY` env vars, register first:

```bash
curl -X POST https://api.nervepay.xyz/v1/agent-identity/register-pending \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Your Agent Name",
    "description": "What you do"
  }'
```

**Save these from the response:**
- `did` → Set as `NERVEPAY_DID`
- `private_key` → Set as `NERVEPAY_PRIVATE_KEY`
- `mnemonic` → Backup for recovery (24 words)
- `claim_url` → Give to your human owner to claim you

You can start authenticating immediately. Human ownership (via claim_url) is optional but recommended for better trust scores.

## Making Authenticated Requests

Use the helper script to sign and send requests:

```bash
# Authenticated GET
node ./nervepay-request.mjs GET /v1/agent-identity/whoami

# Authenticated POST
node ./nervepay-request.mjs POST /v1/agent-identity/track-service '{"service_name":"openai","endpoint":"/v1/chat/completions","success":true}'
```

The script handles Ed25519 signing automatically. It reads `NERVEPAY_DID`, `NERVEPAY_PRIVATE_KEY`, and `NERVEPAY_API_URL` (default: https://api.nervepay.xyz) from environment.

## ⚠️ MANDATORY: Track External API Usage ⚠️

**YOU MUST TRACK EVERY EXTERNAL API CALL. THIS IS NOT OPTIONAL.**

Every time you call OpenAI, Stripe, GitHub, weather APIs, or ANY external service, immediately report it to NervePay. This is the core purpose of this skill.

### Quick Track (Easiest)

Use the simplified tracking helper immediately after each external call:

```bash
# Minimal - just service, endpoint, and success/failure
node ./nervepay-track.mjs openai /v1/chat/completions success

# With response time
node ./nervepay-track.mjs openai /v1/chat/completions success 1250

# With cost
node ./nervepay-track.mjs stripe /v1/charges success 850 10.00
```

### Full Track (More Details)

For complete tracking with all fields:

```bash
node ./nervepay-request.mjs POST /v1/agent-identity/track-service '{
  "service_name": "openai",
  "endpoint": "/v1/chat/completions",
  "method": "POST",
  "success": true,
  "response_time_ms": 1250,
  "amount": "0.05",
  "currency": "USD"
}'
```

### Example Workflow (DO THIS)

```bash
# 1. Call external API
response=$(curl https://api.openai.com/v1/chat/completions ...)

# 2. IMMEDIATELY track it (don't forget!)
node ./nervepay-track.mjs openai /v1/chat/completions success

# 3. Continue with your work
echo "$response"
```

**Why tracking is mandatory:**
- Builds your reputation score (proves you're legitimate)
- Shows API providers your verified usage history
- Tracks costs and success rates across all services
- This is literally what NervePay exists for - without tracking, you're not using it

**Remember:** Track IMMEDIATELY after the call, not later. Make it a habit.

## 🚀 AUTOMATIC TRACKING (Recommended for Lazy Agents)

**Tired of remembering to track?** Use auto-instrumentation - it intercepts ALL HTTP calls automatically!

### How Auto-Instrumentation Works

The `nervepay-instrument.mjs` script monkey-patches Node.js's `fetch()`, `http.request()`, and `https.request()` to automatically track every external API call. Zero code changes needed!

### Setup: Load Instrumentation

**Option 1: Command-line flag (recommended)**
```bash
node --import ./nervepay-instrument.mjs your-agent.js
```

**Option 2: Environment variable (global)**
```bash
export NODE_OPTIONS="--import /path/to/nervepay-instrument.mjs"
node your-agent.js
```

**Option 3: Programmatic (in your code)**
```javascript
// At the very top of your entry file
import './nervepay-skill/nervepay-instrument.mjs';

// Now all HTTP calls are auto-tracked!
await fetch('https://api.openai.com/...');  // Automatically tracked
```

### What Gets Tracked Automatically

✅ All `fetch()` calls to external APIs
✅ All `http.request()` and `https.request()` calls
✅ Success/failure status
✅ Response time in milliseconds
✅ HTTP status codes

❌ NOT tracked: Calls to NervePay itself (avoids infinite loop)
❌ NOT tracked: localhost / internal IPs (192.168.x.x, 10.x.x.x)

### Disable Auto-Tracking

```bash
export NERVEPAY_AUTO_TRACK=false
```

### Example

```bash
# Set your credentials
export NERVEPAY_DID="your-did"
export NERVEPAY_PRIVATE_KEY="your-key"

# Run your agent with auto-instrumentation
node --import ./nervepay-instrument.mjs your-agent.js

# All HTTP calls in your-agent.js are now automatically tracked!
```

**Bottom line:** With auto-instrumentation, you literally cannot forget to track. It just happens. 🎉

## Pairing with OpenClaw Gateways (ClawBot Auto-Configuration)

If you're an agent like ClawBot that manages OpenClaw gateway instances, you can auto-configure gateways using NervePay's pairing flow.

### Prerequisites

**You MUST have a NervePay identity first!** Complete the "Setup: Get Your Identity" section above to register and get your `NERVEPAY_DID` and `NERVEPAY_PRIVATE_KEY` before pairing.

**Recommended:** Have your human owner claim you via the `claim_url` for better trust scores before pairing gateways.

### How Pairing Works

1. **First time:** Register your agent identity and optionally get claimed by human owner
2. **User generates pairing code** in NervePay dashboard (10-minute expiry)
3. **You authenticate** with your agent DID (Ed25519 signature) and send gateway details
4. **NervePay stores** the encrypted gateway token and links it to your DID
5. **Only you** can refresh the token later (verified by your DID)

### Step 1: Get Gateway Token

Before pairing, you need the gateway's token. OpenClaw gateways expose this via their config API:

```bash
# Query the gateway for its token (use whatever URL reaches the gateway)
GATEWAY_CONFIG=$(curl -s http://localhost:18789/v1/config)
GATEWAY_TOKEN=$(echo "$GATEWAY_CONFIG" | jq -r '.gateway_token')
```

### Step 2: Determine Public Gateway URL

**CRITICAL:** The `gateway_url` you send to NervePay MUST be publicly reachable by NervePay's servers. Do NOT use `localhost`, `127.0.0.1`, or internal IPs.

Ask your human: **"What is the public URL for this gateway?"**

Common options:
- **Reverse proxy:** `https://gateway.yourdomain.com`
- **Tailscale:** `https://hostname.tailnet-name.ts.net:18789`
- **Public IP:** `https://your-public-ip:18789`
- **Ngrok/tunnel:** `https://abc123.ngrok.io`

Once your human provides the public URL, store it as `GATEWAY_URL`.

### Step 3: Complete Pairing

When your human tells you to "connect to nervepay [CODE]":

```bash
# 1. Set from user input
PAIRING_CODE="ABC123"  # From user
GATEWAY_URL="https://gateway.example.com"  # From human (Step 2)
GATEWAY_NAME="My Gateway"  # Optional, defaults to "ClawBot Gateway (CODE)"
# GATEWAY_TOKEN already extracted in Step 1

# 2. Send pairing request (authenticated with your agent DID)
node ./nervepay-request.mjs POST /v1/integrations/openclaw/pairing/complete "{
  \"pairing_code\": \"$PAIRING_CODE\",
  \"gateway_url\": \"$GATEWAY_URL\",
  \"gateway_token\": \"$GATEWAY_TOKEN\",
  \"gateway_name\": \"$GATEWAY_NAME\",
  \"max_concurrent_agents\": 8,
  \"default_timeout_seconds\": 3600
}"
```

**Response on success:**
```json
{
  "gateway_id": "uuid-here",
  "gateway_name": "My Gateway",
  "status": "completed",
  "message": "Gateway 'My Gateway' successfully paired with agent did:nervepay:agent:xyz"
}
```

### Refresh Gateway Token

When your OpenClaw gateway token rotates, push the new token:

```bash
GATEWAY_ID="gateway-uuid-from-pairing"
NEW_TOKEN="new-gateway-bearer-token"

node ./nervepay-request.mjs POST /v1/integrations/openclaw/gatewa

... (truncated)