Developer API

Chain Intelligence APIs

Address & token risk scoring have a free tier (score + risk level, no payment needed). Add an X-PAYMENT header to unlock the full report ($0.01/address · $0.02/token via x402). Gas endpoint is $0.005/req. No API keys. No subscriptions.

Endpoints

Free → $0.01
GET /api/v1/risk/address/{address}

Address & contract risk scoring — GoPlus + Etherscan + community blacklists

Free → $0.02
GET /api/v1/risk/token/{address}

Token security — honeypot detection, tax analysis, holder concentration, LP analysis

$0.005
GET /api/v1/gas

Real-time multi-chain gas estimation from live RPC nodes

How x402 Works

The x402 protocol repurposes HTTP's 402 status code for native web payments. No accounts, no API keys — just pay per request.

1
Request
Send GET to any paid endpoint
→
2
402 Response
Payment requirements returned
→
3
Pay & Retry
Sign USDC transfer, retry with header
→
4
200 + Data
Server verifies payment, returns data

Risk Intelligence API

Query the risk profile of any Ethereum address or smart contract. Combines data from three sources:

GoPlus Security
20+ signals
Phishing, sanctions, money laundering, cybercrime, honeypot, malicious contracts
Etherscan API
6 chains
Contract code, tx history, source verification, dangerous function detection
Community Blacklists
715+ addresses
MyEtherWallet ethereum-lists + Tornado Cash contracts

Free Tier — Score & Status

No payment required. Returns risk score (0–100), risk level, blacklist status, and data sources:

Try it free
# Free tier — no payment needed
curl -s https://theonchaindiary.com/api/v1/risk/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 | jq .
200 OK — Free response
{
  "schema_version": "1.1",
  "address": "0xd8da6bf26964afd7eed9e03e53415d37aa96045",
  "chain": "ethereum",
  "is_contract": false,
  "eip7702_delegated": true,
  "score": 15,
  "risk_level": "low",
  "blacklisted": false,
  "data_sources": ["Etherscan", "GoPlus"],
  "checked_at": "2026-06-24T23:00:00.000Z",
  "tier": "free",
  "signals_count": 4,
  "labels_count": 0,
  "upgrade": "Add X-PAYMENT header ($0.01 USDC Base Sepolia) for full signal breakdown, interaction analysis, and risk narrative"
}

Premium Tier — Full Breakdown

Pay $0.01 per request for the complete signal breakdown with weights, risk narrative, and contract details:

Paid request
# Paid tier — x402 payment required
curl -s https://theonchaindiary.com/api/v1/risk/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 \
  -H "X-PAYMENT: " | jq .
200 OK — Premium response
{
  "schema_version": "1.1",
  "address": "0x12d66f87a04a9e220743712ce6d9bb1b5616b8fc",
  "chain": "ethereum",
  "is_contract": true,
  "eip7702_delegated": false,
  "score": 100,
  "risk_level": "critical",
  "blacklisted": true,
  "data_sources": ["Etherscan", "GoPlus", "MyEtherWallet/ethereum-lists"],
  "checked_at": "2026-06-24T23:00:00.000Z",
  "tier": "premium",
  "signals": [
    {
      "type": "blacklist_mixer",
      "detail": "Address is a known mixer contract (Tornado Cash)",
      "weight": 55,
      "source": "internal"
    },
    {
      "type": "mixer_interaction",
      "detail": "Interacted with known mixer (12 txs in recent activity)",
      "weight": 35,
      "source": "Etherscan"
    },
    {
      "type": "verified",
      "detail": \"TornadoCash_eth_0.1ETH\" verified (v0.6.12)",
      "weight": 0,
      "source": "Etherscan"
    }
  ],
  "labels": ["mixer", "mixer_user"],
  "first_seen": "2019-12-16T11:18:01.000Z",
  "recent_tx_count": 200,
  "summary": "High-risk contract. Address is a known mixer contract (Tornado Cash). Interacted with known mixer (12 txs in recent activity).",
  "contract": {
    "name": "TornadoCash_eth_0.1ETH",
    "verified": true,
    "compiler": "v0.6.12+commit.27d51765",
    "proxy": false,
    "implementation": null,
    "license": "Unlicense"
  }
}

Multi-Chain Support

Add ?chain= parameter to query any supported chain:

Cross-chain queries
# Query on Base
curl -s "https://theonchaindiary.com/api/v1/risk/address/0x...?chain=base" | jq .

# Query on Arbitrum
curl -s "https://theonchaindiary.com/api/v1/risk/address/0x...?chain=arbitrum" | jq .

Scoring Methodology

EOA
  • GoPlus security flags (phishing, sanctions, crime)
  • Community blacklist membership
  • Mixer interaction (Tornado Cash)
  • Account age & activity patterns
  • Outgoing diversity (phishing pattern detection)
Contract
  • Source code verification status
  • Dangerous functions (selfdestruct, delegatecall)
  • Unprotected mint detection
  • tx.origin vulnerability
  • Proxy / upgradeable pattern
  • Deployer reputation & contract age

Token Security API

Deep-dive risk analysis for any ERC-20 token. Detect honeypots, tax traps, rug-pull vectors, and concentration risks before you interact.

