Integration Guide

Combine Agent Authentication with x402 Payments for a complete agent economy solution

Complete Solution

NervePay provides two complementary solutions that work seamlessly together: Agent Passport authentication for identity verification, and x402 payments for API monetization. Use them independently or combine them for a full-featured agent economy platform.

Use Cases

Authentication Only

Use Agent Passport authentication without payments. Perfect for internal APIs, free tiers, or when you handle payments separately.

Example: Free weather API with rate limits per agent passport

Payments Only

Use x402 payments with traditional API keys. Great for existing systems adding payment support.

Example: Legacy API adding micropayments via x402 protocol

Combined (Recommended)

Agent authenticates with passport, then pays for API calls. Full security + monetization.

Example: Premium AI service with per-call pricing and agent identity

Combined Authentication + Payment Flow

Agent Gets Passport

Developer creates agent passport in dashboard, receives passport ID and Ed25519 keypair

POST /v1/agent-identity/register
→ Returns: passport_id + private_key

Agent Makes Authenticated Request

Agent signs request with Ed25519 key, includes signature in headers

GET /v1/agents/weather-bot/forecast?city=SF
Agent-Passport: <passport_id>
X-Agent-Signature: <base64-signature>
X-Agent-Nonce: <uuid>
X-Signature-Timestamp: 2026-02-03T10:00:00Z

Server Returns 402 Payment Required

After verifying agent signature, server requests payment

402 Payment Required
{ "accepts": [{ "amount": "0.10", "currency": "USDC", ... }] }

Agent Pays and Retries

Agent signs payment, includes both auth and payment signatures

GET /v1/agents/weather-bot/forecast?city=SF
Agent-Passport: <passport_id>
X-Agent-Signature: <auth-signature>
PAYMENT-SIGNATURE: <payment-signature>

Server Verifies and Responds

Server verifies both signatures, settles payment, returns resource with agent reputation

200 OK + PAYMENT-RESPONSE header
{ "temperature": 72, "conditions": "sunny", "payer_agent": { "passport": "<passport_id>", "reputation_score": 87.5 } }

Reputation Updated

Agent's transaction counters and reputation score automatically updated

agent_identities: total_transactions++, successful_transactions++
reputation_score: recalculated (70% attestations + 30% success rate)
transactions: linked to agent passport for full audit trail

⭐

Automatic Reputation Tracking

When agents pay using their passport signature, every transaction is linked to their identity and their reputation score is automatically updated based on payment success rate.

What's Tracked

• Total transactions count
• Successful transactions count
• Payment success rate
• Reputation score (0-100)
• Transaction history with passport

Reputation Formula

70% attestations + 30% success rate

Agents with higher reputation can be granted higher transaction limits, priority access, or discounted rates in future features.

Python Example

python

1import json
2import base64
3import uuid
4from datetime import datetime
5from nacl.signing import SigningKey
6import requests
7
8# Agent credentials
9AGENT_PASSPORT = "<passport_id>"
10PRIVATE_KEY_BASE58 = "..."  # From registration
11
12# 1. Sign authentication payload
13def sign_request(method, path):
14    nonce = str(uuid.uuid4())
15    timestamp = datetime.utcnow().isoformat() + "Z"
16
17    payload = {
18        "method": method,
19        "path": path,
20        "nonce": nonce,
21        "timestamp": timestamp,
22        "agent_passport": AGENT_PASSPORT
23    }
24
25    # Sign with Ed25519
26    signing_key = SigningKey(base58.b58decode(PRIVATE_KEY_BASE58))
27    message = json.dumps(payload, separators=(',', ':')).encode()
28    signature = signing_key.sign(message).signature
29
30    return {
31        "Agent-Passport": AGENT_PASSPORT,
32        "X-Agent-Signature": base64.b64encode(signature).decode(),
33        "X-Agent-Nonce": nonce,
34        "X-Signature-Timestamp": timestamp
35    }
36
37# 2. Make authenticated request
38headers = sign_request("GET", "/v1/agents/weather-bot/forecast")
39response = requests.get(
40    "https://api.nervepay.xyz/v1/agents/weather-bot/forecast?city=SF",
41    headers=headers
42)
43
44if response.status_code == 402:
45    # 3. Handle payment required
46    payment_details = response.json()
47
48    # Sign payment with facilitator
49    payment_sig = sign_payment(payment_details)
50
51    # 4. Retry with payment
52    headers["PAYMENT-SIGNATURE"] = payment_sig
53    response = requests.get(
54        "https://api.nervepay.xyz/v1/agents/weather-bot/forecast?city=SF",
55        headers=headers
56    )
57
58print(response.json())  # Weather data

Benefits of Combined Approach

Enhanced Security

Two-factor verification: cryptographic identity + payment proof

Full Audit Trail

Know WHO paid (agent passport) and HOW MUCH for every API call

Flexible Monetization

Different prices for different agents based on reputation or tier

Fraud Prevention

Agent identity tied to payments - easier to detect and block bad actors

Analytics

Track usage patterns per agent, identify power users, optimize pricing

Compliance

Complete transaction history with verified agent identities for audits

Get Started

1. Create Agent Passport

Issue your first agent passport with cryptographic authentication

2. Set Up Payment Agent

Configure endpoints and pricing for x402 payments

3. Check API Reference

Complete documentation for both authentication and payments