---
title: "Trace Provenance"
method: POST
path: "/v1/trace/provenance"
tags: ["trace"]
---

# Trace Provenance

`POST /v1/trace/provenance`

## Request

- Base URL: `https://api.bitpoort.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.bitpoort.com/v1/trace/provenance`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Bounded live FIFO provenance PREVIEW of one address — the native-ETH lane
(``asset="ETH"``) or ONE ERC-20 token per call (``asset=<0x contract>``).

The same engine that produced the signed Source-of-Funds artifacts, run for
an arbitrary seed with the chain's mixer + sanctions set as destinations:
the subject's OWN tainted units per destination with the carrier rows (tx
hash each), lane exits, dispositions, and every bound it hit. ADVISORY and
unsigned. Fail-closed: 503 ``provenance_disarmed`` until the interactive tape
read is armed on the deployment (CHAINRAG_PROV_PREVIEW_ARMED=1, founder env word), typed 503s for busy / timeout /
unavailable, a typed 422 ``provenance_subject_over_budget`` for a subject whose
own tape exceeds the row budget — never a fabricated trace.

## Request body

- ProvenancePreviewRequest
  - `address` string, required
  - `chain` string
  - `asset` string
  - `direction` 'forward' | 'backward'
  - `question` BackwardQuestion: P-B: what a backward preview composes — the subject's still-held balance (default) or ONE outbound row named by tx hash (+ trace_path on the native lane / log_index on the token lane when the tx carries several).
    - `kind` 'still_held' | 'outbound_row'
    - `tx_hash` string, nullable
    - `trace_path` integer[], nullable
    - `log_index` integer, nullable
  - `max_addresses` integer
  - `max_hops` integer
  - `max_tape_rows` integer
  - `top_n_edges` integer, nullable
  - `dust_threshold_wei` integer
  - `to_block` integer, nullable

## Response `200`

Successful Response

- object

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/bitpoort/apis/bitpoort-api.md) · [All operations](https://skmtc.dev/bitpoort/apis/bitpoort-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bitpoort/apis/bitpoort-api/revisions/1a51d8566777?raw)