Skip to main content

tickwire (Python SDK)

Typed clients for the Tickwire MT4/MT5 API: one API for both platforms, truthful health, idempotent trading, an audit trail, agent keys with pre-trade hooks, and signed webhooks. Sync and async.

Not published yet. pip install tickwire won't find it. Install from source, from the repository root:

pip install ./sdk/python

Once it is published:

pip install tickwire

Python 3.11 or newer. MIT licensed. Docs: tickwire.io/docs/sdk-python.

Quick start

A free sandbox (no sign-in, no card) against the public API, then a first trade:

from tickwire import Tickwire, sandbox_signup, trade_succeeded

API = "https://api.tickwire.io"
sb = sandbox_signup(API)                     # a twsk_ key (shown once: keep it) and one simulated MT5 account
with Tickwire(API, sb["apiKey"], actor="quickstart") as tw:
    acc = tw.account(sb["account"]["id"])    # MT4 and MT5 look the same
    print(acc.health()["status"])            # healthy | stale | disconnected | down
    print(acc.price("EURUSD"))
    r = acc.market_order("EURUSD", 0.01, reason="quickstart")   # Idempotency-Key generated for you
    print(trade_succeeded(r), r["numericCode"])

sandbox_signup is anonymous and rate limited (5 sandboxes an hour per address), so call it once and reuse the key. With your own API key, skip it: Tickwire("https://api.tickwire.io", "YOUR_API_KEY"), or set TICKWIRE_API_URL and TICKWIRE_API_KEY and call Tickwire(). Then tw.list_accounts() lists your accounts.

sandbox=True reads the sandbox URL from sandbox_url= or TICKWIRE_SANDBOX_URL (it never guesses a host) and raises ConfigError if neither is set.

60 seconds: an AI agent with its own key

