For Submitters

A Submitter is anyone who wants to verify whether a piece of digital content is authentic or AI-generated. You don't need to understand blockchain or cryptography — you just upload your content, spend a small number of credits, and receive a result.

What can you verify?

Attestia supports four types of media content:

How credits work

Attestia uses Attestation Credits (AC) — a simple unit of account that you spend when submitting content. You don't need to manage cryptocurrency or a wallet. Credits are available through the dashboard, via subscription plans, or as one-off bundles.

The number of credits consumed per submission depends on two things: the type of content you're verifying, and the turnaround time you choose.

What you get back

As soon as your media is registered, the Attestia Native Attester produces an initial baseline score. After the verification window closes, the protocol publishes a final authenticity attestation — a permanent, publicly verifiable record that includes:

• A consensus score between 0 (likely synthetic/manipulated) and 1 (likely authentic) — combining native and independent evaluations
• A confidence indicator — how tightly independent attesters agreed with each other
• The number of independent attesters who participated (native attester counted separately in aggregation, not in this tally)
• A cryptographic proof that aggregation followed the native-weight schedule and included all eligible inputs

This attestation is stored permanently on-chain. You can share it, embed it, reference it in editorial or legal contexts, or use it in any downstream workflow.

Step-by-step

For Independent Attesters

An independent attester evaluates submitted media with their own methodology and earns rewards when their score aligns with the protocol's final consensus. Independent attesters are the decentralized core of the network — diverse methods competing under shared rules. This role is distinct from the Attestia Native Attester, which is operated by Attestia itself, does not stake, and is not rewarded or slashed.

Native vs independent attesters

