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

Endpoint	Auth Required	Notes
`GET /v1/on-chain/verify-proof/{agent_id}`	API key	Verifies an agent’s on-chain score
`GET /v1/on-chain/status/{agent_id}`	API key	Checks on-chain status for an agent
`GET /v1/on-chain/history`	API key	Retrieves 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

Endpoint	Rate Limit	Window
`GET /on-chain/verify-proof/{agent_id}`	30 requests	per minute
`GET /on-chain/status/{agent_id}`	30 requests	per minute
`GET /on-chain/history`	30 requests	per 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:

Parameter	In	Type	Required	Description
`agent_id`	path	string	Yes	Agent 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:

Field	Type	Description
`agent_id`	string	Agent identifier
`on_chain_score`	number	Score as recorded on-chain (0-1000)
`grade`	string	Letter grade as recorded on-chain
`metadata_hash`	string	keccak256 hash of the off-chain metadata at time of publication
`published_at`	string	ISO 8601 timestamp of when the score was published on-chain
`block_number`	number	Block number containing the publication transaction
`tx_hash`	string	Transaction hash of the publication
`verified`	boolean	Whether the on-chain score matches the current off-chain score and the proof is valid

Error responses:

Status	Meaning
`401`	API key required or invalid
`404`	Agent not found or no on-chain score exists for this agent
`429`	Rate 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:

Parameter	In	Type	Required	Description
`agent_id`	path	string	Yes	Agent 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:

Field	Type	Description
`agent_id`	string	Agent identifier
`has_on_chain_score`	boolean	Whether this agent has at least one published on-chain score
`latest_score`	object \| null	Latest on-chain score record, or `null` if no score exists
`latest_score.score`	number	Most recent on-chain score
`latest_score.grade`	string	Most recent on-chain grade
`latest_score.block_number`	number	Block number of the latest publication
`latest_score.published_at`	string	Timestamp of the latest publication
`latest_anchor`	object \| null	Latest Merkle root anchor relevant to this agent, or `null`
`latest_anchor.merkle_root`	string	The anchored Merkle root
`latest_anchor.block_number`	number	Block number of the anchor transaction
`latest_anchor.anchored_at`	string	Timestamp of the anchor
`last_updated`	string	Most recent on-chain activity timestamp for this agent

Error responses:

Status	Meaning
`401`	API key required or invalid
`404`	Agent not found
`429`	Rate limit exceeded

GET /v1/on-chain/history

Retrieve the paginated history of on-chain anchoring and score publishing events for your account. Query parameters:

Parameter	Type	Required	Description
`page`	number	No	Page number (default: 1)
`per_page`	number	No	Results 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:

Field	Type	Description
`anchors`	array	List of Merkle root anchor events
`anchors[].anchor_id`	string	Unique anchor identifier
`anchors[].merkle_root`	string	The anchored Merkle root hash
`anchors[].leaf_count`	number	Number of leaves in the tree
`anchors[].tree_depth`	number	Depth of the Merkle tree
`anchors[].tx_hash`	string	Transaction hash
`anchors[].block_number`	number	Block number
`anchors[].anchored_at`	string	ISO 8601 timestamp
`publications`	array	List of score publication events
`publications[].publication_id`	string	Unique publication identifier
`publications[].agent_count`	number	Number of agents in the batch
`publications[].tx_hash`	string	Transaction hash
`publications[].block_number`	number	Block number
`publications[].published_at`	string	ISO 8601 timestamp
`page`	number	Current page number
`per_page`	number	Results per page
`total_anchors`	number	Total anchor events across all pages
`total_publications`	number	Total publication events across all pages

Error responses:

Status	Meaning
`401`	API key required or invalid
`429`	Rate limit exceeded

Error codes

Status	Code	Description
`400`	`invalid_request`	Missing or invalid parameters (e.g., malformed Merkle root, score out of range, invalid grade)
`401`	`unauthorized`	API key required but not provided or invalid
`404`	`not_found`	Agent not found or no on-chain data exists for the specified agent
`409`	`already_anchored`	The specified Merkle root has already been anchored on-chain
`422`	`ineligible_agent`	Agent does not have a computed reputation score (below 50-checkpoint minimum)
`429`	`rate_limited`	Too many requests; check `Retry-After` header
`500`	`internal_error`	Server error; retry with exponential backoff
`502`	`chain_unavailable`	Base 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']}")

​On-Chain API

​Authentication

​Rate limits

​Endpoints

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

​GET /v1/on-chain/status/

​GET /v1/on-chain/history

​Error codes

​SDK usage

​TypeScript

​Python

​See also

On-Chain API

Authentication

Rate limits

Endpoints

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

GET /v1/on-chain/status/

GET /v1/on-chain/history

Error codes

SDK usage

TypeScript

Python

See also