Build with observed evidence.

Two distinct data scopes

Choose the interface for your client

Python SDK

The official fet112 package provides a small Python interface for checking the current monitored security environment before an agent acts. It is intentionally narrower than the full REST, MCP and A2A surface.

pip install fet112

from fet112 import pre_action_check

result = pre_action_check(
    "demo-destination",
    action="transfer",
    amount="1",
    asset="FET",
)

print(result.decision)  # CONTINUE, REVIEW, or STOP

fet112 check demo-destination --amount 1 --asset FET

Use the SDK when you want a compact pre-action check. Use REST, MCP or A2A below when you need the complete analytics, evidence, attestation and verification contracts.

REST API

GET/api/v1 returns available operations and schema links. The input and output schemas are available per operation:

GET https://www.fet112.com/api/v1
GET https://www.fet112.com/api/v1/schemas/analytics_query/input
GET https://www.fet112.com/api/v1/schemas/analytics_query/output

Discover metrics and executable examples, then submit a structured query:

POST https://www.fet112.com/api/v1/analytics_catalog
Content-Type: application/json

{}

POST https://www.fet112.com/api/v1/analytics_query
Content-Type: application/json

{
  "metric": "network.tx.count.v1",
  "period": "yesterday"
}

This minimal body is accepted by the current input schema. Optional fields may be normalized by the server; inspect the echoed query in the response. For reproducible requests, set fields such as grain, aggregation, group_by, compare and limit explicitly.

{
  "schema": "fet112.query-result.v1",
  "chain_id": "fetchhub-4",
  "query": { "metric": "network.tx.count.v1", "period": "yesterday", "...": "..." },
  "observed_at": "...UTC timestamp...",
  "measurement": { "metric": "network.tx.count.v1", "unit": "count", "...": "..." },
  "source_cursor": { "height": 0, "block_hash": "...", "age_seconds": 0, "is_fresh": true },
  "coverage": { "schema_version": 1, "semantic_version": 2, "foundation_validated": true },
  "windows": [{
    "period": { "start": "...Z", "end_exclusive": "...Z", "timezone": "UTC" },
    "coverage": { "finalized_buckets": 0, "expected_buckets": 0, "semantic_errors": 0 },
    "rows": [{ "dimensions": {}, "value": "...", "status": "AVAILABLE" }]
  }],
  "integrity": { "signed": true, "context_hash": "sha256:...", "attestation": { "...": "..." } },
  "interpretation": { "statistical_significance": "NOT_EVALUATED", "anomaly_assessment": "NOT_EVALUATED", "security_decision": "NOT_EVALUATED" }
}

This is a field map, not a literal signed response. Exact output fields vary by metric and query; use the published output schema and verify the complete response object.

Common query fields

Native Fetch Network State Attestation

NetworkStateAttestationV1 is a signed snapshot of observed native Fetch state on fetchhub-4. It covers the latest available finalized hour as four local 15-minute buckets: gas used, included/successful/failed transaction counts and block count, together with the actual UTC window, source cursor, coverage, issue time and expiry. The cutoff can lag the current time; this is not a live chain query.

REST: request and verify

Request the current signed document with an empty object. To verify the exact object, send it intact and supply a trusted fingerprint obtained independently; key discovery from the same server is not an independent trust anchor.

POST https://www.fet112.com/api/v1/network_state_attestation
Content-Type: application/json

{}

Illustrative response shape (excerpt, not a complete signed document):
{"payload":{"schema":"fet112.network-state-attestation.v1",
  "chain_id":"fetchhub-4","issued_at":"…Z","valid_until":"…Z",
  "observation":{"status":"fresh","window":{"start":"…Z","end_exclusive":"…Z"},
    "coverage":{"finalized_buckets":4,"expected_buckets":4,"semantic_errors":0},
    "metrics":{"network.gas.used.v1":{"value":"…","unit":"gas"},"…":"…"}}},
  "integrity":{"algorithm":"Ed25519","canonicalization":"RFC8785",
    "key_id":"sha256:…","content_hash":"sha256:…","signature":"…"}}

jq --arg pin 'sha256:TRUSTED_FINGERPRINT' \
  '{document: ., trusted_key_fingerprint: $pin}' attestation.json |
  curl -fsS -H 'Content-Type: application/json' --data-binary @- \
  https://www.fet112.com/api/v1/verify_network_state_attestation

Discover the current signing key with POST /api/v1/network_state_keys and {}; this is key discovery, not independent trust. The response uses fet112.network-state-verification.v1 and reports cryptographic validity, key trust, expiry, freshness and coverage separately. A trusted fingerprint must be pinned through an independent channel.

MCP: tools to call

{"name":"fet112.network_state_attestation","arguments":{}}

Use the MCP client’s negotiated session and call framing. The returned structured content contains the signed document. The key-discovery tool helps identify the current key but does not establish independent trust.

A2A: structured skill

{"message":{"messageId":"state-001","role":"ROLE_USER","parts":[{"data":{"skill":"network_state_attestation","arguments":{}}}]}}

On success, read the attestation from task.artifacts[].parts[].data. Use verify_network_state_attestation with {"document":{…},"trusted_key_fingerprint":"sha256:…"} to verify it, or network_state_keys to discover the current public key.

State, policy and retention

