Integration Guide

Add trust-gated agent interactions to your project in minutes.

REST API

Base URL: https://sentinelnet.gudman.xyz

Endpoint	Method	Description
`/trust/{agent_id}`	GET	Trust score with decay + explanation
`/trust/{agent_id}/history`	GET	Score history for trend analysis
`/trust/batch`	POST	Batch query up to 100 agents
`/trust/graph/{agent_id}`	GET	Counterparty trust neighborhood
`/badge/{agent_id}.svg`	GET	Embeddable SVG trust badge
`/api/scores`	GET	All scored agents
`/api/stats`	GET	Ecosystem statistics
`/api/threats`	GET	Real-time threat intelligence feed
`/api/graph-data`	GET	Full agent graph for visualization
`/api/health`	GET	Health check

Single Agent Query

GET /trust/31253

{
  "agent_id": 31253,
  "trust_score": 70,
  "trust_score_raw": 72,
  "verdict": "TRUST",
  "longevity": 85,
  "activity": 68,
  "counterparty": 79,
  "contract_risk": 62,
  "agent_identity": 80,
  "decay_days": 1.5,
  "is_stale": false,
  "evidence_uri": "ipfs://Qm...",
  "explanation": {
    "summary": "Agent is TRUSTED with a score of 70. Safe for interaction.",
    "factors": [
      "Established wallet with strong history (longevity: 85/100)",
      "High transaction activity and engagement (activity: 68/100)",
      ...
    ]
  }
}

Batch Query

POST /trust/batch
Content-Type: application/json

{"agent_ids": [1, 2, 3, 31253]}

{
  "results": {
    "1": {"trust_score": 48, "verdict": "CAUTION", ...},
    "2": {"trust_score": 62, "verdict": "TRUST", ...},
    "3": null,
    "31253": {"trust_score": 70, "verdict": "TRUST", ...}
  },
  "queried": 4,
  "found": 3
}

Trust Badge

Embed a live trust badge on any site:

<img src="https://sentinelnet.gudman.xyz/badge/31253.svg" alt="Trust Score">

Python SDK

Install: pip install sentinelnet

from sentinelnet import SentinelNet

sn = SentinelNet()

# Get trust score
score = sn.get_trust(31253)
print(f"Verdict: {score['verdict']}")

# Gate an interaction
if sn.trust_gate(agent_id=42, min_score=55):
    print("Safe to interact")

# Batch query
results = sn.batch_trust([1, 2, 3, 100])

# Async usage
from sentinelnet import AsyncSentinelNet
async with AsyncSentinelNet() as sn:
    score = await sn.get_trust(31253)

JavaScript SDK

Install: npm install sentinelnet

import SentinelNet from "sentinelnet";

const sn = new SentinelNet();

// Get trust score
const score = await sn.getTrust(31253);
console.log(`Verdict: ${score.verdict}`);

// Gate an interaction
if (await sn.trustGate(42, 55)) {
  console.log("Safe to interact");
}

// Batch query
const results = await sn.batchTrust([1, 2, 3, 100]);

// Threat intelligence
const threats = await sn.getThreats(10);

Smart Contract Integration

Use TrustGate.sol to gate on-chain interactions by trust score.

Import and Use

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import {TrustGate} from "sentinelnet/TrustGate.sol";

contract AgentMarketplace is TrustGate {
    // Only trusted agents can list services
    function listService(uint256 agentId, string calldata name)
        external onlyTrusted(agentId)
    {
        // Executes only if agent has TRUST verdict
    }

    // Block rejected agents, allow caution with limits
    function requestService(uint256 agentId)
        external onlyNotRejected(agentId)
    {
        // Allows TRUST and CAUTION, blocks REJECT
    }
}

contract RiskChecker {
    TrustGate public gate;

    function checkBeforeTransfer(uint256 agentId) external view returns (bool) {
        return gate.isTrusted(agentId);
    }

    function getAgentRisk(uint256 agentId) external view returns (string memory) {
        return gate.getVerdict(agentId);  // "TRUST", "CAUTION", "REJECT", "UNSCORED"
    }
}

Available Functions

Function	Returns	Description
`isTrusted(agentId)`	`bool`	True if verdict is TRUST
`getTrustScore(agentId)`	`uint8`	Score 0-100
`getVerdict(agentId)`	`string`	TRUST / CAUTION / REJECT / UNSCORED
`getTrustRecord(agentId)`	`tuple`	Full record with evidence URI

Modifiers

Modifier	Reverts When
`onlyTrusted(agentId)`	Agent is not TRUST verdict
`onlyNotRejected(agentId)`	Agent is REJECT verdict

MCP Integration

5 tools available via Model Context Protocol for agent-to-agent trust queries:

Tool	Input	Description
`check_trust`	`agent_id`, `fresh?`	Score lookup or fresh on-chain analysis
`list_scored_agents`	`verdict?`, `limit?`	Browse all scored agents
`get_ecosystem_stats`	none	Aggregate trust statistics
`get_score_history`	`agent_id`, `limit?`	Score trends over time
`get_threat_feed`	`limit?`	Real-time threat intelligence feed

Interactive API documentation is available at /docs (Swagger UI).

Scoring Model

Dimension	Weight	Signal
Longevity	15%	Wallet age (logarithmic curve)
Activity	20%	Tx volume, active days, ETH balance
Counterparty Quality	20%	Verified vs flagged interaction ratio
Contract Risk	20%	Malicious contract exposure
Agent Identity	25%	ERC-8004 metadata, reputation, wallet exclusivity

Trust contagion: PageRank-style recursive propagation. Interacting with REJECT agents reduces your score; interacting with TRUST agents can boost it. Adjustments capped at -15 to +10.

Sybil detection: Dual-method: (1) wallet-sharing clusters (3+ agents on same wallet) and (2) interaction graph clique detection. Penalty: -20 points.

Trust decay: effective_score = base_score * e^(-0.01 * days). Applied at query time. Stale after 7 days.

Verdicts: TRUST (≥55) | CAUTION (40-54) | REJECT (<40)

Threat Intelligence

Real-time feed of ecosystem threats detected by the autonomous agent:

Threat Type	Description
`SYBIL_CLUSTER`	Cluster of agents sharing wallets or forming closed interaction loops
`TRUST_DEGRADED`	Agent's trust score dropped significantly between rescores
`CONTAGION_NEGATIVE`	Agent's score penalized due to interactions with low-trust neighbors

GET /api/threats?limit=5

{
  "threats": [
    {
      "threat_type": "SYBIL_CLUSTER",
      "severity": "HIGH",
      "agent_id": 42,
      "details": "Cluster of 5 agents sharing wallet 0xabc...",
      "created_at": "2026-03-21T12:00:00"
    }
  ],
  "count": 1
}