EI
EthIntel
EthIntel API
Interactive REST reference
Interactive API Docs

Build against the EthIntel REST API without guessing what any endpoint returns.

This page documents the complete EthIntel surface: transaction explainers, address intelligence, validator and network analytics, operational utility endpoints, API key management, and the Telegram webhook. Every example is hardcoded and interactive, with no live API calls.

Base URL https://ethintel.io
Explain and scan
Narratives, SSE progress streams, and pre-sign simulations for wallet and dashboard UX.
Validator and network data
Beacon validator detail, rewards, duties, tax exports, slashings, and network-wide snapshots.
Operationally explicit
Authentication, rate limits, response headers, and per-endpoint error codes are documented upfront.
Explain Playground

Interactive GET /api/explain/{txHash} playground

The controls below update the example request and mock response without making any network calls. The same state also drives the explain examples in the right-hand rail.

Request controls
Public endpoints accept anonymous requests, but bearer auth raises your rate window.
Detected chain
ethereum (sample)
Narration depth
Standard
Rate window
Plan-specific
Preview
Request and response tabs stay synchronized with the current playground state.
cURL
GET /api/explain/{txHash}
curl "https://ethintel.io/api/explain/0x8f3d0f63b3a948321f1b2291e5a8dd3c3df5cc9fd0c8ff9d132d91b2c1e9bc45" \
  --header "Authorization: Bearer ei_live_demo_A9x32kLmQz" \
  --header "Accept: application/json"
Headers
Authorization: Bearer ei_live_demo_A9x32kLmQz
Accept: application/json
Authentication

Bearer token auth with public fallback

All public endpoints accept an optional Authorization: Bearer ei_live_... header. When omitted, the request still works under the anonymous rate window. The protected /api/user/api-key endpoint requires authentication.

Public endpoints
Use auth when you need higher throughput, plan attribution, or clean request ownership.

Public routes include explain, address, scan, validator, network, and utility reads.

Without a bearer token, requests fall back to the anonymous rate window.

Protected endpoints
Key management is tied to the authenticated user and always requires a valid bearer token.

The API key CRUD endpoint returns 401 when the token is missing or invalid.

Secrets should be stored server-side or injected through a trusted client environment.

cURL
Bearer token example
curl "https://ethintel.io/api/explain/0x8f3d0f63b3a948321f1b2291e5a8dd3c3df5cc9fd0c8ff9d132d91b2c1e9bc45" \
  --header "Authorization: Bearer ei_live_demo_A9x32kLmQz" \
  --header "Accept: application/json"
Rate Limits

Plan-aware request windows

PlanMinute windowDaily allowanceNotes
Anonymous10/minShared unauthenticated pool for public exploration.
Free10/min5/dayGood for quick wallet and dashboard prototypes.
Consumer60/minUnlimitedFor personal monitoring and embedded client apps.
Pro120/minUnlimitedFor serious operators with higher sustained concurrency.
API600/minUnlimitedBest for production backends and partner integrations.
Response Headers

Headers worth surfacing in your own tooling

HeaderExampleMeaning
X-Request-Idreq_01JTV2QG6M3R1S1AStable support correlation id for logs, tracing, and tickets.
X-RateLimit-Limit60Requests allowed in the current rolling window.
X-RateLimit-Remaining17Remaining requests in the current rate-limit window.
X-RateLimit-Reset1741981020Unix timestamp when the minute window resets.
X-ChainethereumResolved chain for explain, address, and risk workflows.
Cache-Controlpublic, immutable, max-age=31536000Immutable explain responses can be cached aggressively.
Error Codes

Standard HTTP error semantics

Error codes
Stable HTTP semantics you should expect from this endpoint.
StatusCodeMeaning
400BAD_REQUESTMalformed hash, address, query, or JSON payload.
404NOT_FOUNDThe requested transaction, address, validator, or resource was not found.
429RATE_LIMITEDThe caller exhausted the current minute window.
500INTERNAL_ERRORUnexpected server-side exception in the request pipeline.
503SERVICE_UNAVAILABLEUpstream RPC, AI, or data dependencies are temporarily unavailable.
GET

/api/explain/{txHash}

AI transaction explanation

Explain any supported EVM transaction with decoded actions, asset flows, and safety context.

GETPublic + Bearer

Explain a transaction

Returns a structured transaction narrative with protocol labeling, asset movement summaries, gas detail, and risk signals.

If `chain` is omitted, EthIntel probes supported chains until the transaction is found.
Code examples
Generated from the same hardcoded sample data that powers the desktop code rail.
cURL
GET /api/explain/{txHash}
curl "https://ethintel.io/api/explain/0x8f3d0f63b3a948321f1b2291e5a8dd3c3df5cc9fd0c8ff9d132d91b2c1e9bc45" \
  --header "Authorization: Bearer ei_live_demo_A9x32kLmQz" \
  --header "Accept: application/json"
