● Getting started

Golden path: judgment to freeze packet

The canonical end-to-end run. Open a matter, attach a judgment, dispatch a crypto trace, record a recovery event, build an exchange freeze packet, export it with chain-of-custody, and verify the audit chain.

API version: 2026-07-05. Surface: 45 ops / 11 resources. All responses below are from a live sandbox run against api.kineticanvil.com.

Step sequence

K

Mint a sandbox key

POST kineticanvil.com/api/sandbox-key
0

Health check

GET /v1/health
1

Open a matter

POST /v1/matters
2

Add parties (debtor + claimant)

POST /v1/parties ×2
3

Intake the judgment (all eight required fields)

POST /v1/judgments/intake
4

Validate judgment readiness

POST /v1/judgments/{id}/validate
5

Set enforcement posture

POST /v1/judgments/{id}/enforcement
6

Dispatch crypto trace (202 + poll)

POST /v1/crypto/asset-map → poll GET /v1/jobs/{id}
7

Record recovery event

POST /v1/ledger/recovery-events
8

Build freeze packet

POST /v1/packets
9

Export packet (chain-of-custody PDF)

POST /v1/packets/{id}/export
10

Calculate waterfall, read dashboard, verify audit chain

POST /v1/waterfall/calculate • GET /v1/matters/{id}/dashboard • GET /v1/events/verify-chain

Request contract

Judgment intake takes all eight fields in one request. POST /v1/judgments/intake requires matter_id, court, case_number, jurisdiction, creditor, debtor, amount, and date_entered. A partial intake returns 422 with the missing field names. PATCH /v1/judgments/{id} updates lifecycle fields only: status, appeal_stay_status, bankruptcy_status, renewal_deadline, review_state.
Recovery amounts. gross_amount is the canonical request field. usd_value is accepted as an alias; responses carry both.
Packet types map to intent. To freeze an exchange account, use exchange_freeze. Full enum: exchange_intercept, vasp_legal_process, exchange_freeze, exchange_turnover, turnover_workflow, sanctions_review, law_enforcement_referral, issuer_freeze, burn_reissue, destination_wallet_certificate, ofac_report.
Terminal status is succeeded. Jobs and asset maps both finish succeeded. Requests pinned to a version before 2026-07-05 read complete on asset maps; that alias retires with the version window.

Key: Mint a sandbox key

curl -s -X POST https://kineticanvil.com/api/sandbox-key \
  -H "Content-Type: application/json" \
  -d '{}'

Response 201

{
  "key": "kx_test_...",
  "key_id": "key_b019d27c0687",
  "environment": "sandbox",
  "scope": "sandbox:read sandbox:write",
  "base_url": "https://api.kineticanvil.com",
  "rate_limit": "5000 req/min per key",
  "note": "Shown once. The key is signed, not stored, and cannot be recovered. Mint a replacement if this one is lost.",
  "docs": "https://docs.kineticanvil.com"
}

The key is shown once. Store it immediately. Set ANVIL_KEY=kx_test_... for the commands below.

Step 0: Health check

curl -s https://api.kineticanvil.com/v1/health

Response 200

{
  "status": "ok",
  "object": "health",
  "version": "2026-07-05",
  "environment": "sandbox",
  "store": "neon",
  "timestamp": "2026-07-05T20:33:33.971Z"
}

Step 1: Open a matter

Every judgment lives on a matter. The matter carries authority, economics, and the audit chain for its entire lifecycle.

curl -s -X POST https://api.kineticanvil.com/v1/matters \
  -H "Authorization: Bearer $ANVIL_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: gp-matter-$(date +%s)" \
  -d '{
    "name": "Varela v. Zhao - BTC Recovery",
    "mode": "recovery",
    "lead_counsel": "Sarah L. Varela, Esq."
  }'

Response 201

