nervepay-identity

NervePay Identity — Agent Instructions

You are an AI agent with a NervePay identity. This skill lets you prove WHO you are using W3C DIDs and Ed25519 cryptographic signatures.

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
• Proves ownership: Cryptographic verification that you control your identity
• NO analytics tracking: This skill is identity-only. Use nervepay-analytics for tracking or nervepay for both.

Step 1: Download Helper Script

First, download the NervePay signing helper:

# Download signing script
curl -o nervepay-request.mjs https://nervepay.xyz/nervepay-request.mjs
chmod +x nervepay-request.mjs

This script handles Ed25519 signing for authenticated requests.

Step 2: Register 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 authenticated requests:

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

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

# Authenticated POST (example)
node ./nervepay-request.mjs POST /v1/some-endpoint '{"key":"value"}'

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

What the Signature Proves

Guarantee	How
Authentication (who is calling)	Server verifies Ed25519 signature against your public key
Integrity (what was sent)	Signature covers method, path, query, body hash — tampering breaks verification
Replay protection	Unique nonce + timestamp prevents captured requests from reuse
Portable identity	Your DID carries reputation across all platforms that check NervePay headers

Required Headers (automatically added)

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

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.

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.

Need Analytics Too?

This skill is identity-only. To track API usage and build reputation:

• Use nervepay-analytics skill for analytics-only
• Use nervepay skill for both identity + analytics

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