The account owner creates a scoped agent key; the agent can then trade only through the guarded path (kill switches, the owner's pre-trade hook, audit). This needs your own API key: the restricted key from sandbox_signup cannot create agent keys.

from tickwire import AgentClient, Tickwire

API = "https://api.tickwire.io"
with Tickwire(API, "YOUR_API_KEY") as owner:
    created = owner.create_agent_key("my-agent", [account_id], reason="new agent")
    agent_key = created["key"]                          # twag_…, shown once: store it now

with AgentClient(API, agent_key) as agent:
    r = agent.trade(account_id, {"actionType": "ORDER_TYPE_BUY", "symbol": "EURUSD", "volume": 0.01},
                    reason="breakout above the Asian range")
    if r.outcome == "applied":
        print("filled", r.evidence)
    elif r.outcome == "held":
        print("waiting for approval", r.hold_id)
    elif r.outcome == "rejected":
        print("not executed:", r.error, "sent:", r.sent)
    else:                                               # unknown: it MAY have executed
        print(agent.trade_status(r.idempotency_key))    # never retry with a new key

Async: AsyncTickwire and AsyncAgentClient have the same methods (async with …, await …), plus resumable streams:

async with AsyncTickwire(API, "YOUR_API_KEY") as tw:
    async with tw.account(account_id).stream() as s:    # stream protocol v2
        state = await s.wait_synchronized()
        s.on("positionUpdated", lambda frame, st: print(frame["position"]))

What it covers

Area Methods
Native account (MetaApi-compatible) account(id): health, capabilities, audit, snapshot, account_information, positions, position, orders, order, deals, deals_by_position, history_orders, symbols, price, tick, specification, server_time, trade, check_trade, market_order, close_position, stream
Control plane list_accounts, get_account, list_webhooks, get_webhook, create_webhook, delete_webhook
Webhooks v2 webhook_event_types, webhook_settings, update_webhook, enable_webhook, disable_webhook, rotate_webhook_secret, reveal_webhook_secret, list_webhook_deliveries, get_webhook_delivery, resend_webhook_delivery, resend_event; verify with verify_webhook(secret_or_secrets, headers, body) (all rotation secrets) or verify_standard_webhook
Agent administration create_agent_key, list_agent_keys, get_agent_key, update_agent_key, revoke_agent_key, set_agent_key_kill_switch, list_kill_switches, set_account_kill_switch, create_pretrade_hook, list_pretrade_hooks, get_pretrade_hook, update_pretrade_hook, delete_pretrade_hook, rotate_pretrade_hook_secret, list_holds, get_hold, cancel_hold, agent_audit
Guarded execution execute_trade (returns a TradeResult)
Sandbox, connected AI apps sandbox_signup() (module function, no key needed), sandbox_info, create_sandbox_key, list_connected_apps, disconnect_connected_app
Dedicated IPs, billing dedicated_ips, move_accounts_to_dedicated_ip, billing_summary (read-only)
Agent API (AgentClient) me, accounts, snapshot, health, account_information, positions, orders, price, specification, deals, trade, trade_status, audit

Pagination

Native /v1 lists (agent keys, pre-trade hooks, holds, kill switches, the agent audit log, connected apps, AgentClient.accounts) return one page: {"data" | "entries" | "apps" | "accounts": [...], "has_more", "next_cursor"}. Pass limit= (1 to 500, default 100) and cursor=, or let pages follow the cursor for you:

for page in tw.pages(tw.list_holds, status="pending", limit=100):
    for hold in page["data"]:
        ...
# async: async for page in tw.pages(tw.list_agent_keys): ...

Snapshot

tw.account(id).snapshot() (or AgentClient.snapshot(account_id)) returns account information, positions, orders, health and server time in one read, each section with status (ok, stale, unavailable), read_at and age_ms. The broker's UTC offset is explicit (server_time["data"]["brokerUtcOffsetMinutes"], None when unknown).

Every call maps to an operation in tickwire/_operations.py, generated from the public OpenAPI spec (tickwire.io/openapi.json).

Safety you get by default

  • Idempotency. Every mutation sends Idempotency-Key (yours, or a generated tw_…), X-Actor and X-Reason. Pass idempotency_key= to make a repeat of the same decision safe across restarts.
  • Retries only when safe. Reads retry on transport errors and 408/429/502/503/504 with full-jitter backoff (Retry-After honoured up to the cap), within a per-client RetryBudget so an outage cannot become a retry storm. A mutation retries only when the server confirms it did not run it, always with the same key: connection refused; 409 idempotency_in_flight (the first attempt is still running, so the SDK waits Retry-After and then gets that attempt's stored result); or a 429/5xx whose body says explicitly sent: false (error codes alone never count).
  • unknown is never retried. A lost reply to a mutation (read timeout, reset) or any other 408/5xx raises OutcomeUnknown carrying the idempotency key; the guarded trades (execute_trade, AgentClient.trade) return TradeResult(outcome="unknown", sent="unknown") instead.
  • Streams resume. AccountStream re-subscribes with the last seq; a gap forces a full resync, so the mirror is never silently wrong.
  • Typed errors (NotFound, Conflict, NotSupportedOnMt4, RateLimited, ConfigError, …) keep the server envelope in .body. health() returns the body of a 503: "down" is an answer, not an exception.
  • Webhooks: verify_webhook(secret, headers, body) checks the HMAC-SHA256 signature and rejects replays outside a 5-minute window.
  • Clean close. close() / aclose() release every connection and are idempotent. Credentials never appear in repr().

A bare control plane (no gateway) serves the FxSocket routes at the root: pass control_prefix="".

Examples

A prop-firm risk guard (flatten on daily drawdown), a trade copier, a journal sync and a trading bot: tickwire.io/docs/guides/examples. Demo accounts only.

Metadata

Release files for tickwire 0.1.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 tickwire 0.1.0
File Size Uploaded Provenance Actions
tickwire-0.1.0.tar.gz 48.8 kB Without provenance Details for tickwire-0.1.0.tar.gz

Built distribution (wheel)

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

Total release size: 83.6 kB

Release files / tickwire-0.1.0.tar.gz

Download URL tickwire-0.1.0.tar.gz
Size 48.8 kB
Tags Source
SHA-256 checksum
How to use checksums
d3824c5f7877c20ad96102acdf21fe628664ce90cd4f4da7f2a368d9c6d35b1a
BLAKE2b-256 checksum
How to use checksums
35e258ee6c1bd2ec2b1d1b1d02ed9b9bcec3a8356cf0032565fc412a5ac7cece
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.15

Release files / tickwire-0.1.0-py3-none-any.whl

Download URL tickwire-0.1.0-py3-none-any.whl
Size 34.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e9618c2453625b612bfe8edc40faba59d9ac5ffcdbd4bffd9c90ba5ca3bceec3
BLAKE2b-256 checksum
How to use checksums
59fb82bad130d4cb59b9cb1fa80ca224a9a7ccac8fd91fdcf71cf66e6a6be6d5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.15

Security for tickwire 0.1.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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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

0.1.0 This release

2 release files No 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