Every verification task automatically includes a score from the Attestia Native Attester (Attestia's built-in deepfake detector). You do not apply to operate this component — it runs on every submission to bootstrap results and improve turnaround while the independent network scales.

Independent attesters are external participants who join voluntarily, stake collateral, and compete on accuracy. Their scores are combined with the native score using a predefined weight schedule: native influence is highest when participation is low and falls as more independent attesters contribute.

Who should become an independent attester?

Independent attesters come from a variety of backgrounds. What they share is the ability to evaluate media authenticity reliably and on deadline. The protocol accommodates very different approaches:

How rewards work

Attesters earn rewards for each task they evaluate. Rewards are paid in ETH or the USD-equivalent value.

The size of your reward depends on how closely your score aligns with the final consensus, how much your specific contribution influenced the outcome, and your reputation — a track record built over time that acts as a multiplier on your rewards. The better your history of accurate assessments, the more you earn per task.

What attesters are accountable for

To participate, attesters must lock a stake — a deposit held in ETH or its equivalent in USD, locked by the protocol as collateral. This stake is at risk only when an attester's score deviates significantly from a clear network consensus in a way that cannot be explained by honest disagreement. This mechanism — called slashing — is designed to make systematic dishonesty or negligence economically irrational.

Slashing rules are calibrated to the maturity of the network. In the early stages, penalties are conservative to allow the network to form. As the attester set grows and consensus becomes robust, stronger accountability is enforced. See the Network Phases and Slashing sections for details.

Step-by-step

Protocol Overview

Attestia is a hybrid on-chain / off-chain protocol. The Attestia Native Attester and independent attesters score media off-chain; an Aggregator combines those scores into consensus; final outcomes and settlement live on-chain for public verifiability.

Architecture Layers

The protocol is organized in four distinct layers, each with a specific responsibility. They work together to take a piece of media from submission all the way to a publicly verifiable authenticity record.

High-level architecture

Attestia runs as a hybrid flow: independent scoring happens off-chain for privacy and scalability, while final outcomes and settlement anchors live on-chain for public verifiability.

End-to-End Flow

Design Principles

Attestations

An attestation is the fundamental unit of Attestia. Every action in the protocol — submission, individual score, final aggregate — is expressed as a cryptographically signed attestation.

What is an attestation?

An attestation is a verifiable, auditable statement made by a participant about a specific piece of content. In Attestia, attestations represent evaluations of whether a digital asset is authentic, manipulated, or synthetic — expressed as a score between 0 (fully synthetic) and 1 (fully authentic).

Attestations are cryptographically signed and linked to both the issuer's wallet address and the subject content's CID. This makes every contribution attributable, traceable, and immutable after creation.

Types of Attestations

Hybrid storage model

Attestia uses a hybrid approach: native and independent score attestations are stored off-chain for privacy and efficiency, but each is timestamp-anchored on-chain — so once submitted, it cannot be retroactively altered. Aggregated results and cryptographic proofs live fully on-chain, providing a public, permanent record.

Independent Score Attestation — Draft Schema

The schema below shows the core fields included in each attester's off-chain attestation. This is a representative draft; additional fields related to versioning, metadata, and protocol parameters will be defined at the time of mainnet release.

{
  contentHash:  bytes32,   // IPFS CID of the media asset
  assetId:      bytes32,   // UID of the parent submission attestation
  score:        uint256,   // Authenticity score in [0, 1], scaled to 1e18
  timestamp:    uint64,    // Must be within the submission's expiration window
  attester:     address,   // Wallet address of the signing attester
  // ...
  // Additional fields (methodology flags, confidence indicators,
  // protocol version, nonce, etc.) will be finalized at launch.
}

Aggregate Attestation — Draft Schema

The aggregate attestation is the protocol's public output, anchored on-chain after settlement. It includes the consensus result and a cryptographic commitment to the underlying computation.

{
  assetId:         bytes32,  // UID of the originating submission attestation
  consensusScore:  uint256,  // Combined native + independent consensus × 1e18
  attesterCount:   uint32,   // Number of valid independent attesters (native excluded)
  confidence:      uint256,  // Signal of network agreement (derived from variance)
  scoreSetHash:    bytes32,  // Commitment to the complete set of attester inputs
  zkProofRef:      bytes32,  // Reference to the ZK proof of correct aggregation
  // ...
  // Additional fields (phase identifier, reward pool snapshot,
  // slashing flags, etc.) will be finalized at launch.
}

Participants

Attestia is built around a decentralized network of participants with distinct but complementary roles. Each role has different economic obligations, capabilities, and incentives.

Submitters

Submitters introduce content into the protocol. They may be media organizations, social platforms, legal teams, investigators, or individual users who need verifiable authenticity proofs for digital assets.

To submit content, submitters use Attestation Credits (AC). The required AC amount depends on media type and turnaround selection, and is deducted when the task is opened.

Attestia Native Attester

The Attestia Native Attester is Attestia's AI-powered deepfake detection system. For each submitted media item it produces an initial authenticity score that serves as a baseline input to aggregation — not a final verdict.

Its relative weight in the consensus formula is higher when few independent attesters participate and progressively lower as more independent evaluations are submitted (see Aggregation & Consensus). The native attester participates in aggregation but does not stake, earn attester rewards, or face slashing. Its role is operational: bootstrap useful results, improve response time, and complement the decentralized market.

Independent attesters

Independent attesters are the decentralized evaluators of the network. Each independently analyzes submitted content and produces an authenticity score between 0 (fully synthetic) and 1 (fully authentic).

Independent attesters can use any evaluation method — the protocol enforces when and under what conditions the score is submitted, not how it is computed. This open design allows:

• Machine learning models and deepfake detection pipelines
• OSINT analysis and investigative methods
• Domain-specific human expertise
• Hybrid pipelines combining automated and manual review

Unlike submitters, independent attesters lock a stake (0.10 ETH at initialization, ETH-equivalent thereafter) as active collateral. It earns rewards when they align with the final consensus, but may be partially forfeited if their scores deviate significantly when the network has clearly converged. The native attester is outside this economic loop. Slashing rules evolve with network phase — see Network Phases and Slashing.

Consumers (External Applications)

Any application, platform, or smart contract can consume Attestia attestations as trust signals. Consumers do not need to stake or participate in verification — they simply read the on-chain EAS attestations produced by the protocol.

Role comparison

Verification as a Market

Attestia models verification as a hybrid system: Attestia's native detector supplies an immediate, operational baseline, while an open market of independent attesters adds diverse, staked evaluations. No single participant defines ground truth — the published consensus emerges from their weighted aggregation.

Why a market model?

Traditional verification relies either on a single detection algorithm or a single certifying authority. Both are fragile: algorithms miss novel synthesis techniques, and centralized authorities can be wrong, captured, or opaque.

Attestia does not abandon algorithmic detection — it combines Attestia's native detector with a market of independent attesters. The native score keeps early-stage verification useful and fast; independent competition makes the long-term outcome decentralized, diverse, and economically accountable.

Structural defense against adversarial evasion

Any single detection system faces a persistent arms race: as detection improves, generation techniques evolve to evade it. Attestia's native detector provides scalable baseline coverage; the independent market ensures there is no single point to evade forever. A technique that bypasses one attester's model may still be caught by others — including the native stack and unrelated methodologies.

Submission & Anchoring

A verification task begins when a submitter uploads their content through the Attestia interface, pays the required Attestation Credits, and selects a verification speed. The platform handles all the technical steps automatically.

Step 1 — Upload your content

The submitter uploads the media file through the Attestia dashboard. The platform stores the file on a decentralized storage network (IPFS), ensuring it remains accessible to every attester in the network without being stored on-chain. Each file is assigned a unique cryptographic fingerprint: if anyone tampers with the file, the fingerprint changes and the modification is immediately detectable.

Media is never stored directly on the blockchain — only its fingerprint and metadata are anchored there, keeping costs low while preserving integrity.

Step 2 — Configure and pay

Before the task is opened to attesters, the submitter selects their verification speed and pays the corresponding Attestation Credits (AC):

• Standard (30 min): Attesters have 30 minutes to evaluate the content. This is the default option and the most cost-efficient.
• Priority (5 min): The verification window is reduced to 5 minutes, at 2× the credit cost. Useful when a faster result is needed.

Step 3 — The task is anchored and opened

Once the payment is confirmed, the platform automatically registers the task on-chain. This creates a permanent, tamper-proof record that:

• Identifies the submitted content by its unique fingerprint
• Records the media type and any contextual metadata
• Sets the verification deadline (standard or priority)

From this moment, the task is publicly visible. The Attestia Native Attester begins analysis immediately, and independent attesters can retrieve the media and run their own evaluations until the deadline.

Verification Phase

Once a submission is anchored, verification runs on two tracks in parallel: the Attestia Native Attester records a baseline score, while independent attesters evaluate the same media and submit sealed off-chain scores before the deadline (default 30 minutes, priority 5 minutes).

Native attester — baseline score

The Attestia Native Attester analyzes the submitted media as soon as it is registered. It produces an authenticity score stored as an off-chain attestation and timestamp-anchored on-chain. This score is not treated as a final authority; it is one input to the aggregate, with weight that decreases as more independent attesters participate.

The native attester does not wait for the review window to close — submitters benefit from an immediate operational signal while independent evaluation proceeds.

Independent attesters — discovering submissions

Attesters continuously monitor active submission attestations on-chain. They can do this via:

• The Attestia dashboard (protocol-native interface)
• Direct EAS event subscriptions (on-chain events emitted at submission)
• The Attestia API (coming soon)

Independent evaluation — open methodology

For independent attesters, the protocol places no constraints on evaluation methodology. What matters is accuracy and timeliness — not which tools or methods are used. Diversity across independent attesters — combined with the native detector — makes the aggregate far more resilient than any single system alone.

Submitting a score

The evaluation result is encoded as a signed off-chain EAS attestation containing the authenticity score and the necessary cryptographic references. Scores must be submitted before the expiration time.

Each off-chain attestation is timestamp-anchored on-chain at the moment of submission. This means once a score is committed, its existence and timing are permanently recorded on the blockchain — the attester cannot change their answer after observing the deadline pass or seeing other results.

Aggregation & Consensus

After the submission window closes, the Aggregator retrieves the Attestia Native Attester score and all valid independent attester scores, then computes a single consensus result using a predefined weighted rule. The computation is made trustless through a Zero-Knowledge proof.

How the consensus is computed

The consensus score x̄ combines two components:

• x_A — authenticity score from the Attestia Native Attester
• x_m — scores from independent attesters, each weighted by reputation ρ_m

Formally (as defined in the Whitepaper):

x̄ = wA(N) · xA + (1 − wA(N)) · ( Σ ρmxm / Σ ρm )

where N is the number of participating independent attesters and w_A(N) is the weight assigned to the native score. When N = 0, the consensus reduces to the native score alone — ensuring a usable result during network bootstrap.

Native attester weight schedule

Native influence follows a fixed decreasing schedule as independent participation grows:

Reputation ρ_m applies within the independent set (see Reputation System). It rewards reliable independent attesters over time without letting any single participant dominate unboundedly.

The Zero-Knowledge Proof

Computing the consensus is straightforward — the challenge is making the computation trustless. How can anyone be sure the aggregator didn't exclude some scores, include fake ones, or apply the formula incorrectly?

Attestia addresses this through a Zero-Knowledge proof: a cryptographic certificate that proves the following facts without revealing any sensitive data:

• The native score and every eligible independent score were included — none omitted or fabricated
• The native-weight schedule w_A(N) and reputation weighting were applied exactly as specified
• The published consensus score is the mathematically correct result

This proof is published alongside the final attestation, so anyone can independently verify the result. They don't need to re-run the computation or trust the aggregator — the proof is mathematically sufficient.

Confidence score

Alongside the consensus score, the aggregator computes a confidence value based on how much the attesters' scores agreed with each other. When all attesters land close together, confidence is high — the network has a clear, decisive view. When scores are spread out, confidence is lower — the content may be genuinely ambiguous or the attester set hasn't converged.

Both the consensus score and the confidence value are included in the final on-chain attestation, giving downstream consumers a richer signal than a simple score alone.

On-Chain Settlement

After aggregation, the protocol publishes the final result on-chain and evaluates how each independent attester performed — distributing rewards to those who aligned with consensus and applying penalties to clear outliers. The Attestia Native Attester is outside this settlement loop.

Publishing the aggregate attestation

The Aggregator posts the consensus score, confidence value, independent attester count (native excluded), and ZK commitment as an on-chain EAS attestation. This is the protocol's public output — a compact, tamper-resistant record of the combined native and independent judgment about the submitted media.

Once published, this attestation can be read by anyone: the submitter who submitted the media, downstream applications integrating Attestia, or any third party who wants to independently verify the authenticity assessment.

Evaluating independent attester behavior

Settlement applies only to independent attesters. The native attester does not receive protocol rewards and is not subject to staking or slashing — it provides a baseline signal and commercial responsiveness, not market participation.

Rather than rewarding absolute correctness — which would require knowing ground truth — Attestia measures alignment with the published consensus (which already includes the native score via w_A(N)). If independent attesters converge near 0.82 and one submits 0.83, they are aligned. A score of 0.20 against a tight cluster suggests error or manipulation and may trigger reduced rewards or slashing when variance is low.

Importantly, the protocol is careful not to punish honest disagreement. If the network itself is divided — with scores spread widely across the range — then a large individual deviation may simply reflect legitimate uncertainty. Penalties are only applied when the network has clearly converged and a specific attester stands far outside the consensus. This is governed by the Slashing rules and varies by Network Phase.

Reward distribution

Each participating independent attester receives rewards denominated in ETH and ATTA according to the active network phase. Reward size depends on deviation from consensus, informative contribution, and reputation — see Reward Mechanism.

Staking Model

Staking applies to independent attesters only — not the Attestia Native Attester. By locking collateral before participating, independent attesters have economic skin in the game: stake earns rewards when aligned with consensus and is at risk when slashing rules apply.

Independent attester stake

To participate as an independent attester, a deposit must be locked into the AttestiaStake contract. This deposit is denominated in ETH or its equivalent in USD, and is held as active collateral — it grants access to the reward pool but is also subject to partial forfeiture (slashing) in case of systematic deviation from a clear network consensus.

The required stake amount increases progressively as the network matures. Early-phase attesters face a lower barrier to entry; as consensus becomes more robust and economic security requirements grow, the stake threshold rises accordingly.

Stake transition

At initialization, attesters stake ETH. In the mature network phase, the staking requirement transitions from ETH to ATTA — the protocol's native token. Attesters who have accumulated ATTA through participation can transition their stake without additional capital outlay. New entrants must acquire ATTA on the open market.

Reward Mechanism

Independent attesters are rewarded based on alignment with the published consensus (which includes the native score via w_A(N)) and how informative their contribution was. The Attestia Native Attester does not participate in the reward pool. This dual incentive prevents blind conformity and low-effort copying.

What gets rewarded?

Alignment with consensus

The primary driver of an attester's reward is how close their score is to the network's final consensus. An attester who lands precisely on the consensus receives the maximum alignment bonus. The further away their score, the smaller this component of the reward. Importantly, the penalty for deviation grows disproportionately: small differences barely affect the reward, but large deviations reduce it sharply.

Informative contribution

The second component rewards attesters whose score actually moved the aggregate. This is measured by asking: how much would the consensus have changed if this attester had not participated? An attester who submits an independent, carefully considered score that shifts the aggregate — even slightly — earns a meaningful influence bonus. An attester who submits a score identical to what the consensus would have been anyway earns very little from this component.

This design prevents a common gaming strategy: waiting for other scores to leak, then submitting a near-identical value to collect rewards without doing real analysis. Attestia's hidden-score window already limits this by withholding scores until the deadline, and the influence component adds another layer of defense.

Reputation multiplier

Both components are multiplied by the attester's reputation score. A well-established attester with a long track record of accurate assessments earns a larger reward for the same quality of submission than a newcomer. This creates a meaningful career path within the protocol: building a strong reputation is financially worthwhile.

Reputation System

Every independent attester maintains a reputation score ρ_m reflecting historical alignment with consensus. Reputation weights independent scores inside the aggregation formula and multiplies reward payouts — it is bounded so no participant can dominate indefinitely.

How reputation works

After each round, reputation updates from how closely an independent attester's score matched the final consensus x̄ (native + independent aggregate). Updates use an exponentially weighted average (λ = 0.8 in the Whitepaper), so recent performance matters more while history is retained.

Reputation is bounded (ρ_m ∈ [0.5, 1.5] per the Whitepaper). High performers contribute more inside the independent average and earn larger rewards; poor performers retain baseline participation but carry less weight and smaller payouts.

Reputation tiers

Slashing

Slashing is the protocol's mechanism for penalizing clear outliers. It is designed carefully — punishing genuinely anomalous behavior while protecting attesters who take legitimate minority positions on ambiguous content.

When does slashing apply?

A large deviation from consensus alone is not enough to trigger slashing. The protocol takes context into account: if the attester network itself is divided and scores are spread widely, then any individual deviation may simply reflect genuine uncertainty about the content — not negligence or manipulation.

Slashing is triggered only when two conditions are met simultaneously:

• The attester's score is far enough from the consensus to be statistically significant
• The overall spread of attester scores is low — meaning the network converged clearly, and this attester's deviation cannot be explained by general ambiguity

When scores are widely dispersed across the network, slashing is suppressed entirely — even for attesters who deviate a lot. The protocol reasons that if the network itself is uncertain, penalizing any individual for diverging from an unstable consensus would be unjust.

Slashing by network phase

The strictness of slashing evolves with the network. In the early stages, consensus is fragile and the attester set is small — so penalties are conservative or absent. As the network matures and consensus becomes robust, the protocol can reasonably enforce tighter standards.

The exact thresholds and conditions for each phase are detailed in the protocol's technical specification. For a thorough treatment, refer to the Whitepaper. A high-level description of how the phases differ is covered in the Network Phases section.

Network Phases

Attestia's incentive structure is not static — it evolves as the attester set grows. Early stages require conservative penalties and generous incentives to attract the first participants. As the network matures, stronger guarantees can be enforced without discouraging honest involvement.

Phase 0 — Bootstrapping

In the earliest stage, the attester set is small and still forming. Disagreement between attesters is expected and does not indicate malicious behavior — with only a handful of participants, random variation naturally matters more.

• Slashing: Fully disabled — no stake at risk for deviation
• Rewards: Reduced from the base rate, reflecting lower confidence in an early-stage aggregate
• Reputation: Updates are active from day one — early participants build their track record immediately
• Primary goal: Attract the first attesters, bootstrap supply, validate the core protocol

Phase 1 — Weak Consensus

As the network grows, it begins to produce meaningful signals. Slashing is introduced selectively — only when the network has clearly converged on a result and an attester's deviation cannot be explained by genuine ambiguity.

• Slashing: A moderate fraction of attester stake, applied only when both the deviation is large and the network's score variance is low
• Rewards: Increased toward the full base rate
• Primary goal: Establish reliable consensus, improve attester quality through selective accountability

Phase 2 — Mature Network

The network is large enough that the aggregate outcome is robust and reliable. The variance condition for slashing is lifted — high deviation is penalized regardless of how spread out the scores are, because the network as a whole can be trusted.

• Slashing: A larger fraction of attester stake, applied whenever deviation exceeds the threshold
• Rewards: Full base rate — maximum incentive for accurate participation
• Primary goal: Maximum economic security, highest-quality outputs, full protocol credibility

Full Walkthrough

This page walks through a complete, concrete scenario — from media submission to final settlement — using a single consistent example that ties together every concept covered in the docs.

Step 1 — Submission

The journalist opens the Attestia dashboard and uploads the video clip. The platform securely stores the file and registers the verification request — setting a 30-minute window for independent experts to evaluate it (or 5 minutes in priority mode).

The journalist pays the required Attestation Credits (AC) for the selected media type and verification speed. No blockchain knowledge or cryptocurrency wallet is needed — everything happens through the dashboard.

Step 2 — Native baseline score

Immediately after anchoring, the Attestia Native Attester analyzes the clip and records a baseline score of 0.22 — consistent with likely manipulation. The journalist can see this operational signal while the independent window remains open.

Step 3 — Independent attesters evaluate

Three active independent attesters discover the task and work in parallel. They cannot see each other's scores until the window closes.

• Attester A detects face-swap artifacts and submits 0.21.
• Attester B finds metadata and A/V sync issues and submits 0.18.
• Attester C flags synthetic generation and submits 0.24.

Step 4 — Aggregation

With N = 3 independent attesters, native weight w_A = 80%. The reputation-weighted independent average is approximately 0.20. Consensus ≈ 0.80×0.22 + 0.20×0.20 ≈ 0.22 — clearly in the synthetic/manipulated range, aligned with both native and independent signals.

Independent variance is very low, yielding a high confidence indicator. A ZK proof attests that the native score, all three independent scores, and the weight schedule were applied correctly — without revealing individual sealed scores.

Step 5 — The result is recorded

The final result is permanently recorded as a public attestation — think of it as a tamper-proof digital certificate, permanently stored on the blockchain, that anyone can look up and verify at any time. It contains:

• Consensus score: 0.22 (likely synthetic/manipulated)
• Confidence: high (tight independent agreement)
• Independent attester count: 3 (native weight at aggregation: 80%)
• A cryptographic proof that the result was computed correctly

This attestation is now permanently on record. The journalist can embed it in their article, share it with editors, or use it in any legal or editorial process. Anyone can independently look it up and verify it.

Step 6 — Settlement

Settlement runs for independent attesters only. All three are close to consensus (~0.22), so all receive rewards:

No slashing is triggered. Attester C's reputation ticks upward toward the Trusted tier.

Outcome

The journalist holds a publicly verifiable attestation: Attestia's native detector and three independent experts — diverse methods, staked accountability, and a published weight schedule — assessed the clip as likely synthetic with high confidence. The process, not just the number, is what establishes trust.

API Reference

The Attestia v1 HTTP API lets attesters query open media and submitters register assets using signed requests (access key + timestamp + HMAC). Public routes are available without signing. An optional WebSocket feed may be available for the same data when your deployment exposes it. Attester integrations should treat that realtime feed as the trigger that new media is ready for review.

Base URL (v1)

All versioned REST routes are under . Use your production or staging hostname in place of the one shown here.

Sections

General information

Public endpoints for connectivity and clock sync. Signed routes are documented under REST endpoints.

HTTP

Test connectivity

GET /ping

{}

Check server time

GET /time

{
  "serverTime": 1735689600000
}

serverTime is the server's Unix time in milliseconds; you can compare it with your own clock before signing requests.

Service metadata

GET /health

{
  "ok": true,
  "service": "attestia-api",
  "version": 1,
  "timestamp": "2026-05-04T12:00:00.000Z"
}

Request signing

Private v1 routes require an access key and a signing secret (created in the app dashboard). Each request must include a timestamp and an HMAC signature over a canonical string. The signing secret is never sent on the wire after initial creation.

API keys

In the Attestia web app, open Dashboard (or your role workspace) and create an attester or submitter API key. You receive an accessKey and a signingSecret. Copy the signing secret immediately; it is shown only once. Revoke keys from the same screen when you no longer need them.

{
  "accessKey": "ak_att_0123456789abcdef",
  "signingSecret": "<shown once>",
  "key": { "id": "0123456789abcdef", "display": "ak_att_01234567********", "kind": "attester", "...": "..." },
  "warning": "Store signingSecret now (shown once). ..."
}

For automation against your own session, you can call POST /api/dashboard/api-keys with Authorization: Bearer <session_access_token> and body { "kind": "attester" | "submitter", "label": "my-bot" }. Revoke with DELETE /api/dashboard/api-keys?id=<key_id> using the same session token.

HTTP headers (signed requests)

Header names are case-insensitive. You may use the X-Attestia-* aliases if your stack requires an X- prefix on custom headers.

Canonical payload

Concatenate exactly four lines (newline character \n between lines, no trailing newline):

1) <Attestia-Timestamp as string, e.g. "1735689600000">
2) <HTTP_METHOD in UPPERCASE, e.g. GET or POST>
3) <path + query exactly as in the request URL, e.g. "/api/v1/attester/media?includeMyScore=1">
4) <lowercase hex SHA-256 of the raw request body bytes interpreted as UTF-8 string (empty string for GET)>