Resolved request URL
https://ethintel.io/api/explain/0x8f3d0f63b3a948321f1b2291e5a8dd3c3df5cc9fd0c8ff9d132d91b2c1e9bc45
Path parameters
NameTypeRequiredDescription
txHashstringRequired
0x-prefixed transaction hash.
Query parameters
NameTypeRequiredDescription
chain"ethereum" | "base" | "arbitrum" | "optimism" | "polygon"Optional
Optional chain override or enrichment context.
level"simple" | "standard" | "technical"Optional
Controls the detail level of the narration.
Default: "standard"
200
TransactionExplanation
Structured explanation tuned for wallets, dashboards, and analyst tooling.
TransactionExplanation schema
txHash
stringTransaction hash that was analyzed.
chain
"ethereum" | "base" | "arbitrum" | "optimism" | "polygon"Resolved chain for the request.
level
"simple" | "standard" | "technical"Narration depth.
status
"success" | "reverted" | "pending"Execution result.
category
stringHigh-level intent such as swap or approval.
protocol
string | nullResolved protocol or dapp brand.
action
stringCompact action description.
headline
stringOne-line summary for UI surfaces.
detail
stringHuman explanation using the selected level.
used
stringGas used by execution.
totalFeeEth
stringTotal fee paid in ETH.
totalFeeUsd
number | nullApproximate USD value for the fee.
score
numberNormalized risk score from 0 to 100.
level
"low" | "medium" | "high"Risk band.
requestId
stringSupport correlation id.
cached
booleanTrue when the explanation was served from immutable cache.
JSON
200 example
{
  "txHash": "0x8f3d0f63b3a948321f1b2291e5a8dd3c3df5cc9fd0c8ff9d132d91b2c1e9bc45",
  "chain": "ethereum",
  "level": "standard",
  "status": "success",
  "classification": {
    "category": "swap",
    "protocol": "Uniswap V3",
    "action": "Swap ETH for USDC"
  },
  "summary": {
    "headline": "Swapped 1.2 ETH for 3,861.44 USDC.",
    "detail": "The signer sent 1.2 ETH into the Uniswap V3 router, which wrapped the asset into WETH and traded it for 3,861.44 USDC. The trade completed normally, paid 0.0080 ETH in gas, and returned the USDC to the originating wallet."
  },
  "assets": {
    "sent": [
      {
        "symbol": "ETH",
        "amount": "1.2",
        "destination": "Uniswap V3 Router"
      }
    ],
    "received": [
      {
        "symbol": "USDC",
        "amount": "3861.44",
        "source": "Uniswap V3 Pool"
      }
    ]
  },
  "gas": {
    "used": "192843",
    "totalFeeEth": "0.008021",
    "totalFeeUsd": 27.01
  },
  "risk": {
    "score": 21,
    "level": "low",
    "signals": [
      {
        "severity": "info",
        "code": "KNOWN_PROTOCOL",
        "message": "The primary contract is a labeled Uniswap V3 router."
      },
      {
        "severity": "info",
        "code": "STANDARD_SWAP_FLOW",
        "message": "The transaction flow matches a common single-hop swap path."
      }
    ]
  },
  "requestId": "req_01JTV2QG6M3R1S1A",
  "cached": true
}
Error codes
Stable HTTP semantics you should expect from this endpoint.
StatusCodeMeaning
400BAD_REQUESTThe request payload or parameters are invalid.
404NOT_FOUNDThe transaction hash was not found on the requested or auto-detected chain.
429RATE_LIMITEDToo many requests for the current minute window.
500INTERNAL_ERRORUnexpected server-side exception.
503SERVICE_UNAVAILABLEOne or more upstream dependencies are unavailable.
GET

/api/explain/{txHash}/stream

Explain stream

Subscribe to pipeline progress over SSE while the explanation is being assembled.

GETPublic + Bearer

Stream explanation progress

Use SSE when you want visible progress updates for decoding, safety analysis, narration, and completion.

Code examples
Generated from the same hardcoded sample data that powers the desktop code rail.
cURL
GET /api/explain/{txHash}/stream
curl -N "https://ethintel.io/api/explain/0x8f3d0f63b3a948321f1b2291e5a8dd3c3df5cc9fd0c8ff9d132d91b2c1e9bc45/stream" \
  --header "Authorization: Bearer ei_live_demo_A9x32kLmQz" \
  --header "Accept: text/event-stream"
Resolved request URL
https://ethintel.io/api/explain/0x8f3d0f63b3a948321f1b2291e5a8dd3c3df5cc9fd0c8ff9d132d91b2c1e9bc45/stream
Path parameters
NameTypeRequiredDescription
txHashstringRequired
0x-prefixed transaction hash.
Query parameters
NameTypeRequiredDescription
chain"ethereum" | "base" | "arbitrum" | "optimism" | "polygon"Optional
Optional chain override or enrichment context.
level"simple" | "standard" | "technical"Optional
Controls the detail level of the narration.
Default: "standard"
Stream events
Each event is a discrete progress signal emitted by the SSE pipeline.
EventMeaning
statusInitial progress update for the request.
decodedDecoded calldata and first structural facts.
safetyRisk analysis and labeled counterparties.
narrationHuman-readable explanation segments.
completeTerminal event containing the full explanation.
errorTerminal failure event with an error payload.
200
ExplainStreamEvent
SSE event frames for the explain pipeline.
ExplainStreamEvent schema
event
stringSSE event name.
stage
stringPipeline stage name.
progress
numberApproximate percentage complete.
message
stringStage summary.
payload
object | nullOptional stage-specific payload.
Text
200 example
{
  "event": "decoded",
  "data": {
    "stage": "decode",
    "progress": 42,
    "message": "Decoded calldata and mapped the router call.",
    "payload": {
      "function": "exactInputSingle",
      "protocol": "Uniswap V3"
    }
  }
}
Error codes
Stable HTTP semantics you should expect from this endpoint.
StatusCodeMeaning
400BAD_REQUESTThe request payload or parameters are invalid.
429RATE_LIMITEDToo many requests for the current minute window.
500INTERNAL_ERRORUnexpected server-side exception.
503SERVICE_UNAVAILABLEOne or more upstream dependencies are unavailable.
GET

/api/address/{address}

Address profile

Resolve an address or ENS name into an enriched profile with labels, activity, and safety context.

GETPublic + Bearer

Fetch an address profile

Returns identity, balance context, activity snapshots, top interactions, and a compact risk assessment.

Code examples
Generated from the same hardcoded sample data that powers the desktop code rail.
cURL
GET /api/address/{address}
curl "https://ethintel.io/api/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?chain=ethereum" \
  --header "Authorization: Bearer ei_live_demo_A9x32kLmQz" \
  --header "Accept: application/json"
