API documentation

Base URL: https://h-scope.xr-utilities.ai

All endpoints return JSON. A scan costs $0.10 via the x402 protocol; the showroom scan on this site is free and abuse-gated. The engine reads the address from public chain infrastructure, runs a shared catalog of behavioral signals, scores two deterministic axes, and returns AI-written advisory reasoning over that result.

POST /scan

Scan an on-chain address and return its behavioral signals, entity-posture classification, and reasoning. Requires an x402 payment header; without one the server responds with 402 Payment Required and a payment options envelope.

Headers

X-Payment: <x402 envelope (base64)>
Content-Type: application/json

Request body

{
  "subject": "string (CAIP-10, e.g. eip155:8453:0x... or hedera:mainnet:0.0.x)",
  "mode": "pre_auth | standing | full  (optional, default full)",
  "relationshipTo": "string (optional CAIP-10 second address)"
}

Response 200

{
  "subject": "eip155:8453:0x...",
  "activityScore": 0,
  "activityLevel": "Low | Medium | High | Dormant | Unknown",
  "entityPosture": { "score": 0, "tier": "none | minimal | moderate | institutional | core-institutional", "contributors": [] },
  "classification": { "primary": "issuer | exchange | contract | institution | whale | automated | dust-beacon | fresh | dormant | personal | undetermined", "roles": [], "label": "string" },
  "confidence": "low | med | high",
  "signals": [ { "id": "NET_OUTBOUND_SWEEP", "category": "flow", "description": "string" } ],
  "recentActivity": [ { "hash": "string", "direction": "in | out", "assetAmount": "string", "assetSymbol": "string" } ],
  "narrative": { "deterministicGloss": "string", "llmSummary": "string (advisory, only when the LLM tier is enabled)", "provenance": {} }
}

The recent-activity list carries a per-transaction asset amount and symbol across all five chains.

GET /config

Returns the service configuration: the scan price, the supported chains, the accepted x402 payment options per chain, the full signal catalog, and the set of classifications. This is the live contract; treat it as the source of truth.

Signals and scoring

Deterministic signals

Each signal is a pure predicate over a normalized, chain-agnostic feature set, grouped by category (flow, cadence, counterparty, identity, structure, lifecycle, and chain-native markers for the primitives a given ledger has). Signals are descriptive context, never a verdict. The full catalog, with the chains each signal applies to, is served from /config.

Two-axis result and reasoning

The signals reduce to two reproducible axes (an activity level and an entity-posture tier), each a fixed function of the fired signals, so a scan is reproducible from the same on-chain data. An AI model then writes advisory reasoning over that deterministic result; it narrates the facts and never invents or overrides a score. Other H-Series products pull the posture tier at their own trust boundary, and H-Scope emits an abuse-flag risk signal onto the shared audit topic, where it feeds a subject's H-Cert standing.

On-chain calibration corpus

The entity-posture tiers are calibrated against a labeled corpus of on-chain-verified wallets: hundreds of addresses across all five chains (XRPL, Stellar, Hedera, Base, Solana), at least twelve per archetype per chain, spanning the whale, exchange, treasury, issuer, real-world-asset (RWA), institutional, and automated-agent (bot) classes. Each label is a descriptive behavioral descriptor, never a risk, compliance, or sanctions verdict.

The corpus is anchored to a dedicated Hedera Consensus Service topic (0.0.10631992) as immutable, operator-signed, versioned per-chain snapshots (message kind h-scope.corpus-snapshot). This makes the calibration tamper-evident, timestamped, and reconstructible from a public mirror replay, so it survives the operator; it was previously a repo-only asset. Each snapshot carries a change summary (added, removed, reclassified), so the topic is a self-documenting on-chain audit trail. Publishing is autonomous: the service self-anchors a new version when the corpus changes on a deploy.

A weekly ingest keeps labels current by pulling public attribution directories (the MIT-licensed stellar.expert directory and XRPScan well-known), verifying every candidate on chain before adding it and never adopting a third-party verdict. The abuse (scam) class is deliberately never anchored, only counted: an operator-signed, immutable, public abuse label is a liability the neutral roles do not carry.

MCP tools

H-Scope is also exposed as MCP tools (namespace h_scope_*) through the shared H-Series MCP server at https://mcp.xr-utilities.ai/mcp. An agent can call the scan directly from its tool interface, with the same x402 payment and settlement re-verified on chain.

Payment

Payment for a scan is handled via the x402 protocol. When a client sends a scan request without payment, the server responds with 402 Payment Required and a payment options envelope listing the accepted stablecoin rails. The client selects a method, constructs a signed payment, and resubmits with an X-Payment header containing the base64-encoded x402 envelope. Every settlement is re-verified on chain; the facilitator is never trusted.