{
  "name": "Varela v. Zhao - BTC Recovery",
  "mode": "recovery",
  "lead_counsel": "Sarah L. Varela, Esq.",
  "matter_id": "matter_3ee6c9d0418fz52bdq",
  "id": "matter_3ee6c9d0418fz52bdq",
  "organization_id": "org_8eefaa57986d",
  "status": "active",
  "created_at": "2026-07-05T20:33:57.005Z"
}

Save the matter_id. It links every subsequent call.

Step 2: Add parties

Attach a debtor and at least one claimant. The claimant share (0–1.0) drives waterfall calculations later.

curl -s -X POST https://api.kineticanvil.com/v1/parties \
  -H "Authorization: Bearer $ANVIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "matter_id": "matter_3ee6c9d0418fz52bdq",
    "role": "debtor",
    "name": "Wei Zhao",
    "notes": "Known BTC wallet 1A1zP1eP5QGefi2DMPTfTL5SLmv7Divfna"
  }'

Response 201

{
  "matter_id": "matter_3ee6c9d0418fz52bdq",
  "role": "debtor",
  "name": "Wei Zhao",
  "party_id": "party_3b1fc5ebeeebrsaxnx",
  "id": "party_3b1fc5ebeeebrsaxnx",
  "object": "party",
  "status": "active",
  "created_at": "2026-07-05T20:34:07.762Z",
  "updated_at": "2026-07-05T20:34:07.762Z"
}

curl -s -X POST https://api.kineticanvil.com/v1/parties \
  -H "Authorization: Bearer $ANVIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "matter_id": "matter_3ee6c9d0418fz52bdq",
    "role": "claimant",
    "name": "Elena Varela",
    "share": 1.0
  }'

Response 201

{
  "matter_id": "matter_3ee6c9d0418fz52bdq",
  "role": "claimant",
  "name": "Elena Varela",
  "party_id": "party_f964f9cd5f49zgtl8y",
  "id": "party_f964f9cd5f49zgtl8y",
  "object": "party",
  "status": "active",
  "created_at": "2026-07-05T20:34:07.954Z",
  "updated_at": "2026-07-05T20:34:07.954Z"
}

Step 3: Intake the judgment

All eight intake fields are required in the same request. PATCH updates lifecycle fields only; it cannot add core fields after the fact.

curl -s -X POST https://api.kineticanvil.com/v1/judgments/intake \
  -H "Authorization: Bearer $ANVIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "matter_id": "matter_3ee6c9d0418fz52bdq",
    "amount": 285000,
    "court": "Southern District of New York",
    "case_number": "1:24-cv-04471",
    "date_entered": "2024-11-15",
    "jurisdiction": "United States - SDNY",
    "creditor": "Elena Varela",
    "debtor": "Wei Zhao"
  }'

Response 201

{
  "matter_id": "matter_3ee6c9d0418fz52bdq",
  "court": "Southern District of New York",
  "case_number": "1:24-cv-04471",
  "jurisdiction": "United States - SDNY",
  "creditor": "Elena Varela",
  "debtor": "Wei Zhao",
  "amount": 285000,
  "date_entered": "2024-11-15",
  "judgment_id": "judgment_7c716919f8eftbuwa5",
  "id": "judgment_7c716919f8eftbuwa5",
  "object": "judgment",
  "status": "active",
  "created_at": "2026-07-05T20:34:08.102Z"
}

Step 4: Validate judgment readiness

Runs every gate in sequence and returns ready: true/false with every failing gate named. A pass emits judgment.validated to your webhook endpoint.

curl -s -X POST \
  https://api.kineticanvil.com/v1/judgments/judgment_7c716919f8eftbuwa5/validate \
  -H "Authorization: Bearer $ANVIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 200

{
  "object": "judgment_validation",
  "judgment_id": "judgment_7c716919f8eftbuwa5",
  "matter_id": "matter_3ee6c9d0418fz52bdq",
  "ready": true,
  "gates": {
    "judgment_present": true,
    "amount_set": true,
    "court_set": true,
    "parties_linked": true,
    "not_expired": true
  },
  "validated_at": "2026-07-05T20:34:50.308Z"
}

