Back to topics

Dividends & withholding tax

WheelTrading.io imports dividends twice a day from the IBKR Flex Web Service (cash-transactions section).

Dividend forecast (/dashboard/dividends)

A dedicated page with three blocks:

  • Stat cards: total received, year-to-date, last 12 months and

average per month (rolling 12M).

  • Upcoming dividends: joins your active stock positions against the

dividend calendar (yfinance) and estimates the payout as shares * gross_per_share. Horizon selectable (30 / 60 / 90 / 180 / 365 days). Sums are aggregated per currency.

  • Top payers (5) plus a table of the most recent dividend cash-ins.

Forecast requirements: an active long_stock position and at least one calendar entry (filled nightly by the yfinance pool refresh).

Quick link: "Forecast" button in the cockpit header.

Types we capture

  • DIVIDEND - regular dividend payment (positive)
  • WITHHOLDING_TAX - withholding tax on dividends (negative)

Idempotency

Each transaction is uniquely identified by (user_id, ibkr_transaction_id). Repeated imports never duplicate a booking. The table is append-only - no update path.

Schedule

  • 06:00 UTC and 18:00 UTC daily.
  • Each user runs in its own DB session; one user's failure does not

block others.

  • On Flex errors or rate-limit hits (1 call per 15 minutes per query)

we just retry on the next tick.

Configuration

Per user you need:

  • Flex token (in global settings)
  • Query ID Dividends (separate query, cash transactions only)
Important: Token and query ID are stored encrypted and never logged.

Symbol column

OCC option symbols (e.g. CMCSA 260116P00045000) are supported up to 40 characters - covering all US-listed option symbols.

Filter blockers

In filter settings you can set blocker windows around ex-dividend:

  • Blocker days Put before ex-dividend - no new short puts.
  • Blocker days Call before ex-dividend - no new covered calls.
  • Safety days after ex-dividend - quiet window after the event.