✕
Honeypot
Can buy but can't sell
%
Tax Analysis
Buy / sell / transfer rates
◈
Holder Concentration
Top holder & top-10 % stake
⬡
Liquidity Safety
LP lock status & concentration

Free Tier — Quick Check

Returns risk score, honeypot status, and source verification:

Try it free
# Free tier — no payment needed
curl -s https://theonchaindiary.com/api/v1/risk/token/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 | jq .
200 OK — Free response
{
  "schema_version": "1.0",
  "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
  "chain": "ethereum",
  "token_name": "USD Coin",
  "token_symbol": "USDC",
  "score": 0,
  "risk_level": "low",
  "is_honeypot": false,
  "source_verified": true,
  "data_sources": ["GoPlus", "Etherscan"],
  "checked_at": "2026-06-24T16:12:07Z",
  "tier": "free",
  "signals_count": 5,
  "labels_count": 3,
  "upgrade": "Add X-PAYMENT header ($0.02) for full signal breakdown, tax analysis, holder concentration, and liquidity data"
}

Premium Tier — Full Analysis

Pay $0.02 for complete signal breakdown, tax rates, top-10 holder list, liquidity pool data, and risk narrative:

200 OK — Premium response
{
  "schema_version": "1.0",
  "address": "0x6982508145454ce325ddbe47a25d4ec3d2311933",
  "chain": "ethereum",
  "token_name": "Pepe",
  "token_symbol": "PEPE",
  "score": 15,
  "risk_level": "low",
  "is_honeypot": false,
  "source_verified": true,
  "tier": "premium",
  "signals": [
    {
      "type": "verified_source",
      "detail": "Contract source code is verified",
      "weight": 0,
      "source": "GoPlus"
    },
    {
      "type": "deploy_age",
      "detail": "Deployed 420d ago",
      "weight": 0,
      "source": "Etherscan"
    }
  ],
  "labels": ["verified"],
  "taxes": { "buy_pct": 0, "sell_pct": 0, "transfer_pct": 0 },
  "holders": {
    "total_count": 210000,
    "top_holder_pct": 8.5,
    "top_10_pct": 42.3,
    "creator_pct": 0.0
  },
  "liquidity": {
    "in_dex": true,
    "lp_locked": true,
    "lp_holder_count": 12,
    "lp_top_holder_pct": 15.2,
    "pools": [
      { "exchange": "Uniswap V3", "liquidity_usd": 1200000 }
    ]
  },
  "summary": ""Pepe" (PEPE) — Low risk based on available data. No critical issues detected."
}

Token Risk Signals

Critical
  • Honeypot (can't sell)
  • Buy/sell blocked
  • Per-address tax modification
  • Owner can change balances
  • Creator has honeypot history
High Risk
  • Unverified source code
  • Mintable (unlimited supply)
  • Hidden owner / not renounced
  • Slippage modifiable (tax change)
  • Tax rate > 25%
  • Top holder > 50% supply

Gas Estimation API

Real-time gas data from 6 EVM chains. $0.005 per request via x402.

Quick test (will return 402)
curl -s https://theonchaindiary.com/api/v1/gas | jq .
200 OK — Paid response
{
  "chains": [
    {
      "chain": "ethereum",
      "label": "Ethereum",
      "baseFeeGwei": 12.34,
      "priorityFeeGwei": { "slow": 0.8, "standard": 1.2, "fast": 2.1 },
      "totalFeeGwei": { "slow": 13.14, "standard": 13.54, "fast": 14.44 },
      "blockNumber": 21000000
    }
    // ...5 more chains
  ]
}

Use @x402/evm client library for automatic payment handling:

npm install @x402/evm viem
import { wrapFetchWithPayment } from '@x402/evm/exact/client';
import { createWalletClient, http } from 'viem';
import { baseSepolia } from 'viem/chains';
import { privateKeyToAccount } from 'viem/accounts';

const account = privateKeyToAccount('0xYourPrivateKey');

const fetchWithPayment = wrapFetchWithPayment(
  fetch,
  account,
  'eip155:84532',
);

const res = await fetchWithPayment(
  'https://theonchaindiary.com/api/v1/gas'
);
const data = await res.json();

console.log(data);

The 402 Response

Without payment (on paid endpoints), the server returns HTTP 402:

402 Payment Required
{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:84532",
      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      "price": "$0.01 / $0.02",
      "payTo": "0x46fb532887176a90c0767ca4be48b882cf326e1a"
    }
  ],
  "error": "Payment required for deep risk analysis"
}

Supported Chains

Ethereum
Base
Arbitrum One
Optimism
Polygon PoS
BNB Smart Chain

Risk scoring aggregates signals from GoPlus and Etherscan across all 6 chains. Gas data is fetched live from public RPC endpoints.

Roadmap

Done Address & contract risk scoring (GoPlus + Etherscan + blacklists)
Done Multi-chain gas estimation API
Done x402 payment flow (Base Sepolia testnet)
Done Token security endpoint (honeypot detection, tax analysis, holder concentration)
Next Mainnet deployment (Base USDC)
Planned Transaction simulation endpoint

Built with the x402 protocol — open standard for HTTP-native payments.

Questions? Email hi@theonchaindiary.com