Skip to main content

​
On-Chain API

Part of CLPI Phase 4: On-Chain Verification. The On-Chain API anchors reputation data to Base L2 for immutable, third-party-verifiable trust records.
The On-Chain API provides programmatic access to Mnemom’s on-chain verification system — anchoring Merkle roots, publishing reputation scores, and verifying agent trust data on Base L2. All on-chain operations are submitted via Mnemom’s relayer; you do not need to hold ETH or interact with smart contracts directly. Base URL: https://api.mnemom.ai/v1/on-chain
Anchoring and score publishing are Mnemom-operated cron jobs, not customer-callable endpoints. Customers consume on-chain data through the three read endpoints below, or by querying the smart contracts on Base L2 directly. See the On-Chain Verification guide for the operational details.

​
Authentication

EndpointAuth RequiredNotes
GET /v1/on-chain/verify-proof/{agent_id}API keyVerifies an agent’s on-chain score
GET /v1/on-chain/status/{agent_id}API keyChecks on-chain status for an agent
GET /v1/on-chain/historyAPI keyRetrieves anchoring and publishing history
API key authentication: Pass in the Authorization header: 
Authorization: Bearer {api_key}
API keys can be created in your dashboard under Settings or via POST /v1/api-keys.

​
Rate limits

EndpointRate LimitWindow
GET /on-chain/verify-proof/{agent_id}30 requestsper minute
GET /on-chain/status/{agent_id}30 requestsper minute
GET /on-chain/history30 requestsper minute
Rate-limited responses return HTTP 429 with a Retry-After header.

​
Endpoints

​
GET /v1/on-chain/verify-proof/

Verify an agent’s on-chain reputation score and retrieve the cryptographic proof linking the on-chain record to the underlying integrity data. Parameters:
ParameterInTypeRequiredDescription
agent_idpathstringYesAgent identifier
Response: 200 OK 
{
  "agent_id": "mnm-550e8400-e29b-41d4-a716-446655440000",
  "on_chain_score": 782,
  "grade": "A",
  "metadata_hash": "0x9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba",
  "published_at": "2026-02-26T10:35:00.000Z",
  "block_number": 18234589,
  "tx_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "verified": true
}
Response fields:
FieldTypeDescription
agent_idstringAgent identifier
on_chain_scorenumberScore as recorded on-chain (0-1000)
gradestringLetter grade as recorded on-chain
metadata_hashstringkeccak256 hash of the off-chain metadata at time of publication
published_atstringISO 8601 timestamp of when the score was published on-chain
block_numbernumberBlock number containing the publication transaction
tx_hashstringTransaction hash of the publication
verifiedbooleanWhether the on-chain score matches the current off-chain score and the proof is valid
Error responses:
StatusMeaning
401API key required or invalid
404Agent not found or no on-chain score exists for this agent
429Rate limit exceeded

​
GET /v1/on-chain/status/

Check whether an agent has an on-chain score and retrieve the current on-chain state, including the latest score and anchor information. Parameters:
ParameterInTypeRequiredDescription
agent_idpathstringYesAgent identifier
Response: 200 OK 
{
  "agent_id": "mnm-550e8400-e29b-41d4-a716-446655440000",
  "has_on_chain_score": true,
  "latest_score": {
    "score": 782,
    "grade": "A",
    "block_number": 18234589,
    "published_at": "2026-02-26T10:35:00.000Z"
  },
  "latest_anchor": {
    "merkle_root": "0xabc123def456789012345678901234567890123456789012345678901234abcd",
    "block_number": 18234567,
    "anchored_at": "2026-02-26T10:30:00.000Z"
  },
  "last_updated": "2026-02-26T10:35:00.000Z"
}
Response fields:
FieldTypeDescription
agent_idstringAgent identifier
has_on_chain_scorebooleanWhether this agent has at least one published on-chain score
latest_scoreobject | nullLatest on-chain score record, or null if no score exists
latest_score.scorenumberMost recent on-chain score
latest_score.gradestringMost recent on-chain grade
latest_score.block_numbernumberBlock number of the latest publication
latest_score.published_atstringTimestamp of the latest publication
latest_anchorobject | nullLatest Merkle root anchor relevant to this agent, or null
latest_anchor.merkle_rootstringThe anchored Merkle root
latest_anchor.block_numbernumberBlock number of the anchor transaction
latest_anchor.anchored_atstringTimestamp of the anchor
last_updatedstringMost recent on-chain activity timestamp for this agent
Error responses:
StatusMeaning
401API key required or invalid
404Agent not found
429Rate limit exceeded

​
GET /v1/on-chain/history