Line 3 must match what your HTTP client sends: start with /, include ? and the query string when present. Only the path and query are signed, not the scheme or host (for example under the signed path begins with /api/v1/).

signature = HMAC_SHA256(
  key = UTF8(signingSecret),
  message = UTF8(canonicalPayload)
)
Attestia-Signature = lowercaseHex(signature)

Timestamp window

Attestia-Timestamp must be within 30 seconds of server time unless your deployment documentation states otherwise. On 401 responses that indicate clock skew, compare your clock with GET /api/v1/time.

Example: signed GET

import { createHash, createHmac } from "node:crypto";

const ORIGIN = "https://your-host";
const ACCESS_KEY = process.env.ATTESTIA_ACCESS_KEY ?? "";
const SIGNING_SECRET = process.env.ATTESTIA_SIGNING_SECRET ?? "";

function sha256HexUtf8(s: string) {
  return createHash("sha256").update(s, "utf8").digest("hex");
}

function signRequest(method: string, pathWithQuery: string, body: string) {
  const ts = String(Date.now());
  const bodyHash = sha256HexUtf8(body);
  const payload = [ts, method.toUpperCase(), pathWithQuery, bodyHash].join(String.fromCharCode(10));
  const signature = createHmac("sha256", SIGNING_SECRET).update(payload, "utf8").digest("hex");
  return {
    headers: {
      "Attestia-Access-Key": ACCESS_KEY,
      "Attestia-Timestamp": ts,
      "Attestia-Signature": signature,
    },
  };
}

