Crypto transaction tracker: look up and trace any transfer

"""Follow an exchange wallet's money two hops out and read who it reached.

Run:  VIKE_API_KEY=... python oc-trace-money.py    (--dry-run lists the requests and makes none)
"""
import os
import sys
from urllib.parse import urlencode

NAME = "oc-trace-money"
BASE = "https://data.vike.io"
DRY = "--dry-run" in sys.argv
ROOT = "0x28C6c06298d514Db089934071355E5743bf21d60"  # the Binance 14 hot wallet


def fail(why):
    sys.exit(f"{NAME}: {why}")


def call(path, method="GET", **params):
    url = BASE + path + ("?" + urlencode(params) if params else "")
    if DRY:
        print(method, url)
        return None
    key = os.environ.get("VIKE_API_KEY") or fail("set VIKE_API_KEY")
    import requests

    r = requests.request(method, url, headers={"X-API-Key": key}, timeout=60)
    if r.status_code != 200:
        fail(f"{method} {path} answered HTTP {r.status_code}: {r.text[:200]}")
    return r.json()


def main():
    # Cost grows with depth x width, so this is the heaviest route in the namespace: keep both small.
    # min_usd defaults to 10,000 when omitted; the graph holds only transfers that clear it.
    graph = call(f"/v1/onchain/wallets/{ROOT}/trace", depth=2, width=3, window="30d")
    if DRY:
        return
    nodes = graph["nodes"]
    if len(nodes) < 2:
        fail("the trace reached nobody beyond the root")
    names = {n["address"]: f"{n.get('label') or n['address'][:10]} ({n.get('wallet_type') or '?'})" for n in nodes}
    print(f"{graph['stats']['node_count']} wallets, {graph['stats']['edge_count']} edges, "
          f"{graph['stats']['max_depth_reached']} hop(s) reached, floor ${graph['min_usd']:,.0f} per transfer")
    # An edge is a pair of wallets, not a one-way payment: out_usd and in_usd split the volume by direction.
    for e in sorted(graph["edges"], key=lambda e: -e["volume_usd"])[:5]:
        print(f"  {names.get(e['from'], e['from'][:10])} <-> {names.get(e['to'], e['to'][:10])}  "
              f"out ${e['out_usd']:,.0f}  in ${e['in_usd']:,.0f}  {e['tx_count']} txs")


if __name__ == "__main__":
    try:
        main()
    except Exception as e:  # a shape the example does not expect fails by name, not by traceback
        fail(f"{type(e).__name__}: {e}")

import os
import requests

API_KEY = os.environ["VIKE_API_KEY"]  # your key, read from the environment

# who funded this wallet, who funded them, and one hop further, top 3 senders per hop over 30 days
r = requests.get(
    "https://data.vike.io/v1/onchain/wallets/0x84b38bc60f3bd82640ecefa320dab2be62e2da15/trace?direction=in&depth=3&width=3&window=30d",
    headers={"X-API-Key": API_KEY},
)

import os
import requests

API_KEY = os.environ["VIKE_API_KEY"]  # your key, read from the environment

# follow inbound transfers of 100 USD and up
r = requests.get(
    "https://data.vike.io/v1/onchain/wallets/0x84b38bc60f3bd82640ecefa320dab2be62e2da15/trace?direction=in&depth=3&width=3&window=30d&min_usd=100",
    headers={"X-API-Key": API_KEY},
)

import os
import requests

API_KEY = os.environ["VIKE_API_KEY"]  # your key, read from the environment

# inbound over all recorded history, two hops
r = requests.get(
    "https://data.vike.io/v1/onchain/wallets/0x84b38bc60f3bd82640ecefa320dab2be62e2da15/trace?direction=in&depth=2&width=3&window=all",
    headers={"X-API-Key": API_KEY},
)

import os
import requests

API_KEY = os.environ["VIKE_API_KEY"]  # your key, read from the environment

# every address the trace reached, with its hop and label
r = requests.get(
    "https://data.vike.io/v1/onchain/wallets/0x84b38bc60f3bd82640ecefa320dab2be62e2da15/trace?direction=in&depth=3&width=3&window=30d",
    headers={"X-API-Key": API_KEY},
)
# then: jq '[.nodes[] | {address, depth, label, wallet_type}]'

import os
import requests

API_KEY = os.environ["VIKE_API_KEY"]  # your key, read from the environment

# where the Bybit exploiter's money went: two hops, three recipients per wallet, transfers of 100,000 USD and up
r = requests.get(
    "https://data.vike.io/v1/onchain/wallets/0x47666Fab8bd0Ac7003bce3f5C3585383F09486E2/trace?direction=out&depth=2&width=3&window=all&min_usd=100000",
    headers={"X-API-Key": API_KEY},
)