• fresh: four complete valid buckets, source cursor age ≤300 seconds and finalized window age ≤1200 seconds.
• stale: complete coverage, but the cursor or window cutoff is beyond its freshness threshold; values remain labeled with their actual period.
• partial: a bucket is missing/open or semantic validation failed. Totals are omitted.
• unavailable: the source cannot provide valid evidence. The signed document carries reason codes and omits totals.
• Default document TTL is 120 seconds (configurable from 30 to 300). Expiry and source freshness are independent checks.
• Exact-document retrieval is process-local, limited to 128 documents for up to one hour, can evict earlier at capacity, and is lost on restart. Save the complete document if you need durable records.

MCP tools and resources

Connect an MCP-compatible client to https://www.fet112.com/mcp. Let the client negotiate the supported MCP protocol version and discover the server’s tools/resources using MCP. The endpoint is not a REST JSON endpoint; use an MCP client rather than posting a made-up JSON wrapper.

Available tools

{
  "name": "fet112.analytics_query",
  "arguments": {
    "metric": "network.tx.count.v1",
    "period": "yesterday"
  }
}

The object above is the arguments passed to the MCP tools/call operation inside an MCP session. The MCP client handles protocol framing, initialization, request IDs and transport headers.

Available resources

• fet112://security-report/current — current SecurityReportV1.
• fet112://attestation/current — attestation for the current report.
• fet112://network-status/current — current machine-facing status projection for the Ethereum security scope.
• Network State Attestation is exposed as a tool result, not as a resource URI.

A2A Agent Card and skills

Fetch the Agent Card at https://www.fet112.com/.well-known/agent-card.json. It advertises an HTTP+JSON A2A interface at https://fet112.com/a2a, protocol version 1.0, and the available skills. Use the live card as the authority for the current endpoint, skills and transport capabilities. Its version is agent build metadata; it is distinct from A2A protocol version 1.0 and the REST catalogue’s api_version. Streaming, push notifications and extended cards are not advertised.

Structured requests go to POST /a2a/message:send with Content-Type: application/a2a+json and A2A-Version: 1.0. A structured command uses message.parts[].data with an operation name in skill and an object in arguments.

POST https://fet112.com/a2a/message:send
Content-Type: application/a2a+json
A2A-Version: 1.0

{
  "message": {
    "messageId": "request-001",
    "role": "ROLE_USER",
    "parts": [{
      "data": {
        "skill": "analytics_query",
        "arguments": {
          "metric": "network.tx.count.v1",
          "period": "yesterday"
        }
      }
    }]
  }
}

The successful HTTP response is an A2A task envelope. Read task.status and the structured data in task.artifacts[].parts[].data. Use the task endpoints from the Agent Card/API contract for task retrieval and pagination. A failed task may carry a structured ErrorV1 result.

Available structured skills

Query examples from the live catalogue

Use these to understand the supported intent, then fetch the current catalogue because metric support and examples are server-published.

Response handling and stable errors

Analytics results use fet112.query-result.v1; request failures use ErrorV1. Branch on the stable error code and honor HTTP headers where present.

Validation errors may return other stable ErrorV1 codes and HTTP statuses. Inspect the response body and the live API schema/catalogue.

Network-state operation errors

The attestation operations also use ErrorV1: INVALID_REQUEST (400), ATTESTATION_NOT_FOUND (404), QUERY_BUSY (429), SIGNING_UNAVAILABLE (503) and ATTESTATION_UNAVAILABLE (503). Evidence degradation such as stale or partial source data is returned as a signed attestation with reason codes, not as a transport error.

Attestations and verification

Quantitative analytics and NetworkStateAttestationV1 use separate signed contracts and verification operations. Network-state documents are signed with Ed25519 over RFC 8785 canonical JSON of the complete payload, using a dedicated domain separator. Verify them with verify_network_state_attestation; quantitative responses may contain an Ed25519 attestation under integrity.attestation. The signed object is the complete response excluding its integrity field, per the published quantitative attestation schema. Preserve the complete object when verifying; a shortened display excerpt cannot be verified.

• REST: use POST /api/v1/verify_quantitative_context with the complete context and, when establishing identity, a trusted fingerprint.
• MCP: call fet112.verify_quantitative_context with context and optional trusted_key_fingerprint.
• A2A: call verify_quantitative_context with the same structured arguments.
• Network State Attestation uses POST /api/v1/verify_network_state_attestation, MCP fet112.verify_network_state_attestation, or A2A verify_network_state_attestation.
• Ethereum SecurityReportV1 uses the distinct verify_attestation operation.

A valid signature establishes integrity and signer identity relative to a trusted key. It does not independently establish source accuracy, current chain canonicality, or freshness at verification time. Offline verification may explicitly return NOT_CHECKED_OFFLINE and NOT_CHECKED_AT_VERIFICATION.

Scope, coverage and honest limits

• Analytics are native Fetch measurements for fetchhub-4. Periods are UTC; end times are exclusive; comparisons use equivalent windows.
• Action counts are explicit top-level message actions. One transaction may contain multiple actions; nested Authz message types are not inferred from accounting effects.
• Grouped dimension results can be sparse; omitted entities are not necessarily zero. A requested total/rollup covers source rows even if visible details are truncated.
• Wallet reactivation requires 30 full, continuous days of finalized prior 15-minute coverage. If coverage is insufficient, the API returns INSUFFICIENT_HISTORY; earlier activity is unknown.
• FET112 does not identify wallet owners, exchanges, bots or whales; return arbitrary wallet balances or transaction hashes; infer mutually exclusive transaction categories; or issue a native-chain security verdict.
• Statistical significance, native activity anomaly assessment and causal attribution are not evaluated unless a response explicitly says otherwise. Network-state attestations also report security_decision: NOT_EVALUATED and chain_canonicality: NOT_CHECKED_LIVE.