Skip to main content

iqair

An unofficial Python wrapper for IQ Option's websocket trading API.

This is v1.0 - a ground-up rebuild of an older, long-unmaintained iqoptionapi fork. Every endpoint listed as "implemented" below has been independently re-verified against the live backend (never assumed from old code or documentation), typically by capturing real trade traffic from IQ Option's own web UI (HAR capture) and matching this library's requests against it byte-for-byte. Where something is confirmed vs. presumed, the docstring on the relevant method says so explicitly - see iqair/broker.py's module docstring for the full picture.

This talks to a real trading account. Every example below and every test in tests/ runs against the PRACTICE balance only - never REAL. Use your own judgment before pointing this at anything else.

Install

pip install -e .

Requires Python 3 and requests, websocket-client (see setup.py).

Quickstart

from iqair.client import IQOptionClient

api = IQOptionClient("you@example.com", "your-password")
check, reason = api.connect()
if not check:
    raise SystemExit(f"connect failed: {reason}")

api.change_balance("PRACTICE")

# Low-level: place a turbo option directly
check, order_id = api.buy(1, "EURUSD", "call", 1)  # $1, 1-minute turbo

The OOP wrapper (api.broker)

For most use cases, api.broker is friendlier than the low-level per-mode methods - one trade()/.close() interface across every mode:

from iqair.broker import TradeMode, TradeSide

trade = api.broker.trade(
    mode=TradeMode.TURBO,
    asset="EURUSD",
    side=TradeSide.CALL,
    amount=1,
    expiration=1,
)
trade.wait()          # blocks until the trade settles
print(trade.pnl)

# Margin modes (forex/crypto/cfd) need `leverage`; `amount` is margin,
# not stake, for these:
trade = api.broker.trade(
    mode=TradeMode.FOREX,
    asset="EURUSD",
    side=TradeSide.BUY,
    amount=10,       # margin, in dollars
    leverage=100,
)
print(trade.state, trade.pnl)
trade.close()

For the full end-to-end guide (every mode, streaming, positions/P&L, error handling), see docs/USAGE.md. For finding valid ticker strings specifically, see docs/TICKERS.md - the short version is api.get_asset_metadata().

Using this with an LLM orchestrator / agent

iqair.agent wraps the library as flat JSON-in/JSON-out tools for LLM function-calling (direct import, a generic call_tool(name, args) dispatcher, or an optional HTTP server via pip install iqair[agent]). See docs/AGENT.md.

Supported trading modes

Mode Open Close Notes
Turbo / Binary ✅ live-verified ✅ live-verified api.buy() / api.sell_option()
Digital options ✅ live-verified ✅ live-verified api.buy_digital_spot() / api.close_digital_option() - resolves a real, currently-tradable instrument server-side rather than constructing one client-side
Forex (margin) ✅ live-verified ✅ live-verified api.buy_forex_market() / api.close_margin_position()
Crypto (margin) ✅ live-verified ✅ live-verified api.buy_crypto_market()
CFD (margin) ✅ live-verified ✅ live-verified api.buy_cfd_market() - covers commodities, stocks, indices, AND ETFs; IQ Option has no separate mode for any of these, they're all marginal-cfd

All six are also available through api.broker.trade(mode=TradeMode.*, ...).

The old buy_order() / close_position() / close_position_v2() methods are confirmed dead (they send flat, non-namespaced message names IQ Option's backend no longer responds to at all) and are kept only for backwards compatibility - they emit a DeprecationWarning. Use the methods in the table above instead.

Streaming (api.stream)

for candle in api.stream.candles("EURUSD", timeframe=60):
    print(candle)

for tick in api.stream.price("EURUSD"):
    print(tick.bid, tick.ask)

for update in api.stream.trade_updates():   # all position-changed events
    print(update)

for event in api.stream.connection():       # connection state changes
    print(event)

api.stream.payout() and api.stream.asset_status() are poll-based (IQ Option doesn't push these two live) rather than true push streams; api.stream.news() is a documented stub - a live news feed wasn't captured/confirmed during this project.

Every stream returns a Subscription - iterate it directly, or call .close() to unsubscribe early.

Positions, history, P&L

ok, positions = api.get_positions("digital-option")   # or "turbo-option", "marginal-forex", etc.
ok, history = api.get_position_history_v2("marginal-cfd", limit=10, offset=0)
pnl = api.get_pnl(positions["positions"][0])          # takes a raw position dict

Matching a position back to the order id that opened it is not always a plain equality check - digital and margin positions key external_id as the position id, not the order id (order ids live in a separate list). Use IQOptionClient.position_matches_order_id() rather than comparing external_id directly if you're writing your own matching logic; get_digital_position() / get_margin_position() / Trade.refresh() already do this correctly.

Testing

See tests/README.md for the full test suite - it runs against the real backend (PRACTICE balance), gated behind IQ_EMAIL/IQ_PASSWORD and opt-in flags (IQ_ALLOW_TRADE, IQ_ALLOW_DIGITAL, IQ_ALLOW_MARGIN) for anything that places a trade.

export IQ_EMAIL="you@example.com"
export IQ_PASSWORD="your-password"
pytest                    # read-only tests
IQ_ALLOW_TRADE=1 IQ_ALLOW_DIGITAL=1 IQ_ALLOW_MARGIN=1 pytest   # everything

Project layout

iqair/
  client.py         high-level client (IQOptionClient) - most users start here
  broker.py         OOP wrapper (api.broker) - Trade/TradeMode/TradeSide
  streaming.py       api.stream namespace
  api.py             low-level request/response plumbing
  models.py          typed dataclasses (Position, Candle, etc.)
  ws/                websocket client + per-endpoint request builders
  agent/              LLM tool-calling / orchestrator integration (tools, dispatcher, HTTP server)
docs/
  USAGE.md            full end-to-end usage guide
  AGENT.md            orchestrator / LLM tool-calling integration guide
  TICKERS.md          how to find valid ticker strings per trading mode
tests/                live-backend test suite (see tests/README.md)

Disclaimer

This is an unofficial, community-maintained wrapper, not affiliated with or endorsed by IQ Option. IQ Option's API is undocumented and can change without notice - endpoints that work today may not tomorrow. Use at your own risk, and always test against the PRACTICE balance before trusting anything with real funds.

Metadata

Release files for iqair 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for iqair 1.0.0
File Size Uploaded Provenance Actions
iqair-1.0.0.tar.gz 88.5 kB With provenance Details for iqair-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for iqair 1.0.0
File Interpreter ABI Platform Actions
iqair-1.0.0-py3-none-any.whl Python 3 none any Details for iqair-1.0.0-py3-none-any.whl

Total release size: 186.5 kB

Release files / iqair-1.0.0.tar.gz

Download URL iqair-1.0.0.tar.gz
Size 88.5 kB
Tags Source
SHA-256 checksum
How to use checksums
001237669577e35ca8c413d236556b29e06122048f81e6675bab03c65d007406
BLAKE2b-256 checksum
How to use checksums
8edc9c709f7258eee0f2dc136d14ae5d33ed76096fe02c22acddeb6eeb264462
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 4, 2026.

Transparency log

Release files / iqair-1.0.0-py3-none-any.whl

Download URL iqair-1.0.0-py3-none-any.whl
Size 98.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b0ec8aebfd8b6a6b9880b1fe896786b6545d050e82d4b19aaa123611c961e50d
BLAKE2b-256 checksum
How to use checksums
e3be015611fa5d9c35aae0b21234fac8540e594bf455ea5c663dc69e79ff7221
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 4, 2026.

Transparency log

Security for iqair 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for iqair-1.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 4, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page