Nervepay

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):

# 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:

# 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:

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:

# 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:

# 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:

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)

# 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)

node --import ./nervepay-instrument.mjs your-agent.js

Option 2: Environment variable (global)

export NODE_OPTIONS="--import /path/to/nervepay-instrument.mjs"
node your-agent.js

Option 3: Programmatic (in your code)

// 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

export NERVEPAY_AUTO_TRACK=false

Example

# 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:

# 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]":

# 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:

{
  "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:

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

node ./nervepay-request.mjs POST /v1/integrations/openclaw/gateways/$GATEWAY_ID/refresh-token '{
  "new_token": "'$NEW_TOKEN'"
}'

Security: NervePay verifies you're the agent that originally paired the gateway (checks linked_agent_did). Only you can refresh this gateway's token.

Why Pairing?

• Zero manual setup for users (just give them a code)
• Cryptographic auth proves you control the gateway
• Token encryption keeps gateway credentials secure (AES-256-GCM)
• Auto-expiration detection if gateway returns 401, NervePay marks token as expired
• Trust: Your verified DID proves the gateway is managed by you

Managing Agent Secrets (Secure Vault)

Your human owner can configure secrets for you in the NervePay dashboard (like API keys, credentials, tokens). You can then securely retrieve these secrets when you need them - perfect for storing OpenAI keys, database passwords, or any sensitive credentials.

How the Vault Works

• Per-agent isolation: Each agent only sees its own secrets (verified by your DID signature)
• Envelope encryption: Secrets are encrypted at rest using AES-256-GCM
• Audit logging: Every secret access is logged for security
• Environment support: Secrets can be scoped to production, development, or staging

Retrieve a Secret by Name

The most common operation - get a specific secret by its name:

# Get your OpenAI API key
node ./nervepay-request.mjs GET /v1/vault/secrets/OPENAI_API_KEY

# Get your database password
node ./nervepay-request.mjs GET /v1/vault/secrets/DATABASE_PASSWORD

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "OPENAI_API_KEY",
  "value": "sk-abc123...",
  "description": "OpenAI API key for production",
  "provider": "openai",
  "environment": "production",
  "created_at": "2026-02-05T12:00:00Z",
  "updated_at": "2026-02-05T12:00:00Z",
  "expires_at": null
}

Usage in your workflow:

# 1. Retrieve your OpenAI key
response=$(node ./nervepay-request.mjs GET /v1/vault/secrets/OPENAI_API_KEY)
OPENAI_KEY=$(echo "$response" | jq -r '.value')

# 2. Use it in your API call
curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_KEY" \
  -d '{"model":"gpt-4","messages":[...]}'

# 3. Track the usage (mandatory!)
node ./nervepay-track.mjs openai /v1/chat/completions success

List All Your Secrets

See all secrets configured for you (values are NOT included in list view for security):

node ./nervepay-request.mjs GET /v1/vault/secrets

Response:

{
  "secrets": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "OPENAI_API_KEY",
      "description": "OpenAI API key for production",
      "provider": "openai",
      "environment": "production",
      "created_at": "2026-02-05T12:00:00Z",
      "updated_at": "2026-02-05T12:00:00Z",
      "expires_at": null
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "STRIPE_SECRET_KEY",
      "description": "Stripe secret key",
      "provider": "stripe",
      "environment": "production",
      "created_at": "2026-02-05T12:00:00Z",
      "updated_at": "2026-02-05T12:00:00Z",
      "expires_at": null
    }
  ]
}

Filter by Environment

# Only production secrets
node ./nervepay-request.mjs GET '/v1/vault/secrets?environment=production'

# Only development secrets
node ./nervepay-request.mjs GET '/v1/vault/secrets?environment=development'

Filter by Provider

# Only OpenAI secrets
node ./nervepay-request.mjs GET '/v1/vault/secrets?provider=openai'

# Only Stripe secrets
node ./nervepay-request.mjs GET '/v1/vault/secrets?provider=stripe'

When Secrets Are Missing

If you try to access a secret that doesn't exist:

node ./nervepay-request.mjs GET /v1/vault/secrets/NONEXISTENT_KEY

Response (404):

{
  "error": "Secret not found",
  "message": "Secret 'NONEXISTENT_KEY' not found for agent did:nervepay:agent:abc123xyz"
}

What to do: Ask your human owner to create the secret in the NervePay dashboard at https://nervepay.xyz/dashboard/agent-identities

Security Notes

• Your human configures secrets: You cannot create/update/delete secrets yourself - only retrieve them. This prevents compromised agents from modifying credentials.
• Dashboard-only management: Secrets are created and updated in the NervePay dashboard by your human owner.
• Signature required: Every secret retrieval requires Ed25519 signature authentication.
• Audit trail: Every access is logged with timestamp, IP, and success/failure.
• Expiration support: Secrets can have expiration dates - expired secrets return 410 Gone.

Common Secret Names (Conventions)

Use these naming conventions for consistency:

Common Commands

Test authentication

node ./nervepay-request.mjs GET /v1/agent-identity/whoami

Returns your DID, name, reputation score, and confirms authentication works.

Check your capabilities

node ./nervepay-request.mjs GET /v1/agent-identity/capabilities

Shows your spending limits, allowed operations, and permissions.

Verify another agent

curl "https://api.nervepay.xyz/v1/agent-identity/verify/did:nervepay:agent:abc123xyz"

No auth required. Returns public profile, reputation, and transaction stats for any agent.

Poll claim status (check if human claimed you)

curl "https://api.nervepay.xyz/v1/agent-identity/register-pending/SESSION_ID/status"

Returns: pending, claimed, expired, or revoked.

What the Signature Proves

Required Headers (already handled by script)

The helper script adds these automatically:

• Agent-DID: Your DID
• X-Agent-Signature: Base64-encoded Ed25519 signature
• X-Agent-Nonce: Unique nonce (UUID)
• X-Signature-Timestamp: ISO 8601 timestamp

Security Notes

• Private key: NEVER send to any server. Only send signatures.
• Nonces: Single-use. Generate new for each request (script handles this).
• Timestamps: Must be within 5 minutes of server time.
• Mnemonic: 24-word backup phrase. Store securely offline.

Modular Skills (Choose What You Need)

This skill provides the full NervePay stack. If you only need part of it:

• nervepay-identity - Identity-only (registration, authentication, no tracking)

  • Use when: You only need cryptographic authentication
  • Downloads: nervepay-request.mjs

• nervepay-analytics - Analytics-only (tracking, requires existing identity)

  • Use when: You already have an identity and just want tracking
  • Downloads: nervepay-request.mjs, nervepay-track.mjs, nervepay-instrument.mjs

• nervepay - Full stack (this skill - identity + analytics)

  • Use when: You want everything
  • Downloads: All three scripts

Full API Reference

For complete endpoint documentation, error codes, and advanced usage, see:

• Online: https://nervepay.xyz/docs
• Download API reference: curl -o api.md https://nervepay.xyz/api.md

API Base: https://api.nervepay.xyz/v1 Docs: https://nervepay.xyz/docs GitHub: https://github.com/nervepay/nervepay