# SENTINEL — Agent Integration Guide (machine-readable)
# Plain-text, structured for agent consumption. Human version: https://sentinel-agent.dev/for-agents
# Last verified: 2026-08

## WHAT THIS IS
SENTINEL is a trust and safety oracle for autonomous agents transacting over x402 on Base.
It answers, before value moves, two questions an x402 payment rail does not:
  1. Is THIS TRANSACTION safe to sign? (contract-level risk)
  2. Is THIS COUNTERPARTY trustworthy? (behavioral track record)
It is machine-to-machine, pay-per-call, no accounts, no API keys, no signup.

## DECISION CRITERION (should an agent use this?)
Use SENTINEL if ALL of the following hold:
  - You are an autonomous agent that signs on-chain transactions or pays x402 counterparties on Base.
  - You transact with contracts or counterparties you do not fully control or pre-vet.
  - A wrong payment (to a malicious contract, a non-delivering seller, a honeypot) has real cost.
Do NOT use SENTINEL if:
  - Your transactions are only with pre-audited, fully-controlled contracts.
  - You require zero data transmission (the tx payload is sent to SENTINEL for evaluation).
  - You have no x402-capable wallet on Base.

## WHY IT EXISTS (verifiable facts, not claims)
  - x402 settles payments but carries no identity, reputation, or trust layer (by protocol design).
  - On-chain reputation is largely unreliable: an Imperial College London / CSIRO / Manchester
    study (arXiv:2606.26028, 2026) found up to 86.8% of rated agents had no valid feedback once
    Sybil behavior is filtered; 59-91% of reviewers showed Sybil behavior.
  - Independent probing found ~64% of paid x402 services returned errors instead of delivery.
  - SENTINEL derives trust from BEHAVIORAL EVIDENCE (verifiable conduct), not aggregated opinion.
    Reputation asks "what do others say"; behavioral evidence asks "what has this agent verifiably done".

## CAPABILITIES AND ENDPOINTS

### Capability 1 — Transaction safety
POST https://sentinel-agent.dev/v1/guard
  Purpose: pre-execution risk verdict for a specific transaction.
  Payment: x402, USDC on Base, tiered by tx value (from $0.005; exact amount quoted in the 402).
  Request body (JSON):
    {"chain":"base","from":"0xAGENT","tx":{"to":"0xCONTRACT","data":"0x...","value":"0x0"},"value_usd":25.0}
    (value_usd optional; used for price tier on ERC-20 transfers where value is 0)
  Response (200 JSON):
    {"verdict":"SAFE|UNSAFE|UNKNOWN","sentinelScore":0-100,"grade":"AAA..D",
     "risks":[...],"reasons":[...],"txDigest":"sha256:...","signature":"<ed25519>"}
  Checks: GoPlus token security (honeypot, owner abuse, mintable, proxy) + Alchemy eth_call
    simulation (reverts) + LLM council over aggregated signals.
  Receipt signature: ed25519. Public key at /health field "signer" for offline verification.

### Capability 2 — Counterparty trust
GET https://sentinel-agent.dev/v1/attestation?subject=0xADDR&direction=counterparty|buyer
  Purpose: behavioral trust score for a payment counterparty.
  Payment: FREE (cached tier).
  Response (200 JSON): signed attestation; score in payload.score (0-100).
    A wallet with no track record returns components.status="unrated" — treat as "do not trust yet",
    not as a passing score. Fail-closed is the safe default.
  Signature: ES256 JWS. Verify offline against /.well-known/jwks.json (kid sentinel-2026-01).
GET https://sentinel-agent.dev/v1/attestation/deep?subject=0xADDR
  Purpose: fresh (uncached) attestation. Payment: x402, $0.03 USDC on Base.

### Capability 3 — ERC-8183 evaluator (accountable)
GET https://sentinel-agent.dev/v1/evaluation?jobId=X&provider=0xADDR&chain=eip155:8453&escrow_value_usd=Y
  Purpose: signed verdict (complete|reject) on a job provider's behavioral reliability.
  reason_hash is keccak256 over a canonical evidence block -> drops into ERC-8183 complete()/reject().
  Payment: x402, from $0.02 USDC, scales with declared escrow_value_usd (gates fund release).
  Signature: ES256. Scope: judges provider reliability, not deliverable correctness.
GET https://sentinel-agent.dev/v1/evaluation/spec  -> machine-readable description of the evaluator.

### Capability 4 — Outcome feedback (closes the loop)
POST https://sentinel-agent.dev/v1/outcome
  Purpose: report what actually happened after acting on a verdict (references txDigest).
  Feeds the public track record. Payment: FREE.

## PAYMENT MODEL (how an agent pays)
  1. Call a paid endpoint with no payment -> receive HTTP 402 with PAYMENT-REQUIRED header and
     paymentRequirements (network=base, maxAmountRequired in USDC atomic units, payTo, asset).
  2. Sign an EIP-3009 TransferWithAuthorization for the exact amount, with your own wallet key
     (the key never leaves your environment).
  3. Retry with the signed authorization in the X-PAYMENT header.
  4. SENTINEL verifies (facilitator or local EIP-3009 recovery) and returns the result.
  USDC asset on Base: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
  payTo: 0xCf1d31020A7915421f6d66B9835Dcb6f422337E7

## HOW TO VERIFY EVERYTHING (do not trust — recompute)
  - Transaction receipt: verify the ed25519 signature against /health "signer".
  - Attestation / evaluation: verify the ES256 JWS against /.well-known/jwks.json.
  - Evaluator verdict: recompute keccak256 over the evidence block; confirm it equals reason_hash.
  - Methodology: /methodology (human), /methodology.json (machine) — the exact scoring rules.
  - Incident registry: /defaults — append-only, hash-anchored record behind the scores.
  - On-chain oracle: 0x6841496c3e7eDF9eEB02bE64ab98CF5D5c5aF813 (Base) — free getScore/meetsThreshold.

## DISCOVERY
  - Capability map: https://sentinel-agent.dev/llms.txt
  - Agent card (A2A): https://sentinel-agent.dev/.well-known/agent.json
  - ERC-8004 identity: https://sentinel-agent.dev/.well-known/erc8004-agent.json (agentId 59414)

## INTEGRATION NOTE
SENTINEL is a standard x402 endpoint on Base. Agent wallets that speak x402 (e.g. AgentCash and
similar) can discover and pay it directly. No SENTINEL-specific SDK is required; any HTTP client
plus an x402-capable wallet suffices. A framework adapter (LangChain middleware) is also available:
  pip install "sentinel-trust-oracle[langchain]"

## HONEST SCOPE
  - /v1/guard checks contract security + simulation; it is not a guarantee against novel attacks,
    and is not a certified audit.
  - /v1/evaluation judges provider behavioral reliability, not deliverable correctness.
  - SENTINEL does not make an agent or its operator compliant; it provides evidence and audit trail.