Resolved request URL
https://ethintel.io/api/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?chain=ethereum
Path parameters
NameTypeRequiredDescription
addressstringRequired
0x-prefixed address or ENS name where supported.
Query parameters
NameTypeRequiredDescription
chain"ethereum" | "base" | "arbitrum" | "optimism" | "polygon"Optional
Optional chain override or enrichment context.
200
AddressProfile
Enriched wallet or contract profile.
AddressProfile schema
address
stringCanonical 0x address.
chain
stringChain context used for enrichment.
ens
string | nullResolved ENS name.
label
string | nullKnown label or display name.
category
stringEntity class such as individual, protocol, or exchange.
balancesUsd
numberApproximate total tracked asset balance in USD.
txCount
numberTransactions observed in the last 30 days.
activeDays
numberDays with at least one transaction.
lastTxHash
string | nullMost recent observed transaction.
address
stringFrequently interacted contract or wallet.
label
string | nullResolved label.
count
numberInteraction count in the recent lookback window.
item
stringDescriptive tag applied by the labeling system.
score
numberNormalized safety score for the address.
level
"low" | "medium" | "high"Risk band.
JSON
200 example
{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "chain": "ethereum",
  "ens": "vitalik.eth",
  "label": "Vitalik Buterin",
  "category": "individual",
  "balancesUsd": 2528613.68,
  "activity30d": {
    "txCount": 31,
    "activeDays": 11,
    "lastTxHash": "0x29f1a5c4f612329c38ef2d3b67bc912f84f6f458f9ae34ef6dcd8e01b7145bb8"
  },
  "topInteractions": [
    {
      "address": "0xE592427A0AEce92De3Edee1F18E0157C05861564",
      "label": "Uniswap V3 Router",
      "count": 7
    }
  ],
  "tags": [
    "public-figure",
    "dao-participant",
    "contract-deployer"
  ],
  "risk": {
    "score": 11,
    "level": "low",
    "signals": [
      {
        "severity": "info",
        "code": "KNOWN_ENTITY",
        "message": "This address matches a known public identity."
      }
    ]
  }
}
Error codes
Stable HTTP semantics you should expect from this endpoint.
StatusCodeMeaning
400BAD_REQUESTThe request payload or parameters are invalid.
404NOT_FOUNDThe requested resource does not exist.
429RATE_LIMITEDToo many requests for the current minute window.
500INTERNAL_ERRORUnexpected server-side exception.
503SERVICE_UNAVAILABLEOne or more upstream dependencies are unavailable.
GET

/api/address/{address}/stream

Address stream

Receive address enrichment stages as SSE events while the profile is assembled.

GETPublic + Bearer

Stream address analysis progress

Designed for interfaces that want progressive address enrichment updates instead of waiting on a single response.

Code examples
Generated from the same hardcoded sample data that powers the desktop code rail.
cURL
GET /api/address/{address}/stream
curl -N "https://ethintel.io/api/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/stream?chain=ethereum" \
  --header "Authorization: Bearer ei_live_demo_A9x32kLmQz" \
  --header "Accept: text/event-stream"
Resolved request URL
https://ethintel.io/api/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/stream?chain=ethereum
Path parameters
NameTypeRequiredDescription
addressstringRequired
0x-prefixed address or ENS name where supported.
Query parameters
NameTypeRequiredDescription
chain"ethereum" | "base" | "arbitrum" | "optimism" | "polygon"Optional
Optional chain override or enrichment context.
Stream events
Each event is a discrete progress signal emitted by the SSE pipeline.
EventMeaning
statusRequest accepted and profiling started.
profileCore identity and balance enrichment completed.
riskRisk and labeling analysis completed.
activityRecent activity snapshot completed.
completeFinal consolidated profile payload.
errorTerminal error event.
200
AddressStreamEvent
SSE event frames for address analysis.
AddressStreamEvent schema
event
stringSSE event name.
stage
stringPipeline stage name.
progress
numberApproximate percentage complete.
message
stringStage summary.
payload
object | nullOptional stage-specific payload.
Text
200 example
{
  "event": "risk",
  "data": {
    "stage": "risk",
    "progress": 76,
    "message": "Risk and labeling analysis completed.",
    "payload": {
      "score": 11,
      "level": "low"
    }
  }
}
Error codes
Stable HTTP semantics you should expect from this endpoint.
StatusCodeMeaning
400BAD_REQUESTThe request payload or parameters are invalid.
404NOT_FOUNDThe requested resource does not exist.
429RATE_LIMITEDToo many requests for the current minute window.
500INTERNAL_ERRORUnexpected server-side exception.
503SERVICE_UNAVAILABLEOne or more upstream dependencies are unavailable.
POST

/api/scan

Pre-signing simulation

Simulate a transaction before signing and return a verdict, approvals, and risk signals.

POSTPublic + Bearer

Scan an unsigned transaction

Useful for wallet confirmation screens, browser extensions, and automated transaction review pipelines.

Code examples
Generated from the same hardcoded sample data that powers the desktop code rail.
cURL
POST /api/scan
curl -X POST "https://ethintel.io/api/scan" \
  --header "Authorization: Bearer ei_live_demo_A9x32kLmQz" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "transaction": {
      "from": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
      "to": "0x4F5fB3cA6dE8E5F39bC4174d5Dd5C0F5F135F4A1",
      "data": "0x095ea7b30000000000000000000000004f5fb3ca6de8e5f39bc4174d5dd5c0f5f135f4a1ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
      "value": "0",
      "chainId": 1
    },
    "typedData": null
  }'
