# maouv/opensea-list architecture

> Architecture diagram of the GitHub repository maouv/opensea-list, 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/maouv/opensea-list
- Repository: https://github.com/maouv/opensea-list

## Overview

opensea-list is a multi-wallet NFT operations product controlled through Telegram and a companion web panel. The main workflow resolves a collection and chain, verifies wallet holdings, gathers listing or mint choices, summarizes the action, then executes and reports results. Separate branches cover managing existing listings and timed drop mints. The README documents capabilities beyond the sampled excerpts; those are shown at subsystem level where wiring is not directly evidenced.

Main entry points: [`panel/server.js`](https://github.com/maouv/opensea-list/blob/main/panel/server.js) (Panel API), [`bot.js`](https://github.com/maouv/opensea-list/blob/main/bot.js) (Telegram bot), [`lib/opensea.js`](https://github.com/maouv/opensea-list/blob/main/lib/opensea.js) (OpenSea operations), [`lib/holdings.js`](https://github.com/maouv/opensea-list/blob/main/lib/holdings.js) (Holdings verification)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_telegram["Telegram bot<br/>[bot.js]"]
  node_panel_ui["Web panel UI<br/>[index.html]"]
  node_panel_server["Panel API<br/>[server.js]"]
end

subgraph group_listing["Listing and holdings"]
  node_listing_flow["Listing workflows<br/>[bot.js]"]
  node_fast_list["Fast List settings<br/>[bot.js]"]
  node_holdings["Holdings verification<br/>[holdings.js]"]
  node_opensea["OpenSea operations<br/>[opensea.js]"]
  node_offer_ops["Offer acceptance<br/>[osoffers.js]"]
end

subgraph group_minting["Minting and schedules"]
  node_schedules["Schedule manager<br/>[schedules.js]"]
  node_mint_flow["Mint workflows<br/>[bot.js]"]
  node_mint_logic["Mint probing<br/>[mint.js]"]
  node_mint_tx["Mint transactions<br/>[minttx.js]"]
  node_eligibility["Drop eligibility<br/>[oselig.js]"]
  node_os_auth["OpenSea wallet auth<br/>[osauth.js]"]
end

subgraph group_shared["Shared services"]
  node_limiter["Request limiter<br/>[limiter.js]"]
  node_state["Shared state<br/>[state.js]"]
  node_sessions["Conversation sessions<br/>[session.js]"]
end

node_telegram_user(("Telegram user"))
node_web_user(("Panel user"))
node_chain_rpc[("Chain RPCs")]
node_opensea_service["OpenSea API"]
node_telegram_service["Telegram service"]
node_schedule_store[("Mint schedules")]
node_fastlist_store[("Fast List settings")]

node_telegram_user -->|"sends actions"| node_telegram
node_telegram -->|"sends messages"| node_telegram_service
node_telegram -->|"tracks sessions"| node_sessions
node_telegram -->|"routes listing"| node_listing_flow
node_telegram -->|"routes minting"| node_mint_flow
node_telegram -->|"manages schedules"| node_schedules
node_telegram -->|"reads settings"| node_state
node_fast_list -->|"reads and writes"| node_fastlist_store
node_telegram -->|"runs fast list"| node_fast_list
node_web_user -->|"uses panel"| node_panel_ui
node_panel_ui -->|"calls API"| node_panel_server
node_panel_server -->|"shares state"| node_state
node_panel_server -->|"gets holdings"| node_holdings
node_panel_server -->|"gets listing data"| node_opensea
node_panel_server -->|"probes mints"| node_mint_logic
node_panel_server -->|"builds mint tx"| node_mint_tx
node_panel_server -->|"accepts offers"| node_offer_ops
node_panel_server -->|"manages schedules"| node_schedules
node_panel_server -->|"reads chain"| node_chain_rpc
node_listing_flow -->|"verifies holdings"| node_holdings
node_listing_flow -->|"lists and manages"| node_opensea
node_listing_flow -->|"checks ownership"| node_chain_rpc
node_opensea -->|"sends SDK requests"| node_limiter
node_limiter -->|"fetches API"| node_opensea_service
node_opensea -->|"queries listings"| node_opensea_service
node_holdings -->|"gets candidates"| node_opensea
node_holdings -->|"verifies owners"| node_chain_rpc
node_mint_flow -->|"probes and checks"| node_mint_logic
node_mint_flow -->|"builds transactions"| node_mint_tx
node_mint_flow -->|"checks eligibility"| node_eligibility
node_mint_flow -->|"creates schedules"| node_schedules
node_mint_flow -->|"simulates and mints"| node_chain_rpc
node_mint_logic -->|"checks drop eligibility"| node_eligibility
node_mint_logic -->|"probes contracts"| node_chain_rpc
node_mint_tx -.->|"builds drop tx"| node_opensea_service
node_eligibility -->|"gets wallet JWT"| node_os_auth
node_os_auth -->|"authenticates wallets"| node_opensea_service
node_eligibility -->|"queries drop stages"| node_opensea_service
node_offer_ops -->|"fetches offers"| node_opensea_service
node_offer_ops -->|"sends acceptance tx"| node_chain_rpc
node_schedules -->|"persists schedules"| node_schedule_store

click node_telegram "https://github.com/maouv/opensea-list/blob/main/bot.js"
click node_panel_ui "https://github.com/maouv/opensea-list/blob/main/panel/public/index.html"
click node_panel_server "https://github.com/maouv/opensea-list/blob/main/panel/server.js"
click node_listing_flow "https://github.com/maouv/opensea-list/blob/main/bot.js"
click node_fast_list "https://github.com/maouv/opensea-list/blob/main/bot.js"
click node_holdings "https://github.com/maouv/opensea-list/blob/main/lib/holdings.js"
click node_opensea "https://github.com/maouv/opensea-list/blob/main/lib/opensea.js"
click node_limiter "https://github.com/maouv/opensea-list/blob/main/lib/limiter.js"
click node_schedules "https://github.com/maouv/opensea-list/blob/main/lib/schedules.js"
click node_mint_flow "https://github.com/maouv/opensea-list/blob/main/bot.js"
click node_mint_logic "https://github.com/maouv/opensea-list/blob/main/lib/mint.js"
click node_mint_tx "https://github.com/maouv/opensea-list/blob/main/lib/minttx.js"
click node_eligibility "https://github.com/maouv/opensea-list/blob/main/lib/oselig.js"
click node_os_auth "https://github.com/maouv/opensea-list/blob/main/lib/osauth.js"
click node_offer_ops "https://github.com/maouv/opensea-list/blob/main/lib/osoffers.js"
click node_state "https://github.com/maouv/opensea-list/blob/main/lib/state.js"
click node_sessions "https://github.com/maouv/opensea-list/blob/main/lib/session.js"
click node_schedule_store "https://github.com/maouv/opensea-list/blob/main/mint-schedules.json"
click node_fastlist_store "https://github.com/maouv/opensea-list/blob/main/fastlist-settings.json"

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_telegram,node_panel_ui,node_panel_server,node_telegram_user,node_web_user toneBlue
class node_listing_flow,node_fast_list,node_holdings,node_opensea,node_offer_ops,node_chain_rpc,node_schedule_store,node_fastlist_store toneAmber
class node_schedules,node_mint_flow,node_mint_logic,node_mint_tx,node_eligibility,node_os_auth,node_opensea_service toneMint
class node_limiter,node_state,node_sessions toneRose
class node_telegram_service toneIndigo
```

## Components

### User interfaces

- [Telegram bot](https://github.com/maouv/opensea-list/blob/main/bot.js): `bot.js`
- [Web panel UI](https://github.com/maouv/opensea-list/blob/main/panel/public/index.html): `panel/public/index.html`
- [Panel API](https://github.com/maouv/opensea-list/blob/main/panel/server.js): `panel/server.js`

### Listing and holdings

- [Listing workflows](https://github.com/maouv/opensea-list/blob/main/bot.js): `bot.js`
- [Fast List settings](https://github.com/maouv/opensea-list/blob/main/bot.js): `bot.js`
- [Holdings verification](https://github.com/maouv/opensea-list/blob/main/lib/holdings.js): `lib/holdings.js`
- [OpenSea operations](https://github.com/maouv/opensea-list/blob/main/lib/opensea.js): `lib/opensea.js`
- [Offer acceptance](https://github.com/maouv/opensea-list/blob/main/lib/osoffers.js): `lib/osoffers.js`

### Minting and schedules

- [Schedule manager](https://github.com/maouv/opensea-list/blob/main/lib/schedules.js): `lib/schedules.js`
- [Mint workflows](https://github.com/maouv/opensea-list/blob/main/bot.js): `bot.js`
- [Mint probing](https://github.com/maouv/opensea-list/blob/main/lib/mint.js): `lib/mint.js`
- [Mint transactions](https://github.com/maouv/opensea-list/blob/main/lib/minttx.js): `lib/minttx.js`
- [Drop eligibility](https://github.com/maouv/opensea-list/blob/main/lib/oselig.js): `lib/oselig.js`
- [OpenSea wallet auth](https://github.com/maouv/opensea-list/blob/main/lib/osauth.js): `lib/osauth.js`

### Shared services

- [Request limiter](https://github.com/maouv/opensea-list/blob/main/lib/limiter.js): `lib/limiter.js`
- [Shared state](https://github.com/maouv/opensea-list/blob/main/lib/state.js): `lib/state.js`
- [Conversation sessions](https://github.com/maouv/opensea-list/blob/main/lib/session.js): `lib/session.js`

### Other components

- **Telegram user**
- **Panel user**
- **Chain RPCs**
- **OpenSea API**
- **Telegram service**
- [Mint schedules](https://github.com/maouv/opensea-list/blob/main/mint-schedules.json): `mint-schedules.json`
- [Fast List settings](https://github.com/maouv/opensea-list/blob/main/fastlist-settings.json): `fastlist-settings.json`

## Connections

- Telegram user → Telegram bot: sends actions
- Telegram bot → Telegram service: sends messages
- Telegram bot → Conversation sessions: tracks sessions
- Telegram bot → Listing workflows: routes listing
- Telegram bot → Mint workflows: routes minting
- Telegram bot → Schedule manager: manages schedules
- Telegram bot → Shared state: reads settings
- Fast List settings → Fast List settings: reads and writes
- Telegram bot → Fast List settings: runs fast list
- Panel user → Web panel UI: uses panel
- Web panel UI → Panel API: calls API
- Panel API → Shared state: shares state
- Panel API → Holdings verification: gets holdings
- Panel API → OpenSea operations: gets listing data
- Panel API → Mint probing: probes mints
- Panel API → Mint transactions: builds mint tx
- Panel API → Offer acceptance: accepts offers
- Panel API → Schedule manager: manages schedules
- Panel API → Chain RPCs: reads chain
- Listing workflows → Holdings verification: verifies holdings
- Listing workflows → OpenSea operations: lists and manages
- Listing workflows → Chain RPCs: checks ownership
- OpenSea operations → Request limiter: sends SDK requests
- Request limiter → OpenSea API: fetches API
- OpenSea operations → OpenSea API: queries listings
- Holdings verification → OpenSea operations: gets candidates
- Holdings verification → Chain RPCs: verifies owners
- Mint workflows → Mint probing: probes and checks
- Mint workflows → Mint transactions: builds transactions
- Mint workflows → Drop eligibility: checks eligibility
- Mint workflows → Schedule manager: creates schedules
- Mint workflows → Chain RPCs: simulates and mints
- Mint probing → Drop eligibility: checks drop eligibility
- Mint probing → Chain RPCs: probes contracts
- Mint transactions → OpenSea API: builds drop tx
- Drop eligibility → OpenSea wallet auth: gets wallet JWT
- OpenSea wallet auth → OpenSea API: authenticates wallets
- Drop eligibility → OpenSea API: queries drop stages
- Offer acceptance → OpenSea API: fetches offers
- Offer acceptance → Chain RPCs: sends acceptance tx
- Schedule manager → Mint schedules: persists schedules