REPUTATION API

Quick Start

curl -H "Authorization: Bearer ds_YOUR_KEY" \
  https://denscope.vercel.app/api/v1/agent/42220/5/score

Get your API key from the Console → API Keys section.

Start with SDK

Prefer TypeScript? Use @denlabs/trust-sdk to query the same trust data used by the portal. It supports both API keys and x402 payment mode.

Repo: github.com/den-labs/trust-sdk

Example: examples/get-score.mjs

x402 Example: examples/get-score-x402.mjs

Install

pnpm add @denlabs/trust-sdk

# For x402 payment mode (optional)
pnpm add viem

Local SDK repo example (after cloning): DENSCOPE_API_KEY=ds_xxx pnpm example:get-score

Local x402 example: DENSCOPE_PRIVATE_KEY=0x... pnpm example:get-score:x402

API Key Example

import { DenScope } from '@denlabs/trust-sdk'

const ds = new DenScope({ apiKey: 'ds_...' })

const { score } = await ds.getScore(42220, 5)
console.log(score.value, score.confidence)

const { signals } = await ds.getSignals(42220, 5, { status: 'open' })
const { agents } = await ds.search({ q: '0xabc', chainId: 42220, limit: 5 })

x402 Example (wallet/agent)

import { DenScope } from '@denlabs/trust-sdk'
import { privateKeyToAccount } from 'viem/accounts'

const account = privateKeyToAccount('0x...')
const ds = new DenScope({ account })

// SDK handles: 402 -> decode PAYMENT-REQUIRED -> sign -> retry
const { score } = await ds.getScore(42220, 5)
const { signals } = await ds.getSignals(42220, 5)

Error Handling Example

import {
  DenScope,
  DenScopeError,
  AuthenticationError,
  PaymentRequiredError,
} from '@denlabs/trust-sdk'

const ds = new DenScope({ apiKey: process.env.DENSCOPE_API_KEY! })

try {
  const { score } = await ds.getScore(42220, 5)
  console.log(score.value, score.confidence)
} catch (e) {
  if (e instanceof AuthenticationError) {
    console.error('Invalid or disabled API key')
  } else if (e instanceof PaymentRequiredError) {
    console.error('x402 payment required (use wallet mode or X-PAYMENT flow)')
  } else if (e instanceof DenScopeError) {
    console.error('Denscope API error', e.status, e.body)
  } else {
    console.error('Unexpected error', e)
  }
}

Interpretation Guide (Portal-Aligned)

The API returns raw score data (value, confidence, feedback stats). In the portal, Denscope maps those fields into semantic states for faster reading.

Note: Semantic labels are UX interpretation helpers. Use raw fields for strict programmatic decisions.

Authentication

Two authentication methods are supported. Use whichever fits your use case:

Option 1: API Key (for developers)

Best for bulk integrations, dashboards, and analytics. Get a key from the Console.

• Authorization: Bearer ds_... (recommended)
• X-API-Key: ds_...

Option 2: x402 Payment (for agents)

Any wallet can query trust data with zero setup. No API key, no account needed. Available on /score and /signals endpoints.

• Call the endpoint without auth → receive HTTP 402 + PAYMENT-REQUIRED header
• Sign an EIP-712 authorization (off-chain, no gas)
• Retry with X-PAYMENT header → receive the data

Rate Limits

Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Endpoints

Trust Evaluation

The /evaluate endpoint goes beyond raw scores. It applies a preset-driven evaluation that returns a structured judgment: trust band, risk level, recommended action, and a human-readable rationale.

Request Body

Presets

Response Schema

The response contains an evaluation object with:

Example Request

curl -X POST https://denscope.vercel.app/api/v1/trust/evaluate \
  -H "Authorization: Bearer ds_..." \
  -H "Content-Type: application/json" \
  -d '{"chainId": 42220, "agentId": 5, "preset": "default_safety"}'

Example Response

{
  "evaluation": {
    "trust_band": "high",
    "status": "active",
    "signal_strength": "strong",
    "risk_level": "minimal",
    "decision_confidence": "high",
    "recommended_action": "allow",
    "flags": [],
    "rationale": "Agent scores 78/100 with high confidence (42 feedbacks, 88% positive). No open incidents. Active within last 3 days. All indicators consistent. Recommended action: allow.",
    "evidence": {
      "score": 78,
      "score_confidence": "high",
      "feedbackCount": 42,
      "positiveRatio": 0.88,
      "openIncidents": 0,
      "lastActivityDays": 3,
      "ageDays": 120
    },
    "preset": "default_safety",
    "evaluatedAt": "2026-03-29T18:30:00Z",
    "chainId": 42220,
    "agentId": 5
  }
}

SDK Example

const result = await ds.evaluate(42220, 5, { preset: 'default_safety' })
console.log(result.evaluation.recommended_action) // "allow"
console.log(result.evaluation.rationale)

Trust Score Formula

The trust score is a transparent, deterministic number between 0 and 100. It updates after every on-chain event.

score = clamp(0, 100, round(
  0.40 * positive_ratio        // positive_count / feedback_count
+ 0.20 * age_score             // min(days_since_first_seen / 90, 1.0)
+ 0.20 * activity_score        // min(feedback_count / (active_days * 2), 1.0)
- 0.10 * incident_penalty      // min(critical*0.15 + warning*0.05, 1.0)
- 0.10 * sybil_penalty         // 1.0 if open sybil_cluster, else 0.0
) * 100)

x402 Payment Flow

The /score and /signals endpoints accept x402 micropayments via the UltravioletaDAO facilitator on Celo. This enables autonomous agents to query trust data without human-managed API keys.

Flow

# 1. Call without auth -> get 402 with payment instructions
curl -i https://denscope.vercel.app/api/v1/agent/42220/5/score
# HTTP/2 402
# PAYMENT-REQUIRED: <base64-encoded JSON>

# 2. Decode PAYMENT-REQUIRED header -> sign EIP-712 off-chain

# 3. Retry with X-PAYMENT header
curl -H "X-PAYMENT: <base64-encoded payment>" \
  https://denscope.vercel.app/api/v1/agent/42220/5/score
# HTTP/2 200 { score: { value: 85, ... } }

Pricing

Details

• Protocol: x402 v2 (HTTP 402 Payment Required)
• Settlement: EIP-3009 TransferWithAuthorization (off-chain signature, no gas for the caller)
• Stablecoin: USDC on Celo (chain ID 42220)
• Facilitator: UltravioletaDAO (facilitator.ultravioletadao.xyz)

Supported Chains

Error Responses