Tracing

Walk an address's funding backwards to find who paid it

The mirror of /v1/trace: walks INCOMING edges backwards to answer 'where did this wallet's money come from'. Any labelled entity is a dead end (the trail stops at the exchange rather than walking into its other customers), and so is an unlabelled wallet whose own degree makes it a service — otherwise a single dispenser pulls in everyone who ever used it.

One call replaces a client-side per-hop BFS. Long walks return done: false with a cursor; pass it back to continue the SAME traversal (state lives server-side for an hour). hop_trace is the delta for that call, source_links and nodes_visited are cumulative.

USD valuation is left to the caller: every flow carries value_raw plus a per-token breakdown.

venues groups every casino (gambling) address the walk met by BRAND: 'Stake.com' and 'Stake.com (deposit)' are one venue, while in source_links they stay two links (that list keeps its shape). Brands are matched as exact strings, not normalised. Each address says which wallet of the venue it is (venue_role) and on what basis; hot_wallet is only ever the address's own role, never a label copied from its cluster's anchor. No attribution axes here: take them from /v2/enrich for the addresses you need.

post/v1/source-trace

Request

  • Base URL: https://intelapi.publicaml.org
  • URL: https://intelapi.publicaml.org/v1/source-trace
  • Auth: one of:
    • API key in header X-API-Key
    • none

Request body

addressstring required

The address whose funding to trace.

The address to look up, in its normal display form.

  • bitcoin — base58 (1…, 3…) or bech32/bech32m (bc1…, bc1p…). Case is SIGNIFICANT for base58; do not lowercase it. A 64-character lowercase TRANSACTION HASH is also accepted here: on bitcoin the graph is bipartite (address → transaction → address), so a transaction is a node with its own neighbours and its own findings. CoinJoin is classified on the transaction, not on the participants, and this is how you read it.
  • ethereum, bsc — 0x + 40 hex characters, any case.
  • tron — base58 (T…, 34 characters); the 0x 20-byte form is accepted too and is what the API stores and echoes.
chain'bitcoin' | 'ethereum' | 'bsc' | 'tron' required

Which blockchain the address belongs to. Send one of the four values in the enum. The short forms used by the older clients (ETH, BTC, TRX, BNB) and any capitalisation are still accepted, but responses always echo the canonical spelling.

Getting this wrong is the single commonest integration bug: the same 0x-prefixed address exists on ethereum, bsc and tron and means a different wallet on each, so the chain is part of the identity, never a hint. If it does not match the address format the call fails with invalid_address_format, which names the chain the address does look like.

max_hopsinteger

How far back to walk.

max_widthinteger

Funders to expand per address, largest first.

max_nodesinteger

Hard ceiling. Hitting it ends the walk with truncated: true.

budget_secnumber

Wall-clock ceiling for this call's walk. Default 8 s (40 s on bitcoin).

top_ninteger

Counterparties in the root profile.

expand_widthinteger

How many hop-1 funders to walk back from. Defaults to max_width.

direct_widthinteger

How many direct funders to report at hop 1.

surface_categoriesstring[]

Which labelled entity types to aggregate into source_links. Default ['gambling'].

stop_at_hubsboolean

Stop at unlabelled high-degree addresses. Turning this off will pull in unrelated wallets.

cursorstring

Resume token from a prior done: false response.

Response

The backward funding trace.

rootobject

The subject's own profile — score, counterparties, source of funds.

source_linksobject[]

Labelled funding sources found, aggregated. Cumulative across resumed calls.

hop_traceobject[]

Nodes visited by THIS call only.

nodes_visitedinteger
hub_stopsinteger

Addresses not expanded because their degree made them a service.

truncatedboolean
doneboolean

false = more remains; re-send with cursor.

cursorstring nullable
effectiveobject

The parameters actually used.

clampedstring[]

Parameters that were reduced to their allowed range.

Changes

No recorded changes to this operation across all 1 revision of this API.