import os
import requests

API_KEY = os.environ["VIKE_API_KEY"]  # your key, read from the environment

# wider and deeper: three hops, ten recipients per wallet, all history
# (for a hack of the last month, window=30d keeps the trail to its fresh moves; this one dates from February 2025)
r = requests.get(
    "https://data.vike.io/v1/onchain/wallets/0x47666Fab8bd0Ac7003bce3f5C3585383F09486E2/trace?direction=out&depth=3&width=10&window=all&min_usd=100000",
    headers={"X-API-Key": API_KEY},
)

import os
import requests

API_KEY = os.environ["VIKE_API_KEY"]  # your key, read from the environment

# nodes whose wallet_type is not flagged
r = requests.get(
    "https://data.vike.io/v1/onchain/wallets/0x47666Fab8bd0Ac7003bce3f5C3585383F09486E2/trace?direction=out&depth=2&width=3&window=all&min_usd=100000",
    headers={"X-API-Key": API_KEY},
)
# then: jq '[.nodes[] | select(.wallet_type != "flagged") | {address, depth, label, wallet_type, total_volume_usd}]'

import os
import requests

API_KEY = os.environ["VIKE_API_KEY"]  # your key, read from the environment

# entity, wallet_type and risk_flag of every node
# NODES: the comma-separated address list of the quick answer's trace
trace = requests.get(
    "https://data.vike.io/v1/onchain/wallets/0x47666Fab8bd0Ac7003bce3f5C3585383F09486E2/trace?direction=out&depth=2&width=3&window=all&min_usd=100000",
    headers={"X-API-Key": API_KEY},
).json()
NODES = ",".join(n["address"] for n in trace["nodes"])
r = requests.post(
    f"https://data.vike.io/v1/onchain/labels/batch?addresses={NODES}",
    headers={"X-API-Key": API_KEY},
)

import os
import requests

API_KEY = os.environ["VIKE_API_KEY"]  # your key, read from the environment

# the hack address's top 50 counterparties by USD
r = requests.get(
    "https://data.vike.io/v1/onchain/wallets/0x47666Fab8bd0Ac7003bce3f5C3585383F09486E2/counterparties?window=all&limit=50",
    headers={"X-API-Key": API_KEY},
)

import os
import requests

API_KEY = os.environ["VIKE_API_KEY"]  # your key, read from the environment

# who sent money to this wallet over 90 days, and who sent money to them
r = requests.get(
    "https://data.vike.io/v1/onchain/wallets/0x556e9d5d9e64638edde632bbd4810c9fd0d88397/trace?direction=in&depth=2&width=3&window=90d",
    headers={"X-API-Key": API_KEY},
)

import os
import requests

API_KEY = os.environ["VIKE_API_KEY"]  # your key, read from the environment

# entity, wallet_type and risk_flag for every wallet in the trail
# NODES: the comma-separated address list of the quick answer's trace
trace = requests.get(
    "https://data.vike.io/v1/onchain/wallets/0x556e9d5d9e64638edde632bbd4810c9fd0d88397/trace?direction=in&depth=2&width=3&window=90d",
    headers={"X-API-Key": API_KEY},
).json()
NODES = ",".join(n["address"] for n in trace["nodes"])
r = requests.post(
    f"https://data.vike.io/v1/onchain/labels/batch?addresses={NODES}",
    headers={"X-API-Key": API_KEY},
)

import os
import requests

API_KEY = os.environ["VIKE_API_KEY"]  # your key, read from the environment

# address, depth, label and wallet_type of every node
r = requests.get(
    "https://data.vike.io/v1/onchain/wallets/0x556e9d5d9e64638edde632bbd4810c9fd0d88397/trace?direction=in&depth=2&width=3&window=90d",
    headers={"X-API-Key": API_KEY},
)
# then: jq '[.nodes[] | {address, depth, label, wallet_type}]'

import os
import requests

API_KEY = os.environ["VIKE_API_KEY"]  # your key, read from the environment

# three hops back, transfers of 1,000 USD and up
r = requests.get(
    "https://data.vike.io/v1/onchain/wallets/0x556e9d5d9e64638edde632bbd4810c9fd0d88397/trace?direction=in&depth=3&width=3&window=90d&min_usd=1000",
    headers={"X-API-Key": API_KEY},
)

import os
import requests

API_KEY = os.environ["VIKE_API_KEY"]  # your key, read from the environment

