/tres-export-3rd-party-contacts

name: tres-export-3rd-party-contacts
description: "Extract all 3rd-party (non-owned) addresses from a TRES Finance environment and export them as an XLSX workbook to help users build their contacts list. Use this skill whenever the user wants to export, list, or identify 3rd-party addresses, counterparties, or external addresses from their transactions — even if they don't say 'contacts'. Also trigger when the user asks to prepare a contacts import file, find unknown addresses, or build an address book from transaction history. Do NOT trigger for viewing existing contacts or searching the address book — only for extracting NEW 3rd-party addresses from transaction data."

TRES Finance — Export 3rd-Party Addresses as Contacts Workbook

Goal

Fetch all **unidentified** external addresses from the user's TRES environment using the `accountTxsSummary` query (the same data source that powers the "Unidentified Addresses" tab in the TRES UI), deduplicate them, enrich them with activity data, and produce an XLSX workbook with two tabs:

1. **Contacts** — the import-ready sheet matching the TRES contacts template. The user fills in names and tags here, then imports this sheet back into TRES. 2. **Address details** — enrichment data (network, tx counts, fiat volumes) to help users identify who each address belongs to.

The workflow gives users a fast way to build their address book: Claude extracts, deduplicates, and enriches the unidentified addresses, and the user just needs to label them.

MCP Server

All GraphQL calls use the **user-tres-finance** MCP server (`execute` tool).

Workflow

Step 1 — Authenticate

Call `get_viewer` (no arguments) to confirm the session is active and note the organization name.

Step 2 — Fetch unidentified addresses

Use the `accountTxsSummary` query with `identificationState: "UNIDENTIFIED"` — this is the same query the TRES UI uses for the "Unidentified Addresses" tab under Accounts. It already excludes the organization's own wallets and returns only external counterparty addresses that haven't been named yet.

query UnidentifiedAddresses($limit: Int, $offset: Int, $identificationState: String, $excludeInternalAccounts: Boolean, $fiatCurrency: String) {
  accountTxsSummary(
    limit: $limit
    offset: $offset
    identificationState: $identificationState
    excludeInternalAccounts: $excludeInternalAccounts
    fiatCurrency: $fiatCurrency
  ) {
    totalCount
    results {
      accountIdentifier
      displayName
      inflowTxCount
      outflowTxCount
      inflowFiatValue
      outflowFiatValue
    }
  }
}

Variables:

{
  "limit": 500,
  "offset": 0,
  "identificationState": "UNIDENTIFIED",
  "excludeInternalAccounts": true,
  "fiatCurrency": "usd"
}

Paginate through all results (increment `offset` by 500 each time until you've collected all entries from `totalCount`).

Step 3 — Deduplicate and detect network

The `accountTxsSummary` query can return the same address more than once (e.g. different casing variants of the same EVM address, or separate rows for sender vs. receiver context). Deduplicate by **lowercased** `accountIdentifier`:

• Build a dictionary keyed by `accountIdentifier.lower()`
• For each address, keep the first occurrence's original casing and accumulate the total inflow + outflow tx count and fiat values
• Skip addresses with an empty or null `accountIdentifier`

Sort the deduplicated addresses by total fiat volume (inflow + outflow) descending, so the most active counterparties appear first — these are typically the ones the user will want to label first.

**Network detection:** The API does not return a network field, so infer the network from the address format. Use these rules:

| Address pattern | Network | |---|---| | Starts with `0x` (42 chars, hex) | EVM | | Starts with `KT1` | Tezos (contract) | | Starts with `tz1`, `tz2`, `tz3` | Tezos | | Starts with `T` (34 chars, base58) | Tron | | Starts with `bc1` or `1` or `3` (25–62 chars) | Bitcoin | | Starts with `r` (25–35 chars) | XRP Ledger | | Starts with `cosmos1` | Cosmos | | Starts with `osmo1` | Osmosis | | Starts with `terra1` | Terra | | Starts with `addr1` or `stake1` | Cardano | | Starts with `bnb1` | BNB Beacon Chain | | Starts with `G` (56 chars) | Stellar | | Starts with `D` or `A` or `L` or `M` or `ltc1` (26–35 chars) | Litecoin/Dogecoin (best guess) | | None of the above | Unknown |

This is a best-effort heuristic — EVM addresses in particular could belong to Ethereum, Polygon, Arbitrum, Base, Avalanche, BSC, or any other EVM-compatible chain. The label "EVM" is intentionally broad because the address alone can't distinguish which chain it's on.

Step 4 — Build the XLSX workbook

Use Python with `openpyxl==3.1.5`. If not installed, stop and display: > "openpyxl is not installed. Please run: `python3 -m venv .venv && .venv/bin/pip install openpyxl==3.1.5`"

Tab 1: "Contacts" (import-ready)

This sheet matches the TRES contacts import template exactly:

| Contact Name | Contact Address | Contact Tag | |---|---|---| | *(blank)* | 0xABC... | *(blank)* |

• **Contact Name**: leave blank (the user will fill this in)
• **Contact Address**: the address identifier (original casing)
• **Contact Tag**: leave blank (the user will fill this in)
• Sorted by total fiat volume descending (same order as Address details)

Tab 2: "Address details" (enrichment)

| Contact Address | Network | Inflow Txs | Outflow Txs | Inflow USD | Outflow USD | Total USD | |---|---|---|---|---|---|---| | 0xABC... | EVM | 142 | 38 | 1,240,500 | 890,200 | 2,130,700 | | KT1Xyz... | Tezos (contract) | 6 | 0 | 40,144,631 | 0 | 40,144,631 | | TBmxn... | Tron | 23 | 5 | 340,100 | 52,000 | 392,100 |

• Same address order as the Contacts tab (sorted by Total USD descending)
• `Network`: inferred from address format (see Step 3)
• `Inflow Txs` / `Outflow Txs`: from `accountTxsSummary` results
• `Inflow USD` / `Outflow USD`: from `accountTxsSumm