const path = "/api/v1/attester/media";
const url = ORIGIN + path;
const { headers } = signRequest("GET", path, "");
const res = await fetch(url, { headers });
console.log(res.status, await res.text());

import hashlib, hmac, os, time
import urllib.request

ORIGIN = os.environ.get("ATTESTIA_SITE_ORIGIN", "https://your-host").rstrip("/")
ACCESS_KEY = os.environ["ATTESTIA_ACCESS_KEY"]
SIGNING_SECRET = os.environ["ATTESTIA_SIGNING_SECRET"]

def sha256_hex_utf8(s: str) -> str:
    return hashlib.sha256(s.encode("utf-8")).hexdigest()

def sign_headers(method: str, path_with_query: str, body: str) -> dict:
    ts = str(int(time.time() * 1000))
    body_hash = sha256_hex_utf8(body)
    payload = "\n".join([ts, method.upper(), path_with_query, body_hash])
    sig = hmac.new(SIGNING_SECRET.encode("utf-8"), payload.encode("utf-8"), hashlib.sha256).hexdigest()
    return {
        "Attestia-Access-Key": ACCESS_KEY,
        "Attestia-Timestamp": ts,
        "Attestia-Signature": sig,
    }

path = "/api/v1/attester/media"
req = urllib.request.Request(ORIGIN + path, headers=sign_headers("GET", path, ""), method="GET")
with urllib.request.urlopen(req) as r:
    print(r.status, r.read().decode())

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.HexFormat;