Step 5: Set enforcement posture

Declares strategy, target venues, and priority order for the trace-and-freeze run. Sets review_required: true until a reviewer clears it.

curl -s -X POST \
  https://api.kineticanvil.com/v1/judgments/judgment_7c716919f8eftbuwa5/enforcement \
  -H "Authorization: Bearer $ANVIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "strategy": "crypto_trace_and_freeze",
    "venues": ["binance", "okx"],
    "priorities": ["trace", "freeze", "disclose"]
  }'

Response 200

{
  "object": "enforcement",
  "judgment_id": "judgment_7c716919f8eftbuwa5",
  "review_required": true,
  "updated_at": "2026-07-05T20:35:08.192Z",
  "strategy": "crypto_trace_and_freeze",
  "venues": ["binance", "okx"],
  "priorities": ["trace", "freeze", "disclose"]
}

Step 6: Dispatch crypto trace

The trace call returns 202 immediately. A brain worker claims the crypto.trace job from the queue and executes it asynchronously. Poll the job endpoint until status is "succeeded", then read the map.

curl -s -X POST https://api.kineticanvil.com/v1/crypto/asset-map \
  -H "Authorization: Bearer $ANVIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "matter_id": "matter_3ee6c9d0418fz52bdq",
    "wallets": ["1A1zP1eP5QGefi2DMPTfTL5SLmv7Divfna"],
    "chains": ["bitcoin"],
    "include_exchanges": true
  }'

Response 202 processing

{
  "object": "crypto_asset_map",
  "map_id": "amap_21cb17f7cf53pu1u73",
  "wallets": [],
  "token_exposures": [],
  "exchange_hypotheses": [],
  "stablecoin_exposure": [],
  "status": "processing",
  "job_id": "job_21cb17f7cf531bvizm"
}

202 poll pattern

Poll GET /v1/jobs/{job_id} every 8 seconds. Terminal states are "succeeded" and "failed". A typical trace on a single address completes in 4–30 seconds depending on on-chain activity.

until [ "$(curl -s https://api.kineticanvil.com/v1/jobs/job_21cb17f7cf531bvizm \
  -H "Authorization: Bearer $ANVIL_KEY" | jq -r .status)" = "succeeded" ]; do
  echo "waiting..."; sleep 8
done

Job response 200 (terminal) succeeded

{
  "job_id": "job_21cb17f7cf531bvizm",
  "object": "job",
  "type": "crypto.trace",
  "status": "succeeded",
  "input": {
    "kind": "asset_map",
    "chains": ["bitcoin"],
    "map_id": "amap_21cb17f7cf53pu1u73",
    "wallets": ["1A1zP1eP5QGefi2DMPTfTL5SLmv7Divfna"],
    "max_hops": 5,
    "direction": "outflow",
    "matter_id": "matter_3ee6c9d0418fz52bdq"
  },
  "result": {
    "hops": 5,
    "chain": "btc",
    "edges": [],
    "flows": [],
    "object": "crypto_asset_map",
    "source": "public_chain_data",
    "wallets": [
      {
        "hop": 0,
        "role": "subject",
        "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7Divfna",
        "network": "btc",
        "wallet_id": "w_0",
        "confidence": "high"
      }
    ],
    "subjects": ["1A1zP1eP5QGefi2DMPTfTL5SLmv7Divfna"],
    "terminals": [],
    "traced_at": "2026-07-05T20:35:22.343Z",
    "edge_count": 0,
    "node_count": 1,
    "exchange_hypotheses": []
  },
  "error": null,
  "matter_id": "matter_3ee6c9d0418fz52bdq",
  "attempts": 1,
  "created_at": "2026-07-05T20:35:18.690Z",
  "updated_at": "2026-07-05T20:35:22.401Z"
}

Then fetch the completed map:

curl -s https://api.kineticanvil.com/v1/crypto/asset-map/amap_21cb17f7cf53pu1u73 \
  -H "Authorization: Bearer $ANVIL_KEY"

