GitHub - pj4533/POEFlip: A native macOS application for monitoring Path of Exile 2 trade listings in real-time using WebSocket connections.

3 min read Original article ↗

POEFlip

A native macOS application for monitoring Path of Exile 2 trade listings in real-time using WebSocket connections.

POEFlip Screenshot

Features

  • ✅ Real-time monitoring of multiple search criteria
  • ✅ WebSocket-based live updates
  • ✅ JSON-based search configuration with edit capability
  • ✅ Instant hideout travel integration
  • ✅ Trade history tracking with automatic sold item detection
  • ✅ Audio/visual notifications
  • ✅ Persistent search management
  • ✅ Secure POESESSID storage in macOS Keychain

Requirements

  • macOS 14.0 (Sonoma) or later
  • Xcode 16.0 or later

Building and Running

  1. Open the project in Xcode:
  1. Select "My Mac" as the run destination
  2. Press ⌘R to build and run

First Time Setup

  1. Launch the application
  2. Open Settings (⌘,)
  3. Enter your POESESSID cookie:
    • Log in to pathofexile.com
    • Open browser developer tools (F12)
    • Go to Application/Storage → Cookies
    • Find and copy the POESESSID value
  4. Click "Save to Keychain"

Managing Searches

Adding Searches

  1. Click "Add Search" in the toolbar
  2. Enter a descriptive name for your search
  3. Paste the JSON query from the Path of Exile trade website:
    • Go to the trade site and configure your search
    • Open browser developer tools → Network tab
    • Perform the search
    • Find the search request and copy the JSON payload
  4. Click "Add Search"

Editing Searches

  • Right-click on any search in the list to edit its name or query
  • Changes are saved automatically

Usage

  • Search Status Panel: Shows all active searches and their connection status
  • Trade History Panel: Displays found items with actions
  • Console Log: Shows system messages and events
  • Item Status Indicators:
    • 🆕 New: Newly found item
    • ✈️ Traveled: Item you traveled to
    • ⏭️ Skipped: Item you passed on
    • 💸 Sold: Item no longer available (404 error)
  • Item Actions: When new items are found, you can:
    • Travel to Hideout: Automatically sends the travel command in-game
    • Skip Item: Marks the item as skipped

Architecture

The application is built using:

  • SwiftUI for the user interface
  • Swift Concurrency (async/await) for asynchronous operations
  • URLSessionWebSocketTask for WebSocket connections
  • Keychain Services for secure credential storage
  • UserNotifications for system notifications
  • Swift Testing for unit tests

Project Structure

POEFlip/
├── Models/           # Data models
├── Views/            # SwiftUI views
├── ViewModels/       # View models and business logic
├── Services/         # API, WebSocket, and system services
├── Utilities/        # Helper utilities and constants
└── Assets.xcassets/  # App resources and icons

Testing

The project includes tests using Swift Testing framework. Run tests in Xcode with ⌘U.

Notes

  • The application requires a valid POESESSID cookie to access the Path of Exile API
  • WebSocket connections automatically reconnect if disconnected
  • Trade history is persisted locally and limited to the last 500 items
  • All searches are saved and restored on app launch

League Support

The league is configurable via Settings (Command-,). The app fetches available leagues from the Path of Exile API and presents them in a picker. The selected league is persisted in UserDefaults.

To change the league:

  1. Open Settings (Command-,)
  2. Select a league from the picker (or enter manually if the API is unavailable)
  3. Click Done
  4. Restart any active searches for the change to take effect

Security

  • POESESSID is stored securely in the macOS Keychain
  • Network access is limited to Path of Exile API endpoints