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.

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 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
• Total number of transactions involving these addresses
• A link to the XLSX file

Then explain what each tab is for:

Your workbook has 2 tabs:

1. Contacts — This is the import-ready sheet. Fill in the Contact Name for each address you recognize, and optionally add a Contact Tag (e.g. Exchange, Vendor, Treasury). When you're done, use the contacts import skill to upload this sheet back into TRES.

2. Address details — Reference tab showing the detected network, activity stats for each address (inflow/outflow transaction counts and USD volumes). Use this to prioritize which addresses to label — the highest-volume counterparties are at the top. The network column helps narrow down which chain the address belongs to.

Edge Cases

• No unidentified addresses found: If the result set is empty, tell the user — it likely means all counterparty addresses are already in the contacts list.
• Mixed-case addresses: EVM addresses can appear in different checksummed forms. Always compare in lowercase for deduplication, but preserve the original case in the output.
• Zero/burn addresses: Include 0x0000000000000000000000000000000000000000 in the output if it appears — the user may still want to label it as "Burn Address" or similar.
• Unknown network: If an address doesn't match any known pattern, set Network to "Unknown". Don't skip the address — it's still a valid counterparty.