API Documentation

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

Most endpoints are read-only GET requests. Responses use JSON with snake_case keys. Authenticated requests using an x-api-key header receive higher rate limits. Write endpoints require a historian session cookie.

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)

Param	Type	Description
q	string	Text search across contract name, token name, symbol, address, and decompiled code
era_id	string	frontier, homestead, dao, tangerine, spurious, byzantium
featured	string	true or 1 = featured only
undocumented_only	string	true or 1 = no short_description yet
unverified	string	1 = only contracts with no verification method set (prioritize crack candidates)
sort	string	siblings = sort by sibling count descending (most shared bytecode first, useful for crack prioritization)
limit	number	1–200, default 50
offset	number	Pagination offset, default 0

Example requests

GET https://ethereumhistory.com/api/agent/contracts?era_id=homestead&featured=true&limit=10
GET https://ethereumhistory.com/api/agent/contracts?q=MyToken&unverified=1&sort=siblings&limit=20

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

Search APIs

Additional endpoints for address lookup, unified search, and bytecode search. Same JSON response style; useful for building UIs or custom integrations.

Address search

GET/api/search?q={address}

Returns basic info for one address. q = full Ethereum address (0x + 40 hex).

Unified search

GET/api/search/unified?q={query}&page={number}

Searches across decompiled code, verified source, ABI, contract name, token name/symbol, address. Pagination: 20 per page; page default 1.

Bytecode search

GET/api/search/bytecode?q={query}&type={decompiled|bytecode|all}&limit={number}

Searches decompiled code and/or bytecode. type default all; limit max 100.

Featured contracts

Homepage-style featured contracts, recent contracts, and eras. Useful for dashboards or discovery.

GET/api/featured

{
  "data": {
    "featuredContracts": [...],
    "recentContracts": [...],
    "eras": [...]
  },
  "meta": { "timestamp": "...", "cached": false }
}

Authentication & Rate Limits

Read endpoints are publicly accessible. Providing an API key via the x-api-key header unlocks higher rate limits for historian-tier users.

Tier	Rate limit
Anonymous	20 requests / minute
Authenticated (historian tier)	120 requests / minute

Authentication header

x-api-key: eh_your_key_here

Generate API keys from your historian profile page. Keys are prefixed with eh_.

Rate limit response headers

X-RateLimit-Remaining — requests remaining in the current window
When the limit is exceeded, the API responds with 429 and a Retry-After header indicating seconds until the window resets

Siblings API

Returns contracts that share the same runtime bytecode hash as the given address. Useful for identifying deployments of the same contract template and prioritizing verification work.

GET/api/contracts/{address}/siblings

Query params: offset (default 0). Returns 100 siblings per page.

Example request

GET https://ethereumhistory.com/api/contracts/0xdbf03b407c01e7cd3cbea99509d93f8dddc8c6fb/siblings?offset=0

Response (200)

{
  "data": {
    "hash": "0xabc123...",
    "count": 42,
    "groupVerified": true,
    "groupName": "StandardToken",
    "groupContractType": "token",
    "contracts": [
      {
        "address": "0x...",
        "deployment_timestamp": "2016-08-01T12:00:00Z",
        "token_name": "Example Token",
        "token_symbol": "EXT",
        "verification_status": "verified"
      }
    ]
  },
  "meta": {
    "timestamp": "2025-02-03T12:00:00.000Z",
    "offset": 0,
    "count": 42
  }
}

ABI API

Returns the machine-readable ABI for a contract. Covers verified contracts and their bytecode siblings.

Ethereum History is the only ABI reference for contracts predating Solidity v0.4.7 (December 2016) — the era that Sourcify and other metadata-based services don't support. For contracts from this early period, ABIs are derived directly from compiler archaeology and bytecode verification.

GET/api/contract/{address}/abi

Example request

GET https://ethereumhistory.com/api/contract/0x283f1161c2d4ff33fd5d5d4486fc0675732cea11/abi

Response (200)

{
  "data": {
    "abi": "[{\"type\":\"function\",\"name\":\"sendCoin\",\"inputs\":[...],\"outputs\":[...]}]",
    "source": "direct",        // "direct" | "sibling"
    "siblingAddress": null     // address of verified sibling if source="sibling"
  },
  "error": null
}

// Returns { "data": null, "error": null } when no ABI is available

Verification Methods

The verification_method field describes how a contract's source was verified. These values appear in contract facts and write payloads.

Value	Description
exact_bytecode_match	Compiled source matches on-chain bytecode byte-for-byte
near_exact_match	Source recovered and all logic verified; a minor gap remains (e.g. metadata hash difference)
author_published_source	The original developer published the source (GitHub, blog post, etc.)
etherscan_verified	Contract is verified on Etherscan; source pulled from there

Contract Write API

Update contract documentation and verification data. Requires an active historian session cookie. This endpoint powers all historian edits on EthereumHistory.com.

POST/api/contract/{address}/history/manage

Requires a valid historian_session cookie. Historians can log in at /historian/login.

Request body (JSON)

Field	Type	Description
shortDescription	string	One-line summary of the contract
description	string	Full canonical narrative / historical summary
historicalContext	string	Surrounding historical context at deployment time
historicalSignificance	string	Why this contract matters historically
verificationMethod	string	One of the verification method values above
verificationProofUrl	string	URL linking to verification proof (GitHub repo, etc.)
verificationNotes	string	Notes about the verification process
compilerCommit	string	Git commit hash of the compiler used
compilerLanguage	string	e.g. solidity, serpent, lll
sourceCode	string	Full verified source code
verificationStatus	string	verified, unverified, partial
contractType	string	token, dao, exchange, wallet, registry, etc.

Example request

POST https://ethereumhistory.com/api/contract/0xdbf03b407c01e7cd3cbea99509d93f8dddc8c6fb/history/manage
Content-Type: application/json
Cookie: historian_session=...

{
  "shortDescription": "Early ERC-20 style token deployed on Homestead.",
  "verificationMethod": "exact_bytecode_match",
  "verificationProofUrl": "https://github.com/cartoonitunes/proof-0xdbf0",
  "compilerCommit": "67c855c5",
  "compilerLanguage": "solidity",
  "sourceCode": "contract MyToken { ... }",
  "verificationStatus": "verified",
  "contractType": "token"
}

Errors

401 — Not authenticated. Valid historian session cookie required.
404 — Contract not found.
500 — Server error.

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 Setup Back to home