Response 200 complete

{
  "object": "crypto_asset_map",
  "map_id": "amap_21cb17f7cf53pu1u73",
  "wallets": [
    {
      "hop": 0,
      "role": "subject",
      "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7Divfna",
      "network": "btc",
      "wallet_id": "w_0",
      "confidence": "high"
    }
  ],
  "token_exposures": [],
  "exchange_hypotheses": [],
  "stablecoin_exposure": [],
  "hops": 5,
  "chain": "btc",
  "edges": [],
  "flows": [],
  "source": "public_chain_data",
  "subjects": ["1A1zP1eP5QGefi2DMPTfTL5SLmv7Divfna"],
  "terminals": [],
  "traced_at": "2026-07-05T20:35:22.343Z",
  "edge_count": 0,
  "node_count": 1,
  "status": "complete",
  "job_id": "job_21cb17f7cf531bvizm"
}

Note: the BTC genesis address carries no outgoing transactions (coinbase-only address), so edges, flows, and exchange_hypotheses are empty. The trace is correct. For multi-hop output, use an address with spending history, such as an active exchange hot-wallet or an Ethereum address like 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045.

Step 7: Record recovery event

Log the estimated or confirmed recovery against the matter ledger. The request field is gross_amount. usd_value is accepted as an alias; responses carry both.

curl -s -X POST https://api.kineticanvil.com/v1/ledger/recovery-events \
  -H "Authorization: Bearer $ANVIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "matter_id": "matter_3ee6c9d0418fz52bdq",
    "source": "crypto_trace",
    "gross_amount": 128000,
    "description": "BTC wallet cluster traced to a reviewed deposit-address hypothesis"
  }'

Response 201

{
  "recovery_event_id": "rcv_e4007d3a1ad6iz4rkg",
  "matter_id": "matter_3ee6c9d0418fz52bdq",
  "event_type": "recovery",
  "asset": "USD",
  "gross_amount": 128000,
  "network": null,
  "usd_value": 128000,
  "source": "crypto_trace",
  "packet_id": null,
  "status": "recorded",
  "audit": {
    "request_id": "req_e4007d3a1ad6b2757380",
    "matter_id": "matter_3ee6c9d0418fz52bdq",
    "timestamp": "2026-07-05T20:36:45.428Z"
  },
  "object": "recovery_event",
  "id": "rcv_e4007d3a1ad6iz4rkg"
}

Step 8: Build the freeze packet

Assembles judgment authority, wallets, and recovery evidence into a structured enforcement artifact. Type must be from the enum: use exchange_freeze to freeze an exchange account (not freeze_package).

curl -s -X POST https://api.kineticanvil.com/v1/packets \
  -H "Authorization: Bearer $ANVIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "matter_id": "matter_3ee6c9d0418fz52bdq",
    "type": "exchange_freeze",
    "judgment_id": "judgment_7c716919f8eftbuwa5",
    "recovery_event_ids": ["rcv_e4007d3a1ad6iz4rkg"],
    "wallets": ["1A1zP1eP5QGefi2DMPTfTL5SLmv7Divfna"],
    "target_venue": "binance"
  }'

Response 201

{
  "packet_id": "pkt_5e9dbd285597mfdews",
  "matter_id": "matter_3ee6c9d0418fz52bdq",
  "type": "exchange_freeze",
  "status": "assembled",
  "authorized_sender": "",
  "judgment_id": "judgment_7c716919f8eftbuwa5",
  "wallets": ["1A1zP1eP5QGefi2DMPTfTL5SLmv7Divfna"],
  "freeze_targets": ["1A1zP1eP5QGefi2DMPTfTL5SLmv7Divfna"],
  "recovery_event_ids": ["rcv_e4007d3a1ad6iz4rkg"],
  "legal_authority_id": null,
  "review_state": {
    "review_required": true,
    "review_status": "pending",
    "review_owner": "",
    "review_notes": ""
  },
  "source_refs": [],
  "content_hash": "771b4ff541528cedb5dcac95a107a8e553f80d1c670ea2213936cd108b6aa395",
  "audit": {
    "request_id": "req_5e9dbd2855970416eaf6",
    "matter_id": "matter_3ee6c9d0418fz52bdq",
    "timestamp": "2026-07-05T20:36:59.649Z"
  },
  "object": "packet"
}