Resolved request URL
https://ethintel.io/api/scan
Request body
Submit the raw transaction and optional typed data for phishing-aware signing analysis.
JSON body schema
from
stringOriginating account.
to
stringTarget contract or recipient.
data
string | nullCalldata hex string.
value
stringNative value in wei.
chainId
numberExecution chain id.
domain
object | nullEIP-712 domain object when present.
types
object | nullEIP-712 type definitions.
primaryType
string | nullPrimary type name.
message
object | nullTyped message payload.
JSON
Sample request body
{
  "transaction": {
    "from": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "to": "0x4F5fB3cA6dE8E5F39bC4174d5Dd5C0F5F135F4A1",
    "data": "0x095ea7b30000000000000000000000004f5fb3ca6de8e5f39bc4174d5dd5c0f5f135f4a1ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
    "value": "0",
    "chainId": 1
  },
  "typedData": null
}
200
ScanResult
Simulation and safety verdict for the proposed action.
ScanResult schema
verdict
"allow" | "warn" | "block"Signing recommendation.
summary
stringShort user-facing explanation.
success
booleanTrue if the simulation executed.
nativeDiffEth
stringNet native asset delta for the signer.
gasEstimate
stringEstimated gas usage.
score
numberNormalized risk score.
level
"low" | "medium" | "high"Risk band.
item
stringSpecific action the user should consider.
JSON
200 example
{
  "verdict": "warn",
  "summary": "This approval grants unlimited USDC spend to an unlabeled contract.",
  "simulation": {
    "success": true,
    "nativeDiffEth": "0",
    "gasEstimate": "68421",
    "assetChanges": [],
    "approvals": [
      {
        "token": "USDC",
        "spender": "0x4F5fB3cA6dE8E5F39bC4174d5Dd5C0F5F135F4A1",
        "allowance": "unlimited"
      }
    ]
  },
  "risk": {
    "score": 72,
    "level": "high",
    "signals": [
      {
        "severity": "critical",
        "code": "UNLIMITED_APPROVAL_UNKNOWN_SPENDER",
        "message": "The spender receives an unlimited approval and is not confidently labeled."
      }
    ]
  },
  "recommendations": [
    "Verify the spender contract independently before signing.",
    "Prefer a bounded allowance instead of an unlimited approval."
  ]
}
Error codes
Stable HTTP semantics you should expect from this endpoint.
StatusCodeMeaning
400BAD_REQUESTThe request payload or parameters are invalid.
429RATE_LIMITEDToo many requests for the current minute window.
500INTERNAL_ERRORUnexpected server-side exception.
503SERVICE_UNAVAILABLEOne or more upstream dependencies are unavailable.
GET

/api/risk/{address}

Risk assessment

Return a compact risk score and machine-readable signals for an address.

GETPublic + Bearer

Assess address safety

A lightweight endpoint for badges, banners, approval warnings, and policy engines.

Code examples
Generated from the same hardcoded sample data that powers the desktop code rail.
cURL
GET /api/risk/{address}
curl "https://ethintel.io/api/risk/0x4F5fB3cA6dE8E5F39bC4174d5Dd5C0F5F135F4A1" \
  --header "Authorization: Bearer ei_live_demo_A9x32kLmQz" \
  --header "Accept: application/json"
Resolved request URL
https://ethintel.io/api/risk/0x4F5fB3cA6dE8E5F39bC4174d5Dd5C0F5F135F4A1
Path parameters
NameTypeRequiredDescription
addressstringRequired
0x-prefixed address or ENS name where supported.
200
RiskAssessment
Compact address risk payload.
RiskAssessment schema
address
stringAddress being assessed.
score
numberNormalized safety score.
level
"low" | "medium" | "high"Risk band.
category
stringResolved address category.
lastUpdated
stringISO-8601 update timestamp.
severity
"info" | "warning" | "critical"Signal severity band.
code
stringStable machine-readable reason code.
message
stringHuman-readable explanation of the signal.
JSON
200 example
{
  "address": "0x4F5fB3cA6dE8E5F39bC4174d5Dd5C0F5F135F4A1",
  "score": 87,
  "level": "high",
  "category": "unknown",
  "lastUpdated": "2026-03-14T19:32:04Z",
  "signals": [
    {
      "severity": "critical",
      "code": "UNLABELED_APPROVAL_TARGET",
      "message": "This address commonly appears as an unlabeled approval spender."
    },
    {
      "severity": "warning",
      "code": "RECENT_COMPLAINT_CLUSTER",
      "message": "User complaints referencing this address increased in the last 7 days."
    }
  ]
}
Error codes
Stable HTTP semantics you should expect from this endpoint.
StatusCodeMeaning
400BAD_REQUESTThe request payload or parameters are invalid.
404NOT_FOUNDThe requested resource does not exist.
429RATE_LIMITEDToo many requests for the current minute window.
500INTERNAL_ERRORUnexpected server-side exception.
503SERVICE_UNAVAILABLEOne or more upstream dependencies are unavailable.
GET

/api/validator/{id}

Validator detail

Inspect a validator’s status, balances, uptime, and withdrawal address.

GETPublic + Bearer

Fetch validator detail

Returns identity and operational metadata for a single beacon validator.

Code examples
Generated from the same hardcoded sample data that powers the desktop code rail.
cURL
GET /api/validator/{id}
curl "https://ethintel.io/api/validator/204321" \
  --header "Authorization: Bearer ei_live_demo_A9x32kLmQz" \
  --header "Accept: application/json"
Resolved request URL
https://ethintel.io/api/validator/204321
Path parameters
NameTypeRequiredDescription
idstring | numberRequired
Validator index or canonical validator identifier.
200
ValidatorDetail
Beacon validator summary and operational context.
ValidatorDetail schema
validatorIndex
numberBeacon chain validator index.
pubkey
stringValidator BLS public key.
status
stringCurrent beacon status.
activationEpoch
numberActivation epoch.
withdrawalAddress
stringResolved withdrawal credential address.
effectiveBalanceEth
numberEffective balance in ETH.
uptime30d
numberAvailability percentage over the last 30 days.
apr
numberEstimated annualized return.
mevRelay
string | nullPrimary MEV relay if observed.
slashed
booleanWhether the validator has been slashed.
JSON
200 example
{
  "validatorIndex": 204321,
  "pubkey": "0x8cdd9d3cb8f1c7f1d4784d1cfd019ba9226c0b7617daef0dca7c41e9e28f7030",
  "status": "active_ongoing",
  "activationEpoch": 174322,
  "withdrawalAddress": "0x91bB2aBC4459d1F21f5c8A7cA2B22A2aF1B0e5D1",
  "effectiveBalanceEth": 32,
  "uptime30d": 99.63,
  "apr": 3.74,
  "mevRelay": "ultrasound",
  "slashed": false
}
Error codes
Stable HTTP semantics you should expect from this endpoint.
StatusCodeMeaning
400BAD_REQUESTThe request payload or parameters are invalid.
404NOT_FOUNDThe requested resource does not exist.
429RATE_LIMITEDToo many requests for the current minute window.
500INTERNAL_ERRORUnexpected server-side exception.
503SERVICE_UNAVAILABLEOne or more upstream dependencies are unavailable.
GET

