OFX Protocol: Direct Bank Connections Without a Browser

The finance_dl.ofx scraper connects directly to financial institutions that support the OFX protocol using the ofxclient Python package — no browser or Selenium required. It downloads transaction and balance data for every account accessible under your credentials, automatically fills historical gaps using repeated requests, and always fetches up to the present date. This page covers all configuration parameters, the output file naming scheme, smart download behavior, how to find OFX connection details for your institution, and how to use the interactive shell.

Configuration Parameters

ofx_params

dict

required

A dictionary containing all connection details for your financial institution. All fields come from ofxhome.com.

Show ofx_params fields

string

required

The FI Id value for your institution. Look this up at ofxhome.com.

org

string

required

The FI Org value for your institution. Look this up at ofxhome.com.

url

string

required

The FI URL value for your institution. Look this up at ofxhome.com.

username

string

required

Your username for the institution.

password

string

required

Your password for the institution.

broker_id

string

Optional FI Broker Id value. Available from ofxhome.com for institutions that require it.

client_args

dict

Optional dictionary of additional arguments passed directly to the ofxclient library. Some institutions (such as Chase) require a minimum OFX version and a unique client ID:

'client_args': {
    'ofx_version': '103',
    'id': '64f0e0bfe04f1a2d32cbddc8d30a3017',  # openssl rand -hex 16
}

The id field should be a random 16-byte hex string. Generate one with openssl rand -hex 16.

output_directory

string

required

Path on the local filesystem where OFX files will be written. The directory (and any account sub-directories) will be created automatically if they do not exist.

acct_dir_map

dict

An optional mapping of account numbers (as they appear in the OFX output) to human-readable directory names. When provided, the mapped name is used exactly as the sub-directory name — if it is not a valid directory name, finance-dl will fail. Unmapped accounts use their account number directly.

acct_dir_map={
    '880012345': 'Roth IRA',
    '880045678': 'FooCorp 401(k)',
    '880078901': 'Taxable Account',
}

overlap_days

int

default:"2"

Number of days of overlap when issuing follow-up requests to fill gaps in downloaded data. Overlapping ranges make it less likely that a transaction is missed; duplicates can be filtered during processing. The default of 2 is suitable in almost all cases.

min_start_date

datetime.date

default:"1990-01-01"

The earliest date from which to attempt data retrieval when no files have been downloaded yet. A binary search is performed starting from this date to find the oldest point at which the server returns a valid response. The default covers essentially all modern financial history.

min_days_retrieved

int

default:"20"

The minimum number of days the server is expected to return per request. If the most recent downloaded range starts no more than this many days before today, no additional request is issued. The default of 20 is appropriate because most OFX servers support at least 30 days per request.

Output Format

Each account’s data is stored in its own sub-directory of output_directory. The sub-directory name is the account number, or the mapped name from acct_dir_map if one is provided. Within each account sub-directory, files are named using the pattern:

<start-date>-<end-date>--<fetch-timestamp>.ofx

<start-date> and <end-date> reflect the DTSTART and DTEND fields in the OFX file, formatted as YYYYMMDD.
<fetch-timestamp> is the Unix epoch time in seconds at the moment of download.

Example: 19991201-20000115--1705000000.ofx

Smart Download Behavior

Because many institutions cap the number of days returnable in a single OFX request, finance_dl.ofx issues multiple requests automatically:

First run — binary search: When no files exist for an account, a binary search is performed from min_start_date toward today to find the earliest date the server will honor. Once found, that batch is saved and subsequent requests fill forward.
Gap filling: On every run, the scraper scans existing files for date-range gaps and issues requests to fill them, using overlap_days of backwards overlap.
Present-day fetch: At least one request reaching up to today’s date is always issued, so the most recent transactions are always retrieved.

Finding Your Institution’s OFX Parameters

Visit ofxhome.com and search for your financial institution by name. The listing shows the FI Id, FI Org, and FI Url values to use in ofx_params. Not all institutions support OFX direct connect — if your institution is not listed, or the connection fails, use the institution’s dedicated Selenium scraper instead.

Discover Card users: Discover enforces a minimum 5-second delay between OFX requests. The finance_dl.ofx module detects Discover automatically (by checking org for the string "Discover") and adds the required delay. No extra configuration is needed.

Config Example

def CONFIG_vanguard():
    # To determine the correct values for `id`, `org`, and `url` for your
    # financial institution, search on https://www.ofxhome.com/
    ofx_params = {
        'id': '15103',
        'org': 'Vanguard',
        'url': 'https://vesnc.vanguard.com/us/OfxDirectConnectServlet',
        'username': 'XXXXXX',
        'password': 'XXXXXX',
    }
    return dict(
        module='finance_dl.ofx',
        ofx_params=ofx_params,
        output_directory=os.path.join(data_dir, 'vanguard'),
        acct_dir_map={
            '880012345': 'Roth IRA',
            '880045678': 'FooCorp 401(k)',
            '880078901': 'Taxable Account',
        }
    )

Chase / Advanced `client_args` Example

Chase and some other institutions require OFX version 103 and a unique client ID. Generate the ID once with openssl rand -hex 16 and reuse it on every run:

def CONFIG_chase():
    ofx_params = {
        'id': 'YOUR_CHASE_FI_ID',        # from ofxhome.com
        'org': 'B1',
        'url': 'https://ofx.chase.com',
        'username': 'XXXXXX',
        'password': 'XXXXXX',
        'client_args': {
            'ofx_version': '103',
            'id': '64f0e0bfe04f1a2d32cbddc8d30a3017',  # openssl rand -hex 16
        },
    }
    return dict(
        module='finance_dl.ofx',
        ofx_params=ofx_params,
        output_directory=os.path.join(data_dir, 'chase'),
    )

Interactive Shell

From the finance-dl interactive shell, the interactive context manager yields the following variables:

Variable	Description
`ofx_params`	The `ofx_params` dict passed in from the config.
`output_directory`	The `output_directory` string passed in from the config.
`inst`	A connected `ofxclient.institution.Institution` object, already authenticated.

You can use inst to explore accounts or trigger downloads manually:

# List all accounts visible to these credentials
inst.accounts()

Protocol-Based

Banking & Payments

Investments

Shopping & Receipts

Bills & Insurance

Aggregators

OFX Protocol: Direct Bank Connections Without a Browser

Configuration Parameters

Output Format

Smart Download Behavior

Finding Your Institution’s OFX Parameters

Config Example

Chase / Advanced `client_args` Example

Interactive Shell

Build docs developers (and LLMs) love

Protocol-Based

Banking & Payments

Investments

Shopping & Receipts

Bills & Insurance

Aggregators

Documentation Index

​Configuration Parameters

​Output Format

​Smart Download Behavior

​Finding Your Institution’s OFX Parameters

​Config Example

​Chase / Advanced client_args Example

​Interactive Shell

Build docs developers (and LLMs) love

Configuration Parameters

Output Format

Smart Download Behavior

Finding Your Institution’s OFX Parameters

Config Example

Chase / Advanced `client_args` Example

Interactive Shell