# graphsense/graphsense-python architecture

> Architecture diagram of the GitHub repository graphsense/graphsense-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/graphsense/graphsense-python
- Repository: https://github.com/graphsense/graphsense-python

## Overview

This is a generated Python client for the GraphSense REST API, used by forensic applications to query cryptocurrency ledger data and annotations. The principal workflow is a caller configuring the client, invoking a domain endpoint, sending an HTTP request to a GraphSense service, and receiving decoded typed API data. The README documents address/entity investigation, deep neighbor search, transaction and block queries, tags, bulk retrieval, statistics, rates, and tokens. API modules are grouped by domain; sampled client and REST excerpts support the transport flow, while endpoint-specific wiring beyond the excerpts is represented only at the documented capability level.

Main entry points: [`graphsense/api_client.py`](https://github.com/graphsense/graphsense-python/blob/master/graphsense/api_client.py) (Request client), [`graphsense/api/entities_api.py`](https://github.com/graphsense/graphsense-python/blob/master/graphsense/api/entities_api.py) (Entity queries), [`graphsense/api/addresses_api.py`](https://github.com/graphsense/graphsense-python/blob/master/graphsense/api/addresses_api.py) (Address queries), [`graphsense/api/txs_api.py`](https://github.com/graphsense/graphsense-python/blob/master/graphsense/api/txs_api.py) (Transaction queries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_domain["Investigation APIs"]
  node_address_api["Address queries<br/>[addresses_api.py]"]
  node_entity_api["Entity queries<br/>[entities_api.py]"]
  node_tx_api["Transaction queries<br/>[txs_api.py]"]
  node_block_api["Block queries<br/>[blocks_api.py]"]
  node_tag_api["Tags and actors<br/>[tags_api.py]"]
  node_bulk_api["Bulk retrieval<br/>[bulk_api.py]"]
  node_general_api["Search and stats<br/>[general_api.py]"]
  node_rates_api["Exchange rates<br/>[rates_api.py]"]
  node_tokens_api["Token support<br/>[tokens_api.py]"]
end

subgraph group_client["Client Runtime"]
  node_api_client["Request client<br/>[api_client.py]"]
  node_configuration["Client configuration<br/>[configuration.py]"]
  node_rest["HTTP transport<br/>[rest.py]"]
end

subgraph group_models["Response Models"]
  node_models["Typed API models"]
  node_address_models["Address data<br/>[address.py]"]
  node_entity_models["Entity and neighbors<br/>[entity.py]"]
  node_search_models["Search paths"]
  node_tx_models["Transaction data<br/>[tx.py]"]
  node_tag_models["Tag and actor data<br/>[tag.py]"]
  node_block_models["Block data<br/>[block.py]"]
end

node_caller(("Forensics caller"))
node_service{{"GraphSense API"}}

node_caller -->|"configures"| node_configuration
node_caller -->|"invokes"| node_address_api
node_caller -->|"invokes"| node_entity_api
node_caller -->|"invokes"| node_tx_api
node_caller -->|"invokes"| node_block_api
node_caller -->|"invokes"| node_tag_api
node_caller -->|"invokes"| node_bulk_api
node_caller -->|"invokes"| node_general_api
node_caller -->|"invokes"| node_rates_api
node_caller -->|"invokes"| node_tokens_api
node_address_api -->|"sends request"| node_api_client
node_entity_api -->|"sends request"| node_api_client
node_tx_api -->|"sends request"| node_api_client
node_block_api -->|"sends request"| node_api_client
node_tag_api -->|"sends request"| node_api_client
node_bulk_api -->|"sends request"| node_api_client
node_general_api -->|"sends request"| node_api_client
node_rates_api -->|"sends request"| node_api_client
node_tokens_api -->|"sends request"| node_api_client
node_api_client -->|"uses settings"| node_configuration
node_api_client -->|"dispatches HTTP"| node_rest
node_rest -->|"requests"| node_service
node_service -->|"returns response"| node_rest
node_api_client -->|"decodes response"| node_models
node_address_api -->|"returns address data"| node_address_models
node_entity_api -->|"returns entity data"| node_entity_models
node_entity_api -->|"returns search paths"| node_search_models
node_tx_api -->|"returns transaction data"| node_tx_models
node_tag_api -->|"returns annotations"| node_tag_models
node_block_api -->|"returns block data"| node_block_models
node_caller -->|"receives typed results"| node_models

click node_address_api "https://github.com/graphsense/graphsense-python/blob/master/graphsense/api/addresses_api.py"
click node_entity_api "https://github.com/graphsense/graphsense-python/blob/master/graphsense/api/entities_api.py"
click node_tx_api "https://github.com/graphsense/graphsense-python/blob/master/graphsense/api/txs_api.py"
click node_block_api "https://github.com/graphsense/graphsense-python/blob/master/graphsense/api/blocks_api.py"
click node_tag_api "https://github.com/graphsense/graphsense-python/blob/master/graphsense/api/tags_api.py"
click node_bulk_api "https://github.com/graphsense/graphsense-python/blob/master/graphsense/api/bulk_api.py"
click node_general_api "https://github.com/graphsense/graphsense-python/blob/master/graphsense/api/general_api.py"
click node_rates_api "https://github.com/graphsense/graphsense-python/blob/master/graphsense/api/rates_api.py"
click node_tokens_api "https://github.com/graphsense/graphsense-python/blob/master/graphsense/api/tokens_api.py"
click node_api_client "https://github.com/graphsense/graphsense-python/blob/master/graphsense/api_client.py"
click node_configuration "https://github.com/graphsense/graphsense-python/blob/master/graphsense/configuration.py"
click node_rest "https://github.com/graphsense/graphsense-python/blob/master/graphsense/rest.py"
click node_models "https://github.com/graphsense/graphsense-python/tree/master/graphsense/model"
click node_address_models "https://github.com/graphsense/graphsense-python/blob/master/graphsense/model/address.py"
click node_entity_models "https://github.com/graphsense/graphsense-python/blob/master/graphsense/model/entity.py"
click node_search_models "https://github.com/graphsense/graphsense-python/blob/master/graphsense/model/search_result_level1.py"
click node_tx_models "https://github.com/graphsense/graphsense-python/blob/master/graphsense/model/tx.py"
click node_tag_models "https://github.com/graphsense/graphsense-python/blob/master/graphsense/model/tag.py"
click node_block_models "https://github.com/graphsense/graphsense-python/blob/master/graphsense/model/block.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_address_api,node_entity_api,node_tx_api,node_block_api,node_tag_api,node_bulk_api,node_general_api,node_rates_api,node_tokens_api toneBlue
class node_api_client,node_configuration,node_rest toneAmber
class node_models,node_address_models,node_entity_models,node_search_models,node_tx_models,node_tag_models,node_block_models,node_service toneMint
class node_caller toneIndigo
```

## Components

### Investigation APIs

- [Address queries](https://github.com/graphsense/graphsense-python/blob/master/graphsense/api/addresses_api.py): `graphsense/api/addresses_api.py`
- [Entity queries](https://github.com/graphsense/graphsense-python/blob/master/graphsense/api/entities_api.py): `graphsense/api/entities_api.py`
- [Transaction queries](https://github.com/graphsense/graphsense-python/blob/master/graphsense/api/txs_api.py): `graphsense/api/txs_api.py`
- [Block queries](https://github.com/graphsense/graphsense-python/blob/master/graphsense/api/blocks_api.py): `graphsense/api/blocks_api.py`
- [Tags and actors](https://github.com/graphsense/graphsense-python/blob/master/graphsense/api/tags_api.py): `graphsense/api/tags_api.py`
- [Bulk retrieval](https://github.com/graphsense/graphsense-python/blob/master/graphsense/api/bulk_api.py): `graphsense/api/bulk_api.py`
- [Search and stats](https://github.com/graphsense/graphsense-python/blob/master/graphsense/api/general_api.py): `graphsense/api/general_api.py`
- [Exchange rates](https://github.com/graphsense/graphsense-python/blob/master/graphsense/api/rates_api.py): `graphsense/api/rates_api.py`
- [Token support](https://github.com/graphsense/graphsense-python/blob/master/graphsense/api/tokens_api.py): `graphsense/api/tokens_api.py`

### Client Runtime

- [Request client](https://github.com/graphsense/graphsense-python/blob/master/graphsense/api_client.py): `graphsense/api_client.py`
- [Client configuration](https://github.com/graphsense/graphsense-python/blob/master/graphsense/configuration.py): `graphsense/configuration.py`
- [HTTP transport](https://github.com/graphsense/graphsense-python/blob/master/graphsense/rest.py): `graphsense/rest.py`

### Response Models

- [Typed API models](https://github.com/graphsense/graphsense-python/tree/master/graphsense/model): `graphsense/model`
- [Address data](https://github.com/graphsense/graphsense-python/blob/master/graphsense/model/address.py): `graphsense/model/address.py`
- [Entity and neighbors](https://github.com/graphsense/graphsense-python/blob/master/graphsense/model/entity.py): `graphsense/model/entity.py`
- [Search paths](https://github.com/graphsense/graphsense-python/blob/master/graphsense/model/search_result_level1.py): `graphsense/model/search_result_level1.py`
- [Transaction data](https://github.com/graphsense/graphsense-python/blob/master/graphsense/model/tx.py): `graphsense/model/tx.py`
- [Tag and actor data](https://github.com/graphsense/graphsense-python/blob/master/graphsense/model/tag.py): `graphsense/model/tag.py`
- [Block data](https://github.com/graphsense/graphsense-python/blob/master/graphsense/model/block.py): `graphsense/model/block.py`

### Other components

- **Forensics caller**
- **GraphSense API**

## Connections

- Forensics caller → Client configuration: configures
- Forensics caller → Address queries: invokes
- Forensics caller → Entity queries: invokes
- Forensics caller → Transaction queries: invokes
- Forensics caller → Block queries: invokes
- Forensics caller → Tags and actors: invokes
- Forensics caller → Bulk retrieval: invokes
- Forensics caller → Search and stats: invokes
- Forensics caller → Exchange rates: invokes
- Forensics caller → Token support: invokes
- Address queries → Request client: sends request
- Entity queries → Request client: sends request
- Transaction queries → Request client: sends request
- Block queries → Request client: sends request
- Tags and actors → Request client: sends request
- Bulk retrieval → Request client: sends request
- Search and stats → Request client: sends request
- Exchange rates → Request client: sends request
- Token support → Request client: sends request
- Request client → Client configuration: uses settings
- Request client → HTTP transport: dispatches HTTP
- HTTP transport → GraphSense API: requests
- GraphSense API → HTTP transport: returns response
- Request client → Typed API models: decodes response
- Address queries → Address data: returns address data
- Entity queries → Entity and neighbors: returns entity data
- Entity queries → Search paths: returns search paths
- Transaction queries → Transaction data: returns transaction data
- Tags and actors → Tag and actor data: returns annotations
- Block queries → Block data: returns block data
- Forensics caller → Typed API models: receives typed results