/api/validator/{id}/rewards

Epoch rewards

Return recent epoch-by-epoch rewards for a validator.

GETPublic + Bearer

Fetch validator rewards

Useful for performance dashboards, accounting exports, and operator summaries.

Code examples
Generated from the same hardcoded sample data that powers the desktop code rail.
cURL
GET /api/validator/{id}/rewards
curl "https://ethintel.io/api/validator/204321/rewards?fromEpoch=248300&toEpoch=248302" \
  --header "Authorization: Bearer ei_live_demo_A9x32kLmQz" \
  --header "Accept: application/json"
Resolved request URL
https://ethintel.io/api/validator/204321/rewards?fromEpoch=248300&toEpoch=248302
Path parameters
NameTypeRequiredDescription
idstring | numberRequired
Validator index or canonical validator identifier.
Query parameters
NameTypeRequiredDescription
fromEpochnumberOptional
Inclusive starting epoch.
toEpochnumberOptional
Inclusive ending epoch.
limitnumberOptional
Max rows to return.
Default: 10
200
ValidatorRewards
Epoch reward rows plus a rolling total.
ValidatorRewards schema
validatorIndex
numberBeacon validator index.
currency
"ETH"Rewards currency.
epoch
numberReward epoch.
proposer
numberProposer reward in ETH.
attestation
numberAttestation reward in ETH.
sync
numberSync committee reward in ETH.
total
numberTotal epoch reward in ETH.
total30d
numberTotal rewards across the last 30 days.
JSON
200 example
{
  "validatorIndex": 204321,
  "currency": "ETH",
  "rows": [
    {
      "epoch": 248300,
      "proposer": 0,
      "attestation": 0.00318,
      "sync": 0,
      "total": 0.00318
    },
    {
      "epoch": 248301,
      "proposer": 0,
      "attestation": 0.00321,
      "sync": 0,
      "total": 0.00321
    },
    {
      "epoch": 248302,
      "proposer": 0,
      "attestation": 0.00342,
      "sync": 0,
      "total": 0.00342
    }
  ],
  "total30d": 0.9124
}
Error codes
Stable HTTP semantics you should expect from this endpoint.
StatusCodeMeaning
400BAD_REQUESTThe request payload or parameters are invalid.
404NOT_FOUNDThe requested resource does not exist.
429RATE_LIMITEDToo many requests for the current minute window.
500INTERNAL_ERRORUnexpected server-side exception.
503SERVICE_UNAVAILABLEOne or more upstream dependencies are unavailable.
GET

/api/validator/{id}/score

Validator scoring

Return a composite operator score with human-readable reasons.

GETPublic + Bearer

Fetch validator score

Designed for ranking views, trust surfaces, and operator comparison tools.

Code examples
Generated from the same hardcoded sample data that powers the desktop code rail.
cURL
GET /api/validator/{id}/score
curl "https://ethintel.io/api/validator/204321/score" \
  --header "Authorization: Bearer ei_live_demo_A9x32kLmQz" \
  --header "Accept: application/json"
Resolved request URL
https://ethintel.io/api/validator/204321/score
Path parameters
NameTypeRequiredDescription
idstring | numberRequired
Validator index or canonical validator identifier.
200
ValidatorScore
Composite score and score breakdown.
ValidatorScore schema
validatorIndex
numberBeacon validator index.
score
numberComposite EthIntel operator score.
grade
"A" | "B" | "C" | "D"Letter grade for dashboards.
performance
numberPerformance sub-score.
reliability
numberReliability sub-score.
decentralization
numberDecentralization sub-score.
taxReadiness
numberTax-report readiness sub-score.
item
stringShort explanations for the current score.
JSON
200 example
{
  "validatorIndex": 204321,
  "score": 91,
  "grade": "A",
  "breakdown": {
    "performance": 93,
    "reliability": 95,
    "decentralization": 78,
    "taxReadiness": 98
  },
  "reasons": [
    "Strong attestation performance over the last 30 days.",
    "No missed sync committee duties in the recent window."
  ]
}
Error codes
Stable HTTP semantics you should expect from this endpoint.
StatusCodeMeaning
400BAD_REQUESTThe request payload or parameters are invalid.
404NOT_FOUNDThe requested resource does not exist.
429RATE_LIMITEDToo many requests for the current minute window.
500INTERNAL_ERRORUnexpected server-side exception.
503SERVICE_UNAVAILABLEOne or more upstream dependencies are unavailable.
GET

/api/validator/{id}/tax

Tax report CSV

Download validator reward activity as CSV for accounting workflows.

GETPublic + Bearer

Download a tax report

Returns CSV content ready for bookkeeping tools, spreadsheets, or archival workflows.

Code examples
Generated from the same hardcoded sample data that powers the desktop code rail.
cURL
GET /api/validator/{id}/tax
curl "https://ethintel.io/api/validator/204321/tax?year=2026" \
  --header "Authorization: Bearer ei_live_demo_A9x32kLmQz" \
  --header "Accept: text/csv"
