gfil-calculators 1.1.0

Trading risk calculators covering Forex, Gold, Crypto, and Indices. The only library with proper pip values for 30+ instruments.

gfil-calculators

Open-source trading calculator library covering Forex, Gold (XAUUSD), Crypto, Indices, and Energy — with proper pip values and contract sizes for 30+ instruments. Available in Python and JavaScript. Zero dependencies. Pure math. Built by GFIL — Global Financial Intelligence Lab.

---

Why GFIL Calculators?

• Multi-asset coverage — Every other calculator library handles one asset class. This one handles all five (Forex, Gold, Crypto, Indices, Energy) with correct pip sizes and contract sizes for each instrument. No other library correctly calculates position size for XAUUSD, BTCUSD, and SPX500 in one API.
• XAUUSD specialist — Gold trading has unique pip values ($0.01 pip size, 100 oz contract) that most forex calculators get wrong. This library handles it correctly out of the box, along with silver (XAGUSD).
• Python + JavaScript dual library — Same formulas, same instrument database, same results. Use Python for backtesting and research; use JavaScript for web dashboards and browser extensions. Published on PyPI and npm.
• MIT licensed, zero dependencies — No numpy, no pandas, no external APIs. Pure math functions you can embed anywhere — even in proprietary commercial products. Attribution appreciated but not required.

---

Calculators Included (22 total)

Calculator	Inputs	Output
Position Size	account_balance, risk_percent, stop_loss_pips, symbol	lots, risk_amount, micro_lots
Position Size (ATR)	account_balance, risk_percent, atr_value, atr_multiplier, symbol	lots, stop_loss_pips, stop_loss_price
Risk Per Trade	account_balance, lots, stop_loss_pips, symbol	risk_percent, risk_amount, risk_level
Pip Value	symbol, lots, account_currency	one_pip, ten_pips, hundred_pips
Pip Value (Cross)	symbol, lots, conversion_rate	one_pip (with currency conversion)
Pips ↔ Price	symbol, price_diff or pips	pips or price difference
ATR	highs[], lows[], closes[], period	ATR series (Wilder's smoothing)
ATR Stop Loss	entry_price, atr_value, direction, multiplier	stop_loss_price
ATR Take Profit	entry_price, atr_value, direction, rrr, multiplier	take_profit_price
Fibonacci Retracement	high, low, direction	7 levels (0%–100%)
Fibonacci Extension	high, low, direction	7 targets (127.2%–423.6%)
Kelly Criterion	win_rate, avg_win, avg_loss, fraction	kelly_percent, adjusted_percent
Kelly from Trades	wins[], losses[], fraction	kelly_percent + trade statistics
Drawdown	equity_curve[]	max_drawdown_percent, recovery_percent
Recovery Needed	drawdown_percent	gain_percent to recover
Consecutive Losses	account_balance, risk_percent, num_losses	remaining_balance, total_loss
Margin Required	symbol, lots, entry_price, leverage	margin, notional_value
Free Margin	account_balance, open_positions[]	free_margin, margin_level
Risk/Reward	entry, stop_loss, take_profit, direction	rrr, breakeven_winrate
Risk/Reward (Sized)	entry, stop_loss, take_profit, lots, pip_value	rrr + risk_dollars, reward_dollars
Profit Factor	total_wins, total_losses	profit_factor, net_profit, assessment
Compound Interest	principal, annual_rate, years, monthly_contribution	final_value, total_interest

---

Quick Start

Python

pip install gfil-calculators

from gfil_calculators.position_size import calculate_position_size
from gfil_calculators.pip_value import calculate_pip_value
from gfil_calculators.instruments import get_instrument

# Position sizing for XAUUSD (Gold)
result = calculate_position_size(10000, 1.0, 50, "XAUUSD")
print(f"Lots: {result['lots']}, Risk: ${result['risk_amount']}")

# Pip value for EURUSD
pip = calculate_pip_value("EURUSD", 1.0, "USD")
print(f"1 pip = ${pip['one_pip']}")

# Get instrument specs
specs = get_instrument("BTCUSD")
print(f"Pip size: {specs['pip_size']}, Contract: {specs['contract_size']}")

JavaScript / Node.js

npm install gfil-trading-calculators

const { calculatePositionSize, calculatePipValue, getInstrument } = require('gfil-trading-calculators');

// Position sizing for XAUUSD (Gold)
const result = calculatePositionSize(10000, 1.0, 50, "XAUUSD");
console.log(`Lots: ${result.lots}, Risk: $${result.risk_amount}`);

// Pip value for EURUSD
const pip = calculatePipValue("EURUSD", 1.0, "USD");
console.log(`1 pip = $${pip.one_pip}`);

---

Supported Instruments (30+)

Category	Instruments
Forex Majors	EURUSD, GBPUSD, USDJPY, USDCHF, AUDUSD, NZDUSD, USDCAD
Forex Crosses	EURGBP, EURJPY, GBPJPY, AUDJPY, EURNZD, GBPAUD, GBPCAD, GBPJPY
Commodities	XAUUSD (Gold), XAGUSD (Silver)
Crypto	BTCUSD, ETHUSD, SOLUSD, XRPUSD, DOGEUSD, ADAUSD
Indices	SPX500, NAS100, DAX40, FTSE100, DJI30
Energy	USOIL (WTI Crude), UKOIL (Brent Crude)

---

Formula Reference

Position Size

lots = (account_balance × risk_percent / 100) / (stop_loss_pips × pip_value_per_lot)

Pip Value

pip_value = pip_size × contract_size × lots

For XAUUSD: pip_size = 0.01, contract_size = 100 oz → 1 pip per lot = $1.00

For USDJPY: pip_size = 0.01, contract_size = 100,000 → 1 pip per lot = ¥1,000 (converted to account currency)

ATR (Average True Range)

TR = max(high - low, |high - prev_close|, |low - prev_close|)
ATR = Wilder's smoothing (14-period default)

Kelly Criterion

f* = (p × b - q) / b   where p = win rate, q = 1 - p, b = avg_win / avg_loss

Drawdown

max_drawdown = max(peak - trough) / peak × 100%
recovery_needed = 100 / (100 - drawdown%) × 100% - 100%

---

Live Demo

Try all 22 calculators free at blog.quant-view.xyz/tools/

• Position Size Calculator
• Pip Value Calculator
• Fibonacci Calculator
• Kelly Criterion Calculator
• ATR Calculator
• Drawdown Calculator

---

Related

• GFIL Terminal — WebSocket-native trading platform (gfil-intel.xyz)
• GFIL Trading Insights — Free calculators, guides, and research (blog.quant-view.xyz)
• GFIL Entity — Knowledge graph for AI engines (blog.quant-view.xyz/tools/entity.html)

---

License

MIT — Use freely in personal, academic, and commercial projects.

---

Citation: GFIL — Global Financial Intelligence Lab. gfil-calculators: Open-source trading calculator library. 2026. Available at https://pypi.org/project/gfil-calculators/ and https://www.npmjs.com/package/gfil-trading-calculators/