public class AttesterList {
  static String sha256HexUtf8(String s) throws Exception {
    byte[] h = MessageDigest.getInstance("SHA-256").digest(s.getBytes(StandardCharsets.UTF_8));
    return HexFormat.of().formatHex(h);
  }

  public static void main(String[] args) throws Exception {
    String origin = System.getenv().getOrDefault("ATTESTIA_SITE_ORIGIN", "https://your-host");
    if (origin.endsWith("/")) origin = origin.substring(0, origin.length() - 1);
    String accessKey = System.getenv("ATTESTIA_ACCESS_KEY");
    String signingSecret = System.getenv("ATTESTIA_SIGNING_SECRET");
    String path = "/api/v1/attester/media";
    String ts = String.valueOf(System.currentTimeMillis());
    String body = "";
    String bodyHash = sha256HexUtf8(body);
    String payload = String.join("\n", ts, "GET", path, bodyHash);
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(signingSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
    String sig = HexFormat.of().formatHex(mac.doFinal(payload.getBytes(StandardCharsets.UTF_8)));

    HttpRequest req = HttpRequest.newBuilder()
        .uri(URI.create(origin + path))
        .header("Attestia-Access-Key", accessKey)
        .header("Attestia-Timestamp", ts)
        .header("Attestia-Signature", sig)
        .GET()
        .build();
    HttpResponse res = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
    System.out.println(res.statusCode() + " " + res.body());
  }
}

use hmac::{Hmac, Mac};
use sha2::{Digest, Sha256};
use std::env;
use std::time::{SystemTime, UNIX_EPOCH};

type HmacSha256 = Hmac;

fn sha256_hex_utf8(s: &str) -> String {
    let mut h = Sha256::new();
    h.update(s.as_bytes());
    hex::encode(h.finalize())
}

fn main() -> Result<(), Box> {
    let mut origin = env::var("ATTESTIA_SITE_ORIGIN").unwrap_or_else(|_| "https://your-host".into());
    while origin.ends_with('/') { origin.pop(); }
    let access_key = env::var("ATTESTIA_ACCESS_KEY")?;
    let signing_secret = env::var("ATTESTIA_SIGNING_SECRET")?;
    let path = "/api/v1/attester/media";
    let ts = SystemTime::now().duration_since(UNIX_EPOCH)?.as_millis().to_string();
    let body = "";
    let body_hash = sha256_hex_utf8(body);
    let payload = format!("{ts}\nGET\n{path}\n{body_hash}");
    let mut mac = HmacSha256::new_from_slice(signing_secret.as_bytes())?;
    Mac::update(&mut mac, payload.as_bytes());
    let sig = hex::encode(mac.finalize().into_bytes());

    let client = reqwest::blocking::Client::new();
    let res = client
        .get(format!("{origin}{path}"))
        .header("Attestia-Access-Key", access_key)
        .header("Attestia-Timestamp", &ts)
        .header("Attestia-Signature", sig)
        .send()?;
    println!("{} {}", res.status(), res.text()?);
    Ok(())
}

REST endpoints

All paths below are rooted at . Private routes require request signing. Rate limits are per access key (see Limits & errors).

Endpoint index

{
  "assets": [
    {
      "id": "...",
      "title": "...",
      "mediaContext": "...",
      "contentHash": "0x...",
      "uri": "ipfs://...",
      "status": "open",
      "mediaType": "image",
      "turnaround": "standard",
      "scoreCount": 3,
      "myScore": { "submitted": true, "authenticityScore": 90, "...": "..." }
    }
  ],
  "stake": { "stakedWei": "...", "minStakeWei": "..." }
}

{
  "score": { "id": "...", "assetId": "...", "attesterAddress": "0x...", "authenticityScore": 90, "deepfakeRiskBps": 1200, "...": "..." },
  "aggregate": { "...": "..." }
}

import { createHash, createHmac } from "node:crypto";

const ORIGIN = "https://your-host";
const ACCESS_KEY = process.env.ATTESTIA_ACCESS_KEY ?? "";
const SIGNING_SECRET = process.env.ATTESTIA_SIGNING_SECRET ?? "";

function sha256HexUtf8(s: string) {
  return createHash("sha256").update(s, "utf8").digest("hex");
}

function signRequest(method: string, pathWithQuery: string, body: string) {
  const ts = String(Date.now());
  const bodyHash = sha256HexUtf8(body);
  const payload = [ts, method.toUpperCase(), pathWithQuery, bodyHash].join(String.fromCharCode(10));
  const signature = createHmac("sha256", SIGNING_SECRET).update(payload, "utf8").digest("hex");
  return {
    headers: {
      "Content-Type": "application/json",
      "Attestia-Access-Key": ACCESS_KEY,
      "Attestia-Timestamp": ts,
      "Attestia-Signature": signature,
    },
  };
}

const path = "/api/v1/submitter/media";
const body = JSON.stringify({
  title: "My asset",
  mediaContext: "Context here",
  contentHash: "0x" + "ab".repeat(32),
  uri: "ipfs://...",
  contributorAttestationUid: "0x" + "cd".repeat(32),
  verificationDeadline: new Date(Date.now() + 12 * 3600 * 1000).toISOString(),
  mediaType: "image",
  turnaround: "standard",
});
const { headers } = signRequest("POST", path, body);
const res = await fetch(ORIGIN + path, { method: "POST", headers, body });
console.log(res.status, await res.text());

import hashlib, hmac, json, os, time, urllib.request
from datetime import datetime, timedelta, timezone

ORIGIN = os.environ.get("ATTESTIA_SITE_ORIGIN", "https://your-host").rstrip("/")
ACCESS_KEY = os.environ["ATTESTIA_ACCESS_KEY"]
SIGNING_SECRET = os.environ["ATTESTIA_SIGNING_SECRET"]

def sha256_hex_utf8(s: str) -> str:
    return hashlib.sha256(s.encode("utf-8")).hexdigest()

def sign_headers(method: str, path_with_query: str, body: str) -> dict:
    ts = str(int(time.time() * 1000))
    body_hash = sha256_hex_utf8(body)
    payload = "\n".join([ts, method.upper(), path_with_query, body_hash])
    sig = hmac.new(SIGNING_SECRET.encode("utf-8"), payload.encode("utf-8"), hashlib.sha256).hexdigest()
    return {
        "Content-Type": "application/json",
        "Attestia-Access-Key": ACCESS_KEY,
        "Attestia-Timestamp": ts,
        "Attestia-Signature": sig,
    }

path = "/api/v1/submitter/media"
payload = {
    "title": "My asset",
    "mediaContext": "Context here",
    "contentHash": "0x" + "ab" * 32,
    "uri": "ipfs://...",
    "contributorAttestationUid": "0x" + "cd" * 32,
    "verificationDeadline": (datetime.now(timezone.utc) + timedelta(hours=12)).isoformat().replace("+00:00", "Z"),
    "mediaType": "image",
    "turnaround": "standard",
}
body = json.dumps(payload, separators=(',', ':'))
req = urllib.request.Request(ORIGIN + path, data=body.encode("utf-8"), headers=sign_headers("POST", path, body), method="POST")
with urllib.request.urlopen(req) as r:
    print(r.status, r.read().decode())

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.time.Instant;
import java.time.temporal.ChronoUnit;
import java.util.HexFormat;

public class SubmitterMedia {
  static String sha256HexUtf8(String s) throws Exception {
    byte[] h = MessageDigest.getInstance("SHA-256").digest(s.getBytes(StandardCharsets.UTF_8));
    return HexFormat.of().formatHex(h);
  }