Resolved request URL
https://ethintel.io/api/validator/204321/tax?year=2026
Path parameters
NameTypeRequiredDescription
idstring | numberRequired
Validator index or canonical validator identifier.
Query parameters
NameTypeRequiredDescription
yearnumberRequired
Tax year to export.
200
ValidatorTaxCsv
CSV metadata and a representative row shape.
ValidatorTaxCsv schema
contentType
"text/csv"Response media type.
filename
stringSuggested downloaded filename.
item
stringCSV column name.
epoch
numberReward epoch.
rewardType
stringReward classification.
amountEth
numberETH-denominated amount.
amountUsd
numberApproximate USD value.
Text
200 example
validator_index,epoch,reward_type,amount_eth,amount_usd
204321,248300,attestation,0.00318,10.74
204321,248301,attestation,0.00321,10.85
204321,248302,attestation,0.00342,11.56
Error codes
Stable HTTP semantics you should expect from this endpoint.
StatusCodeMeaning
400BAD_REQUESTThe request payload or parameters are invalid.
404NOT_FOUNDThe requested resource does not exist.
429RATE_LIMITEDToo many requests for the current minute window.
500INTERNAL_ERRORUnexpected server-side exception.
503SERVICE_UNAVAILABLEOne or more upstream dependencies are unavailable.
GET

/api/validator/{id}/duties

Validator duties

Inspect proposer, attester, and sync committee duties across an epoch window.

GETPublic + Bearer

Fetch validator duties

Useful for upcoming schedule views, missed-duty analysis, and operator alerts.

Code examples
Generated from the same hardcoded sample data that powers the desktop code rail.
cURL
GET /api/validator/{id}/duties
curl "https://ethintel.io/api/validator/204321/duties?fromEpoch=248300&toEpoch=248304" \
  --header "Authorization: Bearer ei_live_demo_A9x32kLmQz" \
  --header "Accept: application/json"
Resolved request URL
https://ethintel.io/api/validator/204321/duties?fromEpoch=248300&toEpoch=248304
Path parameters
NameTypeRequiredDescription
idstring | numberRequired
Validator index or canonical validator identifier.
Query parameters
NameTypeRequiredDescription
fromEpochnumberRequired
Inclusive start epoch.
toEpochnumberRequired
Inclusive end epoch.
200
ValidatorDuties
Scheduled and observed duties for the window.
ValidatorDuties schema
validatorIndex
numberBeacon validator index.
fromEpoch
numberInclusive start epoch.
toEpoch
numberInclusive end epoch.
epoch
numberDuty epoch.
slot
numberDuty slot.
type
"proposer" | "attester" | "sync"Duty type.
status
"scheduled" | "completed" | "missed"Observed status.
JSON
200 example
{
  "validatorIndex": 204321,
  "window": {
    "fromEpoch": 248300,
    "toEpoch": 248304
  },
  "duties": [
    {
      "epoch": 248300,
      "slot": 7945632,
      "type": "attester",
      "status": "completed"
    },
    {
      "epoch": 248302,
      "slot": 7945696,
      "type": "proposer",
      "status": "scheduled"
    }
  ]
}
Error codes
Stable HTTP semantics you should expect from this endpoint.
StatusCodeMeaning
400BAD_REQUESTThe request payload or parameters are invalid.
404NOT_FOUNDThe requested resource does not exist.
429RATE_LIMITEDToo many requests for the current minute window.
500INTERNAL_ERRORUnexpected server-side exception.
503SERVICE_UNAVAILABLEOne or more upstream dependencies are unavailable.
GET

/api/validator/by-address/{address}

Validator lookup by withdrawal address

Resolve a withdrawal address into one or more matching validators.

GETPublic + Bearer

Find validators by withdrawal address

Helpful when mapping operator wallets to validators or reconciling rewards exports.

Code examples
Generated from the same hardcoded sample data that powers the desktop code rail.
cURL
GET /api/validator/by-address/{address}
curl "https://ethintel.io/api/validator/by-address/0x91bB2aBC4459d1F21f5c8A7cA2B22A2aF1B0e5D1" \
  --header "Authorization: Bearer ei_live_demo_A9x32kLmQz" \
  --header "Accept: application/json"
Resolved request URL
https://ethintel.io/api/validator/by-address/0x91bB2aBC4459d1F21f5c8A7cA2B22A2aF1B0e5D1
Path parameters
NameTypeRequiredDescription
addressstringRequired
0x-prefixed address or ENS name where supported.
200
ValidatorByAddress
Validators linked to the supplied withdrawal address.
ValidatorByAddress schema
address
stringWithdrawal address used for lookup.
validatorIndex
numberMatching validator index.
status
stringBeacon status.
balanceEth
numberObserved balance.
withdrawalCredentialsType
stringCredential type.
JSON
200 example
{
  "address": "0x91bB2aBC4459d1F21f5c8A7cA2B22A2aF1B0e5D1",
  "validators": [
    {
      "validatorIndex": 204321,
      "status": "active_ongoing",
      "balanceEth": 32.4821,
      "withdrawalCredentialsType": "0x01"
    },
    {
      "validatorIndex": 204322,
      "status": "active_ongoing",
      "balanceEth": 32.4818,
      "withdrawalCredentialsType": "0x01"
    }
  ]
}
Error codes
Stable HTTP semantics you should expect from this endpoint.
StatusCodeMeaning
400BAD_REQUESTThe request payload or parameters are invalid.
404NOT_FOUNDThe requested resource does not exist.
429RATE_LIMITEDToo many requests for the current minute window.
500INTERNAL_ERRORUnexpected server-side exception.
503SERVICE_UNAVAILABLEOne or more upstream dependencies are unavailable.
GET

/api/network

Network stats

Get a compact network-wide snapshot for validator and staking dashboards.

GETPublic + Bearer

Fetch network stats

Returns top-line beacon chain metrics for system views and overview pages.

Code examples
Generated from the same hardcoded sample data that powers the desktop code rail.
cURL
GET /api/network
curl "https://ethintel.io/api/network" \
  --header "Authorization: Bearer ei_live_demo_A9x32kLmQz" \
  --header "Accept: application/json"
