Ethereum History
BrowseFor Agents
Back to home

API Documentation

Ethereum History — read-only historical contract data for agents and developers

All endpoints are GET only. No authentication required. Responses use JSON with snake_case keys.

Base URL

https://ethereumhistory.com

Manifest

Machine-readable skill manifest: capabilities, endpoints, and terms. Use this to register Ethereum History as a skill or MCP server.

GET/api/agent/manifest

No query parameters.

Response (200)

{
  "name": "Ethereum History",
  "id": "ethereumhistory",
  "description": "Historical contract data and documentation...",
  "version": "1.0",
  "base_url": "https://ethereumhistory.com",
  "capabilities": ["contract_facts", "discovery", "temporal_queries"],
  "endpoints": [
    {
      "capability": "contract_facts",
      "method": "GET",
      "path": "/api/agent/contracts/{address}",
      "description": "Factual contract data for one address..."
    },
    ...
  ],
  "terms": "Read-only. No opinions or editorial stance..."
}

Contract facts (one address)

Full factual data for a single contract: address, era, deployer, deployment block/timestamp, runtime_bytecode, decompiled_code (when available), short_description, description (canonical narrative; historical_summary mirrors it for API compatibility), historical_significance, historical_context, token metadata, heuristics, links, metadata.

GET/api/agent/contracts/{address}

Path: address — Ethereum address (0x + 40 hex chars). Required.

Example request

GET https://ethereumhistory.com/api/agent/contracts/0xdbf03b407c01e7cd3cbea99509d93f8dddc8c6fb

Response (200)

{
  "data": {
    "address": "0x...",
    "era_id": "homestead",
    "era": {
      "id": "homestead",
      "name": "Homestead",
      "start_block": 1150000,
      "end_block": 1920000,
      "start_date": "2016-03-14",
      "end_date": "2016-09-22"
    },
    "deployer_address": "0x...",
    "deployment_tx_hash": "0x...",
    "deployment_block": 1234567,
    "deployment_timestamp": "2016-08-01T12:00:00Z",
    "runtime_bytecode": "0x60806040...",
    "decompiled_code": "// Decompiled source...",
    "decompilation_success": true,
    "code_size_bytes": 1234,
    "gas_used": 500000,
    "gas_price": "20000000000",
    "heuristics": {
      "contract_type": "token",
      "confidence": 0.9,
      "is_proxy": false,
      "has_selfdestruct": false,
      "is_erc20_like": true
    },
    "ens_name": null,
    "deployer_ens_name": null,
    "etherscan_contract_name": "MyToken",
    "etherscan_verified": true,
    "token_name": "Example Token",
    "token_symbol": "EXT",
    "token_decimals": 18,
    "short_description": "Early ERC-20 style token...",
    "description": "...",
    "historical_summary": "... (same as description; deprecated, use description)",
    "historical_significance": "...",
    "historical_context": "...",
    "verification_status": "verified",
    "links": [{ "id": 1, "title": "...", "url": "...", "source": null, "note": null, "created_at": "..." }],
    "metadata": [{ "key": "...", "value": "...", "json_value": null, "source_url": null, "created_at": "..." }]
  },
  "meta": { "timestamp": "2025-02-03T12:00:00.000Z", "cached": false }
}

Errors

  • 400 — Invalid address format. Body: { "error": "Invalid Ethereum address format..." }
  • 404 — Contract not found. Body: { "error": "Contract not found in our historical archive." }
  • 500 — Server error.

Discovery (list contracts)

List contracts with optional filters. Returns minimal fields for discovery; fetch full facts via the contract-by-address endpoint when needed.

GET/api/agent/contracts

Query parameters (all optional)

ParamTypeDescription
era_idstringfrontier, homestead, dao, tangerine, spurious
featuredstringtrue or 1 = featured only
undocumented_onlystringtrue or 1 = no short_description yet
limitnumber1–200, default 50
offsetnumberPagination offset, default 0

Example request

GET https://ethereumhistory.com/api/agent/contracts?era_id=homestead&featured=true&limit=10

Response (200)

{
  "data": [
    {
      "address": "0x...",
      "era_id": "homestead",
      "deployer_address": "0x...",
      "deployment_timestamp": "2016-08-01T12:00:00Z",
      "has_short_description": true,
      "decompilation_success": true,
      "etherscan_contract_name": "MyToken",
      "token_name": "Example Token",
      "token_symbol": "EXT"
    }
  ],
  "meta": {
    "timestamp": "2025-02-03T12:00:00.000Z",
    "cached": false,
    "limit": 10,
    "offset": 0,
    "count": 10
  }
}

Temporal queries (by time range)

Same endpoint as discovery. Add from_timestamp and/or to_timestamp (ISO 8601) to filter by deployment time.

GET/api/agent/contracts

Query params: from_timestamp, to_timestamp (ISO 8601), plus era_id, limit, offset.

GET https://ethereumhistory.com/api/agent/contracts?from_timestamp=2015-07-30T00:00:00Z&to_timestamp=2016-12-31T23:59:59Z&limit=50

Usage notes

  • Read-only. No opinions or editorial stance. Data as documented on EthereumHistory.com.
  • Factual only. What something is and is not. No hype or persuasion.
  • When history (short_description, etc.) is not yet documented, contract facts still include runtime_bytecode and decompiled_code when available.
  • For the full machine-readable manifest, call GET https://ethereumhistory.com/api/agent/manifest.
MCP SetupBack to home