  public static void main(String[] args) throws Exception {
    String origin = System.getenv().getOrDefault("ATTESTIA_SITE_ORIGIN", "https://your-host");
    if (origin.endsWith("/")) origin = origin.substring(0, origin.length() - 1);
    String accessKey = System.getenv("ATTESTIA_ACCESS_KEY");
    String signingSecret = System.getenv("ATTESTIA_SIGNING_SECRET");
    String path = "/api/v1/submitter/media";
    String deadline = Instant.now().plus(12, ChronoUnit.HOURS).toString();
    String body =
        "{\"title\":\"My asset\",\"mediaContext\":\"Context here\",\"contentHash\":\"0x" +
            "ab".repeat(32) +
            "\",\"uri\":\"ipfs://...\",\"contributorAttestationUid\":\"0x" +
            "cd".repeat(32) +
            "\",\"verificationDeadline\":\"" + deadline + "\",\"mediaType\":\"image\",\"turnaround\":\"standard\"}";
    String ts = String.valueOf(System.currentTimeMillis());
    String bodyHash = sha256HexUtf8(body);
    String payload = String.join("\n", ts, "POST", path, bodyHash);
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(signingSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
    String sig = HexFormat.of().formatHex(mac.doFinal(payload.getBytes(StandardCharsets.UTF_8)));

    HttpRequest req = HttpRequest.newBuilder()
        .uri(URI.create(origin + path))
        .header("Content-Type", "application/json")
        .header("Attestia-Access-Key", accessKey)
        .header("Attestia-Timestamp", ts)
        .header("Attestia-Signature", sig)
        .POST(HttpRequest.BodyPublishers.ofString(body))
        .build();
    HttpResponse res = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
    System.out.println(res.statusCode() + " " + res.body());
  }
}

use chrono::{Duration, SecondsFormat, Utc};
use hmac::{Hmac, Mac};
use serde_json::json;
use sha2::{Digest, Sha256};
use std::env;

type HmacSha256 = Hmac;

fn sha256_hex_utf8(s: &str) -> String {
    let mut h = Sha256::new();
    h.update(s.as_bytes());
    hex::encode(h.finalize())
}

fn main() -> Result<(), Box> {
    let mut origin = env::var("ATTESTIA_SITE_ORIGIN").unwrap_or_else(|_| "https://your-host".into());
    while origin.ends_with('/') { origin.pop(); }
    let access_key = env::var("ATTESTIA_ACCESS_KEY")?;
    let signing_secret = env::var("ATTESTIA_SIGNING_SECRET")?;
    let path = "/api/v1/submitter/media";
    let deadline = (Utc::now() + Duration::hours(12)).to_rfc3339_opts(SecondsFormat::Millis, true);
    let body = json!({
        "title": "My asset",
        "mediaContext": "Context here",
        "contentHash": format!("0x{}", "ab".repeat(32)),
        "uri": "ipfs://...",
        "contributorAttestationUid": format!("0x{}", "cd".repeat(32)),
        "verificationDeadline": deadline,
        "mediaType": "image",
        "turnaround": "standard",
    })
    .to_string();
    let ts = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)?
        .as_millis()
        .to_string();
    let body_hash = sha256_hex_utf8(&body);
    let payload = format!("{ts}\nPOST\n{path}\n{body_hash}");
    let mut mac = HmacSha256::new_from_slice(signing_secret.as_bytes())?;
    Mac::update(&mut mac, payload.as_bytes());
    let sig = hex::encode(mac.finalize().into_bytes());