# a large wallet's five biggest counterparties over 90 days
r = requests.get(
    "https://data.vike.io/v1/onchain/wallets/0x176f3dab24a159341c0509bb36b833e7fdd0a132/counterparties?window=90d&limit=5",
    headers={"X-API-Key": API_KEY},
)

import os
import requests

API_KEY = os.environ["VIKE_API_KEY"]  # your key, read from the environment

# the long-run ranking over all recorded history
r = requests.get(
    "https://data.vike.io/v1/onchain/wallets/0x176f3dab24a159341c0509bb36b833e7fdd0a132/counterparties?window=all&limit=50",
    headers={"X-API-Key": API_KEY},
)

import os
import requests

API_KEY = os.environ["VIKE_API_KEY"]  # your key, read from the environment

# the same address on BSC
r = requests.get(
    "https://data.vike.io/v1/onchain/wallets/0x176f3dab24a159341c0509bb36b833e7fdd0a132/counterparties?chain=bsc&window=90d&limit=20",
    headers={"X-API-Key": API_KEY},
)

import os
import requests

API_KEY = os.environ["VIKE_API_KEY"]  # your key, read from the environment

# just the counterparty addresses
r = requests.get(
    "https://data.vike.io/v1/onchain/wallets/0x176f3dab24a159341c0509bb36b833e7fdd0a132/counterparties?window=90d&limit=50",
    headers={"X-API-Key": API_KEY},
)
# then: jq -r '.[].wallet'

import os
import requests

API_KEY = os.environ["VIKE_API_KEY"]  # your key, read from the environment

# label the wallet's top five counterparties in one call
r = requests.post(
    "https://data.vike.io/v1/onchain/labels/batch?addresses=0xe731dfadbff20542e10d09d26fc71445c70d4232,0x44032bd442c5719ad4ffa123f8ec3d39c840f686,0x23617e59a5925b2a4bf75d73ff6711cd0b29de85,0x60594a405d53811d3bc4766596efd80fd545a270,0x998252ea9cb19b3fbc137e111d87808aafff08cf",
    headers={"X-API-Key": API_KEY},
)

import os
import requests

API_KEY = os.environ["VIKE_API_KEY"]  # your key, read from the environment

# the top five counterparties over 90 days, joined with commas
r = requests.get(
    "https://data.vike.io/v1/onchain/wallets/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/counterparties?window=90d&limit=5",
    headers={"X-API-Key": API_KEY},
)
# then: jq -r '[.[].wallet] | join(",")'

import os
import requests

API_KEY = os.environ["VIKE_API_KEY"]  # your key, read from the environment

# the counterparties labelled as exchanges, with the volume each way
r = requests.get(
    "https://data.vike.io/v1/onchain/wallets/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/counterparties?window=90d&limit=50",
    headers={"X-API-Key": API_KEY},
)
# then: jq '[.[] | select(.wallet_type == "cex") | {wallet, entity, sent_usd, received_usd}]'

import os
import requests

API_KEY = os.environ["VIKE_API_KEY"]  # your key, read from the environment

# every labelled exchange the wallet sent to or received from over the same 90 days
r = requests.get(
    "https://data.vike.io/v1/onchain/wallets/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/exchange-usage?window=90d",
    headers={"X-API-Key": API_KEY},
)

import os
import requests

API_KEY = os.environ["VIKE_API_KEY"]  # your key, read from the environment

# what a Binance hot wallet and a Wintermute wallet have in common over 30 days, three of each
r = requests.get(
    "https://data.vike.io/v1/onchain/wallets/compare?address_a=0x28C6c06298d514Db089934071355E5743bf21d60&address_b=0xeae7380dd4cef6fbd1144f49e4d1e6964258a4f4&limit=3&window=30d",
    headers={"X-API-Key": API_KEY},
)

import os
import requests

API_KEY = os.environ["VIKE_API_KEY"]  # your key, read from the environment

# up to 50 shared counterparties and 50 shared tokens
r = requests.get(
    "https://data.vike.io/v1/onchain/wallets/compare?address_a=0x28C6c06298d514Db089934071355E5743bf21d60&address_b=0xeae7380dd4cef6fbd1144f49e4d1e6964258a4f4&limit=50&window=30d",
    headers={"X-API-Key": API_KEY},
)

import os
import requests

API_KEY = os.environ["VIKE_API_KEY"]  # your key, read from the environment

# the same pair over 180 days
r = requests.get(
    "https://data.vike.io/v1/onchain/wallets/compare?address_a=0x28C6c06298d514Db089934071355E5743bf21d60&address_b=0xeae7380dd4cef6fbd1144f49e4d1e6964258a4f4&limit=50&window=180d",
    headers={"X-API-Key": API_KEY},
)

