# Coin Lineage

> Walk a Chia coin back through its parents or forward through its children for N hops, classifying each step (XCH / CAT / NFT / DID) and labelling known addresses. Use when the user wants provenance, forensics, "where did this coin come from", or "where did the funds go after this spend". Accepts coin_id, direction, hops as arguments for programmatic invocation.

- Skill: `spacetime-technology/coin-lineage` (Agent Skill)
- Install (CLI): `npx skillmds@latest add spacetime-technology/coin-lineage`
- Raw SKILL.md: https://api.skillmd.com/api/skills/spacetime-technology/coin-lineage/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Spacetime-Technology (https://skillmd.com/u/spacetime-technology)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/spacetime-technology/coin-lineage

---


# Coin lineage

You are tracing a Chia coin's lineage: walking back through its parents (provenance) or forward through its children (where did it go). Each step is classified by puzzle type — plain XCH, CAT, NFT, DID, settlement-payments — and any known destination address (exchanges, market makers, prefarm wallets) is labelled.

This skill follows the conventions in this repo's `SKILLS.md`. Read that if anything below is unclear.

## Required capabilities

- **chia-explorer** (`mcp__chia-explorer__*`) — mandatory. Uses `get_coin_by_name`, `get_coin_records_by_parent_ids`, `get_puzzle_and_solution`, `decompile_puzzle`, `list_prefarm_addresses`.

## Resolve inputs

You need: `$coin_id`, `$direction`, `$hops`.

- `$coin_id` — coin name as `0x...` hex (32 bytes / 64 hex chars). Required.
- `$direction` — one of `back` (walk parents), `forward` (walk children), or `both`. Default `back`.
- `$hops` — how many hops to walk. Default `5`. Hard cap at `20` to keep RPC pressure bounded.

Resolve: arguments → context → ask user.

Validate `$coin_id` (32 bytes hex). Reject anything else.

If `$hops > 20`, cap it and tell the user inline ("walking 20 hops max — bump in the skill if you need more").

## Walk back (provenance)

Start from the supplied coin. For each hop:

1. Look up the coin record by name. Capture: parent_coin_info, puzzle_hash, amount, spent_block, created_block.
2. Decompile the puzzle at the spent block to classify the coin (XCH / CAT / NFT / DID / settlement / unknown).
3. Convert the puzzle_hash to a bech32m address. Check chia-explorer's prefarm registry for a label; if matched, attach it (`prefarm: swiss_cold`, `exchange: HTX`, etc.).
4. Move to `parent_coin_info` as the next coin_id to look up.

Stop conditions:

- Hit the configured `$hops` limit.
- Reach a coin whose parent is a coinbase / farming reward (height-encoded parent). Note this as the lineage origin.
- Reach a coin that can't be resolved (chia-explorer returns nothing). Note "lineage broken".

## Walk forward (where did it go)

Start from the supplied coin. For each hop:

1. Verify the coin is spent. If unspent, the chain ends here — note "still unspent".
2. Call `get_coin_records_by_parent_ids` with the current coin as the parent to fetch the children.
3. For each child:
   - Classify (XCH / CAT / NFT / DID / etc.).
   - Resolve the puzzle_hash to an address; check the prefarm registry for a label.
4. If there's more than one child, the lineage branches. Walk each branch up to `$hops` levels deep but note the branching so the report is honest.

Stop conditions:

- Hit `$hops`.
- All children are unspent at the current frontier.
- A child has a known destination label (exchange / market maker) and the user only wanted "where did the money go": stopping at the labelled destination is more useful than walking further.

## Both

Run `back` and `forward` independently. Render two trees in the report.

## Compose the report

Inline ASCII tree, one line per hop, classification and address label visible.

```
Coin lineage — 0xabc...123 (back, 5 hops)

  0xabc...123   3.500 XCH    spent at 6,532,217   XCH (p2)
    → parent
  0xdef...456   3.550 XCH    spent at 6,532,210   XCH (p2)    addr: xch1zzz...
    → parent
  0x789...      10.000 XCH   spent at 6,531,800   XCH (p2)    addr: xch1aaa...  (exchange: Coinbase)
    → parent
  0x654...      10.000 XCH   farming reward at 6,531,799      (lineage origin)
```

For forward walks, show branching:

```
Coin lineage — 0xabc...123 (forward, 5 hops)

  0xabc...123   3.500 XCH    spent at 6,532,217   XCH (p2)
  ├─ child  0xfff...   2.000 XCH    XCH (p2)   addr: xch1bbb...
  │  └─ child  0xeee...   2.000 XCH   spent at 6,532,224   XCH (p2)   addr: xch1ccc... (exchange: HTX)
  └─ child  0xggg...   1.500 XCH    XCH (p2)   addr: xch1ddd...   (still unspent)
```

Trim coin ids and addresses to first 8 / last 6 chars in the tree. Always list the full ids in a short footer for copy-paste.

## Risk and provenance notes

When you spot interesting things, surface them at the bottom:

- The lineage passes through a labelled exchange address — common provenance pattern.
- The lineage passes through the prefarm — note which custody wallet and at what height.
- One hop is a CAT melt (CAT → XCH) — note it; can be relevant to tax accounting.
- The lineage branches into many children at one step — possibly a batch send or a CAT puzzle.

Don't editorialise on whether the coin is "clean" or "dirty". Report observations.

## Hard rules

- **Read-only.** Never sign, never broadcast.
- **Hop cap is real.** Don't trace 10,000 hops; that's an explorer's job, not a skill's.
- **Always show full ids in the footer.** Truncation in the tree is for readability; full values are for verification.
- **Don't invent ownership.** An address labelled "Coinbase" means it matches chia-explorer's registry. It does *not* mean the coin is or isn't legitimately on Coinbase.

## Recovery patterns

- **Coin not found.** Emit `STATUS: failed`, `REASON: coin not found by name`.
- **Puzzle decompile fails for one hop.** Mark that hop "decode failed" but continue the walk.
- **Forward walk explodes** (200+ children at one step). Stop at that hop, summarise as "fan-out: N children, not walked further".

## Output

```
STATUS: success | partial | failed | aborted
DIRECTION: back | forward | both
HOPS_WALKED: <int, may be less than requested if origin was reached>
TERMINAL: lineage_origin | unspent_frontier | hop_cap | broken_lineage
RISK_NOTES: <comma-separated tags, e.g. exchange_addr, prefarm_passthrough, cat_melt> | none
ARTIFACT: none
REASON: <one line, only when STATUS is failed, partial, or aborted>
```