    let client = reqwest::blocking::Client::new();
    let res = client
        .post(format!("{origin}{path}"))
        .header("Content-Type", "application/json")
        .header("Attestia-Access-Key", access_key)
        .header("Attestia-Timestamp", &ts)
        .header("Attestia-Signature", sig)
        .body(body)
        .send()?;
    println!("{} {}", res.status(), res.text()?);
    Ok(())
}

WebSocket API

Open media is also available over HTTP as an SSE stream at /api/v1/attester/media/stream (same signing as other attester routes). Some deployments additionally offer a WebSocket endpoint for the same feed; use the wss:// or ws:// URL you were given. The examples use ATTESTIA_WS_URL as a placeholder. Attester services should keep this connection open and treat new-open-assets as the trigger that newly registered media is available for review. The open-assets snapshot is still sent whenever the open set changes.

Connection URL

Authenticate

Send a single JSON text frame immediately after connect:

{
  "type": "auth",
  "accessKey": "ak_att_0123456789abcdef",
  "timestamp": 1735689600000,
  "signature": "<lowercase hex HMAC-SHA256>"
}

signature uses the same signingSecret as REST. Canonical payload (four lines, UTF-8, newline-separated):

1) <timestamp as string, same as JSON field>
2) CONNECT
3) /__attestia_ws__/<accessKey>
4) <sha256Hex of empty string>

After a successful auth, attester connections follow the same eligibility rules as signed REST attester routes (including stake requirements).

Server messages

Example client

Pick the language tab that matches your stack. Set ATTESTIA_WS_URL, ATTESTIA_ACCESS_KEY, and ATTESTIA_SIGNING_SECRET in your environment.

import WebSocket from "ws";
import { createHash, createHmac } from "node:crypto";

const WS_URL = process.env.ATTESTIA_WS_URL ?? "ws://127.0.0.1:3001";
const ACCESS_KEY = process.env.ATTESTIA_ACCESS_KEY ?? "";
const SIGNING_SECRET = process.env.ATTESTIA_SIGNING_SECRET ?? "";

function sha256HexUtf8(s: string) {
  return createHash("sha256").update(s, "utf8").digest("hex");
}

