tres-export-3rd-party-contacts

# 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.

```graphql
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:
```json
{
  "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 `accountTxsSummary` fiat values
- `Total USD`: sum of inflow + outflow fiat values

#### Formatting guidelines

- Bold the header row on all tabs
- Auto-fit column widths for readability
- Format USD columns as numbers (no $ prefix in cells — use Excel number formatting)
- The "Contacts" tab should be the first/active sheet when the file opens, since that's the one the user will work in

### Step 5 — Save and present

Save the XLSX to the outputs directory. Use a descriptive filename like `tres_3rd_party_contacts_<org_name>_<date>.xlsx` (replace spaces and special chars with underscores).

Present the file to the user with a brief summary:
- How many unique unidentified addresses were found
-