Resolved request URL
https://ethintel.io/api/network
200
NetworkStats
Current network-wide staking and finality metrics.
NetworkStats schema
chain
"ethereum"Network identifier.
currentSlot
numberCurrent observed beacon slot.
currentEpoch
numberCurrent observed epoch.
finalizedEpoch
numberLatest finalized epoch.
activeValidators
numberActive validator count.
pendingValidators
numberPending validator count.
totalStakedEth
numberTotal actively staked ETH.
participationRate
numberCurrent participation rate.
slashings30d
numberSlashings observed in the last 30 days.
JSON
200 example
{
  "chain": "ethereum",
  "currentSlot": 7945740,
  "currentEpoch": 248304,
  "finalizedEpoch": 248302,
  "activeValidators": 1123048,
  "pendingValidators": 11892,
  "totalStakedEth": 35980412,
  "participationRate": 0.996,
  "slashings30d": 4
}
Error codes
Stable HTTP semantics you should expect from this endpoint.
StatusCodeMeaning
429RATE_LIMITEDToo many requests for the current minute window.
500INTERNAL_ERRORUnexpected server-side exception.
503SERVICE_UNAVAILABLEOne or more upstream dependencies are unavailable.
GET

/api/network/slashings

Slashing events

List recent slashing events with penalties and brief reasons.

GETPublic + Bearer

Fetch recent slashings

Useful for status pages, operator monitoring, and compliance or review workflows.

Code examples
Generated from the same hardcoded sample data that powers the desktop code rail.
cURL
GET /api/network/slashings
curl "https://ethintel.io/api/network/slashings?limit=20" \
  --header "Authorization: Bearer ei_live_demo_A9x32kLmQz" \
  --header "Accept: application/json"
Resolved request URL
https://ethintel.io/api/network/slashings?limit=20
Query parameters
NameTypeRequiredDescription
limitnumberOptional
Maximum rows to return.
Default: 20
200
SlashingEvents
Recent slashing event rows.
SlashingEvents schema
chain
"ethereum"Network identifier.
validatorIndex
numberSlashed validator index.
epoch
numberSlash event epoch.
reason
stringShort slash explanation.
penaltyEth
numberEstimated penalty amount.
whistleblower
string | nullWhistleblower address or label.
JSON
200 example
{
  "chain": "ethereum",
  "items": [
    {
      "validatorIndex": 182441,
      "epoch": 248291,
      "reason": "Proposer equivocation",
      "penaltyEth": 0.5124,
      "whistleblower": null
    },
    {
      "validatorIndex": 190112,
      "epoch": 248295,
      "reason": "Attester slashable vote",
      "penaltyEth": 0.4869,
      "whistleblower": null
    }
  ]
}
Error codes
Stable HTTP semantics you should expect from this endpoint.
StatusCodeMeaning
429RATE_LIMITEDToo many requests for the current minute window.
500INTERNAL_ERRORUnexpected server-side exception.
503SERVICE_UNAVAILABLEOne or more upstream dependencies are unavailable.
GET

/api/health

Service health

Expose subsystem health for load balancers, monitors, and status pages.

GETPublic

Check service health

A lightweight synthetic monitoring endpoint with per-subsystem latency detail.

Code examples
Generated from the same hardcoded sample data that powers the desktop code rail.
cURL
GET /api/health
curl "https://ethintel.io/api/health" \
  --header "Accept: application/json"
Resolved request URL
https://ethintel.io/api/health
200
Health
Overall health plus subsystem checks.
Health schema
status
"ok" | "degraded"Overall service status.
version
stringRunning API version.
status
"ok" | "degraded"RPC subsystem status.
latencyMs
numberObserved subsystem latency.
status
"ok" | "degraded"Cache subsystem status.
latencyMs
numberObserved subsystem latency.
status
"ok" | "degraded"AI subsystem status.
latencyMs
numberObserved subsystem latency.
status
"ok" | "degraded"Beacon data subsystem status.
latencyMs
numberObserved subsystem latency.
timestamp
stringISO-8601 server timestamp.
JSON
200 example
{
  "status": "ok",
  "version": "2026.03.14",
  "checks": {
    "rpc": {
      "status": "ok",
      "latencyMs": 121
    },
    "redis": {
      "status": "ok",
      "latencyMs": 7
    },
    "ai": {
      "status": "ok",
      "latencyMs": 912
    },
    "beacon": {
      "status": "ok",
      "latencyMs": 42
    }
  },
  "timestamp": "2026-03-14T20:06:11Z"
}
Error codes
Stable HTTP semantics you should expect from this endpoint.
StatusCodeMeaning
429RATE_LIMITEDToo many requests for the current minute window.
500INTERNAL_ERRORUnexpected server-side exception.
503SERVICE_UNAVAILABLEOne or more upstream dependencies are unavailable.
GET

/api/labels/stats

Label database stats

Inspect label freshness, counts, and source composition.

GETPublic + Bearer

Fetch label database stats

Useful when debugging coverage, synchronizing datasets, or exposing data quality metrics.

Code examples
Generated from the same hardcoded sample data that powers the desktop code rail.
cURL
GET /api/labels/stats
curl "https://ethintel.io/api/labels/stats" \
  --header "Authorization: Bearer ei_live_demo_A9x32kLmQz" \
  --header "Accept: application/json"
Resolved request URL
https://ethintel.io/api/labels/stats
200
LabelStats
Aggregate label counts and source breakdowns.
LabelStats schema
totalLabels
numberTotal indexed labels.
totalAddresses
numberDistinct labeled addresses.
totalProtocols
numberDistinct protocols with labels.
name
stringSource dataset name.
labels
numberLabels contributed by the dataset.
lastUpdated
stringRefresh timestamp.
lastUpdated
stringGlobal refresh timestamp.
JSON
200 example
{
  "totalLabels": 418762,
  "totalAddresses": 305441,
  "totalProtocols": 1874,
  "sources": [
    {
      "name": "ethintel-core",
      "labels": 221843,
      "lastUpdated": "2026-03-14T03:00:00Z"
    },
    {
      "name": "community-curated",
      "labels": 104332,
      "lastUpdated": "2026-03-13T23:41:00Z"
    },
    {
      "name": "protocol-manifests",
      "labels": 92587,
      "lastUpdated": "2026-03-14T01:12:00Z"
    }
  ],
  "lastUpdated": "2026-03-14T03:00:00Z"
}
Error codes
Stable HTTP semantics you should expect from this endpoint.
StatusCodeMeaning
429RATE_LIMITEDToo many requests for the current minute window.
500INTERNAL_ERRORUnexpected server-side exception.
503SERVICE_UNAVAILABLEOne or more upstream dependencies are unavailable.
GET