function wsAuthPayload(ts: string, accessKey: string) {
  const ak = accessKey.toLowerCase();
  const path = `/__attestia_ws__/${ak}`;
  const bodyHash = sha256HexUtf8("");
  const lines = [ts, "CONNECT", path, bodyHash];
  return lines.join(String.fromCharCode(10));
}

function signWs(ts: string, accessKey: string) {
  const payload = wsAuthPayload(ts, accessKey);
  return createHmac("sha256", SIGNING_SECRET).update(payload, "utf8").digest("hex");
}

const ts = String(Date.now());
const ak = ACCESS_KEY.toLowerCase();
const ws = new WebSocket(WS_URL);
ws.on("open", () => {
  ws.send(JSON.stringify({
    type: "auth",
    accessKey: ak,
    timestamp: Number(ts),
    signature: signWs(ts, ak),
  }));
});
ws.on("message", (d) => console.log(String(d)));

import hashlib, hmac, json, os, time
import websocket

WS_URL = os.environ.get("ATTESTIA_WS_URL", "ws://127.0.0.1:3001")
ACCESS_KEY = os.environ["ATTESTIA_ACCESS_KEY"]
SIGNING_SECRET = os.environ["ATTESTIA_SIGNING_SECRET"]

def sha256_hex_utf8(s: str) -> str:
    return hashlib.sha256(s.encode("utf-8")).hexdigest()

def ws_auth_payload(ts: str, access_key: str) -> str:
    ak = access_key.lower()
    path = f"/__attestia_ws__/{ak}"
    body_hash = sha256_hex_utf8("")
    return "\n".join([ts, "CONNECT", path, body_hash])

def sign_ws(ts: str, access_key: str) -> str:
    payload = ws_auth_payload(ts, access_key)
    return hmac.new(SIGNING_SECRET.encode("utf-8"), payload.encode("utf-8"), hashlib.sha256).hexdigest()

ts = str(int(time.time() * 1000))
ak = ACCESS_KEY.lower()
ws = websocket.WebSocket()
ws.connect(WS_URL)
ws.send(json.dumps({
    "type": "auth",
    "accessKey": ak,
    "timestamp": int(ts),
    "signature": sign_ws(ts, ak),
}))
while True:
    print(ws.recv())

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.WebSocket;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.HexFormat;
import java.util.Locale;
import java.util.concurrent.CompletionStage;

public class WsGatewayAuth {
  static String sha256HexUtf8(String s) throws Exception {
    byte[] h = MessageDigest.getInstance("SHA-256").digest(s.getBytes(StandardCharsets.UTF_8));
    return HexFormat.of().formatHex(h);
  }

  public static void main(String[] args) throws Exception {
    String wsUrl = System.getenv().getOrDefault("ATTESTIA_WS_URL", "ws://127.0.0.1:3001");
    String accessKey = System.getenv("ATTESTIA_ACCESS_KEY");
    String signingSecret = System.getenv("ATTESTIA_SIGNING_SECRET");
    String ts = String.valueOf(System.currentTimeMillis());
    String ak = accessKey.toLowerCase(Locale.ROOT);
    String path = "/__attestia_ws__/" + ak;
    String payload = String.join("\n", ts, "CONNECT", path, sha256HexUtf8(""));
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(signingSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
    String sig = HexFormat.of().formatHex(mac.doFinal(payload.getBytes(StandardCharsets.UTF_8)));
    String json = String.format(Locale.ROOT,
        "{\"type\":\"auth\",\"accessKey\":\"%s\",\"timestamp\":%s,\"signature\":\"%s\"}",
        ak, ts, sig);

    HttpClient.newHttpClient()
        .newWebSocketBuilder()
        .buildAsync(
            URI.create(wsUrl),
            new WebSocket.Listener() {
              @Override
              public void onOpen(WebSocket webSocket) {
                webSocket.sendText(json, true);
                WebSocket.Listener.super.onOpen(webSocket);
              }

              @Override
              public CompletionStage onText(WebSocket webSocket, CharSequence data, boolean last) {
                System.out.println(data);
                return WebSocket.Listener.super.onText(webSocket, data, last);
              }
            })
        .join();
    System.out.println("Press Enter to exit...");
    System.in.read();
  }
}

use hmac::{Hmac, Mac};
use sha2::{Digest, Sha256};
use std::env;
use tungstenite::{connect, Message};

type HmacSha256 = Hmac;

fn sha256_hex_utf8(s: &str) -> String {
    let mut h = Sha256::new();
    h.update(s.as_bytes());
    hex::encode(h.finalize())
}

fn main() -> Result<(), Box> {
    let ws_url = env::var("ATTESTIA_WS_URL").unwrap_or_else(|_| "ws://127.0.0.1:3001".into());
    let access_key = env::var("ATTESTIA_ACCESS_KEY")?;
    let signing_secret = env::var("ATTESTIA_SIGNING_SECRET")?;
    let ts = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)?
        .as_millis()
        .to_string();
    let ak = access_key.to_lowercase();
    let path = format!("/__attestia_ws__/{ak}");
    let body_hash = sha256_hex_utf8("");
    let payload = format!("{ts}\nCONNECT\n{path}\n{body_hash}");
    let mut mac = HmacSha256::new_from_slice(signing_secret.as_bytes())?;
    Mac::update(&mut mac, payload.as_bytes());
    let sig = hex::encode(mac.finalize().into_bytes());
    let ts_ms: u64 = ts.parse()?;
    let auth_json = format!(
        "{\"type\":\"auth\",\"accessKey\":\"{}\",\"timestamp\":{},\"signature\":\"{}\"}",
        ak,
        ts_ms,
        sig,
    );

    let (mut socket, _) = connect(ws_url.as_str())?;
    socket.write_message(Message::Text(auth_json))?;
    loop {
        if let Message::Text(t) = socket.read_message()? {
            println!("{t}");
        }
    }
}

Limits & errors

Attestia uses conventional HTTP status codes and JSON bodies for errors. Rate limits apply per API access key.

Rate limits

HTTP/1.1 429 Too Many Requests
Retry-After: <seconds>

{"error":"rate limit exceeded"}

HTTP status codes

Error payload

{
  "error": "human readable message"
}