Retrieve the paginated history of on-chain anchoring and score publishing events for your account. Query parameters:
ParameterTypeRequiredDescription
pagenumberNoPage number (default: 1)
per_pagenumberNoResults per page (default: 20, max: 100)
Response: 200 OK 
{
  "anchors": [
    {
      "anchor_id": "anc-7f8a9b2c",
      "merkle_root": "0xabc123def456789012345678901234567890123456789012345678901234abcd",
      "leaf_count": 347,
      "tree_depth": 9,
      "tx_hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "block_number": 18234567,
      "anchored_at": "2026-02-26T10:30:00.000Z"
    }
  ],
  "publications": [
    {
      "publication_id": "pub-3e4f5a6b",
      "agent_count": 2,
      "tx_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
      "block_number": 18234589,
      "published_at": "2026-02-26T10:35:00.000Z"
    }
  ],
  "page": 1,
  "per_page": 20,
  "total_anchors": 42,
  "total_publications": 18
}
Response fields:
FieldTypeDescription
anchorsarrayList of Merkle root anchor events
anchors[].anchor_idstringUnique anchor identifier
anchors[].merkle_rootstringThe anchored Merkle root hash
anchors[].leaf_countnumberNumber of leaves in the tree
anchors[].tree_depthnumberDepth of the Merkle tree
anchors[].tx_hashstringTransaction hash
anchors[].block_numbernumberBlock number
anchors[].anchored_atstringISO 8601 timestamp
publicationsarrayList of score publication events
publications[].publication_idstringUnique publication identifier
publications[].agent_countnumberNumber of agents in the batch
publications[].tx_hashstringTransaction hash
publications[].block_numbernumberBlock number
publications[].published_atstringISO 8601 timestamp
pagenumberCurrent page number
per_pagenumberResults per page
total_anchorsnumberTotal anchor events across all pages
total_publicationsnumberTotal publication events across all pages
Error responses:
StatusMeaning
401API key required or invalid
429Rate limit exceeded

​
Error codes

StatusCodeDescription
400invalid_requestMissing or invalid parameters (e.g., malformed Merkle root, score out of range, invalid grade)
401unauthorizedAPI key required but not provided or invalid
404not_foundAgent not found or no on-chain data exists for the specified agent
409already_anchoredThe specified Merkle root has already been anchored on-chain
422ineligible_agentAgent does not have a computed reputation score (below 50-checkpoint minimum)
429rate_limitedToo many requests; check Retry-After header
500internal_errorServer error; retry with exponential backoff
502chain_unavailableBase L2 network is temporarily unavailable; retry after a short delay
All error responses follow the standard envelope: 
{
  "error": {
    "code": "invalid_request",
    "message": "Merkle root must be a 32-byte hex string prefixed with 0x"
  }
}

​
SDK usage

​
TypeScript

import {
  verifyOnChainScore,
  getOnChainStatus,
  getOnChainHistory,
} from '@mnemom/on-chain';

// Verify an agent's on-chain score
const proof = await verifyOnChainScore('mnm-550e8400-e29b-41d4-a716-446655440000');
console.log(`Verified: ${proof.verified}, Score: ${proof.on_chain_score}`);

// Check on-chain status
const status = await getOnChainStatus('mnm-550e8400-e29b-41d4-a716-446655440000');
console.log(`Has on-chain score: ${status.has_on_chain_score}`);

// View history
const history = await getOnChainHistory({ page: 1, perPage: 20 });
console.log(`Total anchors: ${history.total_anchors}`);
console.log(`Total publications: ${history.total_publications}`);

​
Python

import httpx

API_BASE = "https://api.mnemom.ai"
HEADERS = {"Authorization": f"Bearer {api_key}"}

# Verify an agent's on-chain score
proof = httpx.get(
    f"{API_BASE}/v1/on-chain/verify-proof/mnm-550e8400-e29b-41d4-a716-446655440000",
    headers=HEADERS,
).json()
print(f"Verified: {proof['verified']}, Score: {proof['on_chain_score']}")

# Check on-chain status
status = httpx.get(
    f"{API_BASE}/v1/on-chain/status/mnm-550e8400-e29b-41d4-a716-446655440000",
    headers=HEADERS,
).json()
print(f"Has on-chain score: {status['has_on_chain_score']}")

# View history
history = httpx.get(
    f"{API_BASE}/v1/on-chain/history",
    headers=HEADERS,
    params={"page": 1, "per_page": 20},
).json()
print(f"Total anchors: {history['total_anchors']}")
print(f"Total publications: {history['total_publications']}")

​
See also