Step 9: Export packet

Produces a chain-of-custody PDF artifact. The response carries both the packet content hash and a per-export hash for independent verification.

curl -s -X POST \
  https://api.kineticanvil.com/v1/packets/pkt_5e9dbd285597mfdews/export \
  -H "Authorization: Bearer $ANVIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format": "pdf", "include_chain_of_custody": true}'

Response 201

{
  "export_id": "pex_22c437966cb5ujl78w",
  "object_type": "packet",
  "object_id": "pkt_5e9dbd285597mfdews",
  "format": "pdf",
  "status": "available",
  "download_url": "https://api.kineticanvil.com/v1/exports/pex_22c437966cb5ujl78w.pdf",
  "audit_id": "req_22c437966cb58606da82",
  "export_hash": "d9cd3e861f2642acd08e3dd17ce7aa3a2644b2ec0cd31d9d4bc4c3c298dcd1e0",
  "packet_hash": "771b4ff541528cedb5dcac95a107a8e553f80d1c670ea2213936cd108b6aa395",
  "object": "packet_export"
}

Step 10: Waterfall, dashboard, and verify chain

Calculate claimant distributions, read the matter phase, and confirm every event in the matter's audit chain is unbroken.

curl -s -X POST https://api.kineticanvil.com/v1/waterfall/calculate \
  -H "Authorization: Bearer $ANVIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"matter_id": "matter_3ee6c9d0418fz52bdq", "fee_pct": 20}'

Response 200

{
  "waterfall_id": "wf_aa4c67a80c0ejxklor",
  "matter_id": "matter_3ee6c9d0418fz52bdq",
  "gross_recovered": {
    "amount": 128000,
    "currency": "USD",
    "valuation_time": "2026-07-05T20:37:08.698Z"
  },
  "costs": {},
  "claimant_distributions": [
    {
      "claimant_id": "party_f964f9cd5f49zgtl8y",
      "party_id": "party_f964f9cd5f49zgtl8y",
      "amount": 128000
    }
  ],
  "holdbacks": [],
  "review_state": {
    "review_required": true,
    "review_status": "pending",
    "review_owner": "",
    "review_notes": ""
  },
  "object": "waterfall"
}

curl -s \
  https://api.kineticanvil.com/v1/matters/matter_3ee6c9d0418fz52bdq/dashboard \
  -H "Authorization: Bearer $ANVIL_KEY"

Response 200

{
  "matter_id": "matter_3ee6c9d0418fz52bdq",
  "judgment_value": { "amount": 128000, "currency": "USD" },
  "known_crypto_exposure": { "amount": 128000, "currency": "USD" },
  "open_actions": 1,
  "open_packets": 1,
  "alerts": 0,
  "recovery_events": 1,
  "recovery_phase": "dispatched",
  "phase_index": 3,
  "remittances": 0,
  "packets": 1
}

Phase machine: intake → traced → packaged → dispatched → remitting → settled → closed. Phase dispatched (index 3) reflects a freeze packet assembled and pending reviewer clearance.

curl -s https://api.kineticanvil.com/v1/events/verify-chain \
  -H "Authorization: Bearer $ANVIL_KEY"

Response 200

{
  "object": "chain_verification",
  "valid": true,
  "events_checked": 17,
  "first_break": null,
  "head": "ed246d2ef5eb2c8c5b688f054bccb3545bb82e28adf55a965dba252b49ab0d44",
  "verified_at": "2026-07-05T20:37:35.406Z"
}

Chain valid. 17 events. No breaks. The packet content hash (771b4ff5...) and export hash (d9cd3e86...) are both independently verifiable against the exported PDF.