/api/openapi.json

OpenAPI spec

Download the machine-readable API contract for codegen and validation.

GETPublic

Fetch the OpenAPI spec

The source of truth for SDK generation, contract testing, and API client tooling.

Code examples
Generated from the same hardcoded sample data that powers the desktop code rail.
cURL
GET /api/openapi.json
curl "https://ethintel.io/api/openapi.json" \
  --header "Accept: application/json"
Resolved request URL
https://ethintel.io/api/openapi.json
200
OpenApiDocument
OpenAPI 3 document describing the API surface.
OpenApiDocument schema
openapi
stringOpenAPI version string.
title
stringAPI title.
version
stringAPI version.
description
stringTop-level spec description.
url
stringServer base URL.
description
stringServer label.
paths
objectPath objects keyed by route.
components
objectReusable schemas, responses, and security schemes.
JSON
200 example
{
  "openapi": "3.1.0",
  "info": {
    "title": "EthIntel REST API",
    "version": "2026-03-14",
    "description": "Hardcoded documentation sample for the EthIntel REST API."
  },
  "servers": [
    {
      "url": "https://ethintel.io",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/explain/{txHash}": {
      "get": {
        "summary": "Explain a transaction"
      }
    }
  },
  "components": {
    "schemas": {
      "TransactionExplanation": {
        "type": "object"
      }
    }
  }
}
Error codes
Stable HTTP semantics you should expect from this endpoint.
StatusCodeMeaning
429RATE_LIMITEDToo many requests for the current minute window.
500INTERNAL_ERRORUnexpected server-side exception.
503SERVICE_UNAVAILABLEOne or more upstream dependencies are unavailable.
GETPOSTDELETE

/api/user/api-key

API key CRUD

Inspect, create, rotate, or revoke the authenticated user’s API key.

GETAuth required

Fetch current API key metadata

Returns the currently active key metadata without exposing the secret value.

Code examples
Generated from the same hardcoded sample data that powers the desktop code rail.
cURL
GET /api/user/api-key
curl "https://ethintel.io/api/user/api-key" \
  --header "Authorization: Bearer ei_live_demo_A9x32kLmQz" \
  --header "Accept: application/json"
Resolved request URL
https://ethintel.io/api/user/api-key
200
ApiKeyMetadata
Display-safe information for the active API key.
ApiKeyMetadata schema
keyPrefix
stringPublic prefix safe to display in dashboards.
plan
stringCurrent plan associated with the key.
item
stringGranted scope.
createdAt
stringCreation timestamp.
lastUsedAt
string | nullLatest usage timestamp.
requestsToday
numberRequests made in the current UTC day.
JSON
200 example
{
  "keyPrefix": "ei_live_demo",
  "plan": "API",
  "scopes": [
    "explain:read",
    "address:read",
    "validator:read"
  ],
  "createdAt": "2026-02-28T09:15:00Z",
  "lastUsedAt": "2026-03-14T19:54:04Z",
  "requestsToday": 842
}
Error codes
Stable HTTP semantics you should expect from this endpoint.
StatusCodeMeaning
401UNAUTHORIZEDA valid bearer token is required for this endpoint.
429RATE_LIMITEDToo many requests for the current minute window.
500INTERNAL_ERRORUnexpected server-side exception.
POST

/api/bot/webhook

Telegram bot webhook

Receive Telegram bot updates and route them through EthIntel bot handlers.

POSTPublic

Handle Telegram webhook updates

The webhook endpoint accepts Telegram update payloads and returns a compact processing status.

In production, protect this route with Telegram’s secret token validation even though the payload itself is plain JSON.
Code examples
Generated from the same hardcoded sample data that powers the desktop code rail.
cURL
POST /api/bot/webhook
curl -X POST "https://ethintel.io/api/bot/webhook" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "update_id": 992114321,
    "message": {
      "message_id": 1042,
      "text": "/explain 0x8f3d0f63b3a948321f1b2291e5a8dd3c3df5cc9fd0c8ff9d132d91b2c1e9bc45",
      "chat": {
        "id": 1049923,
        "type": "private"
      },
      "from": {
        "id": 99872,
        "username": "ethintel_user"
      }
    }
  }'
Resolved request URL
https://ethintel.io/api/bot/webhook
Request body
Telegram update payload forwarded by the webhook integration.
JSON body schema
update_id
numberTelegram update identifier.
message_id
number | nullTelegram message id.
text
string | nullIncoming message text.
id
numberTelegram chat id.
type
stringChat type.
id
numberTelegram user id.
username
string | nullTelegram username.
JSON
Sample request body
{
  "update_id": 992114321,
  "message": {
    "message_id": 1042,
    "text": "/explain 0x8f3d0f63b3a948321f1b2291e5a8dd3c3df5cc9fd0c8ff9d132d91b2c1e9bc45",
    "chat": {
      "id": 1049923,
      "type": "private"
    },
    "from": {
      "id": 99872,
      "username": "ethintel_user"
    }
  }
}
200
BotWebhookResponse
Webhook processing status.
BotWebhookResponse schema
ok
booleanTrue when the update was accepted.
accepted
booleanTrue when processing succeeded.
action
stringHigh-level action taken for the update.
requestId
stringSupport correlation id.
JSON
200 example
{
  "ok": true,
  "accepted": true,
  "action": "queued_explain_request",
  "requestId": "req_01JTV2T0YF5E7YZZ"
}
Error codes
Stable HTTP semantics you should expect from this endpoint.
StatusCodeMeaning
400BAD_REQUESTThe request payload or parameters are invalid.
429RATE_LIMITEDToo many requests for the current minute window.
500INTERNAL_ERRORUnexpected server-side exception.
503SERVICE_UNAVAILABLEOne or more upstream dependencies are unavailable.