Arkham API

Arkham Intelligence API Skill

Configuration

API Key must be set in Claude Code settings:

// ~/.claude/settings.json
{
  "env": {
    "ARKHAM_API_KEY": "your_api_key_here"
  }
}

Restart Claude Code after adding the key.

Making API Calls

Important: Always use this pattern for API calls:

KEY=$(printenv ARKHAM_API_KEY)
curl -s "https://api.arkm.com/ENDPOINT" -H "API-Key: $KEY" | jq .

Rate Limits

• Standard endpoints: 20 req/sec
• Heavy endpoints (1 req/sec): /transfers, /swaps, /counterparties/*, /token/top_flow/*, /token/volume/*

Quick Reference

Intelligence

# Address info
curl -s "https://api.arkm.com/intelligence/address/0x...?chain=ethereum" -H "API-Key: $KEY" | jq .

# Entity info (binance, wintermute, jump-trading, etc.)
curl -s "https://api.arkm.com/intelligence/entity/wintermute" -H "API-Key: $KEY" | jq .

Balances & Portfolio

# Entity balances
curl -s "https://api.arkm.com/balances/entity/wintermute" -H "API-Key: $KEY" | jq .

# Address balances
curl -s "https://api.arkm.com/balances/address/0x...?chains=ethereum,solana" -H "API-Key: $KEY" | jq .

Transfers

# Recent transfers from entity
curl -s "https://api.arkm.com/transfers?base=binance&flow=out&timeLast=24h&limit=20" -H "API-Key: $KEY" | jq .

# Large transfers
curl -s "https://api.arkm.com/transfers?usdGte=1000000&timeLast=24h&limit=50" -H "API-Key: $KEY" | jq .

Token Analysis

# Top holders
curl -s "https://api.arkm.com/token/holders/pepe?groupByEntity=true" -H "API-Key: $KEY" | jq .

# Trending tokens
curl -s "https://api.arkm.com/token/trending" -H "API-Key: $KEY" | jq .

# Top tokens by volume
curl -s "https://api.arkm.com/token/top?timeframe=24h&orderByAgg=volume&orderByDesc=true&orderByPercent=false&from=0&size=20" -H "API-Key: $KEY" | jq .

# Token flows (inflows/outflows)
curl -s "https://api.arkm.com/token/top_flow/ethereum?timeLast=24h" -H "API-Key: $KEY" | jq .

Market Data

# Network status (prices, volume, market cap)
curl -s "https://api.arkm.com/networks/status" -H "API-Key: $KEY" | jq .

# Altcoin index (altseason indicator)
curl -s "https://api.arkm.com/marketdata/altcoin_index" -H "API-Key: $KEY" | jq .

Practical Use Cases

1. Find Smart Money / Market Makers

KEY=$(printenv ARKHAM_API_KEY)

# Get market maker info
curl -s "https://api.arkm.com/intelligence/entity/wintermute" -H "API-Key: $KEY" | jq .

# Check their holdings (balances organized by chain)
cat > /tmp/flatten_balances.jq << 'EOF'
[.balances | to_entries[] | .key as $chain | .value[] | {symbol, usd, chain: $chain}] | sort_by(-.usd) | .[:10]
EOF
curl -s "https://api.arkm.com/balances/entity/wintermute" -H "API-Key: $KEY" | jq -f /tmp/flatten_balances.jq

# Get total portfolio value (totalBalance is object by chain)
curl -s "https://api.arkm.com/balances/entity/wintermute" -H "API-Key: $KEY" | jq '[.totalBalance | to_entries[] | .value] | add'

2. Analyze Whale Holdings for Meme/Speculative Tokens

KEY=$(printenv ARKHAM_API_KEY)

# Get portfolio and filter by USD value (must flatten across chains first)
cat > /tmp/whale_holdings.jq << 'EOF'
[.balances | to_entries[] | .value[] | select(.usd > 100000) | {symbol, usd}] | sort_by(-.usd)
EOF
curl -s "https://api.arkm.com/balances/entity/wintermute" -H "API-Key: $KEY" | jq -f /tmp/whale_holdings.jq

3. Track Large Movements

KEY=$(printenv ARKHAM_API_KEY)

# Whale transfers last 24h (note: use historicalUSD, not unitValueUsd)
curl -s "https://api.arkm.com/transfers?usdGte=5000000&timeLast=24h&limit=50" -H "API-Key: $KEY" \
  | jq '.transfers[] | {from: .fromAddress.arkhamEntity.name, to: .toAddress.arkhamEntity.name, usd: .historicalUSD, token: .tokenSymbol}'

4. Token Holder Analysis

KEY=$(printenv ARKHAM_API_KEY)

# Who holds this token? (entityTopHolders organized by chain)
cat > /tmp/token_holders.jq << 'EOF'
[.entityTopHolders | to_entries[] | .key as $chain | .value[:10][] | {
  entity: .entity.name,
  type: .entity.type,
  usd,
  chain: $chain
}] | sort_by(-.usd) | .[:15]
EOF
curl -s "https://api.arkm.com/token/holders/pepe?groupByEntity=true" -H "API-Key: $KEY" | jq -f /tmp/token_holders.jq

5. ETH Accumulation Analysis (Who's Buying/Selling)

KEY=$(printenv ARKHAM_API_KEY)

# Create filter for complex jq query (avoids bash escaping issues)
cat > /tmp/accumulators.jq << 'EOF'
[.[] | select(.address.arkhamEntity.name != null) | {
  entity: .address.arkhamEntity.name,
  type: .address.arkhamEntity.type,
  net_flow_usd: (.inUSD - .outUSD),
  inETH: .inValue,
  outETH: .outValue
}] | sort_by(-.net_flow_usd) | .[:20]
EOF

# Find who's accumulating ETH (positive net flow = buying)
curl -s "https://api.arkm.com/token/top_flow/ethereum?timeLast=7d" \
  -H "API-Key: $KEY" | jq -f /tmp/accumulators.jq

# Find who's distributing ETH (sort ascending for sellers)
cat > /tmp/sellers.jq << 'EOF'
[.[] | select(.address.arkhamEntity.name != null) | {
  entity: .address.arkhamEntity.name,
  type: .address.arkhamEntity.type,
  net_flow_usd: (.inUSD - .outUSD)
}] | sort_by(.net_flow_usd) | .[:15]
EOF

curl -s "https://api.arkm.com/token/top_flow/ethereum?timeLast=7d" \
  -H "API-Key: $KEY" | jq -f /tmp/sellers.jq

6. Track Hacker/Exploit Funds

KEY=$(printenv ARKHAM_API_KEY)

# Check known hacker entity
curl -s "https://api.arkm.com/intelligence/entity/lazarus-group" -H "API-Key: $KEY" | jq '{name, type}'

# Check their current holdings
cat > /tmp/hacker_holdings.jq << 'EOF'
{
  total_usd: ([.totalBalance | to_entries[] | .value] | add),
  top_holdings: [.balances | to_entries[] | .value[] | {symbol, usd}] | sort_by(-.usd) | .[:10]
}
EOF
curl -s "https://api.arkm.com/balances/entity/lazarus-group" -H "API-Key: $KEY" | jq -f /tmp/hacker_holdings.jq

# Track their recent transfers
curl -s "https://api.arkm.com/transfers?base=lazarus-group&timeLast=30d&limit=20" -H "API-Key: $KEY" \
  | jq '.transfers[] | {to: .toAddress.arkhamEntity.name, usd: .historicalUSD, token: .tokenSymbol}'

7. Compare Market Maker Portfolios

KEY=$(printenv ARKHAM_API_KEY)

# Download both portfolios
curl -s "https://api.arkm.com/balances/entity/wintermute" -H "API-Key: $KEY" > /tmp/wm.json
curl -s "https://api.arkm.com/balances/entity/jump-trading" -H "API-Key: $KEY" > /tmp/jt.json

# Compare totals and top holdings
cat > /tmp/portfolio_summary.jq << 'EOF'
{
  total_usd: ([.totalBalance | to_entries[] | .value] | add),
  top_5: [.balances | to_entries[] | .value[] | {symbol, usd}] | sort_by(-.usd) | .[:5]
}
EOF

echo "=== WINTERMUTE ===" && jq -f /tmp/portfolio_summary.jq /tmp/wm.json
echo "=== JUMP TRADING ===" && jq -f /tmp/portfolio_summary.jq /tmp/jt.json

8. Market-Wide CEX Flow Analysis (Sentiment Indicator)

KEY=$(printenv ARKHAM_API_KEY)

# Analyze all CEX ETH flows to gauge market sentiment
cat > /tmp/cex_flows.jq << 'EOF'
[.[] | select(.address.arkhamEntity.type == "cex") | {
  exchange: .address.arkhamEntity.name,
  net_flow_usd: (.inUSD - .outUSD),
  inUSD,
  outUSD
}] | group_by(.exchange) | map({
  exchange: .[0].exchange,
  total_net_flow: (map(.net_flow_usd) | add),
  total_inflow: (map(.inUSD) | add),
  total_outflow: (map(.outUSD) | add)
}) | sort_by(-.total_net_flow)
EOF

curl -s "https://api.arkm.com/token/top_flow/ethereum?timeLast=7d" -H "API-Key: $KEY" | jq -f /tmp/cex_flows.jq
# Positive = accumulation (bullish), Negative = distribution (bearish)

9. Network Analysis - Find Entity Trading Partners

KEY=$(printenv ARKHAM_API_KEY)

# Get top counterparties aggregated across all chains
cat > /tmp/network.jq << 'EOF'
[to_entries[] | .key as $chain | .value[] | {
  counterparty: (.address.arkhamEntity.name // .address.arkhamLabel.name // "Unknown"),
  type: .address.arkhamEntity.type,
  usd,
  txCount: .transactionCount,
  chain: $chain
}] | group_by(.counterparty) | map({
  counterparty: .[0].counterparty,
  type: .[0].type,
  total_usd: (map(.usd) | add),
  total_tx: (map(.txCount) | add),
  chains: (map(.chain) | unique)
}) | sort_by(-.total_usd) | .[:15]
EOF

curl -s "https://api.arkm.com/counterparties/entity/wintermute?timeLast=30d&limit=100" \
  -H "API-Key: $KEY" | jq -f /tmp/network.jq

Entity Types

• exchange - CEX (binance, coinbase)
• market_maker - MM (wintermute, jump-trading, cumberland-drw)
• fund - Investment funds (a16z, paradigm)
• individual - Whales (vitalik-buterin)
• protocol - DeFi (uniswap, aave)

Common Parameters

Supported Chains

ethereum, bitcoin, solana, polygon, arbitrum_one, base, optimism, avalanche, bsc, tron, ton, flare, mantle, dogecoin, sonic, zcash

Known Limitations & Gotchas

Critical Issues (from benchmark testing)

Endpoint-Specific Notes

• /transfers: Use /transfers?base={entity} (NOT /transfers/entity/{entity}), USD in historicalUSD field
• /swaps: Works - returns swap data with entity filtering
• /counterparties: HEAVY endpoint, organized by chain like balances
• /networks/status: Chain-organized object (.ethereum.price), not array
• /token/top: Requires orderByPercent param, returns {tokens: [], total}
• /token/holders: Uses .entity.name not .arkhamEntity.name
• Heavy endpoints (1 req/sec): /transfers, /swaps, /counterparties/*, /token/top_flow/*, /token/volume/*

jq Escaping in Bash

Bash escapes special characters in jq filters. Use .jq files for complex queries:

# ❌ FAILS - bash escapes these operators:
#    !=  becomes \!=
#    //  becomes problematic (null coalescing)

# ✅ WORKS - write filter to file
cat > /tmp/filter.jq << 'EOF'
[.[] | select(.address.arkhamEntity.name != null) | {
  entity: (.address.arkhamEntity.name // "unknown"),
  type: .address.arkhamEntity.type,
  net_flow: (.inUSD - .outUSD)
}] | sort_by(-.net_flow)
EOF

curl -s "https://api.arkm.com/token/top_flow/ethereum?timeLast=7d" \
  -H "API-Key: $KEY" | jq -f /tmp/filter.jq

# ✅ For simple cases, use alternative syntax:
curl ... | jq 'select(.name | . != null)'  # wrap in subexpression

Response Structure Variations

⚠️ CRITICAL: Most endpoints return data organized by chain, NOT flat arrays!

Key Fields:

• Transfers: historicalUSD (not unitValueUsd)
• Token holders: .entity.name (not .arkhamEntity.name)
• Balances: organized by chain, totalBalance is object not number

Tip: Always run jq 'keys' or jq 'type' first to explore unknown structures.

All Endpoints Reference

For detailed parameters, see ARKHAM_API_DOCUMENTATION.md