import os
import requests

API_KEY = os.environ["VIKE_API_KEY"]  # your key, read from the environment

# each shared counterparty with both sides' volume
r = requests.get(
    "https://data.vike.io/v1/onchain/wallets/compare?address_a=0x28C6c06298d514Db089934071355E5743bf21d60&address_b=0xeae7380dd4cef6fbd1144f49e4d1e6964258a4f4&limit=50&window=30d",
    headers={"X-API-Key": API_KEY},
)
# then: jq '[.shared_counterparties[] | {wallet, entity, a_volume_usd, b_volume_usd}]'

import os
import requests

API_KEY = os.environ["VIKE_API_KEY"]  # your key, read from the environment

# who sent the first ETH to wallet A, with the sender's label
r = requests.get(
    "https://data.vike.io/v1/onchain/wallets/0x556e9d5d9e64638edde632bbd4810c9fd0d88397/first-funder",
    headers={"X-API-Key": API_KEY},
)
# then: jq '.first_native_in | {from, label, wallet_type, time, amount, amount_symbol}'

import os
import requests

API_KEY = os.environ["VIKE_API_KEY"]  # your key, read from the environment

# who sent the first ETH to wallet B
r = requests.get(
    "https://data.vike.io/v1/onchain/wallets/0xdfd5293d8e347dfe59e90efd55b2956a1343963d/first-funder",
    headers={"X-API-Key": API_KEY},
)
# then: jq '.first_native_in | {from, label, wallet_type, time, amount, amount_symbol}'

import os
import requests

API_KEY = os.environ["VIKE_API_KEY"]  # your key, read from the environment

# the addresses that sent money to wallet A, and who funded them, over 90 days
r = requests.get(
    "https://data.vike.io/v1/onchain/wallets/0x556e9d5d9e64638edde632bbd4810c9fd0d88397/trace?direction=in&depth=2&width=5&window=90d&min_usd=1000",
    headers={"X-API-Key": API_KEY},
)
# then: jq -r '.nodes[] | "\(.address) \(.depth) \(.label)"'

import os
import requests

API_KEY = os.environ["VIKE_API_KEY"]  # your key, read from the environment

# counterparties and tokens the two wallets share over 180 days
r = requests.get(
    "https://data.vike.io/v1/onchain/wallets/compare?address_a=0x556e9d5d9e64638edde632bbd4810c9fd0d88397&address_b=0xdfd5293d8e347dfe59e90efd55b2956a1343963d&window=180d&limit=20",
    headers={"X-API-Key": API_KEY},
)

import os
import requests

API_KEY = os.environ["VIKE_API_KEY"]  # your key, read from the environment

# the five addresses that moved the most USD to and from the Chainlink staking pool, all history
r = requests.get(
    "https://data.vike.io/v1/onchain/wallets/0xbc10f2e862ed4502144c7d632a3459f49dfcdb5e/counterparties?window=all&limit=5",
    headers={"X-API-Key": API_KEY},
)

import os
import requests

API_KEY = os.environ["VIKE_API_KEY"]  # your key, read from the environment

# entity, wallet type and risk flag for the top counterparties
r = requests.post(
    "https://data.vike.io/v1/onchain/labels/batch?addresses=0xedf03cd5075f93174614febf9c6789a3e7581d4c,0xd031c0d7b7996899d4712d50f33d2a539794d985,0xaa6d57e15af3d58feb0ea3f02cbb5319046a26e5",
    headers={"X-API-Key": API_KEY},
)

import os
import requests

API_KEY = os.environ["VIKE_API_KEY"]  # your key, read from the environment

# what the second-ranked staker holds now, on all four chains, holdings of 1,000 USD and up
r = requests.get(
    "https://data.vike.io/v1/onchain/wallets/0xd031c0d7b7996899d4712d50f33d2a539794d985/balances?min_usd=1000",
    headers={"X-API-Key": API_KEY},
)

import os
import requests

API_KEY = os.environ["VIKE_API_KEY"]  # your key, read from the environment

# the top 50, keeping rows where one direction carries more than 60% of the volume
r = requests.get(
    "https://data.vike.io/v1/onchain/wallets/0xbc10f2e862ed4502144c7d632a3459f49dfcdb5e/counterparties?window=all&limit=50",
    headers={"X-API-Key": API_KEY},
)
# then: jq '[.[] | select(.sent_usd > 0.6 * .total_volume_usd or .received_usd > 0.6 * .total_volume_usd)]'