@observer-protocol/sdk

Observer Protocol trust layer for Stripe machine payments and agent-to-agent commerce

Quick Start

Express Middleware (5 lines)

const { ObserverClient } = require('@observer-protocol/sdk');
const observer = new ObserverClient();

// Protect all /api routes with reputation checks
app.use('/api/*', observer.reputationMiddleware({ 
  fallback: 'review',
  policy: 'lenient'  // or 'strict'
}));

Manual Reputation Query (3 lines)

const { ObserverClient } = require('@observer-protocol/sdk');
const observer = new ObserverClient();

const rep = await observer.getReputation('maxi-0001');
console.log(rep.trust_tier, rep.reputation_score);

Installation

npm install @observer-protocol/sdk

Usage

Basic Express Integration

const express = require('express');
const { ObserverClient } = require('@observer-protocol/sdk');

const app = express();
const observer = new ObserverClient();

// Apply middleware
app.use('/api/*', observer.reputationMiddleware());

// Access reputation in your routes
app.post('/api/purchase', (req, res) => {
  const reputation = req.observerReputation;
  
  if (reputation?.trust_tier === 'trusted') {
    // Give discount to trusted agents
    return res.json({ price: 0.5, discount: '50%' });
  }
  
  res.json({ price: 1.0 });
});

Python / FastAPI

from observer_sdk import ObserverClient, require_reputation
from fastapi import FastAPI, Depends

app = FastAPI()
observer = ObserverClient()

# Add middleware
app.middleware("http")(observer.reputation_middleware)

# Require minimum tier
@app.get("/api/premium")
async def premium_data(
    reputation = Depends(require_reputation(min_tier="active"))
):
    return {"data": "premium content", "tier": reputation.trust_tier}

Response Shape

{
  "agent_id": "maxi-0001",
  "verified": true,
  "reputation_score": 0.45,
  "trust_tier": "active",
  "payment_history": {
    "total_verified_events": 20,
    "protocols_used": ["lightning", "x402", "L402"],
    "oldest_event": "2026-02-22",
    "most_recent_event": "2026-03-18",
    "payment_frequency_daily_avg": 0.83
  },
  "risk_signals": {
    "known_bad": false,
    "sudden_volume_spike": false,
    "protocol_diversity_score": 0.75
  },
  "suggested_action": "accept",
  "cache_ttl_seconds": 300
}

Trust Tiers

| Tier | Description | Access Level | |------|-------------|--------------| | unknown | Not registered or no history | Review required | | new | Registered, < 5 payments | Limited rate limits | | active | 5+ payments across 30+ days | Standard access | | established | 20+ payments across 90+ days | Elevated limits | | trusted | 100+ payments, no flags | Premium access |

X-Observer Headers

Agents identify themselves using headers:

X-Observer-Agent-ID: maxi-0001
X-Observer-Signature: 0x3045022100...

The middleware checks these in order:

1. X-Observer-Agent-ID header
2. X-Agent-Wallet header (EVM address)
3. from field in x402 payment proof body

See X-OBSERVER-HEADERS.md for full specification.

Middleware Options

observer.reputationMiddleware({
  fallback: 'review',   // 'accept' | 'review' | 'reject' on error
  policy: 'lenient'     // 'lenient' | 'strict'
})

• fallback: Action when OP API is unavailable
• policy: 'strict' returns 402 for unknown agents; 'lenient' allows through

API Reference

ObserverClient

Constructor

const observer = new ObserverClient({
  apiKey: 'optional',           // For higher rate limits
  baseUrl: 'https://api.agenticterminal.ai'  // Optional override
});

Methods

• getReputation(agentId) - Get reputation by agent ID
• getReputationByWallet(address) - Get reputation by EVM address
• reputationMiddleware(options) - Express middleware factory

Why Observer Protocol?

Portable reputation. One identity works across any seller. Your payment history follows you.

Payment-rail agnostic. Works with Lightning, x402, L402, MPP — whatever the agent uses.

Shared intelligence. Bad actors flagged once, protected everywhere.

Examples

See examples/ for complete integrations:

• stripe-x402-seller.js - Full Express app with tier-based pricing

License

MIT